Arbeiten mit Content Control SDT

In Microsoft Word können Sie ein Formular erstellen, indem Sie mit einer Vorlage beginnen und Inhaltssteuerelemente hinzufügen, einschließlich Kontrollkästchen, Textfelder, Datumsauswahl und Dropdown-Listen. In Aspose.Words wird ein strukturiertes Dokument-Tag oder ein Inhaltssteuerelement aus jedem in Aspose.Words geladenen Dokument als StructuredDocumentTag-Knoten importiert. Strukturierte Dokument-Tags (SDT oder Inhaltskontrolle) ermöglichen die Einbettung kundenspezifischer Semantik sowie deren Verhalten und Erscheinungsbild in ein Dokument.

StructuredDocumentTag kann in einem Dokument an folgenden Stellen vorkommen:

• Blockebene – Zwischen Absätzen und Tabellen, als untergeordnetes Element eines Body-, HeaderFooter-, Comment-, Footnote- oder Shape-Knotens
• Zeilenebene – Zwischen Zeilen in einer Tabelle, als untergeordnetes Element eines Tabellenknotens
• Zellenebene – Zwischen Zellen in einer Tabellenzeile, als untergeordnetes Element eines Zeilenknotens
• Inline-Ebene – Unter Inline-Inhalten im Inneren, als untergeordnetes Element eines Absatzes – In einem anderen StructuredDocumentTag verschachtelt

Einfügen von Inhaltssteuerelementen in ein Dokument

In dieser Version von Aspose.Words können die folgenden Arten von SDT oder Inhaltskontrolle erstellt werden:

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

Das folgende Codebeispiel zeigt, wie Sie ein Inhaltssteuerelement vom Typ Kontrollkästchen erstellen:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_WorkingWithDocument();
// Open the empty document
Document doc = new Document();

DocumentBuilder builder = new DocumentBuilder(doc);
StructuredDocumentTag SdtCheckBox = new StructuredDocumentTag(doc, SdtType.Checkbox, MarkupLevel.Inline);

// Insert content control into the document
builder.InsertNode(SdtCheckBox);
dataDir = dataDir + "CheckBoxTypeContentControl_out.docx";

doc.Save(dataDir, SaveFormat.Docx);

Das folgende Codebeispiel zeigt, wie Sie ein Inhaltssteuerelement vom Typ Rich-Text-Box erstellen:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_WorkingWithDocument();
Document doc = new Document();
StructuredDocumentTag sdtRichText = new StructuredDocumentTag(doc, SdtType.RichText, MarkupLevel.Block);

Paragraph para = new Paragraph(doc);
Run run = new Run(doc);
run.Text = "Hello World";
run.Font.Color = Color.Green;
para.Runs.Add(run);
sdtRichText.ChildNodes.Add(para);
doc.FirstSection.Body.AppendChild(sdtRichText);

dataDir = dataDir + "RichTextBoxContentControl_out.docx";
doc.Save(dataDir);

Das folgende Codebeispiel zeigt, wie Sie ein Inhaltssteuerelement vom Typ Kombinationsfeld erstellen:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_WorkingWithDocument();
Document doc = new Document();
StructuredDocumentTag sdt = new StructuredDocumentTag(doc, SdtType.ComboBox, MarkupLevel.Block);

sdt.ListItems.Add(new SdtListItem("Choose an item", "-1"));
sdt.ListItems.Add(new SdtListItem("Item 1", "1"));
sdt.ListItems.Add(new SdtListItem("Item 2", "2"));
doc.FirstSection.Body.AppendChild(sdt);

dataDir = dataDir + "ComboBoxContentControl_out.docx";
doc.Save(dataDir);

So aktualisieren Sie Inhaltssteuerelemente

In diesem Abschnitt wird erläutert, wie Sie die Werte von SDT oder Inhaltssteuerung programmgesteuert aktualisieren.

Das folgende Codebeispiel zeigt, wie der aktuelle Status des Kontrollkästchens festgelegt wird:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
// Open an existing document
Document doc = new Document(dataDir + "CheckBoxTypeContentControl.docx");

DocumentBuilder builder = new DocumentBuilder(doc);
// Get the first content control from the document
StructuredDocumentTag SdtCheckBox = (StructuredDocumentTag)doc.GetChild(NodeType.StructuredDocumentTag, 0, true);

// StructuredDocumentTag.Checked property gets/sets current state of the Checkbox SDT
if (SdtCheckBox.SdtType == SdtType.Checkbox)
    SdtCheckBox.Checked = true;

dataDir = dataDir + "SetCurrentStateOfCheckBox_out.docx";
doc.Save(dataDir);

Das folgende Codebeispiel zeigt, wie Inhaltssteuerelemente vom Typ “Einfaches Textfeld”, “Dropdown-Liste” und “Bild” geändert werden:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
// Open an existing document
Document doc = new Document(dataDir + "CheckBoxTypeContentControl.docx");

foreach (StructuredDocumentTag sdt in doc.GetChildNodes(NodeType.StructuredDocumentTag, true))
{
    if (sdt.SdtType == SdtType.PlainText)
    {
        sdt.RemoveAllChildren();
        Paragraph para = sdt.AppendChild(new Paragraph(doc)) as Paragraph;
        Run run = new Run(doc, "new text goes here");
        para.AppendChild(run);
    }
    else if (sdt.SdtType == SdtType.DropDownList)
    {
        SdtListItem secondItem = sdt.ListItems[2];
        sdt.ListItems.SelectedValue = secondItem;
    }
    else if (sdt.SdtType == SdtType.Picture)
    {
        Shape shape = (Shape)sdt.GetChild(NodeType.Shape, 0, true);
        if (shape.HasImage)
        {
            shape.ImageData.SetImage(dataDir + "Watermark.png");
        }
    }
}


dataDir = dataDir + "ModifyContentControls_out.docx";
doc.Save(dataDir);

Bindung der Inhaltskontrolle an benutzerdefinierte XML-Teile

Sie können Inhaltssteuerelemente mit XML-Daten (benutzerdefinierter XML-Teil) in Word-Dokumenten binden.

Das folgende Codebeispiel zeigt, wie die Inhaltssteuerung an benutzerdefinierte XML-Teile gebunden wird:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document();
CustomXmlPart xmlPart = doc.CustomXmlParts.Add(Guid.NewGuid().ToString("B"), "<root><text>Hello, World!</text></root>");

StructuredDocumentTag sdt = new StructuredDocumentTag(doc, SdtType.PlainText, MarkupLevel.Block);
doc.FirstSection.Body.AppendChild(sdt);

sdt.XmlMapping.SetMapping(xmlPart, "/root[1]/text[1]", "");

dataDir = dataDir + "BindSDTtoCustomXmlPart_out.doc";

// Save the document to disk.
doc.Save(dataDir);

XMLMapping des Tag-Bereichs strukturierter Dokumente

Sie können die Zuordnung dieses strukturierten Dokument-Tag-Bereichs zu XML-Daten in einem benutzerdefinierten XML-Teil des aktuellen Dokuments mithilfe von StructuredDocumentTagRangeStart.XmlMapping-Eigenschaft erhalten. Allerdings kann die SetMapping-Methode verwendet werden, um einen strukturierten Dokument-Tag-Bereich XML-Daten zuzuordnen.

Das folgende Codebeispiel zeigt, wie die XML-Zuordnung festgelegt wird:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document(dataDir + "input.docx");
            
StructuredDocumentTagRangeStart sdtRangeStart = (StructuredDocumentTagRangeStart)doc.GetChild(NodeType.StructuredDocumentTagRangeStart, 0, true);

sdtRangeStart.XmlMapping.SetMapping(doc.CustomXmlParts[0], "/Root/Element", null);

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

Inhalte eines Inhaltssteuerelements löschen

Sie können den Inhalt eines Inhaltssteuerelements löschen, indem Sie einen Platzhalter anzeigen. Die StructuredDocumentTag.Clear-Methode löscht den Inhalt dieses strukturierten Dokument-Tags und zeigt einen Platzhalter an, sofern dieser definiert ist. Es ist jedoch nicht möglich, den Inhalt eines Inhaltssteuerelements zu löschen, wenn es Revisionen aufweist. Wenn ein Inhaltssteuerelement keinen Platzhalter hat, werden wie in Microsoft Word fünf Leerzeichen eingefügt (außer sich wiederholende Abschnitte, sich wiederholende Abschnittselemente, Gruppen, Kontrollkästchen, Zitate). Wenn ein Inhaltssteuerelement benutzerdefiniertem XML zugeordnet ist, wird der referenzierte XML-Knoten gelöscht.

Das folgende Codebeispiel zeigt, wie der Inhalt der Inhaltssteuerung gelöscht wird:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET

            Document doc = new Document(dataDir + "input.docx");
            StructuredDocumentTag sdt = (StructuredDocumentTag)doc.GetChild(NodeType.StructuredDocumentTag, 0, true);
            sdt.Clear();

            dataDir = dataDir + "ClearContentsControl_out.doc";

            // Save the document to disk.
            doc.Save(dataDir);

Ändern Sie die Hintergrund- und Rahmenfarben der Inhaltssteuerung

Mit der StructuredDocumentTag.Color-Eigenschaft können Sie die Farbe der Inhaltssteuerung abrufen oder festlegen. Die Farbe beeinflusst die Inhaltssteuerung in zwei Situationen:

1. MS Word hebt den Hintergrund des Inhaltssteuerelements hervor, wenn die Maus über das Inhaltssteuerelement bewegt wird. Dies hilft, die Inhaltskontrolle zu identifizieren. Die Hervorhebungsfarbe ist etwas “weicher” als beim Color. Beispielsweise hebt MS Word den Hintergrund rosa hervor, wenn Color rot ist.
2. Wenn Sie mit dem Inhaltssteuerelement interagieren (Bearbeiten, Auswählen usw.), wird der Rand des Inhaltssteuerelements mit dem Color gefärbt.

Das folgende Codebeispiel zeigt, wie Sie die Farbe des Inhaltssteuerelements ändern:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET

            Document doc = new Document(dataDir + "input.docx");
            StructuredDocumentTag sdt = (StructuredDocumentTag)doc.GetChild(NodeType.StructuredDocumentTag, 0, true);
            sdt.Color = Color.Red;

            dataDir = dataDir + "SetContentControlColor_out.docx";

            // Save the document to disk.
            doc.Save(dataDir);

So legen Sie den Stil fest, um in das Inhaltssteuerelement eingegebenen Text zu formatieren

Wenn Sie den Stil der Inhaltssteuerung festlegen möchten, können Sie StructuredDocumentTag.Style- oder StructuredDocumentTag.StyleName-Eigenschaften verwenden. Wenn Sie den Text in die Inhaltssteuerung im Ausgabedokument eingeben, hat der eingegebene Text den Stil “Zitat”.

Beachten Sie, dass nur verknüpfte Stile und Zeichenstile auf die Inhaltssteuerung angewendet werden können. Eine InvalidOperationException (“Dieser Stil kann nicht auf das SDT angewendet werden”) wird ausgelöst, wenn ein Stil angewendet wird, der vorhanden, aber nicht verknüpft oder Zeichenstil ist.

Das folgende Codebeispiel zeigt, wie Sie den Stil der Inhaltssteuerung festlegen:

// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
Document doc = new Document(dataDir + "input.docx");
StructuredDocumentTag sdt = (StructuredDocumentTag)doc.GetChild(NodeType.StructuredDocumentTag, 0, true);
Style style = doc.Styles[StyleIdentifier.Quote];
sdt.Style = style;

dataDir = dataDir + "SetContentControlStyle_out.docx";
// Save the document to disk.
doc.Save(dataDir);

Arbeiten mit der Inhaltskontrolle für wiederkehrende Abschnitte

Die Inhaltssteuerung für sich wiederholende Abschnitte ermöglicht die Wiederholung des darin enthaltenen Inhalts. Mithilfe von Aspose.Words können die strukturierten Dokument-Tag-Knoten der Typen “Wiederholungsabschnitt” und “Wiederholungsabschnitt” erstellt werden. Zu diesem Zweck stellt SdtType-Aufzählungstyp RepeatingSectionItem-Eigenschaften bereit.

Das folgende Codebeispiel zeigt, wie ein sich wiederholendes Abschnittsinhaltssteuerelement an eine Tabelle gebunden wird.

// 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);

CustomXmlPart xmlPart = doc.CustomXmlParts.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 table = builder.StartTable();

builder.InsertCell();
builder.Write("Title");

builder.InsertCell();
builder.Write("Author");

builder.EndRow();
builder.EndTable();

StructuredDocumentTag repeatingSectionSdt =
    new StructuredDocumentTag(doc, SdtType.RepeatingSection, MarkupLevel.Row);
repeatingSectionSdt.XmlMapping.SetMapping(xmlPart, "/books[1]/book", "");
table.AppendChild(repeatingSectionSdt);

StructuredDocumentTag repeatingSectionItemSdt =
    new StructuredDocumentTag(doc, SdtType.RepeatingSectionItem, MarkupLevel.Row);
repeatingSectionSdt.AppendChild(repeatingSectionItemSdt);

Row row = new Row(doc);
repeatingSectionItemSdt.AppendChild(row);

StructuredDocumentTag titleSdt =
    new StructuredDocumentTag(doc, SdtType.PlainText, MarkupLevel.Cell);
titleSdt.XmlMapping.SetMapping(xmlPart, "/books[1]/book[1]/title[1]", "");
row.AppendChild(titleSdt);

StructuredDocumentTag authorSdt =
    new StructuredDocumentTag(doc, SdtType.PlainText, MarkupLevel.Cell);
authorSdt.XmlMapping.SetMapping(xmlPart, "/books[1]/book[1]/author[1]", "");
row.AppendChild(authorSdt);

doc.Save(dataDir + "Document.docx");