أدخل الحقول

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

• باستخدام DocumentBuilder
• باستخدام FieldBuilder
• باستخدام Aspose.Words نموذج كائن المستند (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-Java
// The path to the documents directory.
String dataDir = Utils.getDataDir(InsertField.class);

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertField("MERGEFIELD MyFieldName \\* MERGEFORMAT");

doc.save(dataDir + "output.docx");

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

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

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

for (int i = 0; i < 5; i++)
    builder.insertBreak(BreakType.PAGE_BREAK);

builder.moveToHeaderFooter(HeaderFooterType.FOOTER_PRIMARY);

// We want to insert a field like this:
// { IF {PAGE} <> {NUMPAGES} "See Next Page" "Last Page" }
Field field = builder.insertField("IF ");
builder.moveTo(field.getSeparator());
builder.insertField("PAGE");
builder.write(" <> ");
builder.insertField("NUMPAGES");
builder.write(" \"See Next Page\" \"Last Page\" ");

field.update();

doc.save(getArtifactsDir() + "WorkingWithFields.InsertNestedFields.docx");

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

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

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

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

Field field = builder.insertField(FieldType.FIELD_DATE, true);
field.setLocaleId(1049);

builder.getDocument().save(getArtifactsDir() + "WorkingWithFields.SpecifylocaleAtFieldlevel.docx");

أدخل حقل غير مكتوب / فارغ

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

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

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

FieldUnknown field = (FieldUnknown) builder.insertField(FieldType.FIELD_NONE, false);

doc.save(getArtifactsDir() + "WorkingWithFields.InsertFieldNone.docx");

أدخل حقل COMPARE

يقارن الحقل COMPARE قيمتين ويعيد القيمة الرقمية 1 إذا كانت المقارنة صحيحة أو 0 إذا كانت المقارنة خاطئة.

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

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

FieldCompare field = (FieldCompare) builder.insertField(FieldType.FIELD_COMPARE, true);
field.setLeftExpression("3");
field.setComparisonOperator("<");
field.setRightExpression("2");
field.update();

builder.writeln();

field = (FieldCompare) builder.insertField(FieldType.FIELD_COMPARE, true);
field.setLeftExpression("5");
field.setComparisonOperator("=");
field.setRightExpression("2 + 3");
field.update();

doc.updateFields();
doc.save(getArtifactsDir() + "Field.COMPARE.docx");

أدخل حقل IF

يمكن استخدام الحقل IF لتقييم الوسيطات بشكل مشروط.

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

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

builder.write("Statement 1: ");
FieldIf field = (FieldIf) builder.insertField(FieldType.FIELD_IF, true);
field.setLeftExpression("0");
field.setComparisonOperator("=");
field.setRightExpression("1");

// The IF field will display a string from either its "TrueText" property,
// or its "FalseText" property, depending on the truth of the statement that we have constructed.
field.setTrueText("True");
field.setFalseText("False");
field.update();

builder.write("\nStatement 2: ");
field = (FieldIf) builder.insertField(FieldType.FIELD_IF, true);
field.setLeftExpression("5");
field.setComparisonOperator("=");
field.setRightExpression("2 + 3");
field.setTrueText("True");
field.setFalseText("False");
field.update();

doc.updateFields();
doc.save(getArtifactsDir() + "Field.IF.docx");

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

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

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

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

FieldBuilder firstName = new FieldBuilder(FieldType.FIELD_MERGE_FIELD);
firstName.addArgument("firstname");
FieldBuilder lastName = new FieldBuilder(FieldType.FIELD_MERGE_FIELD);
lastName.addArgument("lastname");

FieldArgumentBuilder firstnameArgumentBuilder = new FieldArgumentBuilder();
firstnameArgumentBuilder.addText("Firstname: ");
firstnameArgumentBuilder.addField(firstName);

FieldArgumentBuilder lastnameArgumentBuilder = new FieldArgumentBuilder();
lastnameArgumentBuilder.addText("Lastname: ");
lastnameArgumentBuilder.addField(lastName);

// Prepare IF field with two nested MERGEFIELD fields: { IF "left expression" = "right expression" "Firstname: { MERGEFIELD firstname }" "Lastname: { MERGEFIELD lastname }"}
FieldBuilder fieldBuilder = new FieldBuilder(FieldType.FIELD_IF);
fieldBuilder.addArgument("left expression");
fieldBuilder.addArgument("=");
fieldBuilder.addArgument("right expression");
fieldBuilder.addArgument(firstnameArgumentBuilder);
fieldBuilder.addArgument(lastnameArgumentBuilder);

// Insert IF field in exact location
Field field = fieldBuilder.buildAndInsert(doc.getFirstSection().getBody().getFirstParagraph());
field.update();

doc.save(getArtifactsDir() + "Field.InsertFieldUsingFieldBuilder.docx");

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

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

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

MERGEFIELD field in Word document can be represented by the FieldMergeField class. You can use FieldMergeField class to perform the following operations:

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

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

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

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

Paragraph para = (Paragraph) doc.getChildNodes(NodeType.PARAGRAPH, true).get(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.FIELD_MERGE_FIELD, false);

// { " MERGEFIELD Test1" }
field.setFieldName("Test1");
// { " MERGEFIELD Test1 \\b Test2" }
field.setTextBefore("Test2");
// { " MERGEFIELD Test1 \\b Test2 \\f Test3 }
field.setTextAfter("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(getArtifactsDir() + "WorkingWithFields.InsertMergeFieldUsingDOM.docx");

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

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

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

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

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

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

Paragraph para = (Paragraph) doc.getChildNodes(NodeType.PARAGRAPH, true).get(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.FIELD_ADDRESS_BLOCK, false);

// { ADDRESSBLOCK \\c 1" }
field.setIncludeCountryOrRegionName("1");
// { ADDRESSBLOCK \\c 1 \\d" }
field.setFormatAddressOnCountryOrRegion(true);
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 }
field.setExcludedCountryOrRegionName("Test2");
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 }
field.setNameAndAddressFormat("Test3");
// { ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 \\l \"Test 4\" }
field.setLanguageId("Test 4");

field.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertMailMergeAddressBlockFieldUsingDOM.docx");

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

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

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

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

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

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

Paragraph para = (Paragraph) doc.getChildNodes(NodeType.PARAGRAPH, true).get(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.FIELD_ADVANCE, false);

// { ADVANCE \\d 10 " }
field.setDownOffset("10");
// { ADVANCE \\d 10 \\l 10 }
field.setLeftOffset("10");
// { ADVANCE \\d 10 \\l 10 \\r -3.3 }
field.setRightOffset("-3.3");
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 }
field.setUpOffset("0");
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 }
field.setHorizontalPosition("100");
// { ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 \\y 100 }
field.setVerticalPosition("100");

field.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertAdvanceFieldWithOutDocumentBuilder.docx");

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

يتم استخدام الحقل ASK لمطالبة المستخدم للنص لتعيين إشارة مرجعية في مستند ورد. ASK الحقل في وثيقة كلمة يمكن أن يمثله فئة 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-Java
Document doc = new Document();

Paragraph para = (Paragraph) doc.getChildNodes(NodeType.PARAGRAPH, true).get(0);

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

// { ASK \"Test 1\" " }
field.setBookmarkName("Test 1");
// { ASK \"Test 1\" Test2 }
field.setPromptText("Test2");
// { ASK \"Test 1\" Test2 \\d Test3 }
field.setDefaultResponse("Test3");
// { ASK \"Test 1\" Test2 \\d Test3 \\o }
field.setPromptOnceOnMailMerge(true);

field.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertASKFieldWithOutDocumentBuilder.docx");

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

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

• حدد اسم مؤلف المستند

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

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

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

Paragraph para = (Paragraph) doc.getChildNodes(NodeType.PARAGRAPH, true).get(0);

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

field.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertAuthorField.docx");

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

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

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

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

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

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Java
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.FIELD_INCLUDE_TEXT, false);
fieldIncludeText.setBookmarkName("bookmark");
fieldIncludeText.setSourceFullName(getMyDir() + "IncludeText.docx");

doc.getFirstSection().getBody().appendChild(para);

fieldIncludeText.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertIncludeFieldWithoutDocumentBuilder.docx");

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

ال TOA (Table of Authorities) يبني الحقل ويدرج جدول السلطات. يجمع الحقل TOA الإدخالات المميزة بحقول TA (Table of Authorities Entry). Microsoft كلمة مكتب إدراج الحقل TOA عند النقر فوق Insert Table of Authorities في المجموعة Table of Authorities على علامة التبويب 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-Java
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.FIELD_TOA_ENTRY, false);
fieldTA.setEntryCategory("1");
fieldTA.setLongCitation("Value 0");

doc.getFirstSection().getBody().appendChild(para);

para = new Paragraph(doc);

FieldToa fieldToa = (FieldToa) para.appendField(FieldType.FIELD_TOA, false);
fieldToa.setEntryCategory("1");
doc.getFirstSection().getBody().appendChild(para);

fieldToa.update();
doc.save(getArtifactsDir() + "WorkingWithFields.InsertTOAFieldWithoutDocumentBuilder.docx");