كيفية العمل مع الحقول في .NET
يوضح هذا الدليل كيفية العمل مع حقول Word — DATE، IF، REF، DATABASE، وعشرات أخرى — في Aspose.Words FOSS لـ .NET: إدراج حقل وقراءة نتيجته، تحديث الحقول بعد تعديل برمجي، تكوين سلوك التحديث، تتبع التحديثات عبر رد اتصال، وتحويل أو إزالة الحقل. Aspose.Words FOSS لـ .NET متاح عبر NuGet أو عن طريق بناءه من المصدر.
دليل خطوة بخطوة
الخطوة 1: احصل على المكتبة
استنساخ المستودع وبنائه Aspose.Words.sln في تكوين Release، ثم أضف إشارة مشروع إلى Aspose.Words.csproj من مشروع .NET الخاص بك، كما هو موضح في الـ دليل التثبيت. أضف using Aspose.Words; and using Aspose.Words.Fields; في أعلى أي ملف يتعامل مع الحقول.
الخطوة 2: إدراج حقل وقراءة نتيجته
DocumentBuilder.InsertField() يدرج حقلًا جديدًا عند المؤشر، مع تحميلات إما تُحدّث نتيجة الحقل فورًا أو تتركها لتمرير تحديث لاحق. كل حقل هو كائن Field مكوّن من ثلاث عقد علامات — FieldStart، Separator، وFieldEnd، تُعرض كـ Field.Start / Field.Separator / Field.End. Field.Type يحدد أي FieldType يمثل، Field.Result وField.DisplayResult يحتفظان بالقيمة المحسوبة الأخيرة، Field.Format يحتفظ بأي مفاتيح تنسيق مرفقة بالشيفرة، وField.GetFieldCode() يُعيد نص شفرة الحقل الخام.
الخطوة 3: تحديث الحقول بعد تعديل برمجي
Aspose.Words لا تقوم FOSS بإعادة حساب الحقول عند تحميل المستند أو حفظه. بعد تعديل يجب أن يغيّر نتيجة حقل ما، استدعِ Range.UpdateFields() لإعادة حساب كل حقل في ذلك النطاق — استخدم Document.Range.UpdateFields() للمستند بأكمله — أو Field.Update() لحقل واحد. Range.UnlinkFields() يحول كل حقل في النطاق إلى نص ثابت في استدعاء واحد، وRange.NormalizeFieldTypes() يطابق رمز نوع الحقل المخزن مع رمز الحقل الفعلي بعد تعديل يدوي.
الخطوة 4: تكوين سلوك تحديث الحقل باستخدام FieldOptions
Document.FieldOptions (مثيل FieldOptions) يتحكم في كيفية سلوك حقول المستند بالكامل أثناء التحديث: CurrentUser (مثيل UserInformation — Name، Initials، Address) يوفر الهوية التي تقرأ منها الحقول المرتبطة باسم المؤلف أو المستخدم، DefaultDocumentAuthor يزرع نتائج متعلقة بالمؤلف، وLegacyNumberFormat / UseInvariantCultureNumberFormat / PreProcessCulture / FieldUpdateCultureSource تتحكم في تنسيق الأرقام والتواريخ. للخطوط غير المراقبة، عيّن FieldOptions.UserPromptRespondent (وهو IFieldUserPromptRespondent) بحيث لا تحجب الحقول المدفوعة بالمطالبات مثل ASK وFILLIN انتظار الإدخال التفاعلي، واعطِ IFieldDatabaseProvider مخصصًا إلى FieldOptions.FieldDatabaseProvider لتزويد صفوف حقل DATABASE من مصدر البيانات الخاص بك بدلاً من اتصال قاعدة بيانات حقيقي.
الخطوة 5: تتبع تحديثات الحقول باستخدام رد نداء
طبّق IFieldUpdatingCallback (FieldUpdating وFieldUpdated) وعينه إلى FieldOptions لتشغيل الشيفرة مباشرةً قبل وبعد إعادة حساب كل حقل — مفيد لتدقيق أي الحقول تغيرت بالضبط في مهمة دفعة. لتقارير التقدم عبر مستند كبير، طبّق IFieldUpdatingProgressCallback (Notify)، الذي يتلقى FieldUpdatingProgressArgs يكشف عن TotalFieldsCount، UpdatedFieldsCount، وUpdateCompleted.
الخطوة 6: تحويل أو إزالة حقل
Field.Unlink() يستبدل الحقل بنتيجته المحسوبة الأخيرة كنص ثابت عادي، متجاهلاً شفرة الحقل الأساسية — استخدمه عندما تريد أن تكون القيمة مدمجة في المستند بشكل دائم. Field.Remove() يحذف العقد FieldStart وSeparator وFieldEnd مع شفرة الحقل ونتيجته، مما يزيل الحقل تمامًا. يفضَّل استخدام هاتين الطريقتين على حذف عقد العلامة مباشرةً، لأن إزالة جزء فقط من بنية الحقل يدويًا قد تترك شجرة المستند غير متناسقة.
المشكلات الشائعة والحلول
تصبح النتيجة المعروضة للحقل قديمة بعد تحرير المستند. Aspose.Words FOSS لا يقوم بتحديث الحقول تلقائيًا عند التحميل أو الحفظ. استدعِ Range.UpdateFields() or Field.Update() بشكل صريح بعد التعديل.
PAGE, NUMPAGES, أو رقم صفحة جدول المحتويات يُظهر دائمًا 0. Page-layout/rendering ليس جزءًا من هذه النسخة، لذا الحقول التي تعتمد نتيجتها على التقسيم إلى صفحات تُقَيَّم كعنصر نائب 0. هذا سلوك متوقع في هذه النسخة.
يبدو أن تحديث مجموعة الحقول يتعطل. حقل مدفوع بالمطالبة (ASK, FILLIN) ليس لديه IFieldUserPromptRespondent مُعيَّن. عيّن FieldOptions.UserPromptRespondent، أو اضبط DefaultResponse على نسخة الحقل الفردية.
الـ DATABASE الحقل لا ينتج أي صفوف. لا IFieldDatabaseProvider مُعيَّن إلى FieldOptions.FieldDatabaseProvider. نفّذ الواجهة وعيّنها قبل الاستدعاء Range.UpdateFields().
الأسئلة المتكررة
هل يقوم Aspose.Words FOSS بتقييم كل نوع حقل في Word؟
نموذج الكائن Field يمثل كل قيمة FieldType ويحدّث معظمها، لكن الحقول التي تعتمد نتيجتها على تخطيط الصفحة — مثل PAGE وNUMPAGES — تُقيّم إلى عنصر نائب 0 لأن هذه النسخة لا تتضمن محرك التخطيط/العرض.
كيف يمكنني إعادة تقييم الحقول بعد تعديل برمجي؟
استدعِ Range.UpdateFields() على النطاق الذي يغطي المحتوى المعدل، أو Document.Range.UpdateFields() للوثيقة بأكملها.
هل يمكنني تحويل حقل إلى نص عادي ثابت؟
نعم — Field.Unlink() يستبدل الحقل بنتيجته المُحتسبة آخرًا كنص عادي.
كيف يمكنني إزالة حقل بالكامل، بما في ذلك نتيجته؟
استدعِ Field.Remove(). يحذف العقد FieldStart وSeparator وFieldEnd مع كود الحقل ومحتوى النتيجة.
كيف يمكنني تزويد الحقل DATABASE ببيانات مخصصة؟
نفّذ IFieldDatabaseProvider وعيّنها إلى Document.FieldOptions.FieldDatabaseProvider. تُعيد تنفيذتها GetQueryResult() كائن FieldDatabaseDataTable مبني من مثيلات FieldDatabaseDataRow.
