كيفية العمل مع امتدادات JavaScript في .NET

يتضمن Aspose.PDF FOSS for .NET تطبيقات من جانب الخادم لدوال PDF JavaScript 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.

دليل خطوة بخطوة

الخطوة 1: تثبيت الحزمة

أضف Aspose.PDF FOSS إلى مشروعك:

dotnet add package Aspose.Pdf.Foss --version 0.1.0-alpha

الخطوة 2: استيراد الفئات المطلوبة

using Aspose.Pdf.Annotations.JavascriptExtensions;

الخطوة 3: تنسيق قيمة حقل التاريخ/الوقت

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، تُعيد الطريقة سلسلة فارغة.

الخطوة 4: تنسيق حقل رقمي كعملة

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 - صحيح لوضع الرمز قبل الرقم
fieldValue - السلسلة الرقمية الخام للتنسيق

الخطوة 5: تنسيق حقل رقمي كنسبة مئوية

FieldNumberPercentFormatter.Format(precision, sepStyle, isPrependPercent, fieldValue) ينسق سلسلة رقمية كنسبة مئوية، مضاعفًا القيمة الأولية بـ 100 أولاً. يتطابق هذا مع دالة 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 - السلسلة الرقمية الخام (المُنسق يضربها في 100)

المشكلات الشائعة والحلول

FieldDateTimeFormatter يُعيد سلسلة فارغة
يحدث هذا عندما لا يمكن تحليل الوسيط dateValue بنمط التاريخ في dateFormat. رموز تاريخ Acrobat تختلف عن سلاسل تنسيق .NET DateTime.

FieldNumberCurrencyFormatter ينتج فاصل عشري خاطئ المُعامل sepStyle يتحكم في فاصل الآلاف. لاستخدام نقطة كفاصل للآلاف، مرّر sepStyle: 1.

إخراج FieldNumberPercentFormatter أكبر بـ 100 مرة
المُنسق يضرب القيمة المدخلة في 100. إذا كان fieldValue الخاص بك يمثل بالفعل نسبة مئوية (مثلاً، “87.5” بدلاً من “0.875”)، فقم بالقسمة على 100 قبل استدعاء Format.

المساحة الاسمية غير موجودة بعد تثبيت الحزمة
تأكد من أنك تستهدف net8.0 أو أحدث. مساحة الاسم JavascriptExtensions متاحة فقط في حزمة Aspose.Pdf.Foss.

NullReferenceException عند قيمة حقل فارغة
تمرير 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 يضاعف الإدخال بـ 100 ويضيف أو يسبق رمز النسبة المئوية.

هل هناك طريقة لسلسلة عدة مُنسّقات؟

لا يتم توفير السلسلة المدمجة. قم بتطبيق المُنسّقات تسلسليًا في الشيفرة.

هل أحتاج إلى مستند PDF كامل لاستخدام هذه الفئات؟

لا. تقوم المُنسّقات بالعمل على سلاسل نصية عادية وتعيد سلاسل نصية مُنسّقة. لا تحتاج إلى مثيل مفتوح Document.