إدراج الحقول

هناك عدة طرق مختلفة لإدراج الحقول في المستند:

• باستخدام DocumentBuilder
• باستخدام FieldBuilder
• باستخدام Aspose.Words Document Object Model (DOM)

في هذه المقالة، سننظر في كل طريقة بمزيد من التفصيل ونحلل كيفية إدراج حقول معينة باستخدام هذه الخيارات.

إدراج الحقول في مستند باستخدام DocumentBuilder

في Aspose.Words يتم استخدام طريقة InsertField لإدراج حقول جديدة في المستند. تقبل المعلمة الأولى رمز الحقل الكامل للحقل المراد إدراجه. المعلمة الثانية اختيارية وتسمح بتعيين نتيجة الحقل يدويًا. إذا لم يتم توفير ذلك، فسيتم تحديث الحقل تلقائيًا. يمكنك تمرير قيمة خالية أو فارغة إلى هذه المعلمة لإدراج حقل بقيمة حقل فارغة. إذا لم تكن متأكدًا من بناء جملة رمز الحقل المحدد، فقم بإنشاء الحقل في Microsoft Word أولاً ثم قم بالتبديل لرؤية رمز الحقل الخاص به.

إذا كان رمز الحقل الخاص بك يحتوي على معلمة تحتوي على مسافة، فيجب أن تكون محاطة بعلامات الكلام. وإلا فإن الحقل في كل من Microsoft Word وAspose.Words قد لا يعمل كما هو متوقع حيث يتم التعامل مع المعلمة من قبل كليهما على أنها مقطوعة.

يوضح مثال التعليمات البرمجية التالي كيفية إدراج حقل دمج في مستند باستخدام DocumentBuilder:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

builder.InsertField(@"MERGEFIELD MyFieldName \* MERGEFORMAT");

doc.Save(ArtifactsDir + "WorkingWithFields.InsertField.docx");

يتم استخدام نفس الأسلوب لإدراج الحقول المتداخلة داخل حقول أخرى.

يوضح مثال التعليمات البرمجية التالي كيفية إدراج الحقول المتداخلة داخل حقل آخر باستخدام DocumentBuilder:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

for (int i = 0; i < 5; i++)
    builder.InsertBreak(BreakType.PageBreak);

builder.MoveToHeaderFooter(HeaderFooterType.FooterPrimary);

// We want to insert a field like this:
// { IF {PAGE} <> {NUMPAGES} "See Next Page" "Last Page" }
Field field = builder.InsertField(@"IF ");
builder.MoveTo(field.Separator);
builder.InsertField("PAGE");
builder.Write(" <> ");
builder.InsertField("NUMPAGES");
builder.Write(" \"See Next Page\" \"Last Page\" ");

field.Update();

doc.Save(ArtifactsDir + "WorkingWithFields.InsertNestedFields.docx");

حدد اللغة على مستوى الحقل

معرف اللغة هو اختصار رقمي دولي قياسي للغة في بلد ما أو منطقة جغرافية ما. باستخدام Aspose.Words، يمكنك تحديد الإعدادات المحلية على مستوى الحقل باستخدام خاصية LocaleId، التي تحصل على معرف الإعدادات المحلية للحقل أو تقوم بتعيينه.

يوضح مثال التعليمات البرمجية التالي كيفية استخدام هذا الخيار:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
DocumentBuilder builder = new DocumentBuilder();

Field field = builder.InsertField(FieldType.FieldDate, true);
field.LocaleId = 1049;

builder.Document.Save(ArtifactsDir + "WorkingWithFields.SpecifylocaleAtFieldlevel.docx");

قم بإدراج حقل غير مكتوب/فارغ

إذا كنت تريد إدراج حقول غير مكتوبة/فارغة ({}) تمامًا كما يسمح Microsoft Word، فيمكنك استخدام أسلوب InsertField مع المعلمة FieldType.FieldNone. لإدراج حقل في مستند Word، يمكنك الضغط على مجموعة المفاتيح “Ctrl + F9”.

يوضح مثال التعليمات البرمجية التالي كيفية إدراج حقل فارغ في المستند:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

FieldUnknown field = (FieldUnknown) builder.InsertField(FieldType.FieldNone, false);

doc.Save(ArtifactsDir + "WorkingWithFields.InsertFieldNone.docx");

إدراج الحقول في مستند باستخدام FieldBuilder

الطريقة البديلة لإدراج الحقول في Aspose.Words هي فئة FieldBuilder. يوفر واجهة سلسة لتحديد مفاتيح الحقول وقيم الوسيطات كنص أو عقد أو حتى حقول متداخلة.

يوضح مثال التعليمات البرمجية التالي كيفية إدراج حقل في مستند باستخدام FieldBuilder:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document();

// Prepare IF field with two nested MERGEFIELD fields: { IF "left expression" = "right expression" "Firstname: { MERGEFIELD firstname }" "Lastname: { MERGEFIELD lastname }"}
FieldBuilder fieldBuilder = new FieldBuilder(FieldType.FieldIf)
    .AddArgument("left expression")
    .AddArgument("=")
    .AddArgument("right expression")
    .AddArgument(
        new FieldArgumentBuilder()
            .AddText("Firstname: ")
            .AddField(new FieldBuilder(FieldType.FieldMergeField).AddArgument("firstname")))
    .AddArgument(
        new FieldArgumentBuilder()
            .AddText("Lastname: ")
            .AddField(new FieldBuilder(FieldType.FieldMergeField).AddArgument("lastname")));

// Insert IF field in exact location            
Field field = fieldBuilder.BuildAndInsert(doc.FirstSection.Body.FirstParagraph);
field.Update();

doc.Save(ArtifactsDir + "Field.InsertFieldUsingFieldBuilder.docx");

إدراج الحقول باستخدام DOM

يمكنك أيضًا إدراج أنواع مختلفة من الحقول باستخدام Aspose.Words Document Object Model (DOM). في هذا القسم، سننظر في بعض الأمثلة.

إدراج حقل دمج في مستند باستخدام DOM

يمكن تمثيل حقل MERGEFIELD في مستند Word بواسطة فئة FieldMergeField. يمكنك استخدام فئة FieldMergeField لتنفيذ العمليات التالية:

• تحديد اسم حقل الدمج
• تحديد تنسيق حقل الدمج
• حدد النص الموجود بين فاصل الحقل ونهاية حقل حقل الدمج
• تحديد النص المراد إدراجه بعد حقل الدمج إذا لم يكن الحقل فارغا
• حدد النص الذي سيتم إدراجه قبل حقل الدمج إذا لم يكن الحقل فارغًا

لمزيد من التفاصيل، راجع فئة FieldMergeField API.

يوضح مثال التعليمات البرمجية التالي كيفية إضافة حقل MERGE باستخدام DOM إلى فقرة في مستند:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Paragraph para = (Paragraph) doc.GetChildNodes(NodeType.Paragraph, true)[0];
builder.MoveTo(para);

// We want to insert a merge field like this:
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m \\v" }
FieldMergeField field = (FieldMergeField) builder.InsertField(FieldType.FieldMergeField, false);

// { " MERGEFIELD Test1" }
field.FieldName = "Test1";
// { " MERGEFIELD Test1 \\b Test2" }
field.TextBefore = "Test2";
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 }
field.TextAfter = "Test3";
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m" }
field.IsMapped = true;
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m \\v" }
field.IsVerticalFormatting = true;

field.Update();
doc.Save(ArtifactsDir + "WorkingWithFields.InsertMergeFieldUsingDOM.docx");

إدراج حقل Mail Merge ADDRESSBLOCK في مستند باستخدام DOM

يتم استخدام حقل ADDRESSBLOCK لإدراج كتلة عنوان Mail Merge في مستند Word. يمكن تمثيل حقل ADDRESSBLOCK في مستند Word بواسطة فئة FieldAddressBlock. يمكنك استخدام فئة FieldAddressBlock لإجراء العمليات التالية:

• حدد ما إذا كنت تريد تضمين اسم البلد/المنطقة في الحقل
• حدد ما إذا كان سيتم تنسيق العنوان وفقًا لبلد/منطقة المستلم كما هو محدد بواسطة POST*CODE (الاتحاد البريدي العالمي 2006)
• حدد اسم البلد/المنطقة المستبعدة
• تحديد تنسيق الاسم والعنوان
• حدد معرف اللغة المستخدم لتنسيق العنوان

لمزيد من التفاصيل، راجع فئة FieldAddressBlock API.

يوضح مثال التعليمات البرمجية التالي كيفية إضافة حقل Mail Merge ADDRESSBLOCK باستخدام DOM إلى فقرة في مستند:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Paragraph para = (Paragraph) doc.GetChildNodes(NodeType.Paragraph, true)[0];
builder.MoveTo(para);

// We want to insert a mail merge address block like this:
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 \\l \"Test 4\" }
FieldAddressBlock field = (FieldAddressBlock) builder.InsertField(FieldType.FieldAddressBlock, false);

// { ADDRESSBLOCK \\c 1" }
field.IncludeCountryOrRegionName = "1";
// { ADDRESSBLOCK \\c 1 \\d" }
field.FormatAddressOnCountryOrRegion = true;
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 }
field.ExcludedCountryOrRegionName = "Test2";
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 }
field.NameAndAddressFormat = "Test3";
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 \\l \"Test 4\" }
field.LanguageId = "Test 4";

field.Update();
doc.Save(ArtifactsDir + "WorkingWithFields.InsertMailMergeAddressBlockFieldUsingDOM.docx");

إدراج حقل ADVANCE في مستند دون استخدام DocumentBuilder

يتم استخدام حقل ADVANCE لإزاحة النص اللاحق داخل سطر إلى اليسار أو اليمين أو لأعلى أو لأسفل. يمكن تمثيل حقل ADVANCE في مستند Word بواسطة فئة FieldAdvance. يمكنك استخدام فئة FieldAdvance لتنفيذ العمليات التالية:

• تحديد عدد النقاط التي يجب من خلالها نقل النص الذي يلي الحقل عموديًا من الحافة العلوية للصفحة
• تحديد عدد النقاط التي يجب من خلالها نقل النص الذي يلي الحقل أفقيًا من الحافة اليسرى للعمود أو الإطار أو مربع النص
• تحديد عدد النقاط التي يجب من خلالها نقل النص الذي يلي الحقل إلى اليسار أو اليمين أو لأعلى أو لأسفل

لمزيد من التفاصيل، راجع فئة FieldAdvance API.

يوضح مثال التعليمات البرمجية التالي كيفية إضافة حقل ADVANCE باستخدام DOM إلى فقرة في مستند:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document();
Paragraph para = (Paragraph) doc.GetChildNodes(NodeType.Paragraph, true)[0];

// We want to insert an Advance field like this:
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 \\y 100 }
FieldAdvance field = (FieldAdvance) para.AppendField(FieldType.FieldAdvance, false);

// { ADVANCE \\d 10 " }
field.DownOffset = "10";
// { ADVANCE \\d 10 \\l 10 }
field.LeftOffset = "10";
// { ADVANCE \\d 10 \\l 10 \\r -3.3 }
field.RightOffset = "-3.3";
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 }
field.UpOffset = "0";
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 }
field.HorizontalPosition = "100";
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 \\y 100 }
field.VerticalPosition = "100";

field.Update();
doc.Save(ArtifactsDir + "WorkingWithFields.InsertAdvanceFieldWithOutDocumentBuilder.docx");

إدراج حقل ASK في مستند دون استخدام DocumentBuilder

يتم استخدام حقل ASK لمطالبة المستخدم بتعيين نص لإشارة مرجعية في مستند Word. يمكن تمثيل حقل ASK في مستند Word بواسطة فئة FieldAsk. يمكنك استخدام فئة FieldAsk لتنفيذ العمليات التالية:

• حدد اسم الإشارة المرجعية
• تحديد استجابة المستخدم الافتراضية (القيمة الأولية الموجودة في نافذة المطالبة)
• حدد ما إذا كان يجب تلقي استجابة المستخدم مرة واحدة لكل عملية mail merge
• تحديد نص المطالبة (عنوان نافذة المطالبة)

لمزيد من التفاصيل، راجع فئة FieldAsk API.

يوضح مثال التعليمات البرمجية التالي كيفية إضافة حقل ASK باستخدام DOM إلى فقرة في مستند:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document();
Paragraph para = (Paragraph) doc.GetChildNodes(NodeType.Paragraph, true)[0];

// We want to insert an Ask field like this:
// { ASK \"Test 1\" Test2 \\d Test3 \\o }
FieldAsk field = (FieldAsk) para.AppendField(FieldType.FieldAsk, false);
// { ASK \"Test 1\" " }
field.BookmarkName = "Test 1";
// { ASK \"Test 1\" Test2 }
field.PromptText = "Test2";
// { ASK \"Test 1\" Test2 \\d Test3 }
field.DefaultResponse = "Test3";
// { ASK \"Test 1\" Test2 \\d Test3 \\o }
field.PromptOnceOnMailMerge = true;

field.Update();
doc.Save(ArtifactsDir + "WorkingWithFields.InsertASKFieldWithOutDocumentBuilder.docx");

إدراج حقل AUTHOR في مستند دون استخدام DocumentBuilder

يتم استخدام حقل AUTHOR لتحديد اسم مؤلف المستند من خصائص Document. يمكن تمثيل حقل AUTHOR في مستند Word بواسطة فئة FieldAuthor. يمكنك استخدام فئة FieldAuthor لإجراء العمليات التالية:

• تحديد اسم مؤلف الوثيقة

لمزيد من التفاصيل، راجع فئة FieldAuthor API.

يوضح مثال التعليمات البرمجية التالي كيفية إضافة حقل AUTHOR باستخدام DOM إلى فقرة في مستند:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document();
Paragraph para = (Paragraph) doc.GetChildNodes(NodeType.Paragraph, true)[0];

// We want to insert an AUTHOR field like this:
// { AUTHOR Test1 }
FieldAuthor field = (FieldAuthor) para.AppendField(FieldType.FieldAuthor, false);            
field.AuthorName = "Test1"; // { AUTHOR Test1 }

field.Update();
doc.Save(ArtifactsDir + "WorkingWithFields.InsertAuthorField.docx");

إدراج حقل INCLUDETEXT في مستند دون استخدام DocumentBuilder

يقوم حقل INCLUDETEXT بإدراج النص والرسومات الموجودة في المستند المسمى في رمز الحقل. يمكنك إدراج المستند بأكمله أو جزء من المستند المشار إليه بواسطة إشارة مرجعية. يتم تمثيل هذا الحقل في مستند Word بواسطة INCLUDETEXT. يمكنك استخدام فئة FieldIncludeText لتنفيذ العمليات التالية:

• حدد اسم الإشارة المرجعية للوثيقة المضمنة
• تحديد موقع الوثيقة

لمزيد من التفاصيل، راجع فئة FieldIncludeText API.

يوضح مثال التعليمات البرمجية التالي كيفية إضافة حقل INCLUDETEXT باستخدام DOM إلى فقرة في مستند:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document();
Paragraph para = new Paragraph(doc);

// We want to insert an INCLUDETEXT field like this:
// { INCLUDETEXT  "file path" }
FieldIncludeText fieldIncludeText = (FieldIncludeText) para.AppendField(FieldType.FieldIncludeText, false);
fieldIncludeText.BookmarkName = "bookmark";
fieldIncludeText.SourceFullName = MyDir + "IncludeText.docx";

doc.FirstSection.Body.AppendChild(para);

fieldIncludeText.Update();
doc.Save(ArtifactsDir + "WorkingWithFields.InsertIncludeFieldWithoutDocumentBuilder.docx");

إدراج حقل TOA في مستند دون استخدام DocumentBuilder

يقوم الحقل TOA (جدول المراجع المصدقة) بإنشاء جدول المراجع المصدقة وإدراجه. يجمع حقل TOA الإدخالات المميزة بحقول TA (إدخال جدول المراجع). يقوم Microsoft Office Word بإدراج الحقل TOA عند النقر فوق إدراج جدول المراجع في مجموعة جدول السلطات ضمن علامة التبويب References. عندما تقوم بعرض حقل TOA في مستندك، تبدو الصيغة كما يلي:

{ TOA [Switches ] }

لمزيد من التفاصيل، راجع فئة FieldToa API.

يوضح مثال التعليمات البرمجية التالي كيفية إضافة حقل TOA باستخدام DOM إلى فقرة في مستند:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document();
Paragraph para = new Paragraph(doc);

// We want to insert TA and TOA fields like this:
// { TA  \c 1 \l "Value 0" }
// { TOA  \c 1 }
FieldTA fieldTA = (FieldTA) para.AppendField(FieldType.FieldTOAEntry, false);
fieldTA.EntryCategory = "1";
fieldTA.LongCitation = "Value 0";

doc.FirstSection.Body.AppendChild(para);

para = new Paragraph(doc);

FieldToa fieldToa = (FieldToa) para.AppendField(FieldType.FieldTOA, false);
fieldToa.EntryCategory = "1";
doc.FirstSection.Body.AppendChild(para);

fieldToa.Update();
doc.Save(ArtifactsDir + "WorkingWithFields.InsertTOAFieldWithoutDocumentBuilder.docx");