إنشاء الحقول باستخدام FieldBuilder
إنشاء الحقول باستخدام FieldBuilder
يوضح هذا الدليل كيفية إنشاء حقل Word من الصفر في Aspose.Words FOSS لـ .NET باستخدام FieldBuilder and FieldArgumentBuilder، بدلاً من العمل مع حقل موجود مسبقًا في المستند. للقراءة أو التحديث أو إزالة الحقول الموجودة، راجع الـ العمل مع الحقول الدليل.
إنشاء حقل باستخدام FieldBuilder
FieldBuilder يبني حقلًا من رموز كود الحقل — الوسائط والمفاتيح. أنشئ واحدًا باستخدام new FieldBuilder(fieldType)، مع تمرير FieldType للحقل الذي تريد بناؤه. أضف الوسائط باستخدام الطريقة المحملة الزائدة AddArgument(argument)، والتي تقبل string، int، double، FieldBuilder متداخل، أو FieldArgumentBuilder. أضف المفاتيح باستخدام الطرق المحملة الزائدة AddSwitch(switchName)، AddSwitch(switchName, switchArgument) (سلسلة)، أو AddSwitch(switchName, switchArgument) (int/double).
إدراج الحقل المُنشأ
بمجرد أن يحتوي FieldBuilder على وسائطه ومفاتيحه، استدعِ BuildAndInsert(refNode) لإدراجه في المستند — أحد التحميلات الزائدة يقبل عقدة Inline ويُدخل الحقل قبلها، وآخر يقبل Paragraph ويُدخل الحقل في نهاية تلك الفقرة.
تكوين وسائط معقدة باستخدام FieldArgumentBuilder
FieldArgumentBuilder يبني حجة حقل معقدة مكوّنة من حقول وعُقد ونص عادي، للحالات التي يحتاج فيها حجة واحدة إلى أكثر من سلسلة نصية بسيطة. أنشئ واحدة باستخدام new FieldArgumentBuilder()، ثم استدعِ AddText(text) لإضافة نص عادي، وAddNode(node) لإضافة عقدة Inline، أو AddField(fieldBuilder) لتضمين حقل آخر (مبني باستخدام FieldBuilder) داخل الحجة. مرّر الـ FieldArgumentBuilder المكتمل إلى FieldBuilder.AddArgument(argument) لاستخدامه كواحدة من حجج الحقل الخارجي.
نصائح وأفضل الممارسات
- استخدم
FieldBuilderعند إنشاء نوع حقل لا يُدعَّم بأحد فئات الحقول المخصصة (مثلFieldDateأوFieldSymbol)، أو عند توليد رموز الحقول برمجياً من البيانات بدلاً من كتابتها يدوياً. - قم بتضمين حقل فرعي داخل حجة حقل خارجي باستخدام
FieldBuilder.AddArgument(FieldBuilder)لحالة بسيطة، أو أنشئ حجة مختلطة من نص وعُقد وحقول متداخلة باستخدامFieldArgumentBuilderعندما تكون الحجة أكثر من حقل واحد. - اختر التحميل الزائد
BuildAndInsert(refNode)الذي يتطابق مع المكان الذي تريد أن يصل إليه الحقل — قبل عقدةInlineمحددة، أو في نهايةParagraph. - بعد
BuildAndInsert، عامل النتيجة كأي حقل آخر في الشجرة — على سبيل المثال، استدعِUpdate()عليها إذا كان نوع الحقل يتطلب إعادة حساب صريحة.
مشكلات شائعة
| المشكلة | السبب | الحل |
|---|---|---|
BuildAndInsert يستهدف الموقع الخطأ | تم استخدام التحميل الزائد الخطأ لنقطة الإدراج المقصودة | مرّر عقدة Inline للإدراج قبلها، أو Paragraph للإدراج في نهايتها |
| معامل الحقل لا يقبل النص العادي والعقدة معًا | تم استدعاء AddArgument باستخدام string/int/double واحد بدلاً من معامل مركّب | أنشئ المعامل المختلط باستخدام FieldArgumentBuilder (AddText, AddNode, AddField) ومرره إلى AddArgument |
| قيمة المفتاح غير معترف بها في شفرة الحقل المُنشأة | تم استخدام AddSwitch(switchName) عندما يكون المفتاح في الواقع بحاجة إلى معامل | استخدم التحميل الزائد AddSwitch(switchName, switchArgument) مع قيمة السلسلة أو العدد الصحيح أو العدد العشري للمفتاح |
FAQ
متى يجب أن أستخدم FieldBuilder بدلاً من إدراج شفرة حقل مُشكَّلة مسبقًا؟
استخدم FieldBuilder عندما تحتاج إلى تحكم صريح في معاملات الحقل ومفاتيحه أثناء بنائها برمجياً، بدلاً من إدراج سلسلة شفرة حقل مُشكَّلة مسبقًا.
كيف يمكنني إضافة أكثر من معامل واحد إلى حقل؟
استدعِ AddArgument مرة واحدة لكل معامل — إنها مُحمَّلة بأكثر من وظيفة لـ string، int، double، FieldBuilder المتداخلة، وFieldArgumentBuilder.
هل يمكنني إنشاء حقل يحتوي معاملُه على مزيج من النص وحقل آخر؟
نعم — استخدم FieldArgumentBuilder، مع استدعاء AddText وAddNode وAddField حسب الحاجة، ثم مرّرها إلى FieldBuilder.AddArgument.
كيف يمكنني فعليًا وضع الحقل المُنشأ في المستند؟
استدعِ BuildAndInsert(refNode)، مع تمرير إما عقدة Inline (تُدرج قبلها) أو Paragraph (تُدرج في نهايتها).
API Reference ملخص
| الفئة/الطريقة | وصف |
|---|---|
FieldBuilder | يبني حقلًا من رموز كود الحقل (الوسائط والمفاتيح) |
FieldBuilder(fieldType) | منشئ يأخذ FieldType للبناء |
FieldBuilder.AddArgument(argument) | يضيف معاملًا (string، int، double، FieldBuilder أو FieldArgumentBuilder) |
FieldBuilder.AddSwitch(switchName) / AddSwitch(switchName, switchArgument) | يضيف مفتاح حقل، مع أو بدون قيمة |
FieldBuilder.BuildAndInsert(refNode) | يدخل الحقل المبني قبل عقدة Inline أو في نهاية Paragraph |
FieldArgumentBuilder | يبني حجة حقل معقدة من النص والعقد والحقول المتداخلة |
FieldArgumentBuilder.AddText(text) | يضيف نصًا عاديًا إلى الحجة |
FieldArgumentBuilder.AddNode(node) | يضيف عقدة Inline إلى الحجة |
FieldArgumentBuilder.AddField(fieldBuilder) | يدمج حقلًا تم بناؤه بواسطة FieldBuilder داخل الحجة |
