تمامی کلاسها و متدهای عنوان شده در این مثال، در کتابخانه ذکر شده در آخر بحث موجود میباشد.
نظرات مطالب
معرفی کتابخانه PdfReport
ببخشید آقای نصیری آیا با استفاده از این کتابخانه میتوان هر گزارشی را با هر شکلی طراحی کرد؟
ممنونم
ممنونم
نظرات مطالب
مقابله با XSS ؛ یکبار برای همیشه!
کتابخانه امنیتی مایکروسافت خطوط جدید را حذف میکند: (+)
به همین جهت مثال مجددا به روز شد تا این مشکل وجود نداشته باشد
به همین جهت مثال مجددا به روز شد تا این مشکل وجود نداشته باشد
راهنماهای پروژهها
نگارش NET Core.
پاسخ به بازخوردهای پروژهها
مشکل در گروه بندی اطلاعات
با تشکر از شما، مشکل بر طرف شد. مهندس جان واقعاً این کتابخانه شما خوب کار میکند.
راهنماهای پروژهها
لیست مثالهای همراه با سورس کد PdfReport
برای دریافت یکجای تمامی مثالهای ذیل به این آدرس مراجعه کرده و بر روی لینک دانلود کلیک نمائید. همچنین توضیحات بیشتر و تکمیلی این مثالها، در برچسب PdfReport سایت، قابل پیگیری و مطالعه هستند.
• AccountingBalanceColumn/
چگونه باید از مقدار مانده ردیف قبلی در محاسبات ردیف جاری استفاده کرد (چیزی شبیه به گزارشات دفتر کل حسابداری).
• AcroFormTemplate/
چگونه میتوان از قالبهای سفارشی تهیه شده توسط Open office در PdfReport استفاده کرد. اگر در یک سلول قرار است قالب پیچیدهای را نمایش دهید، یکی از روشهای انجام کار استفاده از قالبهای AcroForm است.
• AdHocColumns/
چگونه تولید ستونهای گزارشات را پویا کنیم (بدون نیاز به تعریف جزئیات آنها). برای مثال اگر هربار کوئری متفاوتی را ارسال میکنید یا از منابع داده مختلفی با تعداد ستونهای متغیر در گزارش نهایی استفاده میشود، میتوانید با حذف قسمت تعاریف ستونها، این نوع گزارشات پویا را تهیه نمائید.
• AnnotationField/
نمایشی از قالب سلول سفارشی AnnotationField. Annotationها اشیایی خاص در فایلهای PDF هستند که امکان نوشتن توضیحات طولانی را فراهم میکنند و نهایتا به شکل یک آیکون در گزارش ظاهر خواهند شد.
• Barcodes/
مثالی در مورد نحوه تولید انواع بارکدهای مختلف مانند barcode 128 و barcode 39
• CalculatedFields/
چگونه بر اساس فیلدهای موجود یک گزارش، ستون محاسبه شده جدیدی را تولید کنیم. همچنین مواردی مانند فرمت کردن عدد نمایش داده شده و اضافه کردن جمع به یک ستون نیز در این گزارش لحاظ شده است.
• CharacterMap/
گزارشی شبیه به برنامه معروف character map ویندوز. در این گزارش نوع جدول به TableType.HorizontalStackPanel تنظیم شده است. به این ترتیب رکوردهای تولید شده به صورت افقی و پی در پی نمایش داده خواهند شد.
• ChartImage/
نحوه قرار دادن نمودارهای MS Chart را در گزارشات، در این مثال مشاهده خواهید کرد.
• CsvToPdf/
چگونه رکوردهای یک فایل CSV را تبدیل به فایل PDF کنیم؟ این مثال در حقیقت نحوه استفاده مستقیم از نتایج کوئریهای LINQ را بیان میکند.
• CustomCellTemplate/
چگونه یک قالب سلول سفارشی را تعریف کنیم. یک سری قالب پیش فرض مانند تصویر، متن و غیره در PdfReport به ازای هر سلول قابل تعریف است. اگر این موارد نیاز کاری شما را برآورده نمیکنند، میتوانید آنها را سفارشی سازی کنید.
• CustomHeaderFooter/
چگونه هدر و فوتر گزارشات را سفارشی سازی کنیم؟
• CustomPriceNumber/
چگونه یک قالب سلول سفارشی را جهت نمایش ویژه عدد مبلغ هر ردیف به شکل یک جدول پر شده از اعداد ایجاد کنیم.
• DataAnnotations/
چگونه تعاریف خواص ستونها را به کمک data annotations انجام داده و اینکار را سادهتر نمائیم. با استفاده از data annotations نیز میتوان قسمت تعاریف ستونها را کاملا حذف کرد.
• DbImage/
چگونه تصاویر ذخیره شده در بانک اطلاعاتی را در گزارشات نمایش دهیم.
• DigitalSignature/
چگونه امضای دیجیتال را به گزارشات PDF خود اضافه نمائیم.
• DuplicateColumns/
چگونه از ستونهایی هم نام، استفاده کنیم. برای مثال اگر از دو جدول کوئری میگیرید و دو فیلد به نامهای name اما با معانی و مقادیری متفاوت تعریف شدهاند، چگونه باید ایندکس آنها را جهت تمایز بهتر معرفی کرد.
• DynamicCompile/
چگونه سورس یک گزارش PdfReport را به صورت پویا از یک فایل متنی ساده خوانده و کامپایل کنیم.
• DynamicCrosstab/
چگونه یک گزارش Crosstab پویا را تعریف کنیم. برای مثال گزارشی که تعداد ستونهای آن نامشخص است و هر بار بر اساس بازه روزهای گزارشگیری تعیین میشود.
• EmailInMemoryPdf/
چگونه یک فایل Pdf تولید شده را به صورت خودکار به مقصدی خاص ایمیل کنیم.
• Events/
چگونه میتوان دقیقا پیش و پس از یک گزارش، تعاریف و عناصر دلخواه خود را اضافه کنیم؟
• ExcelToPdf/
چگونه یک فایل اکسل را تبدیل به گزارش PdfReport کنیم؟
• ExpensesCrosstab/
مثالی دیگر از نحوه تولید گزارشات Crosstab.
• ExtraHeadingCells/
چگونه گزارشاتی را تولید کنیم که هدر آنها بیش از یک ردیف است.
• Grouping/
نحوه گروه بندی اطلاعات را در این گزارش بررسی خواهیم کرد.
• HexDump/
یک گزارش ویژه از منبع دادهای anonymously typed.
• HtmlCellTemplate/
چگونه میتوان از Html جهت ساده سازی تعریف سلولهای پیچیده که بیش از یک مقدار را نمایش میدهند استفاده کرد.
• HtmlHeader/
چگونه میتوان از Html برای ساده سازی هدر گزارش استفاده کرد.
• HtmlHeaderRtl/
نسخه راست به چپ و فارسی مثال قبل.
• IList/
چگونه میتوان از لیستهای جنریک گزارش تهیه کرد.
• ImageFilePath/
چگونه میتوان از تصاویر ذخیره شده در فایل سیستم، گزارش گرفت.
• InjectCustomRows/
چگونه میتوان ردیفی سفارشی را در بین ردیفهای دریافت شده از بانک اطلاعاتی قرار داد.
• InlineProviders/
چگونه میتوان تعاریف سفارشی سلولها را در همان محل تعریف گزارش به نحوی سادهتر تعریف کرد.
• InMemory/
نحوه تولید فایلهای PDF درون حافظهای، مناسب جهت برنامههای وب ASP.NET (بدون نیاز به ذخیره فایل بر روی سرور)
• MailingLabel/
چگونه گزارشهای معروف برچسبهای چاپی را توسط PdfReport تولید کنیم.
• MasterDetails/
چگونه از روابط one-to-many بین دو جدول گزارش گیری کنیم؟
• MergePdfFiles/
چگونه از چند منبع داده مختلف استفاده کرده و نهایتا گزارشات حاصل را یکی و تبدیل به یک فایل PDF کنیم. برای نمونه استفاده از سه جدول مختلف با هدرها و سرستونهای متفاوت و سپس تولید یک گزارش یکپارچه از این سه، در قالب یک فایل نهایی. به علاوه در این مثال نحوه بازنویسی فوتر موجود نیز نمایش داده شده است (توسط WriterCustomizer آن).
• MonthCalendar/
چگونه در گزارشات، تقویم میلادی را نمایش دهیم.
• PdfA/
چگونه خروجی PDF حاصل را بر اساس استاندارد PdfA که مخصوص آرشیو و نگهداری است، تولید کنیم.
• PersianFontsListToPdf/
چگونه از لیست قلمهای نصب شده در سیستم گزارش Pdf تهیه کنیم.
• PersianMonthCalendar/
بررسی نحوه نمایش تقویم شمسی، در گزارشات.
• PersianRtl/
بررسی امکانات فارسی توکار کتابخانه PdfReport؛ مانند تهیه گزارشات راست به چپ، تاریخ شمسی، عدد به حروف و غیره.
• ProgressReport/
چگونه درصد پیشرفت یک عملیات را در سلولها نمایش دهیم. همچنین نحوه ایجاد گزارشات چند ستونی، برای صرفه جویی در میزان کاغذ مصرفی چاپ گزارشات را نیز در این گزارش مشاهده خواهید نمود.
• QuestionsAcroForm/
مثالی در مورد نحوه استفاده از قالبهای PDF تولید شده توسط Open office برای تولید برگه سؤالات امتحانی
• QuestionsForm/
مثالی در مورد نحوه طراحی برگه سؤالات امتحانی توسط سفارشی سازی سلولها در PdfReport
• SQLiteDataReader/
چگونه از یک بانک اطلاعاتی SQLite گزارش تهیه کنیم.
• StackedProperties/
چگونه در یک گزارش، در یک سلول بیش از یک فیلد را نمایش دهیم.
• Tax/
چگونه یک گزارش فاکتور فروش طراحی کنیم.
• WorkedHours/
چگونه گزارش حضور و غیاب پرسنل را تهیه کنیم.
• WrapGroupsInColumns/
چگونه گزارشات چندستونی را تولید کنیم.
• XmlToPdf/
چگونه دادههای یک فایل XML را تبدیل به گزارش کنیم.
• ZapfDingbatsSymbols/
چگونه از قلم مخصوص Symbols شرکت Adobe برای نمایش اشکال مختلف میتوان استفاده کرد.
• AccountingBalanceColumn/
چگونه باید از مقدار مانده ردیف قبلی در محاسبات ردیف جاری استفاده کرد (چیزی شبیه به گزارشات دفتر کل حسابداری).
• AcroFormTemplate/
چگونه میتوان از قالبهای سفارشی تهیه شده توسط Open office در PdfReport استفاده کرد. اگر در یک سلول قرار است قالب پیچیدهای را نمایش دهید، یکی از روشهای انجام کار استفاده از قالبهای AcroForm است.
• AdHocColumns/
چگونه تولید ستونهای گزارشات را پویا کنیم (بدون نیاز به تعریف جزئیات آنها). برای مثال اگر هربار کوئری متفاوتی را ارسال میکنید یا از منابع داده مختلفی با تعداد ستونهای متغیر در گزارش نهایی استفاده میشود، میتوانید با حذف قسمت تعاریف ستونها، این نوع گزارشات پویا را تهیه نمائید.
• AnnotationField/
نمایشی از قالب سلول سفارشی AnnotationField. Annotationها اشیایی خاص در فایلهای PDF هستند که امکان نوشتن توضیحات طولانی را فراهم میکنند و نهایتا به شکل یک آیکون در گزارش ظاهر خواهند شد.
• Barcodes/
مثالی در مورد نحوه تولید انواع بارکدهای مختلف مانند barcode 128 و barcode 39
• CalculatedFields/
چگونه بر اساس فیلدهای موجود یک گزارش، ستون محاسبه شده جدیدی را تولید کنیم. همچنین مواردی مانند فرمت کردن عدد نمایش داده شده و اضافه کردن جمع به یک ستون نیز در این گزارش لحاظ شده است.
• CharacterMap/
گزارشی شبیه به برنامه معروف character map ویندوز. در این گزارش نوع جدول به TableType.HorizontalStackPanel تنظیم شده است. به این ترتیب رکوردهای تولید شده به صورت افقی و پی در پی نمایش داده خواهند شد.
• ChartImage/
نحوه قرار دادن نمودارهای MS Chart را در گزارشات، در این مثال مشاهده خواهید کرد.
• CsvToPdf/
چگونه رکوردهای یک فایل CSV را تبدیل به فایل PDF کنیم؟ این مثال در حقیقت نحوه استفاده مستقیم از نتایج کوئریهای LINQ را بیان میکند.
• CustomCellTemplate/
چگونه یک قالب سلول سفارشی را تعریف کنیم. یک سری قالب پیش فرض مانند تصویر، متن و غیره در PdfReport به ازای هر سلول قابل تعریف است. اگر این موارد نیاز کاری شما را برآورده نمیکنند، میتوانید آنها را سفارشی سازی کنید.
• CustomHeaderFooter/
چگونه هدر و فوتر گزارشات را سفارشی سازی کنیم؟
• CustomPriceNumber/
چگونه یک قالب سلول سفارشی را جهت نمایش ویژه عدد مبلغ هر ردیف به شکل یک جدول پر شده از اعداد ایجاد کنیم.
• DataAnnotations/
چگونه تعاریف خواص ستونها را به کمک data annotations انجام داده و اینکار را سادهتر نمائیم. با استفاده از data annotations نیز میتوان قسمت تعاریف ستونها را کاملا حذف کرد.
• DbImage/
چگونه تصاویر ذخیره شده در بانک اطلاعاتی را در گزارشات نمایش دهیم.
• DigitalSignature/
چگونه امضای دیجیتال را به گزارشات PDF خود اضافه نمائیم.
• DuplicateColumns/
چگونه از ستونهایی هم نام، استفاده کنیم. برای مثال اگر از دو جدول کوئری میگیرید و دو فیلد به نامهای name اما با معانی و مقادیری متفاوت تعریف شدهاند، چگونه باید ایندکس آنها را جهت تمایز بهتر معرفی کرد.
• DynamicCompile/
چگونه سورس یک گزارش PdfReport را به صورت پویا از یک فایل متنی ساده خوانده و کامپایل کنیم.
• DynamicCrosstab/
چگونه یک گزارش Crosstab پویا را تعریف کنیم. برای مثال گزارشی که تعداد ستونهای آن نامشخص است و هر بار بر اساس بازه روزهای گزارشگیری تعیین میشود.
• EmailInMemoryPdf/
چگونه یک فایل Pdf تولید شده را به صورت خودکار به مقصدی خاص ایمیل کنیم.
• Events/
چگونه میتوان دقیقا پیش و پس از یک گزارش، تعاریف و عناصر دلخواه خود را اضافه کنیم؟
• ExcelToPdf/
چگونه یک فایل اکسل را تبدیل به گزارش PdfReport کنیم؟
• ExpensesCrosstab/
مثالی دیگر از نحوه تولید گزارشات Crosstab.
• ExtraHeadingCells/
چگونه گزارشاتی را تولید کنیم که هدر آنها بیش از یک ردیف است.
• Grouping/
نحوه گروه بندی اطلاعات را در این گزارش بررسی خواهیم کرد.
• HexDump/
یک گزارش ویژه از منبع دادهای anonymously typed.
• HtmlCellTemplate/
چگونه میتوان از Html جهت ساده سازی تعریف سلولهای پیچیده که بیش از یک مقدار را نمایش میدهند استفاده کرد.
• HtmlHeader/
چگونه میتوان از Html برای ساده سازی هدر گزارش استفاده کرد.
• HtmlHeaderRtl/
نسخه راست به چپ و فارسی مثال قبل.
• IList/
چگونه میتوان از لیستهای جنریک گزارش تهیه کرد.
• ImageFilePath/
چگونه میتوان از تصاویر ذخیره شده در فایل سیستم، گزارش گرفت.
• InjectCustomRows/
چگونه میتوان ردیفی سفارشی را در بین ردیفهای دریافت شده از بانک اطلاعاتی قرار داد.
• InlineProviders/
چگونه میتوان تعاریف سفارشی سلولها را در همان محل تعریف گزارش به نحوی سادهتر تعریف کرد.
• InMemory/
نحوه تولید فایلهای PDF درون حافظهای، مناسب جهت برنامههای وب ASP.NET (بدون نیاز به ذخیره فایل بر روی سرور)
• MailingLabel/
چگونه گزارشهای معروف برچسبهای چاپی را توسط PdfReport تولید کنیم.
• MasterDetails/
چگونه از روابط one-to-many بین دو جدول گزارش گیری کنیم؟
• MergePdfFiles/
چگونه از چند منبع داده مختلف استفاده کرده و نهایتا گزارشات حاصل را یکی و تبدیل به یک فایل PDF کنیم. برای نمونه استفاده از سه جدول مختلف با هدرها و سرستونهای متفاوت و سپس تولید یک گزارش یکپارچه از این سه، در قالب یک فایل نهایی. به علاوه در این مثال نحوه بازنویسی فوتر موجود نیز نمایش داده شده است (توسط WriterCustomizer آن).
• MonthCalendar/
چگونه در گزارشات، تقویم میلادی را نمایش دهیم.
• PdfA/
چگونه خروجی PDF حاصل را بر اساس استاندارد PdfA که مخصوص آرشیو و نگهداری است، تولید کنیم.
• PersianFontsListToPdf/
چگونه از لیست قلمهای نصب شده در سیستم گزارش Pdf تهیه کنیم.
• PersianMonthCalendar/
بررسی نحوه نمایش تقویم شمسی، در گزارشات.
• PersianRtl/
بررسی امکانات فارسی توکار کتابخانه PdfReport؛ مانند تهیه گزارشات راست به چپ، تاریخ شمسی، عدد به حروف و غیره.
• ProgressReport/
چگونه درصد پیشرفت یک عملیات را در سلولها نمایش دهیم. همچنین نحوه ایجاد گزارشات چند ستونی، برای صرفه جویی در میزان کاغذ مصرفی چاپ گزارشات را نیز در این گزارش مشاهده خواهید نمود.
• QuestionsAcroForm/
مثالی در مورد نحوه استفاده از قالبهای PDF تولید شده توسط Open office برای تولید برگه سؤالات امتحانی
• QuestionsForm/
مثالی در مورد نحوه طراحی برگه سؤالات امتحانی توسط سفارشی سازی سلولها در PdfReport
• SQLiteDataReader/
چگونه از یک بانک اطلاعاتی SQLite گزارش تهیه کنیم.
• StackedProperties/
چگونه در یک گزارش، در یک سلول بیش از یک فیلد را نمایش دهیم.
• Tax/
چگونه یک گزارش فاکتور فروش طراحی کنیم.
• WorkedHours/
چگونه گزارش حضور و غیاب پرسنل را تهیه کنیم.
• WrapGroupsInColumns/
چگونه گزارشات چندستونی را تولید کنیم.
• XmlToPdf/
چگونه دادههای یک فایل XML را تبدیل به گزارش کنیم.
• ZapfDingbatsSymbols/
چگونه از قلم مخصوص Symbols شرکت Adobe برای نمایش اشکال مختلف میتوان استفاده کرد.
واکنش نشان دادن به تغییرات صفحات وب، قسمت مهم و عمدهای از کار توسعهی برنامههای وب را تشکیل میدهد. مفاهیم مرتبط با DOM events از زمان IE 4.0 و Netscape Navigator version 2 به مرورگرها اضافه شدند و به مرور تکامل یافتند. پیش از ظهور مرورگرهای مدرن (به IE 9.0 و مرورگرهای پیش از آن، مرورگرهای «باستانی» گفته میشود) به علت عدم هماهنگی آنها با استانداردهای وب و تفاوت روشهای رخدادگردانی، jQuery نقش مهمی را در زمینهی یکدست سازی کدهای مدیریت رخدادها در بین مرورگرهای مختلف ارائه کرد. اما با پیشرفتهای صورت گرفته و هماهنگی بیشتر مرورگرها با استانداردهای وب، دیگر نیازی به jQuery برای ارائهی کدهای یکدست رخدادگردانی نیست و کار مستقیم با API وب مرورگرها برای این منظور کافی است.
انواع رخدادها: بومی و سفارشی
دو رده بندی عمومی رخدادها در مرورگرها وجود دارند: بومی و سفارشی.
بومیها همانهایی هستند که در مستندات رسمی استانداردهای وب ذکر شدهاند؛ مانند click که توسط ماوس و یا صفحه کلید فعال میشود و یا load که در زمان بارگذاری کامل صفحه، تصاویر و یا یک iframe رخ میدهد.
رخدادهای سفارشی مواردی هستند که توسط یک کتابخانهی خاص و یا جهت یک برنامهی خاص تهیه شدهاند. مانند یک رخداد سفارشی که زمان شروع آپلود یک فایل را اعلام میکند.
رخدادهای سفارشی که بدون jQuery ایجاد و رخمیدهند، توسط jQuery نیز قابل بررسی و مدیریت هستند و نه برعکس. به عبارتی رخدادهای سفارشی ایجاد شدهی توسط jQuery غیراستاندارد بوده و صرفا مختص به API آن هستند.
در این بین، شیء استاندارد Event کار اتصال رخدادهای سفارشی و استاندارد را انجام میدهد. هر نوع رخداد DOM (سفارشی و یا بومی)، توسط یک شیء Event بیان میشود که آن نیز به همراه تعدادی خاصیت و متد، جهت مدیریت این رخداد است. برای مثال رخداد click دارای خاصیت type ایی به نام click است که در شیء Event متناظر با آن تعریف شدهاست.
انتشار رخدادها در صفحه
در روزهای آغازین وب، Netscape روش event capturing را برای انتشار رخدادها در صفحه ارائه داد و در مقابل آن IE روش event bubbling را معرفی کرد که متضاد یکدیگر بودند. در سال 2000 با ارائه استاندارد DOM Level 2 Events Specification، این وضعیت تغییر کرد و شامل هر دو مورد event capturing و event bubbling است و در حال حاضر تمام مرورگرهای مدرن این استاندارد را پیاده سازی کردهاند. بر اساس این استاندارد، زمانیکه رویدادی خلق میشود، فاز capturing آغاز میگردد که از شیء window شروع، سپس به شیء document منتشر میشود و این روند تا رسیدن به المانی که سبب بروز رخداد شدهاست ادامه پیدا میکند. پس از پایان فاز capturing، فاز جدید bubbling شروع میشود. در این فاز، رخداد از تمام والدین شیء هدف عبور میکند تا به شیء window برسد.
برای مثال اگر سند HTML ما چنین تعریفی را داشته باشد و بر روی المان «child of child of one» کلیک شده باشد:
این رخداد در فاز capturing از این المانها عبور میکند:
و در فاز Bubbling از این المانها:
هرچند به دلایل تاریخی و همچنین عدم پشتیبانی jQuery از فاز capturing، بیشتر از فاز Bubbling به صورت پیشفرض در رخدادگردانی استفاده میشود. همچنین صدور رخداد از المانی که آنرا ایجاد کردهاست، بیشتر منطقی به نظر میرسد تا عکس آن.
البته باید درنظر داشت که jQuery از روش ارائه شدهی توسط مرورگر برای فاز Bubbling استفاده نمیکند و این مسیر را خودش مجددا محاسبه و رخدادگردانهای این مسیر را به صورت دستی اجرا میکند. به همین جهت کارآیی آن نسبت به روش توکار و بومی مرورگرها کمتر است.
ایجاد رخدادهای DOM و صدور آنها در jQuery
برای نمایش ایجاد و صدور رخدادهای DOM با و بدون jQuery، از قطعه کد HTML زیر استفاده میکنیم:
jQuery به همراه دو متد trigger و triggerHandler برای ایجاد و انتشار رخدادها در طول DOM است. متد trigger سبب ایجاد، صدور و انتشار یک رخداد به تمام والدهای شیء صادر کنندهی رخداد میشود. نوع این انتشار نیز bubbling است. متد triggerHandler، فقط بر روی المانی که فراخوانی میشود، عمل کرده و سبب انتشار این رخداد از طریق bubbling نمیشود:
در این مثالها توسط متد trigger، به دو روش سبب submit یک فرم و همچنین در ابتدا سبب focus یک تکست باکس و سپس رفع آن شدهایم.
هرچند روش دومی نیز در jQuery API برای انجام همینکارها نیز پیش بینی شدهاست:
در اینجا به ازای هر رخداد، یک نام مستعار در jQuery API تدارک دیده شدهاست.
در ادامه فرض کنید یک دکمه داخل یک div قرار گرفتهاست و آن div نیز به همراه یک مدیریت کنندهی رخداد کلیک است. در این حالت اگر بخواهیم با کلیک بر روی دکمه سبب اجرای رویدادگردان div والد نشویم، میتوان از متد triggerHandler استفاده کرد:
ایجاد رخدادهای DOM و صدور آنها در جاوا اسکریپت (بدون استفاده از jQuery)
در web API مرورگرها، برای انجام بروز رخدادهای معادل مثالی که با jQuery مطرح شد، میتوان متدهای بومی متناظر با این رخدادها را بر روی المانها فراخوانی کرد:
قطعه کد فوق به علت استفادهی از querySelector، با IE 8.0 و تمام مرورگرهای پس از آن سازگار است.
متدهای توکار و بومی click ،focus و blur بر روی تمام عناصر DOM که از اینترفیس HTMLElement مشتق شده باشند، وجود دارند. متد submit فقط بر روی المانهایی از نوع <form> وجود دارد و قابل فراخوانی است.
باید دقت داشت که فراخوانی متدهای click و submit از نوع bubbling است؛ اما متدهای focus و blur خیر. از این جهت که این دو رخداد فاز capturing را سبب میشوند.
متدهای یاد شده را توسط سازندهی شیء Event و یا متد createEvent شیء document نیز میتوان ایجاد کرد. یکی از کاربردهای آن، ارائهی رفتاری سفارشی مانند triggerHandler جیکوئری است:
کار با سازندهی شیء Event در تمام مرورگرهای جدید، منهای IE (تمام نگارشهای آن) پشتیبانی میشود. در اینجا اگر این پشتیبانی وجود داشت، از خاصیت bubbles: false شیء Event استفاده میشود و اگر مرورگری قدیمی بود، از متد document.createEvent برای این منظور کمک گرفته میشود. در این حالت دومین پارامتر متد initEvent، همان bubbles است.
ایجاد و صدور رخدادهای سفارشی
فرض کنید در حال تهیهی کتابخانهای هستیم که افزودن و حذف آیتمها را به یک گالری عکس ارائه میدهد. میخواهیم روشی را در اختیار مصرف کننده قرار دهیم تا بتواند به این رخدادهای سفارشی (غیر استانداردی که جزو W3C نیستند) گوش فرا دهد.
در جیکوئری برای ایجاد رخدادهای سفارشی به صورت زیر عمل میشود:
در اینجا نیز صدور رخدادها همانند قبل و توسط همان متد trigger است. اما مشکلی که با آن وجود دارد این است که گوش فرا دهندهی به این رخداد نیز باید توسط جیکوئری ارائه شود و خارج از این کتابخانه قابل دریافت و پیگیری نیست.
در خارج از جیکوئری و توسط web API استاندارد مرورگرها ایجاد و صدور رخدادهای سفارشی به همراه bubbling آن به صورت زیر است:
البته باید بهخاطر داشته باشید این روش صرفا با مرورگرهای جدید (منهای تمام نگارشهای IE) کار میکند. در اینجا اگر نیاز به ارائهی راه حلی سازگار با IE نیز وجود داشت میتوان از document.createEvent استفاده کرد:
و اگر بخواهیم بررسی وجود IE و یا پشتیبانی از CustomEvent را نیز قید کنیم، به قطعه کد زیر خواهیم رسید که با تمام مرورگرهای موجود کار میکند:
گوش فرادادن به رخدادهای صادر شده، توسط jQuery
در جیکوئری با استفاده از متد on آن میتوان به تمام رخدادهای استاندارد و همچنین سفارشی گوش فرا داد:
در ادامه برای حذف تمام گوش فرا دهندههای به رخداد resize میتوان از متد off آن استفاده کرد:
اما مشکلی را که این روش به همراه دارد، از کار انداختن تمام قسمتهای دیگری است که هم اکنون به صدور این رخداد گوش فرا میدهند.
روش بهتر انجام اینکار، ذخیرهی ارجاعی به متدی است که قرار است این رویداد گردانی را انجام دهد:
و در آخر تنها این گوش فرا دهندهی خاص را در صورت نیاز غیرفعال میکنیم و نه تمام گوش فرادهندههای سراسر برنامه را.
همچنین اگر یک گوش فراهندهی به رخدادی تنها قرار است یکبار در طول عمر برنامه اجرا شود، میتوان از متد one استفاده کرد:
پس از یکبار اجرای رخدادگردان کلیک در اینجا، از کلیکهای بعدی صرفنظر خواهد شد.
گوش فرادادن به رخدادهای صادر شده، توسط جاوا اسکریپت خالص (یا همان web API مرورگرها)
ابتداییترین روش گوش فرادادن به رخدادها که از زمان آغاز معرفی آنها در دسترس بودهاست، روش تعریف inline آنها است:
در اینجا متد رویدادگردان به یکی از ویژگی المان انتساب داده میشود. مشکل این روش، نیاز به سراسری تعریف کردن متد handleButtonClick است و دیگر نمیتوان آنرا در فضای نامی خاص و یا سفارشی قرار داد.
روش دیگر ثبت رویدادگردان click، انتساب متد آن به خاصیت رخداد متناظری در آن المان ویژه است:
مزیت این روش، عدم نیاز به استفادهی از متدهای سراسری است.
البته باید دقت داشت که یکی از دو روش یاد شده را میتوانید استفاده کنید. در اینجا آخرین رویدادگردان متصل شدهی به المان، همواره تمام نمونههای موجود دیگر را بازنویسی میکند.
اگر نیاز به معرفی رویدادگردانهای متعددی برای یک المان در ماژولهای مختلف برنامه وجود داشت، از زمان IE 9.0 به بعد، متد addEventListener برای این منظور تدارک دیده شدهاست و syntax آن بسیار شبیه به متد on جیکوئری است:
در این حالت دیگر مشکل نیاز به متدهای سراسری و یا عدم امکان تعریف بیش از یک رویدادگردان خاص برای المانی مشخص، دیگر وجود ندارد.
برای نمونه معادل قطعه کد جیکوئری که پیشتر با متد on نوشتیم، با جاوا اسکریپت خالص به صورت زیر است:
در اینجا برای حذف یک رویدادگردان میتوان از متد removeEventListener استفاده کرد. تفاوت مهم آن با متد off جیکوئری این است که در اینجا حتما باید مشخص باشد کدام رویدادگردان را میخواهید حذف کنید:
یعنی روش حذف رویدادگردانها در اینجا شبیه به مثال دومی است که برای متد off جیکوئری ارائه کردیم. ابتدا باید ارجاعی را به متد رویدادگردان تهیه کنیم و سپس بر اساس این ارجاع، امکان حذف آن وجود خواهد داشت.
در اینجا حتی امکان تعریف متد one جیکوئری نیز پیش بینی شدهاست (البته جزو استانداردهای جدید وب از سال 2016 است):
اگر بخواهیم متد one سازگار با مرورگرهای قدیمیتر را نیز ارائه کنیم، چنین شکلی را پیدا میکند:
در اینجا پس از بروز رخداد، کار removeEventListener آن به صورت خودکار صورت میگیرد.
کنترل انتشار رخدادها
فرض کنید میخواهیم جلوی انتخاب المانهای صفحه مانند تصاویر و متن را توسط ماوس بگیریم. روش انجام اینکار با jQuery به صورت زیر است:
و یا توسط web API مرورگرها به این صورت:
مطابق «W3C DOM Level 3 Events specification» عملکرد پیشفرض رخداد mousedown با انتخاب متون و یا کشیدن و رها کردن المانها آغاز میشود. متد preventDefault یکی از متدهای شیء event است که به رویدادگردانهای تعریف شده ارسال میشود و توسط آن عملکرد پیشفرض آن رخداد لغو میشود.
برای جلوگیری کردن از انتشار رخدادی مانند click جهت رسیدن به سایر رویدادگردانهای ثبت شدهی در بین راه فاز bubbling، میتوان از متد stopPropagation استفاده کرد. روش انجام اینکار در جیکوئری:
البته jQuery صرفا فاز انتشار از نوع bubbling را پشتیبانی میکند.
و با web Api جهت جلوگیری از انتشار رخدادها در فاز capturing (این تنها راه مدیریت فاز capturing است):
و یا استفاده از web API برای جلوگیری از انتشار رخدادها در فاز bubbling:
البته باید درنظر داشت که متد stopPropagation از انتشار رخدادها به سایر گوش فرا دهندههای همان المان صادر کنندهی رخداد جلوگیری نمیکند. برای این منظور باید از متد stopImmediatePropagation استفاده کرد؛ در جیکوئری:
و توسط web API مرورگرها:
یک نکته: در این حالت اگر متد رویدادگردانی مقدار false را برگرداند، به معنای فراخوانی هر دوی متد preventDefault و stopPropagation است.
ارسال اطلاعات به رویدادگردانها
روش ارسال اطلاعات اضافی به رویداد گردانها در جیکوئری به صورت زیر است:
و رویدادگردان گوش فرا دهندهی به آن، به این نحو میتواند به filename دسترسی پیدا کند:
در اینجا دومین پارامتر تعریف شده، امکان دسترسی به تمام خواص سفارشی ارسالی را میسر میکند.
روش انجام اینکار با web API مرورگرها به صورت زیر است:
این روش با تمام مرورگرهای مدرن (منهای تمام نگارشهای IE) کار میکند و روش دسترسی به خاصیت detail سفارشی تعریف و ارسال شده، از طریق همان خاصیت event ارسالی به رویدادگردان است.
و اگر میخواهید از IE هم پشتیبانی کنید، روش جایگزین کردن شیء CustomEvent با createEvent به صورت زیر است:
متوجه شدن زمان بارگذاری یک شیء در صفحه
در حین توسعهی برنامههای وب، با این نوع سؤالات زیاد مواجه خواهید شد: چه زمانی تمام و یا بعضی از المانهای صفحه کاملا بارگذاری و رندر شدهاند؟
پاسخ به این نوع سؤالات در W3C UI Events specification توسط رویداد استاندارد load داده شدهاست.
- چه زمانی تمام المانهای موجود در صفحه کاملا بارگذاری و رندر شده و همچنین شیوهنامههای تعریف شده نیز به آنها اعمال گردیدهاند؟
روش انجام اینکار با jQuery:
و توسط web API بومی مرورگرها که بسیار مشابه نمونهی jQuery است:
- چه زمانی markup استاتیک صفحهی جاری در جای خود قرار گرفتهاند؟
اهمیت این موضوع، به دسترسی به زمان مناسب و امن ایجاد تغییرات در DOM بر میگردد. برای این منظور رویداد استاندارد DOMContentLoaded پیشبینی شدهاست که زودتر از رویداد load، در دسترس برنامه نویس قرار میگیرد. در جیکوئری توسط یکی از دو روش معروف زیر به رویداد یاد شده دسترسی خواهید داشت:
و معادل web API آن در تمام مرورگرهای جدید، همان تعریف رویدادگردانی برای DOMContentLoaded استاندارد است:
یک نکته: بهتر است این تعریف web API را پیش از تگهای <link> قرار دهید. زیرا بارگذاری آنها، اجرای هر نوع اسکریپتی را تا زمان پایان عملیات، سد میکند.
- چه زمانی المانی خاص در صفحه بارگذاری شدهاست و چه زمانی بارگذاری یک المان با شکست مواجه شدهاست؟
در جیکوئری توسط بررسی رویدادهای load و error میتوان به وضعیت نهایی بارگذاری المانهایی خاص دسترسی یافت:
روش انجام اینکار با web API مرورگرها نیز یکی است:
- جلوگیری از ترک اتفاقی صفحهی جاری
گاهی از اوقات نیاز است برای از جلوگیری از تخریب صفحهی جاری و از دست رفتن اطلاعات ذخیره نشدهی کاربر، اگر بر روی دکمهی close بالای صفحه کلیک کرد و یا کاربر به اشتباه به صفحهی دیگری هدایت شد، جلوی اینکار را بگیریم. برای این منظور رخداد استاندارد beforeunload درنظر گرفته شدهاست. روش استفادهی از این رویداد در جیکوئری:
و در web API مرورگرها:
در حالت web API بعضی از مرورگرها از نتیجهی متد استفاده میکنند و بعضی دیگر از مقدار خاصیت event.returnValue. به همین جهت هر دو مورد در اینجا مقدار دهی شدهاند.
انواع رخدادها: بومی و سفارشی
دو رده بندی عمومی رخدادها در مرورگرها وجود دارند: بومی و سفارشی.
بومیها همانهایی هستند که در مستندات رسمی استانداردهای وب ذکر شدهاند؛ مانند click که توسط ماوس و یا صفحه کلید فعال میشود و یا load که در زمان بارگذاری کامل صفحه، تصاویر و یا یک iframe رخ میدهد.
رخدادهای سفارشی مواردی هستند که توسط یک کتابخانهی خاص و یا جهت یک برنامهی خاص تهیه شدهاند. مانند یک رخداد سفارشی که زمان شروع آپلود یک فایل را اعلام میکند.
رخدادهای سفارشی که بدون jQuery ایجاد و رخمیدهند، توسط jQuery نیز قابل بررسی و مدیریت هستند و نه برعکس. به عبارتی رخدادهای سفارشی ایجاد شدهی توسط jQuery غیراستاندارد بوده و صرفا مختص به API آن هستند.
در این بین، شیء استاندارد Event کار اتصال رخدادهای سفارشی و استاندارد را انجام میدهد. هر نوع رخداد DOM (سفارشی و یا بومی)، توسط یک شیء Event بیان میشود که آن نیز به همراه تعدادی خاصیت و متد، جهت مدیریت این رخداد است. برای مثال رخداد click دارای خاصیت type ایی به نام click است که در شیء Event متناظر با آن تعریف شدهاست.
انتشار رخدادها در صفحه
در روزهای آغازین وب، Netscape روش event capturing را برای انتشار رخدادها در صفحه ارائه داد و در مقابل آن IE روش event bubbling را معرفی کرد که متضاد یکدیگر بودند. در سال 2000 با ارائه استاندارد DOM Level 2 Events Specification، این وضعیت تغییر کرد و شامل هر دو مورد event capturing و event bubbling است و در حال حاضر تمام مرورگرهای مدرن این استاندارد را پیاده سازی کردهاند. بر اساس این استاندارد، زمانیکه رویدادی خلق میشود، فاز capturing آغاز میگردد که از شیء window شروع، سپس به شیء document منتشر میشود و این روند تا رسیدن به المانی که سبب بروز رخداد شدهاست ادامه پیدا میکند. پس از پایان فاز capturing، فاز جدید bubbling شروع میشود. در این فاز، رخداد از تمام والدین شیء هدف عبور میکند تا به شیء window برسد.
برای مثال اگر سند HTML ما چنین تعریفی را داشته باشد و بر روی المان «child of child of one» کلیک شده باشد:
<!DOCTYPE html> <html> <head> <title>event propagation demo</title> </head> <body> <section> <h1>nested divs</h1> <div>one <div>child of one <div>child of child of one</div> </div> </div> </section> </body> </html>
1.window 2.document 3.<html> 4.<body> 5.<section> 6.<div>one 7.<div>child of one 8.<div>child of child of one
9.<div>child of child of one 10.<div>child of one 11.<div>one 12.<section> 13.<body> 14.<html> 15.document 16.window
البته باید درنظر داشت که jQuery از روش ارائه شدهی توسط مرورگر برای فاز Bubbling استفاده نمیکند و این مسیر را خودش مجددا محاسبه و رخدادگردانهای این مسیر را به صورت دستی اجرا میکند. به همین جهت کارآیی آن نسبت به روش توکار و بومی مرورگرها کمتر است.
ایجاد رخدادهای DOM و صدور آنها در jQuery
برای نمایش ایجاد و صدور رخدادهای DOM با و بدون jQuery، از قطعه کد HTML زیر استفاده میکنیم:
<div> <button type="button">do something</button> </div> <form method="POST" action="/user"> <label>Enter user name: <input name="user"> </label> <button type="submit">submit</button> </form>
// submits the form $('FORM').trigger('submit'); // submits the form by clicking the button $('BUTTON[type="submit"]').trigger('click'); // focuses the text input $('INPUT').trigger('focus'); // removes focus from the text input $('INPUT').trigger('blur');
هرچند روش دومی نیز در jQuery API برای انجام همینکارها نیز پیش بینی شدهاست:
// submits the form $('FORM').submit(); // submits the form by clicking the button $('BUTTON[type="submit"]').click(); // focuses the text input $('INPUT').focus(); // removes focus from the text input $('INPUT').blur();
در ادامه فرض کنید یک دکمه داخل یک div قرار گرفتهاست و آن div نیز به همراه یک مدیریت کنندهی رخداد کلیک است. در این حالت اگر بخواهیم با کلیک بر روی دکمه سبب اجرای رویدادگردان div والد نشویم، میتوان از متد triggerHandler استفاده کرد:
// clicks the first button - the click event does not bubble $('BUTTON[type="button"]').triggerHandler('click');
ایجاد رخدادهای DOM و صدور آنها در جاوا اسکریپت (بدون استفاده از jQuery)
در web API مرورگرها، برای انجام بروز رخدادهای معادل مثالی که با jQuery مطرح شد، میتوان متدهای بومی متناظر با این رخدادها را بر روی المانها فراخوانی کرد:
// submits the form document.querySelector('FORM').submit(); // submits the form by clicking the button document.querySelector('BUTTON[type="submit"]').click(); // focuses the text input document.querySelector('INPUT').focus(); // removes focus from the text input document.querySelector('INPUT').blur();
متدهای توکار و بومی click ،focus و blur بر روی تمام عناصر DOM که از اینترفیس HTMLElement مشتق شده باشند، وجود دارند. متد submit فقط بر روی المانهایی از نوع <form> وجود دارد و قابل فراخوانی است.
باید دقت داشت که فراخوانی متدهای click و submit از نوع bubbling است؛ اما متدهای focus و blur خیر. از این جهت که این دو رخداد فاز capturing را سبب میشوند.
متدهای یاد شده را توسط سازندهی شیء Event و یا متد createEvent شیء document نیز میتوان ایجاد کرد. یکی از کاربردهای آن، ارائهی رفتاری سفارشی مانند triggerHandler جیکوئری است:
var clickEvent; if (typeof Event === 'function') { clickEvent = new Event('click', {bubbles: false}); } else { clickEvent = document.createEvent('Event'); clickEvent.initEvent('click', false, true); } document.querySelector('BUTTON[type="button"]').dispatchEvent(clickEvent);
ایجاد و صدور رخدادهای سفارشی
فرض کنید در حال تهیهی کتابخانهای هستیم که افزودن و حذف آیتمها را به یک گالری عکس ارائه میدهد. میخواهیم روشی را در اختیار مصرف کننده قرار دهیم تا بتواند به این رخدادهای سفارشی (غیر استانداردی که جزو W3C نیستند) گوش فرا دهد.
در جیکوئری برای ایجاد رخدادهای سفارشی به صورت زیر عمل میشود:
// Triggers a custom "image-removed" element, // which bubbles up to ancestor elements. $libraryElement.trigger('image-removed', {id: 1});
در خارج از جیکوئری و توسط web API استاندارد مرورگرها ایجاد و صدور رخدادهای سفارشی به همراه bubbling آن به صورت زیر است:
var event = new CustomEvent('image-removed', { bubbles: true, detail: {id: 1} }); libraryElement.dispatchEvent(event);
var event = document.createEvent('CustomEvent'); event.initCustomEvent('image-removed', false, true, {id: 1}); libraryElement.dispatchEvent(event);
var event; // If the `CustomEvent` constructor function is not supported, // fall back to `createEvent` method. if (typeof CustomEvent === 'function') { event = new CustomEvent('image-removed', { bubbles: true, detail: {id: 1} }); } else { event = document.createEvent('CustomEvent'); event.initCustomEvent('image-removed', false, true, { id: 1 }); } libraryElement.dispatchEvent(event);
گوش فرادادن به رخدادهای صادر شده، توسط jQuery
در جیکوئری با استفاده از متد on آن میتوان به تمام رخدادهای استاندارد و همچنین سفارشی گوش فرا داد:
$(window).on('resize', function() { // react to new window size });
// remove all resize listeners - usually a bad idea $(window).off('resize');
روش بهتر انجام اینکار، ذخیرهی ارجاعی به متدی است که قرار است این رویداد گردانی را انجام دهد:
var resizeHandler = function() { // react to new window size }; $(window).on('resize', resizeHandler); // ...later // remove only our resize handler $(window).off('resize', resizeHandler);
همچنین اگر یک گوش فراهندهی به رخدادی تنها قرار است یکبار در طول عمر برنامه اجرا شود، میتوان از متد one استفاده کرد:
$(someElement).one('click', function() { // handle click event });
گوش فرادادن به رخدادهای صادر شده، توسط جاوا اسکریپت خالص (یا همان web API مرورگرها)
ابتداییترین روش گوش فرادادن به رخدادها که از زمان آغاز معرفی آنها در دسترس بودهاست، روش تعریف inline آنها است:
<button onclick="handleButtonClick()">click me</button>
روش دیگر ثبت رویدادگردان click، انتساب متد آن به خاصیت رخداد متناظری در آن المان ویژه است:
buttonEl.onclick = function() { // handle button click };
البته باید دقت داشت که یکی از دو روش یاد شده را میتوانید استفاده کنید. در اینجا آخرین رویدادگردان متصل شدهی به المان، همواره تمام نمونههای موجود دیگر را بازنویسی میکند.
اگر نیاز به معرفی رویدادگردانهای متعددی برای یک المان در ماژولهای مختلف برنامه وجود داشت، از زمان IE 9.0 به بعد، متد addEventListener برای این منظور تدارک دیده شدهاست و syntax آن بسیار شبیه به متد on جیکوئری است:
buttonEl.addEventListener('click', function() { // handle button click });
برای نمونه معادل قطعه کد جیکوئری که پیشتر با متد on نوشتیم، با جاوا اسکریپت خالص به صورت زیر است:
window.addEventListener('resize', function() { // react to new window size });
var resizeHandler = function() { // react to new window size }; window.addEventListener('resize', resizeHandler); // ...later // remove only our resize handler window.removeEventListener('resize', resizeHandler);
در اینجا حتی امکان تعریف متد one جیکوئری نیز پیش بینی شدهاست (البته جزو استانداردهای جدید وب از سال 2016 است):
someElement.addEventListener('click', function(event) { // handle click event }, { once: true });
var clickHandler = function() { // handle click event // ...then unregister handler someElement.removeEventListener('click', clickHandler); }; someElement.addEventListener('click', clickHandler);
کنترل انتشار رخدادها
فرض کنید میخواهیم جلوی انتخاب المانهای صفحه مانند تصاویر و متن را توسط ماوس بگیریم. روش انجام اینکار با jQuery به صورت زیر است:
$(window).on('mousedown', function(event) { event.preventDefault(); });
window.addEventListener('mousedown', function(event) { event.preventDefault(); });
برای جلوگیری کردن از انتشار رخدادی مانند click جهت رسیدن به سایر رویدادگردانهای ثبت شدهی در بین راه فاز bubbling، میتوان از متد stopPropagation استفاده کرد. روش انجام اینکار در جیکوئری:
$someElement.on('click', function(event) { event.stopPropagation(); });
و با web Api جهت جلوگیری از انتشار رخدادها در فاز capturing (این تنها راه مدیریت فاز capturing است):
// stop propagation during capturing phase someElement.addEventListener('click', function(event) { event.stopPropagation(); }, true);
// stop propagation during bubbling phase someElement.addEventListener('click', function(event) { event.stopPropagation(); });
$someElement.on('click', function(event) { event.stopImmediatePropagation(); });
someElement.addEventListener('click', function(event) { event.stopImmediatePropagation(); });
یک نکته: در این حالت اگر متد رویدادگردانی مقدار false را برگرداند، به معنای فراخوانی هر دوی متد preventDefault و stopPropagation است.
ارسال اطلاعات به رویدادگردانها
روش ارسال اطلاعات اضافی به رویداد گردانها در جیکوئری به صورت زیر است:
$uploaderElement.trigger('uploadError', { filename: 'picture.jpeg' });
$uploaderParent.on('uploadError', function(event, data) { showAlert('Failed to upload ' + data.filename); });
روش انجام اینکار با web API مرورگرها به صورت زیر است:
// send the failed filename w/ an error event var event = new CustomEvent('uploadError', { bubbles: true, detail: {filename: 'picture.jpeg'} }); uploaderElement.dispatchEvent(event); // ...and this is a listener for the event uploaderParent.addEventListener('uploadError', function(event) { showAlert('Failed to upload ' + event.detail.filename); });
و اگر میخواهید از IE هم پشتیبانی کنید، روش جایگزین کردن شیء CustomEvent با createEvent به صورت زیر است:
// send the failed filename w/ an error event var event = document.createEvent('CustomEvent'); event.initCustomEvent('uploadError', true, true, { filename: 'picture.jpeg' }); uploaderElement.dispatchEvent(event); // ...and this is a listener for the event uploaderParent.addEventListener('uploadError', function(event) { showAlert('Failed to upload ' + event.detail.filename); });
متوجه شدن زمان بارگذاری یک شیء در صفحه
در حین توسعهی برنامههای وب، با این نوع سؤالات زیاد مواجه خواهید شد: چه زمانی تمام و یا بعضی از المانهای صفحه کاملا بارگذاری و رندر شدهاند؟
پاسخ به این نوع سؤالات در W3C UI Events specification توسط رویداد استاندارد load داده شدهاست.
- چه زمانی تمام المانهای موجود در صفحه کاملا بارگذاری و رندر شده و همچنین شیوهنامههای تعریف شده نیز به آنها اعمال گردیدهاند؟
روش انجام اینکار با jQuery:
$(window).on('load', function() { // page is fully rendered });
window.addEventListener('load', function() { // page is fully rendered });
- چه زمانی markup استاتیک صفحهی جاری در جای خود قرار گرفتهاند؟
اهمیت این موضوع، به دسترسی به زمان مناسب و امن ایجاد تغییرات در DOM بر میگردد. برای این منظور رویداد استاندارد DOMContentLoaded پیشبینی شدهاست که زودتر از رویداد load، در دسترس برنامه نویس قرار میگیرد. در جیکوئری توسط یکی از دو روش معروف زیر به رویداد یاد شده دسترسی خواهید داشت:
$(document).ready(function() { // markup is on the page }); //or $(function() { // markup is on the page });
document.addEventListener('DOMContentLoaded', function() { // markup is on the page });
یک نکته: بهتر است این تعریف web API را پیش از تگهای <link> قرار دهید. زیرا بارگذاری آنها، اجرای هر نوع اسکریپتی را تا زمان پایان عملیات، سد میکند.
- چه زمانی المانی خاص در صفحه بارگذاری شدهاست و چه زمانی بارگذاری یک المان با شکست مواجه شدهاست؟
در جیکوئری توسط بررسی رویدادهای load و error میتوان به وضعیت نهایی بارگذاری المانهایی خاص دسترسی یافت:
$('IMG').on('load', function() { // image has successfully loaded }); $('IMG').on('error', function() { // image has failed to load });
document.querySelector('IMG').addEventListener('load', function() { // image has successfully loaded }); document.querySelector('IMG').addEventListener('error', function() { // image has failed to load });
- جلوگیری از ترک اتفاقی صفحهی جاری
گاهی از اوقات نیاز است برای از جلوگیری از تخریب صفحهی جاری و از دست رفتن اطلاعات ذخیره نشدهی کاربر، اگر بر روی دکمهی close بالای صفحه کلیک کرد و یا کاربر به اشتباه به صفحهی دیگری هدایت شد، جلوی اینکار را بگیریم. برای این منظور رخداد استاندارد beforeunload درنظر گرفته شدهاست. روش استفادهی از این رویداد در جیکوئری:
$(window).on('beforeunload', function() { return 'Are you sure you want to unload the page?'; });
window.addEventListener('beforeunload', function(event) { var message = 'Are you sure you want to unload the page?'; event.returnValue = message; return message; });
بحث EF متفاوت است و کاربرد گستردهای دارد؛ از وب تا دسکتاپ و غیره. در تعدادی سکوهای کاری، synchronization context نال هست و در تعدادی دیگر خیر. در ASP.NET Core نال هست و در موارد دیگر خیر. خلاصه به همین جهت مجبور شدند اینکار را انجام دهند. باید ببینید استفاده کنندهی از کتابخانهی شما بیشتر چه کاربردی را دنبال میکند؛ وب هست یا دسکتاپ؟ دات نت قدیم هست یا جدید؟ یک زمانی از EF-Core میشد در برنامههای داتنت قدیم هم استفاده کرد (نگارشهای جدیدتر آن خیر).
API کار با کوکیها نیز در ASP.NET Core نسبت به نگارشهای دیگر تغییریافتهاست که در ادامه این موارد را بررسی خواهیم کرد. همچنین با کمک مطلب «تغییرات رمزنگاری اطلاعات در NET Core.» یک تامین کنندهی سفارشی کوکیهای رمزنگاری شده را نیز ایجاد میکنیم.
خلاصهای از روشهای کار با کوکیها در ASP.NET Core
ایجاد یک کوکی جدید
کوکی جدید را میتوان توسط متد Append مجموعهی کوکیها، به Response اضافه کرد:
همانطور که در تصویر نیز مشخص است، طول عمر این کوکی، به سشن تنظیم شدهاست و با پایان سشن جاری مرورگر (بسته شدن کل مرورگر)، این کوکی نیز غیرمعتبر شده و به صورت خودکار حذف خواهد شد. برای تعیین عمر دقیق یک کوکی میتوان از خاصیت Expires شیء CookieOptions که در مثال فوق مقدار دهی نشدهاست، استفاده کرد؛ مانند:
خواندن محتویات کوکی ذخیره شده
پس از ثبت کوکی در Response، خواندن آن در Request بعدی به شکل زیر است:
در این حالت اگر کلید درخواستی در مجموعهی کوکیها یافت نشد، نال بازگشت داده میشود.
شیء this.Request.Cookies از نوع IRequestCookieCollection است:
و همانطور که ملاحظه میکنید، برای دریافت مقدار یک کوکی یا میتوان از indexer آن مانند مثال فوق و یا از متد TryGetValue استفاده کرد.
در مستندات آن عنوان شدهاست که در حالت استفادهی از indexer، درصورت یافت نشدن کلید، string.Empty بازگشت داده میشود (که آزمایشات null را نمایش میدهند). اما در حالت استفادهی از TryGetValue بر اساس خروجی bool آن دقیقا میتوان مشخص کرد که آیا این کوکی وجود داشتهاست یا خیر.
در اینجا همچنین متد ContainsKey نیز جهت بررسی وجود یک کلید، در مجموعهی کلیدها نیز پیش بینی شدهاست.
بنابراین بهتر است جهت یافتن مقادیر کوکیها از روش ذیل استفاده کرد:
حذف کوکیهای موجود
در اینجا متد Delete نیز پیش بینی شدهاست که باید بر روی کوکیهای Response فراخوانی شود:
کار آن افزودن یک کوکی دیگر با همین کلید، اما منقضی شدهاست؛ تا مرورگر را مجبور به حذف آن کند. در اینجا در صورت نیاز میتوان به عنوان پارامتر دوم، CookieOptions این کوکی جدید را نیز تنظیم کرد.
همانطور که در تصویر نیز مشخص است، در صورت عدم تنظیم CookieOptions، این کوکی جدید اضافه شده، دارای تاریخ انقضای 1970 است که سبب خواهد شد تا توسط مرورگر، غیرمعتبر درنظر گرفته شده و حذف شود.
طراحی یک تامین کنندهی کوکیهای امن
پس از آشنایی با مقدمات کوکیها و همچنین «بررسی تغییرات رمزنگاری اطلاعات در NET Core.»، اکنون میتوان یک تامین کنندهی کوکیهای رمزنگاری شده را برای ASP.NET Core به نحو ذیل طراحی کرد:
- نکاتی را که در ابتدای مطلب در مورد ثبت و خواندن و حذف کوکیها مطالعه کردید، به این کلاس اضافه شدهاند. با این تغییر که پیش از ذخیرهی مقدار کوکی، این مقدار رمزنگاری میشود و همچنین پس از خواندن آن، رمزگشایی خواهد شد.
- در این تامین کنندهی کوکیهای امن، IProtectionProvider تزریقی به سازندهی کلاس را در مطلب «تغییرات رمزنگاری اطلاعات در NET Core.» پیشتر ملاحظه کردهاید.
- در اینجا برای ثبت سرویس جدید، تنظیمات ابتدایی برنامه چنین شکلی را پیدا میکنند و پس از آن میتوان سرویس ISecureCookiesProvider را به کنترلرهای برنامه تزریق و استفاده کرد:
- چون در کلاس SecureCookiesProvider، خاصیت Expires تنظیم نشدهاست، طول عمر این کوکیها محدود است به مدت زمان باز بودن مرورگر. بنابراین در صورت نیاز این مورد را تغییر دهید.
خلاصهای از روشهای کار با کوکیها در ASP.NET Core
ایجاد یک کوکی جدید
using Microsoft.AspNetCore.Http; using Microsoft.AspNetCore.Mvc; namespace Core1RtmEmptyTest.Controllers { public class TestCookiesController : Controller { public IActionResult Index() { this.Response.Cookies.Append("key", "value", new CookieOptions { HttpOnly = true, Path = this.Request.PathBase.HasValue ? this.Request.PathBase.ToString() : "/", Secure = this.Request.IsHttps }); return Content("OK!"); } } }
همانطور که در تصویر نیز مشخص است، طول عمر این کوکی، به سشن تنظیم شدهاست و با پایان سشن جاری مرورگر (بسته شدن کل مرورگر)، این کوکی نیز غیرمعتبر شده و به صورت خودکار حذف خواهد شد. برای تعیین عمر دقیق یک کوکی میتوان از خاصیت Expires شیء CookieOptions که در مثال فوق مقدار دهی نشدهاست، استفاده کرد؛ مانند:
Expires = DateTimeOffset.UtcNow.AddDays(2)
خواندن محتویات کوکی ذخیره شده
پس از ثبت کوکی در Response، خواندن آن در Request بعدی به شکل زیر است:
var value = this.Request.Cookies["key"];
شیء this.Request.Cookies از نوع IRequestCookieCollection است:
public interface IRequestCookieCollection : IEnumerable<KeyValuePair<string, string>>, IEnumerable { string this[string key] { get; } ICollection<string> Keys { get; } bool ContainsKey(string key); bool TryGetValue(string key, out string value); }
در مستندات آن عنوان شدهاست که در حالت استفادهی از indexer، درصورت یافت نشدن کلید، string.Empty بازگشت داده میشود (که آزمایشات null را نمایش میدهند). اما در حالت استفادهی از TryGetValue بر اساس خروجی bool آن دقیقا میتوان مشخص کرد که آیا این کوکی وجود داشتهاست یا خیر.
در اینجا همچنین متد ContainsKey نیز جهت بررسی وجود یک کلید، در مجموعهی کلیدها نیز پیش بینی شدهاست.
بنابراین بهتر است جهت یافتن مقادیر کوکیها از روش ذیل استفاده کرد:
string cookieValue; if (this.Request.Cookies.TryGetValue(key, out cookieValue)) { // TODO: use the cookieValue } else { // this cookie doesn't exist. }
حذف کوکیهای موجود
در اینجا متد Delete نیز پیش بینی شدهاست که باید بر روی کوکیهای Response فراخوانی شود:
this.Response.Cookies.Delete("key");
همانطور که در تصویر نیز مشخص است، در صورت عدم تنظیم CookieOptions، این کوکی جدید اضافه شده، دارای تاریخ انقضای 1970 است که سبب خواهد شد تا توسط مرورگر، غیرمعتبر درنظر گرفته شده و حذف شود.
طراحی یک تامین کنندهی کوکیهای امن
پس از آشنایی با مقدمات کوکیها و همچنین «بررسی تغییرات رمزنگاری اطلاعات در NET Core.»، اکنون میتوان یک تامین کنندهی کوکیهای رمزنگاری شده را برای ASP.NET Core به نحو ذیل طراحی کرد:
public interface ISecureCookiesProvider { void Add(HttpContext context, string token, string value); bool Contains(HttpContext context, string token); string GetValue(HttpContext context, string token); void Remove(HttpContext context, string token); } public class SecureCookiesProvider : ISecureCookiesProvider { private readonly IProtectionProvider _protectionProvider; public SecureCookiesProvider(IProtectionProvider protectionProvider) { _protectionProvider = protectionProvider; } public void Add(HttpContext context, string token, string value) { value = _protectionProvider.Encrypt(value); context.Response.Cookies.Append(token, value, getCookieOptions(context)); } public bool Contains(HttpContext context, string token) { return context.Request.Cookies.ContainsKey(token); } public string GetValue(HttpContext context, string token) { string cookieValue; if (!context.Request.Cookies.TryGetValue(token, out cookieValue)) { return null; } return _protectionProvider.Decrypt(cookieValue); } public void Remove(HttpContext context, string token) { if (context.Request.Cookies.ContainsKey(token)) { context.Response.Cookies.Delete(token); } } /// <summary> /// Expires at the end of the browser's session. /// </summary> private CookieOptions getCookieOptions(HttpContext context) { return new CookieOptions { HttpOnly = true, Path = context.Request.PathBase.HasValue ? context.Request.PathBase.ToString() : "/", Secure = context.Request.IsHttps }; } }
- در این تامین کنندهی کوکیهای امن، IProtectionProvider تزریقی به سازندهی کلاس را در مطلب «تغییرات رمزنگاری اطلاعات در NET Core.» پیشتر ملاحظه کردهاید.
- در اینجا برای ثبت سرویس جدید، تنظیمات ابتدایی برنامه چنین شکلی را پیدا میکنند و پس از آن میتوان سرویس ISecureCookiesProvider را به کنترلرهای برنامه تزریق و استفاده کرد:
public class Startup { public void ConfigureServices(IServiceCollection services) { services.TryAddSingleton<IProtectionProvider, ProtectionProvider>(); services.TryAddSingleton<ISecureCookiesProvider, SecureCookiesProvider>();