نحوه کار با افزونههای JavaScript در .NET
Aspose.PDF FOSS for .NET شامل پیادهسازیهای سمت سرور توابع JavaScript PDF AF_Date_Format، AF_Number_Format و AF_Percent_Format از طریق کلاسهای FieldDateTimeFormatter، FieldNumberCurrencyFormatter و FieldNumberPercentFormatter میباشد. بسته را با dotnet add package Aspose.Pdf.Foss --version 0.1.0-alpha نصب کنید و از این کلاسها برای قالببندی مقادیر فیلد AcroForm در سرور بدون نیاز به موتور JavaScript استفاده کنید.
راهنمای گامبهگام
مرحله ۱: نصب بسته
Aspose.PDF FOSS را به پروژه خود اضافه کنید:
dotnet add package Aspose.Pdf.Foss --version 0.1.0-alphaمرحله ۲: وارد کردن کلاسهای مورد نیاز
using Aspose.Pdf.Annotations.JavascriptExtensions;مرحله ۳: قالببندی مقدار فیلد تاریخ/زمان
FieldDateTimeFormatter.Format(dateFormat, dateValue) یک رشته تاریخ خام را بر اساس الگوی فرمت تاریخ به سبک Acrobat تبدیل میکند. این متناظر با تابع PDF JavaScript AF_Date_Format است.
string formatted = FieldDateTimeFormatter.Format("mm/dd/yyyy", "2026-06-11");پارامتر dateFormat از توکنهای قالب تاریخ Acrobat استفاده میکند (به عنوان مثال mm، dd، yyyy، HH، MM). وقتی ورودی dateValue قابل تجزیه نیست، متد یک رشته خالی برمیگرداند.
مرحله ۴: قالببندی یک فیلد عددی به صورت ارز
FieldNumberCurrencyFormatter.Format(precision, sepStyle, negStyle, currencySymbol, isPrependCurrency, fieldValue) یک رشته عددی را به عنوان مقدار ارز قالببندی میکند. این متناظر با تابع PDF JavaScript AF_Number_Format است.
var currencyFormatter = new FieldNumberCurrencyFormatter();
string formatted = currencyFormatter.Format(
precision: 2,
sepStyle: 0,
negStyle: 0,
currencySymbol: "$",
isPrependCurrency: true,
fieldValue: "1234.5");پارامترها:
precision- تعداد ارقام اعشارsepStyle- سبک جداکننده هزارگان (0 = کاما، 1 = نقطه، 2 = بدون)negStyle- سبک عدد منفی (0 = پرانتز، 1 = پیشوند منفی)currencySymbol- رشته نماد ارزisPrependCurrency- true برای قرار دادن نماد قبل از عددfieldValue- رشته عددی خام برای قالببندی
مرحله 5: قالببندی یک فیلد عددی به صورت درصد
FieldNumberPercentFormatter.Format(precision, sepStyle, isPrependPercent, fieldValue) یک رشته عددی را به صورت درصد قالببندی میکند و ابتدا مقدار خام را در ۱۰۰ ضرب میکند. این متناظر با تابع PDF JavaScript AF_Percent_Format است.
var percentFormatter = new FieldNumberPercentFormatter();
string formatted = percentFormatter.Format(
precision: 1,
sepStyle: 0,
isPrependPercent: false,
fieldValue: "0.875");پارامترها:
precision- تعداد ارقام اعشار پس از نقطهٔ اعشارsepStyle- سبک جداکنندهٔ هزارگان (0 = کاما، 1 = نقطه، 2 = بدون)isPrependPercent- true برای افزودن پیشوند %، false برای افزودن پسوندfieldValue- رشتهٔ عددی خام (فرمتکننده آن را در ۱۰۰ ضرب میکند)
مشکلات رایج و راهحلها
FieldDateTimeFormatter مقدار رشته خالی را برمیگرداند
این زمانی رخ میدهد که آرگومان dateValue نتواند توسط الگوی تاریخ در dateFormat تجزیه شود. توکنهای تاریخ Acrobat با رشتههای قالببندی .NET DateTime متفاوت هستند.
FieldNumberCurrencyFormatter مقدار جداکننده اعشار را بهدرستی تولید نمیکند
پارامتر sepStyle جداکننده هزارگان را کنترل میکند. برای استفاده از نقطه بهعنوان جداکننده هزارگان، sepStyle: 1 را ارسال کنید.
FieldNumberPercentFormatter خروجی ۱۰۰ برابر بزرگ است
فرمتکننده مقدار ورودی را در ۱۰۰ ضرب میکند. اگر fieldValue شما قبلاً یک درصد را نشان میدهد (مثلاً “87.5” به جای “0.875”)، قبل از فراخوانی Format، مقدار را بر ۱۰۰ تقسیم کنید.
فضاینامی پس از نصب بسته یافت نشد
اطمینان حاصل کنید که هدفگذاری شما بر روی net8.0 یا نسخههای بعدی است. فضاینامی JavascriptExtensions فقط در بسته Aspose.Pdf.Foss موجود است.
NullReferenceException در مقدار خالی fieldValue
ارسال null یا یک رشته خالی به عنوان fieldValue باعث بروز استثنای تجزیه میشود. قبل از فراخوانی Format ورودی را اعتبارسنجی کنید.
سوالات متداول
عبارت «corresponds to AF_Date_Format» به چه معنی است؟
PDF AcroForm JavaScript از AF_Date_Format به عنوان تابع قالببندی داخلی برای فیلدهای تاریخ استفاده میکند. FieldDateTimeFormatter همان منطق قالببندی را در کد مدیریت شده .NET تکرار میکند تا بتوانید رشتههای قالببندی فیلد یکسان را بدون اجرای JavaScript اعمال کنید.
آیا میتوانم از این قالبکنندهها خارج از زمینه سند PDF استفاده کنم؟
بله. FieldDateTimeFormatter، FieldNumberCurrencyFormatter و FieldNumberPercentFormatter کلاسهای سادهای هستند که هیچ وابستگیای به یک نمونه Document ندارند. میتوانید از آنها در هر زمینه .NET 8+ به عنوان قالببندهای کمکی استفاده کنید.
تفاوت بین FieldNumberCurrencyFormatter و FieldNumberPercentFormatter چیست؟
FieldNumberCurrencyFormatter عدد را به عنوان مقدار پولی قالببندی میکند بدون ضرب. FieldNumberPercentFormatter ورودی را در ۱۰۰ ضرب میکند و نماد درصد را به انتها یا ابتدای آن اضافه میکند.
آیا راهی برای زنجیرهسازی چندین قالببند وجود دارد؟
هیچ زنجیرهسازی داخلی ارائه نشده است. قالببندها را بهصورت متوالی در کد اعمال کنید.
آیا برای استفاده از این کلاسها به سند PDF کامل نیاز دارم؟
نه. فرمتکنندهها بر روی رشتههای ساده کار میکنند و رشتههای قالببندیشده را برمیگردانند. آنها نیازی به یک نمونه باز Document ندارند.
