آموزش دیتاتیبل (DataTable) اختصاصی خورشید در ASP.NET

این راهنما روش کار با کتابخانهٔ جدولی اختصاصی خورشید در پروژه‌های ASP.NET Web Forms را توضیح می‌دهد: تعریف ستون‌ها، اتصال داده‌های JSON، نمایش وضعیت‌ها، ثبت ویرایش‌های جدول و تهیهٔ خروجی Excel یا PDF. مثال‌ها الگو هستند؛ نام مدل‌ها و روش دسترسی به داده را با پروژهٔ خود هماهنگ کنید.

اگر هدفتان تبدیل جدول HTML موجود به DataTable در سمت کاربر است، آموزش تبدیل جدول HTML به DataTable در ASP.NET را هم ببینید.

۱. افزودن کتابخانهٔ خورشید

در صفحهٔ ASP.NET Web Forms، فایل فشردهٔ کتابخانه را با نشانی فعلی زیر وارد کنید. نشانی قدیمیِ ‎/CDN/Scripts/KhorshidCo.min.js‎ در زمان بررسی پاسخ ۴۰۴ می‌داد؛ مسیر فایل موجود در پروژه ‎/CDN/Libraries/‎ است.

<script src="https://khorshidneshan.ir/CDN/Libraries/KhorshidCo.min.js"></script>

برای استفاده از فایل‌های کتابخانه در پروژهٔ خود، دسترس‌پذیری نشانی و نسخهٔ منتشرشده را هنگام پیاده‌سازی بررسی کنید.

۲. تعریف جدول و نگاشت ستون‌ها

تگ <datatable> جدول را معرفی می‌کند و هر تگ <column> یک ستون می‌سازد. متن داخل براکت، مانند [ProductName]، باید با نام property موجود در دادهٔ JSON یکسان باشد.

<datatable>
  <column header="کد کالا">[ProductId]</column>
  <column header="نام کالا">[ProductName]</column>
  <column header="تعداد">[Quantity]</column>
</datatable>

در ASP.NET Web Forms، برای نگهداری مقادیر ویرایش‌شدهٔ جدول از HiddenField استفاده می‌شود. این فیلد به‌تنهایی محل امنی برای اعتماد به دادهٔ کاربر نیست؛ مقادیر دریافت‌شده را در سرور اعتبارسنجی و مجوز تغییر را بررسی کنید.

<asp:HiddenField ID="hfTableData" ClientIDMode="Static" runat="server" />

۳. ساخت دادهٔ JSON در سمت سرور

کلاس JsonUtility دادهٔ انتخاب‌شده را به JSON تبدیل می‌کند. در پیاده‌سازی این کلاس، وابستگی‌هایی مانند Newtonsoft.Json را مطابق پروژه اضافه کنید. نام فیلدهایی که به JSON می‌فرستید باید با متغیرهای ستون‌ها تطبیق داشته باشد.

protected void Page_Load(object sender, EventArgs e)
{
    BindGrid();
}

private void BindGrid()
{
    var rows = LoadProducts(); // روش دریافت داده را با پروژهٔ خود جایگزین کنید.
    new JsonUtility().CreateJsonFile(rows, item => new
    {
        item.Id,
        item.Name,
        item.Quantity
    });
}

۴. خواندن فایل JSON در Data.aspx

نمونهٔ زیر فقط نام فایل‌هایی را می‌پذیرد که از حروف انگلیسی، عدد، خط تیره و زیرخط تشکیل شده‌اند. مقدار ورودی را مستقیماً به مسیر فایل اضافه نکنید. مستندات Microsoft دربارهٔ Path.GetFileName نیز توضیح می‌دهد که نام فایل دریافتی از ورودی می‌تواند شامل مسیر باشد.

// using System.IO;
// using System.Text.RegularExpressions;

Response.Clear();
Response.ContentType = "application/json; charset=utf-8";
string fileName = Request.QueryString["f"];

if (string.IsNullOrWhiteSpace(fileName) ||
    !Regex.IsMatch(fileName, @"\A[A-Za-z0-9_-]{1,80}\z"))
{
    Response.StatusCode = 400;
    Response.Write("[]");
    Response.End();
    return;
}

string filePath = Server.MapPath("~/Upload/Jsons/" + fileName + ".json");
if (!File.Exists(filePath))
{
    Response.StatusCode = 404;
    Response.Write("[]");
    Response.End();
    return;
}

string jsonData = File.ReadAllText(filePath);
Response.Write(jsonData);
Response.End();

نکتهٔ دسترسی: اگر فایل‌های JSON در پوشهٔ عمومی سایت قرار می‌گیرند، دسترسی مستقیم به آن‌ها را نیز محدود کنید. برای داده‌های مشتری، اطلاعات هویتی یا مالی را در JSON عمومی قرار ندهید و احراز هویت و مجوز دسترسی را در سمت سرور اعمال کنید.

۵. گزینه‌های کاربردی ستون‌ها

• money: نمایش عدد با جداکنندهٔ هزارگان؛ برای نمونه، مبلغ ستون Price خواناتر می‌شود.
• hassum: محاسبه و نمایش جمع مقادیر عددی ستون در پایین جدول.
• display: نمایش یا پنهان‌کردن یک عنصر درون ستون بر اساس مقدار بولی، مانند وضعیت فعال‌بودن.
• visible: نمایش یا پنهان‌کردن ستون بر اساس مقدار بولی.
• checked: نمایش وضعیت چک‌باکس بر پایهٔ مقدار بولی داده.
• noinoutput: کنارگذاشتن ستون از فایل‌های خروجی Excel و PDF.

<datatable>
  <column header="مبلغ (ریال)" money hassum>[TotalPrice]</column>
  <column header="وضعیت">
    <asp:ImageButton runat="server" ImageUrl="~/AddOn/Icons/active.png"
      display="[IsActive]" AlternateText="فعال" />
    <asp:ImageButton runat="server" ImageUrl="~/AddOn/Icons/inactive.png"
      display="![IsActive]" AlternateText="غیرفعال" />
  </column>
  <column header="پرداخت‌شده؟">
    <input type="checkbox" disabled="disabled" checked="[IsPaid]" />
  </column>
</datatable>

ویژگی‌های نمایشی و مخفی‌سازی ستون، کنترل دسترسی محسوب نمی‌شوند. داده‌ای را که کاربر نباید ببیند از پاسخ JSON حذف کنید؛ پنهان‌کردن آن در رابط یا خروجی‌گیری به‌تنهایی کافی نیست.

۶. دریافت تغییرات فیلدهای جدول

برای ورودی‌های قابل ویرایش، شناسه را با الگوی «نام فیلد_شناسه ردیف» تعریف کنید؛ برای نمونه txtScore_1465. کتابخانه مقادیر تغییرکرده را در hfTableData جمع می‌کند تا فرم آن‌ها را به سرور بفرستد. سرور باید مقدار، نوع داده، شناسهٔ ردیف و مجوز کاربر را دوباره بررسی کند.

۷. ساخت چند جدول در یک صفحه

برای هر جدول یک شناسهٔ یکتا تعیین کنید و همان شناسه را هنگام تولید JSON به CreateJsonFile بدهید. به این ترتیب دادهٔ دو جدول با هم اشتباه نمی‌شود.

<datatable id="_dtProductDetail">
  <column header="کد کالا">[ProductId]</column>
  <column header="نام کالا">[ProductName]</column>
  <column header="تعداد">[Amount]</column>
  <column header="فی" money>[Price]</column>
  <column header="کل" money hassum>[TotalPrice]</column>
</datatable>

private void BindOrderProducts(List<TbOrderProduct> result)
{
    new JsonUtility().CreateJsonFile(result, item => new
    {
        item.Id,
        item.ProductId,
        ProductName = item.TbProduct.Name,
        item.Amount,
        item.Price,
        item.TotalPrice
    }, "_dtProductDetail");
}

۸. خروجی Excel و PDF

برای ستون‌هایی مانند دکمهٔ ویرایش و حذف، ویژگی noinoutput را قرار دهید تا این ستون‌ها در خروجی گزارش نیایند. پیش از ساخت خروجی، داده‌های حساس را از دادهٔ ورودی حذف کنید؛ تنظیم خروجی جایگزین کنترل دسترسی نیست.

عیب‌یابی کوتاه

• اگر خانه‌ها خالی‌اند، یکسان‌بودن نام property در JSON و عبارت داخل براکت را بررسی کنید.
• اگر جدول دوم دادهٔ اشتباه می‌گیرد، یکتابودن شناسهٔ datatable و شناسهٔ ارسالی به CreateJsonFile را بررسی کنید.
• اگر JSON بارگذاری نمی‌شود، مسیر فایل، پاسخ شبکه و مجوز دسترسی به Data.aspx را بررسی کنید.

برای پیاده‌سازی سمت کاربر و تبدیل جدول‌های موجود، مطلب تبدیل جدول HTML به DataTable را بخوانید.