کار با Content Control SDT

در Microsoft Word، می‌توانید با شروع با یک الگو و اضافه کردن کنترل‌های محتوا، از جمله چک باکس، جعبه متن، انتخابگر تاریخ و لیست‌های کشویی، فرم ایجاد کنید. در Aspose.Words، یک تگ سند ساختاریافته یا کنترل محتوا از هر سندی که در Aspose.Words بارگذاری شده است، به عنوان یک گره StructuredDocumentTag وارد می شود. تگ‌های سند ساختاریافته (SDT یا کنترل محتوا) امکان تعبیه معنایی تعریف شده توسط مشتری و همچنین رفتار و ظاهر آن را در یک سند می‌دهد.

StructuredDocumentTag می تواند در یک سند در مکان های زیر رخ دهد:

• سطح بلوک - در میان پاراگراف ها و جداول، به عنوان فرزند یک Body، HeaderFooter، Comment، Footnote یا یک گره Shape
• سطح ردیف - در میان ردیف‌های یک جدول، به عنوان فرزند یک گره جدول
• سطح سلول - در میان سلول های یک ردیف جدول، به عنوان فرزند یک گره ردیف
• سطح درون خطی - در میان محتوای درون خطی داخل، به عنوان فرزند یک پاراگراف
• تو در داخل 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-.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);

مثال کد زیر نحوه ایجاد کنترل محتوا از نوع جعبه متن غنی را نشان می دهد:

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

مثال کد زیر نحوه ایجاد کنترل محتوای جعبه ترکیبی نوع را نشان می دهد:

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

نحوه به روز رسانی کنترل های محتوا

این بخش نحوه به روز رسانی مقادیر SDT یا کنترل محتوا را به صورت برنامه ای توضیح می دهد.

مثال کد زیر نحوه تنظیم وضعیت فعلی چک باکس را نشان می دهد:

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

مثال کد زیر نحوه تغییر کنترل‌های محتوا از نوع جعبه متن ساده، لیست کشویی و تصویر را نشان می‌دهد:

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

اتصال کنترل محتوا به قطعات XML سفارشی

می‌توانید کنترل‌های محتوا را با داده‌های XML (بخش XML سفارشی) در اسناد Word متصل کنید.

مثال کد زیر نحوه اتصال کنترل محتوا به قطعات XML سفارشی را نشان می دهد:

// 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 محدوده تگ سند ساختاریافته

می‌توانید نگاشت این محدوده تگ سند ساختاریافته را به داده‌های XML در بخش XML سفارشی سند فعلی با استفاده از ویژگی StructuredDocumentTagRangeStart.XmlMapping دریافت کنید. با این حال، روش SetMapping می تواند برای نگاشت محدوده تگ سند ساختاریافته به داده های XML استفاده شود.

مثال کد زیر نحوه تنظیم نگاشت XML را نشان می دهد:

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

محتویات یک کنترل محتوا را پاک کنید

می توانید محتویات یک کنترل محتوا را با نمایش مکان نگهدار پاک کنید. روش StructuredDocumentTag.Clear محتویات این تگ سند ساختاریافته را پاک می کند و در صورت تعریف، یک مکان نگهدار نمایش می دهد. با این حال، پاک کردن محتوای یک کنترل محتوا در صورتی که دارای بازبینی باشد، امکان پذیر نیست. اگر یک کنترل محتوا فاقد مکان‌نما باشد، پنج فاصله مانند Microsoft Word درج می‌شود (به جز تکرار بخش‌ها، موارد تکراری بخش، گروه‌ها، چک باکس‌ها، نقل‌قول‌ها). اگر یک کنترل محتوا به XML سفارشی نگاشت شود، گره XML ارجاع شده پاک می شود.

مثال کد زیر نحوه پاک کردن محتوای کنترل محتوا را نشان می دهد:

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

تغییر رنگ پس زمینه و حاشیه کنترل محتوا

ویژگی StructuredDocumentTag.Color به شما امکان می دهد رنگ کنترل محتوا را دریافت یا تنظیم کنید. رنگ در دو موقعیت بر کنترل محتوا تأثیر می گذارد:

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

نحوه تنظیم سبک برای قالب بندی متن تایپ شده در کنترل محتوا

اگر می خواهید سبک کنترل محتوا را تنظیم کنید، می توانید از ویژگی های StructuredDocumentTag.Style یا StructuredDocumentTag.StyleName استفاده کنید. هنگامی که متن را در کنترل محتوا در سند خروجی تایپ می کنید، متن تایپ شده دارای سبک “نقل قول” خواهد بود.

توجه داشته باشید که فقط سبک های Linked و Character را می توان برای کنترل محتوا اعمال کرد. یک InvalidOperationException (“نمی توان این سبک را در SDT اعمال کرد”) زمانی که سبکی وجود دارد که پیوند داده نشده است یا سبک کاراکتری اعمال می شود، پرتاب می شود.

مثال کد زیر نحوه تنظیم سبک کنترل محتوا را نشان می دهد:

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

کار با Repeating Section Content Control

کنترل محتوای بخش تکرار شونده امکان تکرار محتوای موجود در آن را فراهم می کند. با استفاده از Aspose.Words می توان گره های تگ سند ساختاریافته از بخش تکرار کننده و انواع آیتم های بخش تکرار شونده ایجاد کرد و برای این منظور نوع شمارش SdtType ویژگی RepeatingSectionItem را ارائه می دهد.

مثال کد زیر نشان می دهد که چگونه یک کنترل محتوای بخش تکراری را به یک جدول متصل کنید.

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