フィールドの挿入

ドキュメントにフィールドを挿入するには、いくつかの方法があります。

• DocumentBuilderを使用する
• FieldBuilderを使用する
• Aspose.Words Document Object Model (DOM)を使用する

この記事では、それぞれの方法を詳しく見て、これらのオプションを使用して特定のフィールドを挿入する方法を分析します。

DocumentBuilder を使用したドキュメントへのフィールドの挿入

Aspose.Words では、insert_field メソッドを使用して新しいフィールドをドキュメントに挿入します。最初のパラメータは、挿入されるフィールドの完全なフィールド コードを受け入れます。 2 番目のパラメータはオプションで、フィールドのフィールド結果を手動で設定できます。これが指定されていない場合、フィールドは自動的に更新されます。このパラメーターに null または空を渡すと、空のフィールド値を持つフィールドを挿入できます。特定のフィールド コードの構文がわからない場合は、まず Microsoft Word でフィールドを作成し、そのフィールド コードを表示するように切り替えます。

フィールド コードにスペースを含むパラメータがある場合は、そのパラメータを音声記号で囲む必要があります。そうしないと、パラメータが両方で切り捨てられたものとして扱われるため、Microsoft Word と Aspose.Words の両方のフィールドが期待どおりに動作しない可能性があります。

次のコード例は、DocumentBuilder を使用して文書に差し込みフィールドを挿入する方法を示しています。

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
builder = aw.DocumentBuilder(doc)
    
builder.insert_field("MERGEFIELD MyFieldName \* MERGEFORMAT")
    
doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_field.docx")

次のコード例は、DocumentBuilder を使用してドイツ語ロケールの差し込みフィールドをドキュメントに挿入する方法を示しています。

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

# Insert content with German locale.
builder.font.locale_id = 1031
builder.insert_field("MERGEFIELD Date1 \\@ \"dddd, d MMMM yyyy\"")
builder.write(" - ")
builder.insert_field("MERGEFIELD Date2 \\@ \"dddd, d MMMM yyyy\"")

同じ手法を使用して、他のフィールド内にネストされたフィールドを挿入します。

次のコード例は、DocumentBuilder を使用して別のフィールド内にネストされたフィールドを挿入する方法を示しています。

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

for i in range(0, 5) :
    builder.insert_break(aw.BreakType.PAGE_BREAK)

builder.move_to_header_footer(aw.HeaderFooterType.FOOTER_PRIMARY)

# We want to insert a field like this:
#  IF PAGE <> NUMPAGES "See Next Page" "Last Page" 
field = builder.insert_field("IF ")
builder.move_to(field.separator)
builder.insert_field("PAGE")
builder.write(" <> ")
builder.insert_field("NUMPAGES")
builder.write(" \"See Next Page\" \"Last Page\" ")

field.update()

doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_nested_fields.docx")

フィールドレベルでロケールを指定する

言語識別子は、国または地理的地域の言語の標準的な国際的な数値略称です。 Aspose.Words を使用すると、フィールド レベルでロケールを指定できます。 locale_id プロパティは、フィールドのロケール ID を取得または設定します。

次のコード例は、このオプションの使用方法を示しています。

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

field = builder.insert_field(aw.fields.FieldType.FIELD_DATE, True)
field.locale_id = 1049
    
builder.document.save(docs_base.artifacts_dir + "WorkingWithFields.specifylocale_at_fieldlevel.docx")

型なし/空のフィールドを挿入

Microsoft Word で許可されているのと同じように、型なし/空のフィールド ({}) を挿入する場合は、FieldType.FIELD_NONE パラメーターを指定した insert_field メソッドを使用できます。 Word 文書にフィールドを挿入するには、「Ctrl + F9」キーの組み合わせを押します。

次のコード例は、空のフィールドをドキュメントに挿入する方法を示しています。

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

field = builder.insert_field(aw.fields.FieldType.FIELD_NONE, False)

doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_field_none.docx")

FieldBuilder を使用してドキュメントにフィールドを挿入する

Aspose.Words にフィールドを挿入する別の方法は、FieldBuilder クラスです。フィールド スイッチと引数値をテキスト、ノード、またはネストされたフィールドとして指定するための流暢なインターフェイスを提供します。

次のコード例は、FieldBuilder を使用してドキュメントにフィールドを挿入する方法を示しています。

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

# Prepare IF field with two nested MERGEFIELD fields: { IF "left expression" = "right expression" "Firstname: { MERGEFIELD firstname }" "Lastname: { MERGEFIELD lastname }"}
field_builder = aw.fields.FieldBuilder(aw.fields.FieldType.FIELD_IF)
field_builder.add_argument("left expression")
field_builder.add_argument("=")
field_builder.add_argument("right expression")
field_builder.add_argument(
    aw.fields.FieldArgumentBuilder()
        .add_text("Firstname: ")
        .add_field(aw.fields.FieldBuilder(aw.fields.FieldType.FIELD_MERGE_FIELD).add_argument("firstname")))
field_builder.add_argument(
    aw.fields.FieldArgumentBuilder()
        .add_text("Lastname: ")
        .add_field(aw.fields.FieldBuilder(aw.fields.FieldType.FIELD_MERGE_FIELD).add_argument("lastname")))

# Insert IF field in exact location            
field = field_builder.build_and_insert(doc.first_section.body.first_paragraph)
field.update()

doc.save(ARTIFACTS_DIR + "Field.insert_field_using_field_builder.docx")

DOM を使用したフィールドの挿入

Aspose.Words Document Object Model (DOM) を使用してさまざまなタイプのフィールドを挿入することもできます。このセクションでは、いくつかの例を見ていきます。

DOM を使用して差し込みフィールドをドキュメントに挿入する

Word 文書の MERGEFIELD フィールドは、FieldMergeField クラスで表すことができます。 FieldMergeField クラスを使用して、次の操作を実行できます。

• 差し込みフィールドの名前を指定します
• 差し込みフィールドの書式設定を指定します
• フィールド区切り文字と差し込みフィールドのフィールド末尾の間にあるテキストを指定します
• 差し込みフィールドが空白でない場合に、差し込みフィールドの後に挿入するテキストを指定します
• 差し込みフィールドが空白でない場合に、差し込みフィールドの前に挿入するテキストを指定します。

次のコード例は、DOM を使用してドキュメント内の段落に Merge フィールドを追加する方法を示しています。

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

para = doc.get_child_nodes(aw.NodeType.PARAGRAPH, True)[0].as_paragraph()
builder.move_to(para)

# We want to insert a merge field like this:
#  " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m \\v" 
field = builder.insert_field(aw.fields.FieldType.FIELD_MERGE_FIELD, False).as_field_merge_field()

#  " MERGEFIELD Test1" 
field.field_name = "Test1"
#  " MERGEFIELD Test1 \\b Test2" 
field.text_before = "Test2"
#  " MERGEFIELD Test1 \\b Test2 \\f Test3 
field.text_after = "Test3"
#  " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m" 
field.is_mapped = True
#  " MERGEFIELD Test1 \\b Test2 \\f Test3 \\m \\v" 
field.is_vertical_formatting = True

field.update()
doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_merge_field_using_dom.docx")

DOM を使用したドキュメントへの Mail Merge ADDRESSBLOCK フィールドの挿入

ADDRESSBLOCK フィールドは、Word 文書に Mail Merge アドレス ブロックを挿入するために使用されます。 Word 文書の ADDRESSBLOCK フィールドは FieldAddressBlock クラスで表現できます。 FieldAddressBlock クラスを使用して、次の操作を実行できます。

• フィールドに国/地域の名前を含めるかどうかを指定します
• POST*CODE (万国郵便連合 2006) で定義されている受信者の国/地域に従って住所をフォーマットするかどうかを指定します。
• 除外する国/地域名を指定します
• 名前とアドレスの形式を指定します
• 住所のフォーマットに使用する言語 ID を指定します

次のコード例は、DOM を使用してドキュメント内の段落に Mail Merge ADDRESSBLOCK フィールドを追加する方法を示しています。

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

para = doc.get_child_nodes(aw.NodeType.PARAGRAPH, True)[0].as_paragraph()
builder.move_to(para)

# We want to insert a mail merge address block like this:
#  ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 \\l \"Test 4\" 
field = builder.insert_field(aw.fields.FieldType.FIELD_ADDRESS_BLOCK, False).as_field_address_block()

#  ADDRESSBLOCK \\c 1" 
field.include_country_or_region_name = "1"
#  ADDRESSBLOCK \\c 1 \\d" 
field.format_address_on_country_or_region = True
#  ADDRESSBLOCK \\c 1 \\d \\e Test2 
field.excluded_country_or_region_name = "Test2"
#  ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 
field.name_and_address_format = "Test3"
#  ADDRESSBLOCK \\c 1 \\d \\e Test2 \\f Test3 \\l \"Test 4\" 
field.language_id = "Test 4"

field.update()
doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_mail_merge_address_block_field_using_dom.docx")

DocumentBuilder を使用せずに ADVANCE フィールドをドキュメントに挿入する

ADVANCE フィールドは、行内の後続のテキストを左、右、上、または下にオフセットするために使用されます。 Word 文書の ADVANCE フィールドは、FieldAdvance クラスで表すことができます。 FieldAdvance クラスを使用して、次の操作を実行できます。

• フィールドに続くテキストをページの上端から垂直に移動するポイント数を指定します。
• フィールドに続くテキストを列、フレーム、またはテキスト ボックスの左端から水平方向に移動するポイント数を指定します。
• フィールドに続くテキストを左、右、上、または下に移動するポイント数を指定します

次のコード例は、DOM を使用してドキュメント内の段落に ADVANCE フィールドを追加する方法を示しています。

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

para = doc.get_child_nodes(aw.NodeType.PARAGRAPH, True)[0].as_paragraph()

# We want to insert an Advance field like this:
#  ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 \\y 100 
field = para.append_field(aw.fields.FieldType.FIELD_ADVANCE, False).as_field_advance()
    
#  ADVANCE \\d 10 " 
field.down_offset = "10"
#  ADVANCE \\d 10 \\l 10 
field.left_offset = "10"
#  ADVANCE \\d 10 \\l 10 \\r -3.3 
field.right_offset = "-3.3"
#  ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 
field.up_offset = "0"
#  ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 
field.horizontal_position = "100"
#  ADVANCE \\d 10 \\l 10 \\r -3.3 \\u 0 \\x 100 \\y 100 
field.vertical_position = "100"

field.update()
doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_advance_field_with_out_document_builder.docx")

DocumentBuilder を使用せずに ASK フィールドをドキュメントに挿入する

ASK フィールドは、Word 文書のブックマークに割り当てるテキストをユーザーに要求するために使用されます。 Word 文書の ASK フィールドは、FieldAsk クラスで表現できます。 FieldAsk クラスを使用して、次の操作を実行できます。

• ブックマークの名前を指定します
• デフォルトのユーザー応答を指定します (プロンプト ウィンドウに含まれる初期値)
• Mail Merge 操作ごとにユーザー応答を 1 回受信するかどうかを指定します
• プロンプトテキスト (プロンプトウィンドウのタイトル) を指定します。

次のコード例は、DOM を使用してドキュメント内の段落に ASK フィールドを追加する方法を示しています。

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

para = doc.get_child_nodes(aw.NodeType.PARAGRAPH, True)[0].as_paragraph()

# We want to insert an Ask field like this:
#  ASK \"Test 1\" Test2 \\d Test3 \\o 
field = para.append_field(aw.fields.FieldType.FIELD_ASK, False).as_field_ask()

#  ASK \"Test 1\" " 
field.bookmark_name = "Test 1"
#  ASK \"Test 1\" Test2 
field.prompt_text = "Test2"
#  ASK \"Test 1\" Test2 \\d Test3 
field.default_response = "Test3"
#  ASK \"Test 1\" Test2 \\d Test3 \\o 
field.prompt_once_on_mail_merge = True

field.update()
doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_ask_field_with_out_document_builder.docx")

DocumentBuilder を使用せずに AUTHOR フィールドをドキュメントに挿入する

AUTHOR フィールドは、Document プロパティからドキュメントの作成者の名前を指定するために使用されます。 Word 文書の AUTHOR フィールドは、FieldAuthor クラスで表現できます。 FieldAuthor クラスを使用して、次の操作を実行できます。

• 文書の作成者の名前を指定します

次のコード例は、DOM を使用してドキュメント内の段落に AUTHOR フィールドを追加する方法を示しています。

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

para = doc.get_child_nodes(aw.NodeType.PARAGRAPH, True)[0].as_paragraph()

# We want to insert an AUTHOR field like this:
#  AUTHOR Test1 
field = para.append_field(aw.fields.FieldType.FIELD_AUTHOR, False).as_field_author()
field.author_name = "Test1" #  AUTHOR Test1 

field.update()
doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_author_field.docx")

DocumentBuilder を使用せずに INCLUDETEXT フィールドをドキュメントに挿入する

INCLUDETEXT フィールドは、フィールド コードで指定されたドキュメントに含まれるテキストとグラフィックを挿入します。文書全体、またはブックマークで参照されている文書の一部を挿入できます。 Word 文書のこのフィールドは INCLUDETEXT で表されます。 FieldIncludeText クラスを使用して、次の操作を実行できます。

• 含まれるドキュメントのブックマーク名を指定します
• ドキュメントの場所を指定します

次のコード例は、DOM を使用してドキュメント内の段落に INCLUDETEXT フィールドを追加する方法を示しています。

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

para = aw.Paragraph(doc)

# We want to insert an INCLUDETEXT field like this:
#  INCLUDETEXT  "file path" 
fieldIncludeText = para.append_field(aw.fields.FieldType.FIELD_INCLUDE_TEXT, False).as_field_include_text()
fieldIncludeText.bookmark_name = "bookmark"
fieldIncludeText.source_full_name = docs_base.my_dir + "IncludeText.docx"

doc.first_section.body.append_child(para)

fieldIncludeText.update()
doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_include_field_without_document_builder.docx")

DocumentBuilder を使用せずに TOA フィールドをドキュメントに挿入する

TOA (典拠表) フィールドは典拠表を作成して挿入します。 TOA フィールドは、TA (Table of Authorities Entry) フィールドでマークされたエントリを収集します。 Microsoft Office Word は、[References] タブの 権威一覧表 グループで [典拠表の挿入] をクリックすると、TOA フィールドを挿入します。ドキュメント内の TOA フィールドを表示すると、構文は次のようになります。

{ TOA [Switches ] }

FieldToa クラスを使用して、TOA フィールドの操作を実行できます。

次のコード例は、DOM を使用してドキュメント内の段落に TOA フィールドを追加する方法を示しています。

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

# We want to insert TA and TOA fields like this:
#  TA  \c 1 \l "Value 0" 
#  TOA  \c 1 
fieldTA = para.append_field(aw.fields.FieldType.FIELD_TOAENTRY, False).as_field_ta()
fieldTA.entry_category = "1"
fieldTA.long_citation = "Value 0"

doc.first_section.body.append_child(para)

para = aw.Paragraph(doc)

fieldToa = para.append_field(aw.fields.FieldType.FIELD_TOA, False).as_field_toa()
fieldToa.entry_category = "1"
doc.first_section.body.append_child(para)

fieldToa.update()
doc.save(docs_base.artifacts_dir + "WorkingWithFields.insert_toa_field_without_document_builder.docx")