این راهنمای سمت کاربر دو روش برای تبدیل جدول به DataTable در ASP.NET را پوشش می‌دهد: افزودن قابلیت‌های جست‌وجو و مرتب‌سازی به یک جدول HTML استاندارد، یا ساخت جدول با تگ اختصاصی <datatable>. مثال‌ها از داده‌های عمومی محصول استفاده می‌کنند؛ نام propertyها و روش دریافت داده را با پروژهٔ خود هماهنگ کنید.
۱. انتخاب روش ساخت جدول
اگر جدول HTML از قبل وجود دارد، برای سازگاری ساختار درست <thead>، <tbody> و تعداد یکسان ستون‌ها در سرآیند و ردیف‌ها را بررسی کنید. این ساختار با راهنمای رسمی نصب DataTables هم‌خوان است.
<table id="productTable">
<thead>
<tr>
<th>کد کالا</th>
<th>نام کالا</th>
<th>تعداد</th>
</tr>
</thead>
<tbody>
<tr>
<td>101</td>
<td>نمونه کالا</td>
<td>4</td>
</tr>
</tbody>
</table>
اگر می‌خواهید ستون‌ها را با قالب مخصوص کتابخانهٔ خورشید تعریف کنید، از <datatable> و <column> استفاده کنید. کتابخانه این ساختار را به جدول HTML تبدیل می‌کند:
<datatable>
<column header="کد کالا">[ProductId]</column>
<column header="نام کالا">[ProductName]</column>
<column header="تعداد">[Quantity]</column>
</datatable>
نام متغیرهای داخل براکت باید دقیقاً با نام property در دادهٔ JSON یکی باشد. برای نمونه، [ProductName] از propertyای به نام ProductName مقدار می‌گیرد.
۲. بارگذاری فایل‌های لازم
در ساختار فعلی پروژه، راه‌انداز کتابخانه می‌تواند ماژول جدول و وابستگی‌های آن را یکجا بارگذاری کند. برای بارگذاری ماژول جدول، این نشانی را در صفحه قرار دهید:
<script src="https://khorshidneshan.ir/CDN/Libraries/KhorshidCo.min.js?only&table"></script>
از افزودن دوبارهٔ فایل‌های CSS و JavaScript همان ماژول خودداری کنید تا فایل‌های تکراری با یکدیگر تداخل نکنند. اگر نسخهٔ منتشرشدهٔ سایت با فایل‌های فعلی پروژه تفاوت دارد، نشانی فایل را پیش از استفاده بررسی کنید.
۳. اتصال دادهٔ JSON
در ساختار اختصاصی <datatable>، مقدار ستون‌ها از JSON خوانده می‌شود. راه‌انداز جدول نشانی فایل را با توجه به صفحه و شناسهٔ جدول از کوکی مرتبط بازیابی می‌کند؛ سمت سرور باید کوکی و نشانی JSON متناظر را برای همان صفحه و جدول آماده کند. شناسهٔ جدول را یکتا نگه دارید، به‌خصوص وقتی یک صفحه چند جدول دارد.
برای ساخت JSON در ASP.NET Web Forms، قالب داده و نمونهٔ endpoint را در راهنمای سمت سرور دیتاتیبل خورشید ببینید. داده‌های قابل‌شناسایی مشتری یا اطلاعات مالی را در پاسخ JSON عمومی قرار ندهید؛ اگر داده خصوصی است، دسترسی را در سرور محدود کنید.
۴. تنظیم ستون‌ها و نمایش مقادیر
ویژگی‌های جدول برای قالب‌بندی یا کنترل نمایش ستون به کار می‌روند. این نمونه از نام کالا، تعداد و مبلغ محصول استفاده می‌کند:
<datatable>
<column header="نام کالا">[ProductName]</column>
<column header="تعداد" money>[Quantity]</column>
<column header="جمع مبلغ (ریال)" money hassum>[TotalPrice]</column>
<column header="وضعیت">
<span display="[IsActive]">فعال</span>
<span display="![IsActive]">غیرفعال</span>
</column>
<column header="موجود است؟">
<input type="checkbox" disabled="disabled" checked="[IsAvailable]" />
</column>
</datatable>
money عدد را با جداکنندهٔ هزارگان نمایش می‌دهد.hassum جمع مقادیر عددی آن ستون را در انتهای جدول نمایش می‌دهد.display یک عنصر درون ستون را بر اساس مقدار بولی نشان می‌دهد یا پنهان می‌کند.checked وضعیت چک‌باکس را بر پایهٔ مقدار بولی داده مشخص می‌کند.
پنهان‌کردن ستون یا کنترل نمایش در مرورگر، محدودیت دسترسی ایجاد نمی‌کند. اطلاعاتی را که کاربر مجاز به دیدن آن نیست از JSON حذف کنید.
۵. دکمه‌های عملیات و HiddenField
در ستون عملیات می‌توان کنترل‌های ASP.NET مانند ImageButton را قرار داد. هنگام اجرای عملیات، کتابخانه شناسهٔ ردیف را در HiddenField با شناسهٔ hfItemId می‌گذارد تا رویداد سمت سرور بتواند ردیف موردنظر را پیدا کند.
<asp:HiddenField ID="hfItemId" ClientIDMode="Static" runat="server" />
<datatable>
<column header="نام کالا">[ProductName]</column>
<column header="عملیات" noinoutput>
<asp:ImageButton runat="server" ImageUrl="~/AddOn/Icons/edit.png"
AlternateText="ویرایش" OnClick="_btnEdit_OnClick" />
</column>
</datatable>
hfItemId برای شناسهٔ ردیف عملیات است. برای نگهداری مقادیر تغییرکردهٔ ورودی‌ها از hfTableData استفاده می‌شود؛ این دو فیلد کاربرد یکسان ندارند. مقادیر ارسالی از مرورگر را در سرور اعتبارسنجی کنید و پیش از ویرایش یا حذف، مجوز کاربر برای همان ردیف را بررسی کنید.
۶. تنظیم خروجی و ستون‌های غیرقابل‌خروجی
ویژگی noinoutput برای حذف ستون‌هایی مانند دکمه‌های عملیات از خروجی Excel و PDF کاربرد دارد. پیش از فعال‌کردن خروجی، ستون‌های لازم را مشخص کنید. این گزینه جایگزین کنترل دسترسی نیست و نباید برای محافظت از دادهٔ حساس به آن تکیه کرد.
عیب‌یابی
- اگر سرآیند یا ردیف‌ها درست نمایش داده نمی‌شوند، وجود
<thead> و <tbody> و تعداد برابر ستون‌ها را کنترل کنید.
- اگر سلول‌های
<datatable> خالی هستند، نام property در JSON و عبارت داخل براکت را مقایسه کنید.
- اگر منبع JSON بارگذاری نمی‌شود، شناسهٔ جدول، کوکی متناظر، مسیر endpoint و مجوز دسترسی را بررسی کنید.
- اگر استایل یا دکمه‌ها تکراری‌اند، فایل‌های کتابخانه را فقط از یک روش بارگذاری کنید.
برای ساخت JSON و اتصال داده در سمت سرور، آموزش دیتاتیبل اختصاصی خورشید در ASP.NET را ادامه دهید.