コンテンツ コントロール SDT の使用

Microsoft Word では、テンプレートから始めて、チェックボックス、テキスト ボックス、日付ピッカー、ドロップダウン リストなどのコンテンツ コントロールを追加することでフォームを作成できます。 Aspose.Words では、Aspose.Words にロードされたドキュメントの構造化ドキュメント タグまたはコンテンツ コントロールが StructuredDocumentTag ノードとしてインポートされます。構造化ドキュメント タグ (SDT またはコンテンツ コントロール) を使用すると、顧客定義のセマンティクスとその動作および外観をドキュメントに埋め込むことができます。 StructuredDocumentTag は、ドキュメント内の次の場所に使用できます。

  • ブロックレベル - 段落と表の間で、BodyHeaderFooterCommentFootnote、または Shape ノードの子として
  • 行レベル - テーブル内の行の間で、Table ノードの子として
  • セルレベル - テーブル行内のセルの間で、Row ノードの子として
  • インラインレベル - 内部のインラインコンテンツの中で、Paragraph の子として
  • 別の StructuredDocumentTag 内にネストされている

ドキュメントへのコンテンツ コントロールの挿入

このバージョンの Aspose.Words では、次のタイプの SDT またはコンテンツ コントロールを作成できます。

  • Checkbox
  • DropDownList
  • ComboBox
  • Date
  • BuildingBlockGallery
  • Group
  • Picture
  • RichText
  • PlainText

次のコード例は、チェックボックス タイプのコンテンツ コントロールを作成する方法を示しています。

# 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)
sdtCheckBox = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.CHECKBOX, aw.markup.MarkupLevel.INLINE)
builder.insert_node(sdtCheckBox)
doc.save(docs_base.artifacts_dir + "WorkingWithSdt.check_box_type_content_control.docx", aw.SaveFormat.DOCX)

次のコード例は、リッチ テキスト ボックス タイプのコンテンツ コントロールを作成する方法を示しています。

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
sdtRichText = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.RICH_TEXT, aw.markup.MarkupLevel.BLOCK)
para = aw.Paragraph(doc)
run = aw.Run(doc)
run.text = "Hello World"
run.font.color = drawing.Color.green
para.runs.add(run)
sdtRichText.child_nodes.add(para)
doc.first_section.body.append_child(sdtRichText)
doc.save(docs_base.artifacts_dir + "WorkingWithSdt.rich_text_box_content_control.docx")

次のコード例は、タイプ コンボ ボックスのコンテンツ コントロールを作成する方法を示しています。

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
sdt = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.COMBO_BOX, aw.markup.MarkupLevel.BLOCK)
sdt.list_items.add(aw.markup.SdtListItem("Choose an item", "-1"))
sdt.list_items.add(aw.markup.SdtListItem("Item 1", "1"))
sdt.list_items.add(aw.markup.SdtListItem("Item 2", "2"))
doc.first_section.body.append_child(sdt)
doc.save(docs_base.artifacts_dir + "WorkingWithSdt.combo_box_content_control.docx")

コンテンツ コントロールを更新する方法

このセクションでは、SDT またはコンテンツ コントロールの値をプログラムで更新する方法について説明します。

次のコード例は、チェックボックスの現在の状態を設定する方法を示しています。

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Structured document tags.docx")
# Get the first content control from the document.
sdtCheckBox = doc.get_child(aw.NodeType.STRUCTURED_DOCUMENT_TAG, 0, True).as_structured_document_tag()
if (sdtCheckBox.sdt_type == aw.markup.SdtType.CHECKBOX) :
sdtCheckBox.checked = True
doc.save(docs_base.artifacts_dir + "WorkingWithSdt.current_state_of_check_box.docx")

次のコード例は、プレーン テキスト ボックス、ドロップダウン リスト、および画像タイプのコンテンツ コントロールを変更する方法を示しています。

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Structured document tags.docx")
for sdt in doc.get_child_nodes(aw.NodeType.STRUCTURED_DOCUMENT_TAG, True) :
sdt = sdt.as_structured_document_tag()
if (sdt.sdt_type == aw.markup.SdtType.PLAIN_TEXT) :
sdt.remove_all_children()
para = sdt.append_child(aw.Paragraph(doc)).as_paragraph()
run = aw.Run(doc, "new text goes here")
para.append_child(run)
elif (sdt.sdt_type == aw.markup.SdtType.DROP_DOWN_LIST) :
secondItem = sdt.list_items[2]
sdt.list_items.selected_value = secondItem
elif (sdt.sdt_type == aw.markup.SdtType.PICTURE) :
shape = sdt.get_child(NodeType.shape, 0, True).as_shape()
if (shape.has_image) :
shape.image_data.set_image(docs_base.images_dir + "Watermark.png")
doc.save(docs_base.artifacts_dir + "WorkingWithSdt.modify_content_controls.docx")

コンテンツ コントロールをカスタム XML パーツにバインドする

Word 文書内の XML データ (カスタム XML 部分) にコンテンツ コントロールをバインドできます。

次のコード例は、コンテンツ コントロールをカスタム XML 部分にバインドする方法を示しています。

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
xmlPart = doc.custom_xml_parts.add(str(uuid.uuid4()), "<root><text>Hello, World!</text></root>")
sdt = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.PLAIN_TEXT, aw.markup.MarkupLevel.BLOCK)
doc.first_section.body.append_child(sdt)
sdt.xml_mapping.set_mapping(xmlPart, "/root[1]/text[1]", "")
doc.save(docs_base.artifacts_dir + "WorkingWithSdt.bind_sd_tto_custom_xml_part.doc")

構造化文書タグ範囲の XML マッピング

StructuredDocumentTagRangeStart.xml_mapping プロパティを使用すると、この構造化ドキュメントのタグ範囲と現在のドキュメントのカスタム XML 部分の XML データとのマッピングを取得できます。ただし、set_mapping メソッドを使用して、構造化文書のタグ範囲を XML データにマップすることはできます。

次のコード例は、XML マッピングを設定する方法を示しています。

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Multi-section structured document tags.docx")
# Construct an XML part that contains data and add it to the document's CustomXmlPart collection.
xmlPartId = str(uuid.uuid4())
xmlPartContent = "<root><text>Text element #1</text><text>Text element #2</text></root>"
xmlPart = doc.custom_xml_parts.add(xmlPartId, xmlPartContent)
print(xmlPart.data.decode("utf-8"))
# Create a StructuredDocumentTag that will display the contents of our CustomXmlPart in the document.
sdtRangeStart = doc.get_child(aw.NodeType.STRUCTURED_DOCUMENT_TAG_RANGE_START, 0, True).as_structured_document_tag_range_start()
# If we set a mapping for our StructuredDocumentTag,
# it will only display a part of the CustomXmlPart that the XPath points to.
# This XPath will point to the contents second "<text>" element of the first "<root>" element of our CustomXmlPart.
sdtRangeStart.xml_mapping.set_mapping(xmlPart, "/root[1]/text[2]", None)
doc.save(docs_base.artifacts_dir + "WorkingWithSdt.structured_document_tag_range_start_xml_mapping.docx")

コンテンツ コントロールのコンテンツをクリアする

プレースホルダーを表示すると、コンテンツ コントロールのコンテンツをクリアできます。 StructuredDocumentTag.clear メソッドは、この構造化文書タグの内容をクリアし、プレースホルダーが定義されている場合はそれを表示します。ただし、コンテンツ コントロールにリビジョンがある場合、コンテンツ コントロールの内容をクリアすることはできません。コンテンツ コントロールにプレースホルダーがない場合は、MS Word と同様に 5 つのスペースが挿入されます (繰り返しセクション、繰り返しセクション項目、グループ、チェックボックス、引用を除く)。コンテンツ コントロールがカスタム XML にマップされている場合、参照された XML ノードはクリアされます。

次のコード例は、コンテンツ コントロールのコンテンツをクリアする方法を示しています。

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Structured document tags.docx")
sdt = doc.get_child(aw.NodeType.STRUCTURED_DOCUMENT_TAG, 0, True).as_structured_document_tag()
sdt.clear()
doc.save(docs_base.artifacts_dir + "WorkingWithSdt.clear_contents_control.doc")

コンテンツ コントロールの背景と境界線の色の変更

StructuredDocumentTag.color プロパティを使用すると、コンテンツ コントロールの色を取得または設定できます。色は、次の 2 つの状況でコンテンツ コントロールに影響します。

  1. MS Word は、マウスをコンテンツ コントロール上に移動すると、コンテンツ コントロールの背景を強調表示します。これは、コンテンツ コントロールを識別するのに役立ちます。ハイライトの色はcolorよりも少し「柔らかい」です。たとえば、color が赤の場合、MS Word は背景をピンク色で強調表示します。
  2. コンテンツ コントロールを操作 (編集、選択など) すると、コンテンツ コントロールの境界線が color で色付けされます。

次のコード例は、コンテンツ コントロールの色を変更する方法を示しています。

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Structured document tags.docx")
sdt = doc.get_child(aw.NodeType.STRUCTURED_DOCUMENT_TAG, 0, True).as_structured_document_tag()
sdt.color = drawing.Color.red
doc.save(docs_base.artifacts_dir + "WorkingWithSdt.set_content_control_color.docx")

スタイルを設定してコンテンツ コントロールに入力されたテキストの書式を設定する方法

コンテンツ コントロールのスタイルを設定する場合は、StructuredDocumentTag.style または StructuredDocumentTag.style_name プロパティを使用できます。出力ドキュメントのコンテンツ コントロールにテキストを入力すると、入力されたテキストのスタイルは「引用」になります。

次のコード例は、コンテンツ コントロールのスタイルを設定する方法を示しています。

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Structured document tags.docx")
sdt = doc.get_child(aw.NodeType.STRUCTURED_DOCUMENT_TAG, 0, True).as_structured_document_tag()
style = doc.styles.get_by_style_identifier(aw.StyleIdentifier.QUOTE)
sdt.style = style
doc.save(docs_base.artifacts_dir + "WorkingWithSdt.set_content_control_style.docx")

繰り返しセクションのコンテンツ コントロールの操作

繰り返しセクションのコンテンツ コントロールを使用すると、その中に含まれるコンテンツを繰り返すことができます。 Aspose.Words を使用すると、繰り返しセクションおよび繰り返しセクション項目タイプの構造化文書タグ ノードを作成できます。この目的のために、SdtType 列挙タイプは REPEATING_SECTION_ITEM プロパティを提供します。

次のコード例は、繰り返しセクションのコンテンツ コントロールをテーブルにバインドする方法を示しています。

# 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)
xmlPart = doc.custom_xml_parts.add("Books",
"<books><book><title>Everyday Italian</title><author>Giada De Laurentiis</author></book>" +
"<book><title>Harry Potter</title><author>J K. Rowling</author></book>" +
"<book><title>Learning XML</title><author>Erik T. Ray</author></book></books>")
table = builder.start_table()
builder.insert_cell()
builder.write("Title")
builder.insert_cell()
builder.write("Author")
builder.end_row()
builder.end_table()
repeatingSectionSdt =aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.REPEATING_SECTION, aw.markup.MarkupLevel.ROW)
repeatingSectionSdt.xml_mapping.set_mapping(xmlPart, "/books[1]/book", "")
table.append_child(repeatingSectionSdt)
repeatingSectionItemSdt = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.REPEATING_SECTION_ITEM, aw.markup.MarkupLevel.ROW)
repeatingSectionSdt.append_child(repeatingSectionItemSdt)
row = aw.tables.Row(doc)
repeatingSectionItemSdt.append_child(row)
titleSdt = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.PLAIN_TEXT, aw.markup.MarkupLevel.CELL)
titleSdt.xml_mapping.set_mapping(xmlPart, "/books[1]/book[1]/title[1]", "")
row.append_child(titleSdt)
authorSdt = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.PLAIN_TEXT, aw.markup.MarkupLevel.CELL)
authorSdt.xml_mapping.set_mapping(xmlPart, "/books[1]/book[1]/author[1]", "")
row.append_child(authorSdt)
doc.save(docs_base.artifacts_dir + "WorkingWithSdt.creating_table_repeating_section_mapped_to_custom_xml_part.docx")