العمل مع الحقول

العمل مع الحقول

حقل Word – DATE, IF, DATABASE, REF، وعشرات أخرى – يُمثَّل في Aspose.Words FOSS for .NET من قبل Field الفئة وفروعها، جميعها في Aspose.Words.Fields النطاق. تغطي هذه الصفحة محرك الحقول الأساسي: الـ Field نموذج الكائن نفسه، كيفية جمع الحقول وتحديثها، وواجهات الاستدعاء التي تتيح لك إدراج بيانات وسلوك مخصصين أثناء تحديث الحقل. عائلات الحقول المحددة – الروابط التشعبية والإشارات المتقاطعة، حقول التاريخ/الوقت، حقول الدمج البريدي، حقول الفهرس وفهرس المحتويات – لكل منها صفحة دليل مطور مخصصة.

نموذج كائن الحقل

كل حقل في مستند هو مثال Field يتألف من ثلاث عقد علامات – FieldStart، Separator، وFieldEnd – تُعرَض كخصائص Field.Start، Field.Separator، وField.End. Field.Type يحدد أي FieldType يمثل الحقل، Field.Result وField.DisplayResult تُظهر القيمة المحسوبة الأخيرة، وField.Format تحتفظ بأي مفاتيح (مثل سلاسل تنسيق رقمية أو تاريخ/وقت) المرفقة بشيفرة الحقل. Field.IsLocked وField.IsDirty تُبلغ عن حالة القفل والقديمة للحقول. استدعِ Field.GetFieldCode() لقراءة نص شيفرة الحقل الخام، Field.Update() لإعادة حساب النتيجة، Field.Unlink() لاستبدال الحقل بنص ثابت، وField.Remove() لحذفها بالكامل.

الوصول إلى الحقول وتحديثها في مستند

Document.Range.Fields تُعيد FieldCollection – الحقول الموجودة في ذلك النطاق، مع Count، Remove()، RemoveAt()، وClear() لإزالة جماعية. Range.UpdateFields() تُعيد حساب كل حقل في النطاق، Range.UnlinkFields() تُحوِّل كل حقل في النطاق إلى نص ثابت، وRange.NormalizeFieldTypes() تُطابق رمز نوع الحقل المخزن مع رمز الحقل الفعلي بعد التعديلات اليدوية. DocumentBuilder.InsertField() تُدرج حقلًا جديدًا عند المؤشر، مع تحميلات إضافية إما لتحديث نتيجة الحقل الجديد فورًا أو تركها لتمرير Range.UpdateFields() لاحق.

خيارات تحديث الحقل والثقافة

Document.FieldOptions هو كائن FieldOptions يتحكم في سلوك حقول المستند بالكامل عند التحديث: CurrentUser يزوّد UserInformation المستخدمة من قبل حقول الهوية، DefaultDocumentAuthor يزرع النتائج المتعلقة بالمؤلف، LegacyNumberFormat وUseInvariantCultureNumberFormat يتحكمان في تنسيق الأرقام، وPreProcessCulture وFieldUpdateCultureSource (مقترنين مع رد النداء IFieldUpdateCultureProvider) يحددان أي ثقافة تتحكم في تنسيق التاريخ والرقم أثناء التحديث. TemplateName وFileName وBuiltInTemplatesPaths يزودون القيم التي تقرأها الحقول الواعية بالقالب واسم الملف.

تتبع وتخصيص تحديثات الحقول

نفّذ IFieldUpdatingCallback (FieldUpdating وFieldUpdated) على FieldOptions لتشغيل الشيفرة فورًا قبل وبعد كل إعادة حساب لحقل — مفيد لتدقيق أي حقول تغيرت في وظيفة دفعة. نفّذ IFieldUpdatingProgressCallback (Notify) لتتبع التقدم الإجمالي عبر مستند كبير؛ يتلقى FieldUpdatingProgressArgs يحتوي على TotalFieldsCount وUpdatedFieldsCount وUpdateCompleted. لتغيير طريقة عرض نتيجة حقل رقمية أو عامة كنص، نفّذ IFieldResultFormatter (Format(value, format) وFormatNumeric(value, format)) وعيّنها إلى FieldOptions.ResultFormatter.

تزويد الحقول ببيانات خارجية

حقل DATABASE يقرأ صفوفه عبر IFieldDatabaseProvider.GetQueryResult()، الذي يُعيد FieldDatabaseDataTable (ColumnNames، Rows) مُنشأ من كائنات FieldDatabaseDataRow (Values) — عيّن تنفيذك إلى FieldOptions.FieldDatabaseProvider. حقول المقارنة مثل IF تُقيّم شرطها عبر IComparisonExpressionEvaluator.Evaluate()، الذي يتلقى ComparisonExpression (LeftExpression، ComparisonOperator، RightExpression) ويُعيد ComparisonEvaluationResult (Result، ErrorMessage)؛ عيّن مقيمًا مخصصًا إلى FieldOptions.ComparisonExpressionEvaluator لتجاوز منطق المقارنة الافتراضي. الحقول التي عادةً ما تُطالب المستخدم بإدخال أثناء التحديث — مثل ASK وFILLIN — تستدعي IFieldUserPromptRespondent.Respond() عندما يُعيّن أحدها إلى FieldOptions.UserPromptRespondent، حتى لا يتوقف التحديث غير المُراقب في انتظار إدخال تفاعلي.

هوية المستخدم والمستند للحقول

UserInformation (Name، Initials، Address، وUserInformation.DefaultUser الثابت) يزوّد الهوية التي تقرأ منها الحقول المتعلقة باسم المؤلف أو المستخدم. عيّن كائنًا إلى Document.FieldOptions.CurrentUser قبل تحديث الحقول التي تعتمد على هوية مؤلف المستند أو هوية المستخدم.

نصائح وأفضل الممارسات

• Aspose.Words FOSS لا يعيد حساب الحقول تلقائيًا عند التحميل أو الحفظ كما يفعل Word – استدعِ Range.UpdateFields() (أو Field.Update() لحقل واحد) صراحةً بعد أي تعديل برمجي يجب أن ينعكس في نتائج الحقل.
• FieldStart، Separator، وFieldEnd هي عقد حقيقية في شجرة المستند؛ احذف حقلًا عبر Field.Remove() أو Field.Unlink() بدلاً من حذف عقد العلامة مباشرة، وإلا قد تصبح بنية الحقل غير متسقة.
• الحقول التي تعتمد نتيجتها على تخطيط الصفحة – PAGE، NUMPAGES، وإدخالات أرقام صفحات الفهرس – تُقيم إلى عنصر نائب 0، لأن هذا الإصدار لا يتضمن محرك تخطيط/عرض الصفحات.
• سجِّل IFieldUpdatingCallback قبل تشغيل Range.UpdateFields() على مستند كبير أو غير مألوف إذا كنت بحاجة إلى تسجيل أو تدقيق الحقول التي تغيرت بالضبط.
• عيّن FieldOptions.UserPromptRespondent (أو قدِّم قيم DefaultResponse على فئات الحقول التي تعتمد على المطالبة الفردية) قبل تحديث مستند في خط أنابيب غير مراقب، حتى لا تتوقف حقول ASK/FILLIN في انتظار إدخال تفاعلي.

مشكلات شائعة

FAQ

هل 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.

ملخص API Reference

انظر أيضاً

• Aspose.Words for .NET — Enterprise Documentation