Office open xml чем открыть

У вас большие запросы!

Точнее, от вашего браузера их поступает слишком много, и сервер VK забил тревогу.

Эта страница была загружена по HTTP, вместо безопасного HTTPS, а значит телепортации обратно не будет.
Обратитесь в поддержку сервиса.

Вы отключили сохранение Cookies, а они нужны, чтобы решить проблему.

Почему-то страница не получила всех данных, а без них она не работает.
Обратитесь в поддержку сервиса.

Вы вернётесь на предыдущую страницу через 5 секунд.
Вернуться назад

Форматы Open XML и расширения имен файлов

Excel для Microsoft 365 Word для Microsoft 365 PowerPoint для Microsoft 365 Excel 2021 Word 2021 PowerPoint 2021 Office 2021 Excel 2019 Word 2019 PowerPoint 2019 Office 2019 Excel 2016 Word 2016 PowerPoint 2016 Office 2016 Excel 2013 Word 2013 PowerPoint 2013 Office 2013 Excel 2010 Word 2010 PowerPoint 2010 Office 2010 Office 2007 Еще. Меньше

Начиная с Microsoft Office 2007, в Microsoft Office используются форматы файлов на основе XML, например DOCX, XLSX и PPTX. Эти форматы и расширения имен файлов применяются к Microsoft Word, Microsoft Excel и Microsoft PowerPoint. В этой статье описаны основные преимущества формата, описаны расширения имен файлов и описано, как можно делиться файлами Office с людьми, которые используют более ранние версии Office.

Каковы преимущества форматов Open XML?

Форматы Open XML имеют множество преимуществ не только для разработчиков и их решений, но и для отдельных людей и организаций любого размера.

• Сжатие файлов Файлы сжимаются автоматически и в некоторых случаях могут быть на 75 процентов меньше. Формат Open XML использует технологию zip-сжатия для хранения документов, что позволяет сэкономить место на диске, необходимое для хранения файлов, и уменьшает пропускную способность, необходимую для отправки файлов по электронной почте, по сетям и через Интернет. Когда вы открываете файл, он автоматически обновляется. При сохранение файла он автоматически застекается снова. Для открытия и закрытия файлов в Office не нужно устанавливать специальные почтовые Office.
• Улучшенные возможности восстановления поврежденных файлов. Файлы имеют модульную структуру, поэтому различные компоненты данных файла хранятся отдельно друг от друга. Это позволяет открывать файлы даже в том случае, если компонент в файле (например, диаграмма или таблица) поврежден.
• Поддержка расширенных функций Многие из расширенных Microsoft 365 требуют, чтобы документ хранился в формате Open XML. Например, автоскрытиеи проверка доступности (вдвух примерах) можно работать только с файлами, которые хранятся в современном формате Open XML.
• Улучшенная конфиденциальность и дополнительный контроль над персональными данными. К документам можно делиться конфиденциально, так как личные сведения и конфиденциальные бизнес-данные, такие как имена авторов, комментарии, отслеживаемые изменения и пути к файлам, можно легко найти и удалить с помощью инспектора документов.
• Улучшенная интеграция и совместимость бизнес-данных. Использование форматов Open XML в качестве основы для обеспечения взаимосвязи данных в наборе продуктов Office означает, что документы, книги, презентации и формы могут быть сохранены в формате XML, который доступен для использования и лицензирования бесплатно. Office также поддерживает определяемую клиентом схему XML, улучшающую существующие Office типов документов. Это означает, что клиенты могут легко разблокировать информацию в существующих системах и действовать с ней в Office программах. Сведения, которые создаются в Office могут быть легко использованы другими бизнес-приложениями. Все, что нужно для открытия и редактирования файла Office, — это с помощью ZIP-редактора и редактора XML.
• Упрощенное обнаружение документов, содержащих макросы. Файлы, сохраненные с использованием стандартного суффикса x (например, .docx, .xlsx и .pptx), не могут содержать макрос Visual Basic для приложений (VBA) и макрос XLM. Макросами могут быть только файлы, расширение имени которых заканчивается на «m» (например, DOCM, XLSM и PPTM).

Прежде чем сохранять файл в двоичном формате, ознакомьтесь со статьей Могут ли разные версии Office одинаковыми файлами?

Как преобразовать файл из старого двоичного формата в современный формат Open XML?

Откройте файл в Приложение Office выберите файл > Сохранить как (или Сохранить копию,если файл хранится в OneDrive или SharePoint) и убедитесь, что для типа Сохранить как за установлен современный формат.

При этом будет создаваться новая копия файла в формате Open XML.

Что такое расширения имен XML-файлов?

По умолчанию документы, книги и презентации, которые вы создаете в Office, сохраняются в формате XML с расширениями имен файлов, которые добавляют «x» или «м» к уже знакомым расширениям имен файлов. Знак «x» означает XML-файл, в котором нет макроса, а «м» — XML-файл, содержащий макрос. Например, при сохранение документа в Word по умолчанию используется расширение .docx имени файла, а не .doc файла.

При сохранение файла в виде шаблона вы видите такое же изменение. Расширение шаблона, используемее в более ранних версиях, уже существует, но теперь в его конце есть «x» или «м». Если файл содержит код или макрос, его необходимо сохранить с помощью нового формата XML-файла с поддержкой макроса, который добавляет в расширение файла «м» для макроса.

В следующих таблицах перечислить все расширения имен файлов по умолчанию в Word, Excel и PowerPoint.

Understand when and how to use Office Open XML in your Word add-in

If you’re building Office Add-ins to run in Word, you might already know that the Office JavaScript API (Office.js) offers several formats for reading and writing document content. These are called coercion types, and they include plain text, tables, HTML, and Office Open XML.

Options for adding rich content

So what are your options when you need to add rich content to a document, such as images, formatted tables, charts, or even just formatted text?

1. Word JavaScript APIs. Start with the APIs available through the WordApi requirement sets to see if they provide what you need. For an example, see the Insert formatted text code snippet. You can try this and other snippets in the Script Lab add-in on Word! To learn more about Script Lab, see Explore Office JavaScript API using Script Lab.
2. HTML coercion. If APIs aren’t yet available, you can use HTML for inserting some types of rich content, such as pictures. Depending on your scenario, there can be drawbacks to HTML coercion, such as limitations in the formatting and positioning options available to your content.
3. Office Open XML. Because Office Open XML is the language in which Word documents (such as .docx and .dotx) are written, you can insert virtually any type of content that a user can add to a Word document, with virtually any type of formatting the user can apply. Determining the Office Open XML markup you need to get it done is easier than you might think.

Office Open XML is also the language behind PowerPoint and Excel (and, as of Office 2013, Visio) documents. However, currently, you can coerce content as Office Open XML only in Office Add-ins created for Word. For more information about Office Open XML, including the complete language reference documentation, see the See also section.

Download the companion code sample

Download the code sample Load and write Open XML in your Word add-in, which contains the Office Open XML markup and Office.js code required for inserting any of the following examples into Word.

Learn about content types

To begin, take a look at some of the content types you can insert using Office Open XML coercion.

Throughout this article, the terms content types and rich content refer to the types of rich content you can insert into a Word document.

Figure 1. Text with direct formatting

Use direct formatting to specify exactly what the text will look like regardless of existing formatting in the user’s document.

Figure 2. Text formatted using a style

Use a style to automatically coordinate the look of text you insert with the user’s document.

Figure 3. A simple image

Use the same method for inserting any Office-supported image format.

Figure 4. An image formatted using picture styles and effects

Adding high quality formatting and effects to your images requires much less markup than you might expect.

Figure 5. A content control

Use content controls with your add-in to add content at a specified (bound) location rather than at the selection.

Figure 6. A text box with WordArt formatting

Text effects are available in Word for text inside a text box (as shown here) or for regular body text.

Figure 7. A shape

Insert built-in or custom drawing shapes, with or without text and formatting effects.

Figure 8. A table with direct formatting

Include text formatting, borders, shading, cell sizing, or any table formatting you need.

Figure 9. A table formatted using a table style

Use built-in or custom table styles just as easily as using a paragraph style for text.

Figure 10. A SmartArt diagram

Office offers a wide array of SmartArt diagram layouts (and you can use Office Open XML to create your own).

Figure 11. A chart

You can insert Excel charts as live charts in Word documents, which also means you can use them in your add-in for Word. As you can see by the preceding examples, you can use Office Open XML coercion to insert essentially any type of content that a user can insert into their own document. There are two simple ways to get the Office Open XML markup you need. Either add your rich content to an otherwise blank Word document and then save the file in Word XML Document format or use a test add-in with the getSelectedDataAsync method to grab the markup. Both approaches provide essentially the same result.

An Office Open XML document is actually a compressed package of files that represent the document contents. Saving the file in the Word XML Document format gives you the entire Office Open XML package flattened into one XML file, which is also what you get when using getSelectedDataAsync to retrieve the Office Open XML markup.

If you save the file to an XML format from Word, note that there are two options under the Save as Type list in the Save As dialog box for .xml format files. Be sure to choose Word XML Document, not the Word 2003 option.

Download the code sample named Word-Add-in-Get-Set-EditOpen-XML, which you can use as a tool to retrieve and test your markup.

So is that all there is to it? Well, not quite. Yes, for many scenarios, you could use the full, flattened Office Open XML result you see with either of the preceding methods and it would work. The good news is that you probably don’t need most of that markup.

If you’re one of the many add-in developers seeing Office Open XML markup for the first time, trying to make sense of the massive amount of markup you get for the simplest piece of content might seem overwhelming, but it doesn’t have to be.

In this topic, you’ll use some common scenarios we’ve been hearing from the Office Add-ins developer community to show you techniques for simplifying Office Open XML for use in your add-in. We’ll explore the markup for some types of content shown earlier along with the information you need for minimizing the Office Open XML payload. We’ll also look at the code you need for inserting rich content into a document at the active selection and how to use Office Open XML with the bindings object to add or replace content at specified locations.

Explore the Office Open XML document package

When you use getSelectedDataAsync to retrieve the Office Open XML for a selection of content (or when you save the document in Word XML Document format), what you’re getting isn’t just the markup that describes your selected content; it’s an entire document with many options and settings that you almost certainly don’t need. In fact, if you use that method from a document that contains a task pane add-in, the markup you get even includes your task pane.

Even a simple Word document package includes parts for document properties, styles, theme (formatting settings), web settings, fonts, and then some, in addition to parts for the actual content.

For example, say that you want to insert just a paragraph of text with direct formatting, as shown earlier in Figure 1. When you grab the Office Open XML for the formatted text using getSelectedDataAsync , you see a large amount of markup. That markup includes a package element that represents an entire document, which contains several parts (commonly referred to as document parts or, in the Office Open XML, as package parts), as you see listed in Figure 13. Each part represents a separate file within the package.

You can edit Office Open XML markup in a text editor like Notepad. If you open it in Visual Studio, use Edit > Advanced > Format Document (Ctrl+K, Ctrl+D) to format the package for easier editing. Then you can collapse or expand document parts or sections of them, as shown in Figure 12, to more easily review and edit the content of the Office Open XML package. Each document part begins with a pkg:part tag.

Figure 12. Collapse and expand package parts for easier editing in Visual Studio

Figure 13. The parts included in a basic Word Office Open XML document package

With all that markup, you might be surprised to discover that the only elements you actually need to insert the formatted text example are pieces of the .rels part and the document.xml part.

The two lines of markup above the package tag (the XML declarations for version and Office program ID) are assumed when you use the Office Open XML coercion type, so you don’t need to include them. Keep them if you want to open your edited markup as a Word document to test it.

Several of the other types of content shown at the start of this topic require additional parts as well (beyond those shown in Figure 13), and you’ll address those later in this topic. Meanwhile, since you’ll see most of the parts shown in Figure 13 in the markup for any Word document package, here’s a quick summary of what each of these parts is for and when you need it:

• Inside the package tag, the first part is the .rels file, which defines relationships between the top-level parts of the package (these are typically the document properties, thumbnail (if any), and main document body). Some of the content in this part is always required in your markup because you need to define the relationship of the main document part (where your content resides) to the document package.
• The document.xml.rels part defines relationships for additional parts required by the document.xml (main body) part, if any.

Important The .rels files in your package (such as the top-level .rels, document.xml.rels, and others you may see for specific types of content) are an extremely important tool that you can use as a guide for helping you quickly edit down your Office Open XML package. To learn more about how to do this, see Create your own markup: best practices later in this topic.

Insert document content at the selection

Let’s take a look at the minimal Office Open XML markup required for the formatted text example shown in Figure 1 and the JavaScript required for inserting it at the active selection in the document.

Simplified Office Open XML markup

The Office Open XML example shown here was edited as described in the preceding section to leave just required document parts and only required elements within each of those parts. You’ll walk through how to edit the markup yourself (and we’ll explain a bit more about the pieces that remain here) in the next section of the topic.

                       This text has formatting directly applied to achieve its font size, color, line spacing, and paragraph spacing.        

If you add the markup shown here to an XML file along with the XML declaration tags for version and mso-application at the top of the file (shown in Figure 13), you can open it in Word as a Word document. Or, without those tags, you can still open it using File > Open in Word. You’ll see Compatibility Mode on the title bar in Word, because you removed the settings that tell Word this is a Word document. Since you’re adding this markup to an existing Word document, that won’t affect your content at all.

JavaScript for using setSelectedDataAsync

Once you save the preceding Office Open XML as an XML file that’s accessible from your solution, use the following function to set the formatted text content in the document using Office Open XML coercion.

In the following function, notice that all but the last line are used to get your saved markup for use in the setSelectedDataAsync method call at the end of the function. setSelectedDataASync requires only that you specify the content to be inserted and the coercion type.

Replace yourXMLfilename with the name and path of the XML file as you’ve saved it in your solution. If you aren’t sure where to include XML files in your solution or how to reference them in your code, see the Load and write Open XML in your Word add-in code sample for examples of that and a working example of the markup and JavaScript shown here.

function writeContent() < const myOOXMLRequest = new XMLHttpRequest(); let myXML; myOOXMLRequest.open('GET', 'yourXMLfilename', false); myOOXMLRequest.send(); if (myOOXMLRequest.status === 200) < myXML = myOOXMLRequest.responseText; >Office.context.document.setSelectedDataAsync(myXML, < coercionType: 'ooxml' >); > 

Create your own markup: best practices

Let’s take a closer look at the markup you need to insert the preceding formatted text example.

For this example, start by simply deleting all document parts from the package other than .rels and document.xml. Then, you’ll edit those two required parts to simplify things further.

Use the .rels parts as a map to quickly gauge what’s included in the package and determine what parts you can delete completely (that is, any parts not related to or referenced by your content). Remember that every document part must have a relationship defined in the package and those relationships appear in the .rels files. So you should see all of them listed in either .rels, document.xml.rels, or a content-specific .rels file.

The following markup shows the required .rels part before editing. Since we’re deleting the add-in and core document property parts, and the thumbnail part, you need to delete those relationships from .rels as well. Notice that this will leave only the relationship (with the relationship ID «rID1» in the following example) for document.xml.

Remove the relationships (that is, the Relationship tag) for any parts that you completely remove from the package. Including a part without a corresponding relationship, or excluding a part and leaving its relationship in the package, will result in an error.

The following markup shows the document.xml part, which includes our sample formatted text content before editing.

                This text has formatting directly applied to achieve its font size, color, line spacing, and paragraph spacing.             

Since document.xml is the primary document part where you place your content, take a quick walk through that part. (Figure 14, which follows this list, provides a visual reference to show how some of the core content and formatting tags explained here relate to what you see in a Word document.)

The opening w:document tag includes several namespace ( xmlns ) listings. Many of those namespaces refer to specific types of content and you only need them if they’re relevant to your content. Notice that the prefix for the tags throughout a document part refers back to the namespaces. In this example, the only prefix used in the tags throughout the document.xml part is w:, so the only namespace that you need to leave in the opening w:document tag is xmlns:w.

Tip If you’re editing your markup in Visual Studio, after you delete namespaces in any part, look through all tags of that part. If you’ve removed a namespace that’s required for your markup, you’ll see a red squiggly underline on the relevant prefix for affected tags. If you remove the xmlns:mc namespace, you must also remove the mc:Ignorable attribute that precedes the namespace listings.

Figure 14. How common tags in document.xml relate to the content and layout of a Word document

In markup you create, you might see another attribute in several tags that includes the characters w:rsid, which you don’t see in the examples used in this topic. These are revision identifiers. They’re used in Word for the Combine Documents feature and they’re on by default. You’ll never need them in markup you’re inserting with your add-in and turning them off makes for much cleaner markup. You can easily remove existing RSID tags or disable the feature (as described in the following procedure) so that they aren’t added to your markup for new content.

Be aware that if you use the co-authoring capabilities in Word (such as the ability to simultaneously edit documents with others), you should enable the feature again when finished generating the markup for your add-in.

To turn off RSID attributes in Word for documents you create going forward, do the following:

1. In Word, choose File and then choose Options.
2. In the Word Options dialog box, choose Trust Center and then choose Trust Center Settings.
3. In the Trust Center dialog box, choose Privacy Options and then disable the setting Store random numbers to improve Combine accuracy. Note that this setting may not be available in newer versions of Word.

To remove RSID tags from an existing document, try the following shortcut with the document open in Office Open XML.

1. With your insertion point in the main body of the document, press Ctrl+Home to go to the top of the document.
2. On the keyboard, press Spacebar, Delete, Spacebar. Then, save the document.

After removing the majority of the markup from this package, you’re left with the minimal markup that needs to be inserted for the sample, as shown in the preceding section.

Use the same Office Open XML structure for different content types

Several types of rich content require only the .rels and document.xml components shown in the preceding example, including content controls, Office drawing shapes and text boxes, and tables (unless a style is applied to the table). In fact, you can reuse the same edited package parts and swap out just the body content in document.xml for the markup of your content.

To check out the Office Open XML markup for the examples of each of these content types shown earlier in Figures 5 through 8, explore the Load and write Open XML in your Word add-in code sample referenced in the overview section.

Before you move on, take a look at differences to note for a couple of these content types and how to swap out the pieces you need.

Understand drawingML markup (Office graphics) in Word

If the markup for your shape or text box looks far more complex than you would expect, there’s a reason for it. With the release of Office 2007, we saw the introduction of the Office Open XML Formats as well as the introduction of a new Office graphics engine that PowerPoint and Excel fully adopted. In the 2007 release, Word only incorporated part of that graphics engine, adopting the updated Excel charting engine, SmartArt graphics, and advanced picture tools. For shapes and text boxes, Word 2007 continued to use legacy drawing objects (VML). It was in the 2010 release that Word took the additional steps with the graphics engine to incorporate updated shapes and drawing tools.

Typically, as you see for the shape and text box examples included in the Load and write Open XML in your Word add-in code sample, the fallback markup can be removed. Word automatically adds missing fallback markup to shapes when a document is saved. However, if you prefer to keep the fallback markup to ensure that you’re supporting all user scenarios, there’s no harm in retaining it.

If you have grouped drawing objects included in your content, you’ll see additional (and apparently repetitive) markup, but this must be retained. Portions of the markup for drawing shapes are duplicated when the object is included in a group.

When working with text boxes and drawing shapes, be sure to check namespaces carefully before removing them from document.xml. (Or, if you’re reusing markup from another object type, be sure to add back any required namespaces you might have previously removed from document.xml.) A substantial portion of the namespaces included by default in document.xml are there for drawing object requirements.

About graphic positioning

In the code samples Load and write Open XML in your Word add-in and Word-Add-in-Get-Set-EditOpen-XML, the text box and shape are set up using different types of text wrapping and positioning settings. (Also be aware that the image examples in those code samples are set up using in line with text formatting, which positions a graphic object on the text baseline.)

The shape in those code samples is positioned relative to the right and bottom page margins. Relative positioning lets you more easily coordinate with a user’s unknown document setup because it will adjust to the user’s margins and run less risk of looking awkward because of paper size, orientation, or margin settings. To retain relative positioning settings when you insert a graphic object, you must retain the paragraph mark (w:p) in which the positioning (known in Word as an anchor) is stored. If you insert the content into an existing paragraph mark rather than including your own, you may be able to retain the same initial visual, but many types of relative references that enable the positioning to automatically adjust to the user’s layout may be lost.

Work with content controls

Content controls are an important feature in Word that can greatly enhance the power of your add-in for Word in multiple ways, including giving you the ability to insert content at designated places in the document rather than only at the selection.

In Word, find content controls on the Developer tab of the ribbon, as shown here in Figure 15.

Figure 15. The Controls group on the Developer tab in Word

Types of content controls in Word include rich text, plain text, picture, building block gallery, check box, dropdown list, combo box, date picker, and repeating section.

• Use the Properties command, shown in Figure 15, to edit the title of the control and to set preferences such as hiding the control container.
• Enable Design Mode to edit placeholder content in the control.

If your add-in works with a Word template, you can include controls in that template to enhance the behavior of the content. You can also use XML data binding in a Word document to bind content controls to data, such as document properties, for easy form completion or similar tasks. (Find controls that are already bound to built-in document properties in Word on the Insert tab, under Quick Parts.)

When you use content controls with your add-in, you can also greatly expand the options for what your add-in can do using a different type of binding. You can bind to a content control from within the add-in and then write content to the binding rather than to the active selection.

Don’t confuse XML data binding in Word with the ability to bind to a control via your add-in. These are completely separate features. However, you can include named content controls in the content you insert via your add-in using OOXML coercion and then use code in the add-in to bind to those controls.

Also be aware that both XML data binding and Office.js can interact with custom XML parts in your app, so it’s possible to integrate these powerful tools. To learn about working with custom XML parts in the Office JavaScript API, see the See also section of this topic.

Working with bindings in your Word add-in is covered in the next section of this topic. First, take a look at an example of the Office Open XML required for inserting a rich text content control that you can bind to using your add-in.

Rich text controls are the only type of content control you can use to bind to a content control from within your add-in.

                     [This text is inside a content control that has its container hidden. You can bind to a content control to add or interact with content at a specified location in the document.]          

As already mentioned, content controls, like formatted text, don’t require additional document parts, so only edited versions of the .rels and document.xml parts are included here.

The w:sdt tag that you see within the document.xml body represents the content control. If you generate the Office Open XML markup for a content control, you’ll see that several attributes have been removed from this example, including the tag and document part properties. Only essential (and a couple of best practice) elements have been retained, including the following:

• The alias is the title property from the Content Control Properties dialog box in Word. This is a required property (representing the name of the item) if you plan to bind to the control from within your add-in.
• The unique id is a required property. If you bind to the control from within your add-in, the ID is the property the binding uses in the document to identify the applicable named content control.
• The appearance attribute is used to hide the control container, for a cleaner look. This feature was introduced in Word 2013, as you see by the use of the w15 namespace. Because this property is used, the w15 namespace is retained at the start of the document.xml part.
• The showingPlcHdr attribute is an optional setting that sets the default content you include inside the control (text in this example) as placeholder content. So, if the user clicks or taps in the control area, the entire content is selected rather than behaving like editable content in which the user can make changes.
• Although the empty paragraph mark ( w:p/ ) that precedes the sdt tag isn’t required for adding a content control (and will add vertical space above the control in the Word document), it ensures that the control is placed in its own paragraph. This may be important, depending upon the type and formatting of content that will be added in the control.
• If you intend to bind to the control, the default content for the control (what’s inside the sdtContent tag) must include at least one complete paragraph (as in this example), in order for your binding to accept multi-paragraph rich content.

The document part attribute that was removed from this sample w:sdt tag may appear in a content control to reference a separate part in the package where placeholder content information can be stored (parts located in a glossary directory in the Office Open XML package). Although document part is the term used for XML parts (that is, files) within an Office Open XML package, the term document parts as used in the sdt property refers to the same term in Word that’s used to describe some content types including building blocks and document property quick parts (for example, built-in XML data-bound controls). If you see parts under a glossary directory in your Office Open XML package, you may need to retain them if the content you’re inserting includes these features. For a typical content control that you intend to use to bind to from your add-in, they aren’t required. Just remember that, if you do delete the glossary parts from the package, you must also remove the document part attribute from the w:sdt tag.

The next section will discuss how to create and use bindings in your Word add-in.

Insert content at a designated location

You’ve already looked at how to insert content at the active selection in a Word document. If you bind to a named content control that’s in the document, you can insert any of the same content types into that control.

So when might you want to use this approach?

• When you need to add or replace content at specified locations in a template, such as to populate portions of the document from a database.
• When you want the option to replace content that you’re inserting at the active selection, such as to provide design element options to the user.
• When you want the user to add data in the document that you can access for use with your add-in, such as to populate fields in the task pane based upon information the user adds in the document.

Download the code sample Word-Add-in-JavaScript-AddPopulateBindings, which provides a working example of how to insert and bind to a content control, and how to populate the binding.

Add and bind to a named content control

As you examine the JavaScript that follows, consider these requirements:

• As previously mentioned, you must use a rich text content control in order to bind to the control from your Word add-in.
• The content control must have a name (this is the Title field in the Content Control Properties dialog box, which corresponds to the Alias tag in the Office Open XML markup). This is how the code identifies where to place the binding.
• You can have several named controls and bind to them as needed. Use a unique content control name, unique content control ID, and a unique binding ID.

function addAndBindControl() < Office.context.document.bindings.addFromNamedItemAsync("MyContentControlTitle", "text", < id: 'myBinding' >, function (result) < if (result.status == "failed") < if (result.error.message == "The named item does not exist.") const myOOXMLRequest = new XMLHttpRequest(); let myXML; myOOXMLRequest.open('GET', '../../Snippets_BindAndPopulate/ContentControl.xml', false); myOOXMLRequest.send(); if (myOOXMLRequest.status === 200) < myXML = myOOXMLRequest.responseText; >Office.context.document.setSelectedDataAsync(myXML, < coercionType: 'ooxml' >, function (result) < Office.context.document.bindings.addFromNamedItemAsync("MyContentControlTitle", "text", < id: 'myBinding' >); >); > >); > 

The code shown here takes the following steps.

• Attempts to bind to the named content control, using addFromNamedItemAsync. Take this step first if there’s a possible scenario for your add-in where the named control could already exist in the document when the code runs. For example, you’ll want to do this if the add-in was inserted into and saved with a template that’s been designed to work with the add-in, where the control was placed in advance. You also need to do this if you need to bind to a control that was placed earlier by the add-in.
• The callback in the first call to the addFromNamedItemAsync method checks the status of the result to see if the binding failed because the named item doesn’t exist in the document (that is, the content control named MyContentControlTitle in this example). If so, the code adds the control at the active selection point (using setSelectedDataAsync ) and then binds to it.

As mentioned earlier and shown in the preceding code, the name of the content control is used to determine where to create the binding. However, in the Office Open XML markup, the code adds the binding to the document using both the name and the ID attribute of the content control.

After running code, if you examine the markup of the document in which your add-in created bindings, you’ll see two parts to each binding. In the markup for the content control where a binding was added (in document.xml), you’ll see the attribute w15:webExtensionLinked/.

In the document part named webExtensions1.xml, you’ll see a list of the bindings you’ve created. Each is identified using the binding ID and the ID attribute of the applicable control, such as the following, where the appref attribute is the content control ID: we:binding type=»text» appref=»1382295294″/.

You must add the binding at the time you intend to act upon it. Don’t include the markup for the binding in the Office Open XML for inserting the content control because the process of inserting that markup will strip the binding.

Populate a binding

The code for writing content to a binding is similar to that for writing content to a selection.

function populateBinding(filename) < const myOOXMLRequest = new XMLHttpRequest(); let myXML; myOOXMLRequest.open('GET', filename, false); myOOXMLRequest.send(); if (myOOXMLRequest.status === 200) < myXML = myOOXMLRequest.responseText; >Office.select("bindings#myBinding").setDataAsync(myXML, < coercionType: 'ooxml' >); > 

As with setSelectedDataAsync , you specify the content to be inserted and the coercion type. The only additional requirement for writing to a binding is to identify the binding by ID. Notice how the binding ID used in this code (bindings#myBinding) corresponds to the binding ID established (myBinding) when the binding was created in the previous function.

The preceding code is all you need whether you are initially populating or replacing the content in a binding. When you insert a new piece of content at a bound location, the existing content in that binding is automatically replaced. Check out an example of this in the previously-referenced code sample Word-Add-in-JavaScript-AddPopulateBindings, which provides two separate content samples that you can use interchangeably to populate the same binding.

Add objects that use additional Office Open XML parts

Many types of content require additional document parts in the Office Open XML package, meaning that they either reference information in another part or the content itself is stored in one or more additional parts and referenced in document.xml.

For example, consider the following:

• Content that uses styles for formatting (such as the styled text shown earlier in Figure 2 or the styled table shown in Figure 9) requires the styles.xml part.
• Images (such as those shown in Figures 3 and 4) include the binary image data in one (and sometimes two) additional parts.
• SmartArt diagrams (such as the one shown in Figure 10) require multiple additional parts to describe the layout and content.
• Charts (such as the one shown in Figure 11) require multiple additional parts, including their own relationship (.rels) part.

You can see edited examples of the markup for all of these content types in the previously-referenced code sample Load and write Open XML in your Word add-in. You can insert all of these content types using the same JavaScript code shown earlier (and provided in the referenced code samples) for inserting content at the active selection and writing content to a specified location using bindings.

Remember, if you’re retaining any additional parts referenced in document.xml, you will need to retain document.xml.rels and the relationship definitions for the applicable parts you’re keeping, such as styles.xml or an image file.

Before you explore the samples, take a look at a few tips for working with each of these content types.

Working with styles

The same approach to editing the markup that you looked at for the preceding example with directly-formatted text applies when using paragraph styles or table styles to format your content. However, the markup for working with paragraph styles is considerably simpler, so that’s the example described here.

Editing the markup for content using paragraph styles

The following markup represents the body content for the styled text example shown in Figure 2.

     This text is formatted using the Heading 1 paragraph style.    

As you see, the markup for formatted text in document.xml is considerably simpler when you use a style, because the style contains all of the paragraph and font formatting that you otherwise need to reference individually. However, as explained earlier, you might want to use styles or direct formatting for different purposes: use direct formatting to specify the appearance of your text regardless of the formatting in the user’s document; use a paragraph style (particularly a built-in paragraph style name, such as Heading 1 shown here) to have the text formatting automatically coordinate with the user’s document.

Use of a style is a good example of how important it is to read and understand the markup for the content you’re inserting, because it isn’t explicit that another document part is referenced here. If you include the style definition in this markup and don’t include the styles.xml part, the style information in document.xml will be ignored regardless of whether or not that style is in use in the user’s document.

However, if you take a look at the styles.xml part, you’ll see that only a small portion of this long piece of markup is required when editing markup for use in your add-in:

• The styles.xml part includes several namespaces by default. If you are only retaining the required style information for your content, in most cases you only need to keep the xmlns:w namespace.
• The w:docDefaults tag content that falls at the top of the styles part will be ignored when your markup is inserted via the add-in and can be removed.
• The largest piece of markup in a styles.xml part is for the w:latentStyles tag that appears after docDefaults, which provides information (such as appearance attributes for the Styles pane and Styles gallery) for every available style. This information is also ignored when inserting content via your add-in and so it can be removed.
• Following the latent styles information, you see a definition for each style in use in the document from which you’re markup was generated. This includes some default styles that are in use when you create a new document and may not be relevant to your content. You can delete the definitions for any styles that aren’t used by your content. Each built-in heading style has an associated Char style that’s a character style version of the same heading format. Unless you’ve applied the heading style as a character style, you can remove it. If the style is used as a character style, it appears in document.xml in a run properties tag ( w:rPr ) rather than a paragraph properties ( w:pPr ) tag. This should only be the case if you’ve applied the style to just part of a paragraph, but it can occur inadvertently if the style was incorrectly applied.
• If you’re using a built-in style for your content, you don’t have to include a full definition. You only must include the style name, style ID, and at least one formatting attribute in order for the coerced Office Open XML to apply the style to your content upon insertion. However, it’s a best practice to include a complete style definition (even if it’s the default for built-in styles). If a style is already in use in the destination document, your content will take on the resident definition for the style, regardless of what you include in styles.xml. If the style isn’t yet in use in the destination document, your content will use the style definition you provide in the markup.

So, for example, the only content you needed to retain from the styles.xml part for the sample text shown in Figure 2, which is formatted using Heading 1 style, is the following:

A complete Word definition for the Heading 1 style has been retained in this example.

Edit the markup for content using table styles

When your content uses a table style, you need the same relative part of styles.xml as described for working with paragraph styles. That is, you only need to retain the information for the style you’re using in your content, and you must include the name, ID, and at least one formatting attribute, but are better off including a complete style definition to address all potential user scenarios.

However, when you look at the markup both for your table in document.xml and for your table style definition in styles.xml, you see enormously more markup than when working with paragraph styles.

• In document.xml, formatting is applied by cell even if it’s included in a style. Using a table style won’t reduce the volume of markup. The benefit of using table styles for the content is for easy updating and easily coordinating the look of multiple tables.
• In styles.xml, you’ll see a substantial amount of markup for a single table style as well, because table styles include several types of possible formatting attributes for each of several table areas, such as the entire table, heading rows, odd and even banded rows and columns (separately), the first column, etc.

Work with images

The markup for an image includes a reference to at least one part that includes the binary data to describe your image. For a complex image, this can be hundreds of pages of markup and you can’t edit it. Since you don’t ever have to touch the binary parts, you can simply collapse it if you’re using a structured editor such as Visual Studio, so that you can still easily review and edit the rest of the package.

If you check out the example markup for the simple image shown earlier in Figure 3, available in the previously-referenced code sample Load and write Open XML in your Word add-in, you’ll see that the markup for the image in document.xml includes size and position information as well as a relationship reference to the part that contains the binary image data. That reference is included in the a:blip tag, as follows:

Be aware that, because a relationship reference is explicitly used ( r:embed=»rID4″ ) and that related part is required in order to render the image, if you don’t include the binary data in your Office Open XML package, you’ll get an error. This is different from styles.xml, explained previously, which won’t throw an error if omitted since the relationship isn’t explicitly referenced and the relationship is to a part that provides attributes to the content (formatting) rather than being part of the content itself.

When you review the markup, notice the additional namespaces used in the a:blip tag. You’ll see in document.xml that the xlmns:a namespace (the main drawingML namespace) is dynamically placed at the beginning of the use of drawingML references rather than at the top of the document.xml part. However, the relationships namespace (r) must be retained where it appears at the start of document.xml. Check your picture markup for additional namespace requirements. Remember that you don’t have to memorize which types of content require what namespaces, you can easily tell by reviewing the prefixes of the tags throughout document.xml.

Understanding additional image parts and formatting

When you use some Office picture formatting effects on your image, such as for the image shown in Figure 4, which uses adjusted brightness and contrast settings (in addition to picture styling), a second binary data part for an HD format copy of the image data may be required. This additional HD format is required for formatting considered a layering effect, and the reference to it appears in document.xml similar to the following:

See the required markup for the formatted image shown in Figure 4 (which uses layering effects among others) in the Load and write Open XML in your Word add-in code sample.

Work with SmartArt diagrams

A SmartArt diagram has four associated parts, but only two are always required. You can examine an example of SmartArt markup in the Load and write Open XML in your Word add-in code sample. First, take a look at a brief description of each of the parts and why they are or aren’t required:

If your content includes more than one diagram, they will be numbered consecutively, replacing the ‘1’ in the file names listed here.

• layout1.xml: This part is required. It includes the markup definition for the layout appearance and functionality.
• data1.xml: This part is required. It includes the data in use in your instance of the diagram.
• drawing1.xml: This part isn’t always required but if you apply custom formatting to elements in your instance of a diagram, such as directly formatting individual shapes, you might need to retain it.
• colors1.xml: This part isn’t required. It includes color style information, but the colors of your diagram will coordinate by default with the colors of the active formatting theme in the destination document, based on the SmartArt color style you apply from the SmartArt Tools design tab in Word before saving out your Office Open XML markup.
• quickStyles1.xml: This part isn’t required. Similar to the colors part, you can remove this as your diagram will take on the definition of the applied SmartArt style that’s available in the destination document (that is, it will automatically coordinate with the formatting theme in the destination document).

The SmartArt layout1.xml file is a good example of places you may be able to further trim your markup but mightn’t be worth the extra time to do so (because it removes such a small amount of markup relative to the entire package). If you would like to get rid of every last line you can of markup, you can delete the dgm:sampData tag and its contents. This sample data defines how the thumbnail preview for the diagram will appear in the SmartArt styles galleries. However, if it’s omitted, default sample data is used.

Be aware that the markup for a SmartArt diagram in document.xml contains relationship ID references to the layout, data, colors, and quick styles parts. You can delete the references in document.xml to the colors and styles parts when you delete those parts and their relationship definitions (and it’s certainly a best practice to do so, since you’re deleting those relationships), but you won’t get an error if you leave them, since they aren’t required for your diagram to be inserted into a document. Find these references in document.xml in the dgm:relIds tag. Regardless of whether or not you take this step, retain the relationship ID references for the required layout and data parts.

Work with charts

Similar to SmartArt diagrams, charts contain several additional parts. However, the setup for charts is a bit different from SmartArt, in that a chart has its own relationship file. Following is a description of required and removable document parts for a chart.

As with SmartArt diagrams, if your content includes more than one chart, they will be numbered consecutively, replacing the ‘1’ in the file names listed here.

• In document.xml.rels, you’ll see a reference to the required part that contains the data that describes the chart (chart1.xml).
• You also see a separate relationship file for each chart in your Office Open XML package, such as chart1.xml.rels. There are three files referenced in chart1.xml.rels, but only one is required. These include the binary Excel workbook data (required) and the color and style parts (colors1.xml and styles1.xml) that you can remove.

Charts that you can create and edit natively in Word are Excel charts, and their data is maintained on an Excel worksheet that’s embedded as binary data in your Office Open XML package. Like the binary data parts for images, this Excel binary data is required, but there’s nothing to edit in this part. So you can just collapse the part in the editor to avoid having to manually scroll through it all to examine the rest of your Office Open XML package.

However, similar to SmartArt, you can delete the colors and styles parts. If you’ve used the chart styles and color styles available in to format your chart, the chart will take on the applicable formatting automatically when it’s inserted into the destination document.

See the edited markup for the example chart shown in Figure 11 in the Load and write Open XML in your Word add-in code sample.

Edit the Office Open XML for use in your task pane add-in

You’ve already seen how to identify and edit the content in your markup. If the task still seems difficult when you take a look at the massive Office Open XML package generated for your document, following is a quick summary of recommended steps to help you edit that package down quickly.

Remember that you can use all .rels parts in the package as a map to quickly check for document parts that you can remove.

1. Open the flattened XML file in Visual Studio and press Ctrl+K, Ctrl+D to format the file. Then use the collapse/expand buttons on the left to collapse the parts you know you need to remove. You might also want to collapse long parts you need, but know you won’t need to edit (such as the base64 binary data for an image file), making the markup faster and easier to visually scan.
2. There are several parts of the document package that you can almost always remove when you are preparing Office Open XML markup for use in your add-in. You might want to start by removing these (and their associated relationship definitions), which will greatly reduce the package right away. These include the theme1, fontTable, settings, webSettings, thumbnail, both the core and add-in properties files, and any taskpane or webExtension parts.
3. Remove any parts that don’t relate to your content, such as footnotes, headers, or footers that you don’t require. Again, remember to also delete their associated relationships.
4. Review the document.xml.rels part to see if any files referenced in that part are required for your content, such as an image file, the styles part, or SmartArt diagram parts. Delete the relationships for any parts your content doesn’t require and confirm that you have also deleted the associated part. If your content doesn’t require any of the document parts referenced in document.xml.rels, you can delete that file also.
5. If your content has an additional .rels part (such as chart#.xml.rels), review it to see if there are other parts referenced there that you can remove (such as quick styles for charts) and delete both the relationship from that file as well as the associated part.
6. Edit document.xml to remove namespaces not referenced in the part, section properties if your content doesn’t include a section break, and any markup that isn’t related to the content that you want to insert. If inserting shapes or text boxes, you might also want to remove extensive fallback markup.
7. Edit any additional required parts where you know that you can remove substantial markup without affecting your content, such as the styles part.

After you’ve taken the preceding seven steps, you’ve likely cut between about 90 and 100 percent of the markup you can remove, depending on your content. In most cases, this is likely to be as far as you want to trim.

Regardless of whether you leave it here or choose to delve further into your content to find every last line of markup you can cut, remember that you can use the previously-referenced code sample Word-Add-in-Get-Set-EditOpen-XML as a scratch pad to quickly and easily test your edited markup.

If you update an Office Open XML snippet in an existing solution while developing, clear temporary Internet files before you run the solution again to update the Office Open XML used by your code. Markup that’s included in your solution in XML files is cached on your computer. You can, of course, clear temporary Internet files from your default web browser. To access Internet options and delete these settings from inside Visual Studio 2019, on the Debug menu, choose Options. Then, under Environment, choose Web Browser and then choose Internet Explorer Options.

Create an add-in for both template and standalone use

In this topic, you’ve seen several examples of what you can do with Office Open XML in your add-ins. You’ve looked at a wide range of rich content type examples that you can insert into documents by using the Office Open XML coercion type, together with the JavaScript methods for inserting that content at the selection or to a specified (bound) location.

So, what else do you need to know if you’re creating your add-in both for standalone use (that is, inserted from the Store or a proprietary server location) and for use in a pre-created template that’s designed to work with your add-in? The answer might be that you already know all you need.

The markup for a given content type and methods for inserting it are the same whether your add-in is designed to standalone or work with a template. If you are using templates designed to work with your add-in, just be sure that your JavaScript includes callbacks that account for scenarios where referenced content might already exist in the document (such as demonstrated in the binding example shown in the section Add and bind to a named content control).

When using templates with your app, whether the add-in will be resident in the template at the time that the user created the document or the add-in will be inserting a template, you might also want to incorporate other elements of the API to help you create a more robust, interactive experience. For example, you may want to include identifying data in a customXML part that you can use to determine the template type in order to provide template-specific options to the user. To learn more about how to work with custom XML in your add-ins, see the additional resources that follow.

See also

• Office JavaScript API
• The complete language reference and related documentation on Open XML: Standard ECMA-376: Office Open XML File Formats
• Explore Office JavaScript API using Script Lab
• Exploring the Office JavaScript API: Data Binding and Custom XML Parts
• Companion code sample: Load and write Open XML in your Word add-in
• Other code samples referenced in this article:
  • Word-Add-in-Get-Set-EditOpen-XML
  • Word-Add-in-JavaScript-AddPopulateBindings

  Узнайте, когда и как использовать Office Open XML в надстройке Word

  Если вы создаете надстройки Office для запуска в Word, возможно, вы уже знаете, что API JavaScript для Office (Office.js) предлагает несколько форматов для чтения и написания содержимого документов. Они называются типами приведения, и к ним относятся обычный текст, таблицы, HTML и Office Open XML.

  Параметры добавления полнофункционированного содержимого

  Итак, что вы можете сделать, если вам нужно добавить в документ форматированный контент, например изображения, форматированные таблицы, диаграммы или просто форматированный текст?

  1. Word API JavaScript. Начните с API- интерфейсов, доступных через наборы требований WordApi , чтобы узнать, предоставляют ли они необходимые вам возможности. Пример см. в разделе Вставка фрагмента кода форматированного текста . Вы можете попробовать этот и другие фрагменты в надстройке Script Lab на Word! Дополнительные сведения о Script Lab см. в статье Изучение API JavaScript для Office с помощью Script Lab.
  2. Приведение HTML. Если API еще не доступны, вы можете использовать HTML для вставки некоторых типов полнофункционированного содержимого, например изображений. В некоторых случаях вам может быть недостаточно возможностей форматирования и размещения содержимого, предоставляемых HTML.
  3. Office Open XML. Так как Office Open XML — это язык документов Word (например, DOCX и DOTX), вы можете вставить практически любое содержимое, которое пользователь может добавить в документ Word, с практически любым форматированием. Определить необходимую разметку Office Open XML проще, чем кажется.

  Office Open XML — это также язык документов PowerPoint и Excel (а начиная с Office 2013 — и документов Visio). However, currently, you can coerce content as Office Open XML only in Office Add-ins created for Word. Дополнительные сведения об Office Open XML, включая полную справочную документацию по языку, см. в разделе См. также .

  Скачивание примера сопутствующего кода

  Скачайте пример кода. Загрузите и напишите Open XML в надстройке Word, которая содержит разметку Office Open XML и Office.js код, необходимый для вставки любого из следующих примеров в Word.

  Сведения о типах контента

  Для начала ознакомьтесь с некоторыми типами содержимого, которые можно вставить с помощью приведения Office Open XML.

  В этой статье термины типы контента и форматированный контент относятся к типам полнофункционированного содержимого, которые можно вставить в документ Word.

  Рис. 1. текст с прямым форматированием;

  

  Используйте прямое форматирование, чтобы указать, как именно будет выглядеть текст независимо от существующего форматирования в документе пользователя.

  Рис. 2. Текст, отформатированный с использованием стиля

  

  Используйте стиль, чтобы автоматически координировать внешний вид текста, который вы вставляете с документом пользователя.

  Рис. 3. Простое изображение

  

  Используйте тот же метод для вставки любого формата изображений, поддерживаемого Office.

  Рис. 4. Изображение, отформатируемое с помощью стилей и эффектов рисунков

  

  Для добавления высококачественного форматирования и эффектов к изображениям требуется намного меньше разметки, чем можно было бы ожидать.

  Рис. 5. Элемент управления содержимым

  

  Используйте элементы управления содержимым с надстройкой, чтобы добавлять содержимое в указанное (привязанное) расположение, а не в выделенное.

  Рисунок 6. Текстовое поле с форматированием WordArt

  

  В Word доступны эффекты для текста в текстовых полях (как показано здесь) и обычного текста документа.

  

  Вставка встроенных или настраиваемых фигур рисования с текстом и эффектами форматирования или без нее.

  Рис. 8. Таблица с прямым форматированием

  

  Включите форматирование текста, границы, заливку, изменение размера ячейки или любое необходимое форматирование таблицы.

  Рис 9. Таблица, отформатированная с использованием стиля таблицы

  

  Используйте встроенные или настраиваемые стили таблиц так же легко, как и стиль абзаца для текста.

  Рис. 10. Схема SmartArt

  

  Office предлагает широкий набор макетов схем SmartArt (и вы можете использовать Office Open XML для создания собственных).

  Рис. 11. Диаграмма

  

  Диаграммы Excel можно вставлять в виде динамических диаграмм в Word документах, что также означает, что их можно использовать в надстройке для Word. Как видно из предыдущих примеров, вы можете использовать приведение Office Open XML для вставки содержимого практически любого типа, которое пользователь может вставить в свой собственный документ. Существует два простых способа получить нужную разметку Office Open XML. Добавьте многофункциональное содержимое в пустой Word документ, а затем сохраните файл в формате XML-документа Word или используйте тестовую надстройку с методом getSelectedDataAsync, чтобы получить разметку. Оба подхода дают одинаковые результаты.

  Документ Office Open XML на самом деле представляет собой сжатый пакет файлов, представляющих содержимое документа. При сохранении файла в формате XML-документа Word весь пакет Office Open XML преобразуется в один XML-файл, что также можно получить при использовании getSelectedDataAsync для получения разметки Office Open XML.

  Обратите внимание, что в списке «Тип файла» из диалогового окна «Сохранение документа» в Word есть два варианта формата XML. Не забудьте выбрать Word XML-документ, а не параметр Word 2003.

  Скачайте пример кода под названием Word-Add-in-Get-Set-EditOpen-XML, с помощью которого можно получить и проверить разметку.

  Итак, это все? Не совсем. Да, в большинстве случаев можно успешно использовать полный плоский результат Office Open XML, обеспечиваемый любым из вышеописанных способов. Скорее всего, вам не понадобится большая часть этой разметки.

  На первый взгляд объем разметки Office Open XML даже для простого содержимого может показаться огромным, но не стоит переживать.

  В этом разделе вы будете использовать некоторые распространенные сценарии, которые мы слышали от сообщества разработчиков надстроек Office, чтобы показать вам методы упрощения Office Open XML для использования в надстройке. Мы рассмотрим разметку для некоторых типов содержимого, показанных выше, а также сведения, необходимые для минимизации полезных данных Office Open XML. Мы также рассмотрим код, необходимый для вставки мультимедиа в документ в выделенном месте, и использование Office Open XML с объектом bindings для добавления или замены содержимого в указанных местах.

  Изучение пакета документов Office Open XML

  Если вы используете getSelectedDataAsync для получения Office Open XML для выбора содержимого (или при сохранении документа в формате XML-документа Word), вы получаете не только разметку, описывающую выбранное содержимое; это целый документ с множеством параметров и параметров, которые почти наверняка не нужны. Если вы используете этот метод из документа, содержащего надстройку области задач, полученная разметка будет включать даже область задач.

  Даже простой пакет документа Word, помимо основного содержимого, включает свойства, стили, тему (параметры форматирования), веб-параметры, шрифты документа и другие части.

  Предположим, вам нужно вставить всего лишь абзац текста с прямым форматированием, как показано на рисунке 1. При захвате Office Open XML для отформатированного текста с помощью getSelectedDataAsync отображается большой объем разметки. Она включает элемент package, который представляет весь документ и содержит несколько частей (обычно называемые частями документа или, в Office Open XML, частями пакета), как показано на рисунке 13. Каждая часть представляет отдельный файл в пакете.

  Вы можете изменить разметку Office Open XML в текстовом редакторе, например в Блокноте. Если вы открываете его в Visual Studio, используйте команду Изменить> документрасширенного>формата (CTRL+K, CTRL+D), чтобы отформатировать пакет для упрощения редактирования. Then you can collapse or expand document parts or sections of them, as shown in Figure 12, to more easily review and edit the content of the Office Open XML package. Each document part begins with a pkg:part tag.

  Рисунок 12. Свертывание и развертывание частей пакета для упрощения редактирования в Visual Studio

  

  Рисунок 13. Компоненты, входящие в базовый пакет документов Office Open XML Word

  

  Вы удивитесь, но единственные элементы, которые необходимо вставить для добавления примера форматированного текста, во всей этой разметке — это элементы RELS-частей и document.xml.

  Две строки разметки над тегом пакета (объявления XML для версии и кода программы Office) применяются автоматически при использовании приведения Open XML, поэтому их не нужно добавлять. Оставьте их, если хотите открыть измененную разметку как документ Word для тестирования.

  Некоторые другие типы содержимого, показанные в начале этого раздела, также требуют дополнительных частей (помимо тех, которые показаны на рис. 13), и вы рассмотрим их далее в этом разделе. Сейчас же, так как вы увидите большинство частей, показанных на рисунке 13, в разметке любого пакета документа Word, кратко рассмотрим каждую часть и ее функции:

  • В теге пакета первой частью является RELS-файл, в котором определяются связи между частями верхнего уровня пакета (обычно это свойства документа, эскиз (если он существует) и тело документа). Определенное содержимое этой части всегда должно быть в разметке, так как необходимо определить связь основной части документа (где хранится контент) с пакетом документа.
  • Часть document.xml.rels определяет связи с дополнительными частями, необходимыми части document.xml (основной текст документа), если такие имеются.

  Важно! RELS-файлы в пакете (такие как RELS-файлы верхнего уровня, document.xml.rels и другие файлы, которые можно увидеть для различных типов контента) — это очень важный инструмент, который можно использовать для быстрого редактирования пакета Office Open XML. Дополнительные сведения о том, как это сделать, см. в статье Создание собственной разметки: рекомендации далее в этом разделе.

  Вставка содержимого документа в выделенный фрагмент

  Рассмотрим минимальную разметку Office Open XML, необходимую для примера форматированного текста на рисунке 1, и код JavaScript, необходимый для вставки разметки в выделенном месте в документе.

  Упрощенная разметка Office Open XML

  Показанный здесь пример Office Open XML был изменен, как описано в предыдущем разделе, чтобы оставить только необходимые части документа и только обязательные элементы в каждой из этих частей. Вы узнаете, как самостоятельно изменить разметку (и мы объясним немного больше о оставшихся здесь фрагментах) в следующем разделе раздела.

                         This text has formatting directly applied to achieve its font size, color, line spacing, and paragraph spacing.        

  Если вы добавите показанную здесь разметку в XML-файл вместе с тегами объявления XML для version и mso-application в верхней части файла (показано на рис. 13), вы можете открыть ее в Word как документ Word. Кроме того, без этих тегов его можно открыть с помощью команды File>Open in Word. Вы увидите режим совместимости в строке заголовка в Word, так как вы удалили параметры, указывающие, Word это Word документ. Так как вы добавляете эту разметку в существующий документ Word, это вообще не повлияет на содержимое.

  Код JavaScript для использования метода setSelectedDataAsync

  После сохранения предыдущего файла Office Open XML в виде XML-файла, доступного из решения, используйте следующую функцию, чтобы задать форматирование текстового содержимого в документе с помощью приведения Office Open XML.

  В следующей функции обратите внимание, что все, кроме последней строки, используются для получения сохраненной разметки для использования в вызове метода setSelectedDataAsync в конце функции. setSelectedDataASync Требуется только указать вставляемый контент и тип приведения.

  Замените yourXMLfilename именем и путем к XML-файлу, сохраненного в решении. Если вы не знаете, где включать XML-файлы в решение или как ссылаться на них в коде, см. примеры и примеры кода для работы с разметкой и JavaScript, показанные здесь, в разделе Загрузка и запись Open XML в надстройке Word.

  function writeContent() < const myOOXMLRequest = new XMLHttpRequest(); let myXML; myOOXMLRequest.open('GET', 'yourXMLfilename', false); myOOXMLRequest.send(); if (myOOXMLRequest.status === 200) < myXML = myOOXMLRequest.responseText; >Office.context.document.setSelectedDataAsync(myXML, < coercionType: 'ooxml' >); > 

  Создание собственной разметки: рекомендации

  Рассмотрим разметку, необходимую для вставки предыдущего примера форматированного текста, более подробно.

  Для начала просто удалим из пакета все части документа, кроме RELS-файла и document.xml. Затем вы измените эти две необходимые части, чтобы упростить работу.

  Используйте RELS-части как карту, чтобы быстро понять, что входит в пакет, и определить, какие части можно полностью удалить (все части, не связанные с контентом и не указанные в нем). Помните, что для каждой части документа в пакете должны существовать связи, которые указываются в RELS-файлах. Все эти связи можно увидеть в RELS-файле, файле document.xml.rels или RELS-файле, связанном с контентом.

  В следующей разметке показана необходимая RELS-часть перед редактированием. Так как мы удаляем части свойств надстройки и основного документа, а также часть эскиза, необходимо также удалить эти связи из rels. Обратите внимание, что после этого останется только связь для document.xml (с кодом rID1 в следующем примере).

  Удалите связи (т. е. тег Связи ) для всех частей, которые полностью удаляются из пакета. Including a part without a corresponding relationship, or excluding a part and leaving its relationship in the package, will result in an error.

  В следующей разметке показана часть document.xml, содержащая пример форматированного текста, перед редактированием.

                  This text has formatting directly applied to achieve its font size, color, line spacing, and paragraph spacing.             

  Так как document.xml является основной частью документа, в которой размещается содержимое, ознакомьтесь с этой частью. (На рисунке 14, который идет после этого списка, показано, как некоторые базовые теги содержимого и теги форматирования связаны с тем, что вы видите в документе Word.)

  Открывающий тег w:document включает несколько пространств имен (xmlns). Многие из них связаны с определенными типами содержимого и необходимы, только если относятся к вашему содержимому. Обратите внимание, что префикс для тегов в части документа относится к пространствам имен. В этом примере единственным префиксом, используемым в тегах в document.xml части, является w:, поэтому единственным пространством имен, которое необходимо оставить в открывающемся теге w:document , является xmlns:w.

  Совет Если вы редактируете разметку в Visual Studio, после удаления пространств имен в любой части просмотрите все теги этой части. Если вы удалили пространство имен, необходимое для разметки, соответствующий префикс тегов будет подчеркнут красной волнистой линией. Кроме того, удаляя пространство имен xmlns:mc, также нужно удалить атрибут mc:Ignorable, предоставляющий список пространств имен.

  Рисунок 14. Как общие теги в document.xml связаны с содержимым и макетом документа Word

  

  В нескольких тегах созданной разметки может встречаться другой атрибут, включающий символы w:rsid, которых нет в примерах из этой статьи. Это идентификаторы исправлений. Они используются в Word для функции объединения документов и включены по умолчанию. В разметке, вставляемой с помощью надстройки, они не нужны, и их отключение делает разметку намного яснее. Вы можете легко удалить существующие теги RSID или отключить функцию (как описано в следующей процедуре), чтобы они не добавлялись в разметку для нового содержимого.

  Помните, что если вы используете возможности совместного редактирования документов в Word, следует опять включить функцию после создания разметки для вашей надстройки.

  Чтобы отключить атрибуты RSID в Word для последующих создаваемых документов, выполните следующие действия:

  1. В Word откройте меню Файл и выберите пункт Параметры.
  2. В диалоговом окне «Параметры Word» выберите пункт Центр управления безопасностью и нажмите кнопку Параметры центра управления безопасностью.
  3. В диалоговом окне «Центр управления безопасностью» выберите пункт Параметры конфиденциальности и снимите флажок Сохранять случайное число для улучшения точности объединения. Обратите внимание, что этот параметр может быть недоступен в более новых версиях Word.

  Чтобы удалить теги RSID из существующего документа, воспользуйтесь приведенным ниже ярлыком с документом, открытым в Office Open XML.

  1. Указав точку вставки в тексте документа, нажмите клавиши CTRL+HOME, чтобы перейти в начало документа.
  2. Нажмите клавиши ПРОБЕЛ, DELETE, ПРОБЕЛ. Затем сохраните документ.

  После удаления большей части разметки из этого пакета остается минимальная разметка, которую необходимо вставить для примера, как показано в предыдущем разделе.

  Используйте одну и ту же структуру Office Open XML для разных типов контента

  Для некоторых типов мультимедиа требуются только части RELS и document.xml, показанные в предыдущем примере, в том числе для элементов управления содержимым, фигур и текстовых полей Office, а также таблиц (если к ним не применяется стиль). Вы можете повторно использовать одни и те же измененные части пакета, меняя только содержимое body в файле document.xml для разметки содержимого.

  Чтобы проверка разметку Office Open XML для примеров каждого из этих типов контента, показанных ранее на рис. 5–8, ознакомьтесь с примером кода надстройки «Загрузка и запись Open XML в Word», на который ссылается раздел обзора.

  Прежде чем двигаться дальше, ознакомьтесь с различиями, которые следует отметить для нескольких из этих типов контента, а также о том, как заменить нужные фрагменты.

  Общие сведения о разметке drawingML (графика Office) в Word

  Если разметка для фигуры или текстового поля выглядит гораздо сложнее, чем вы ожидали, для этого есть причина. После выхода Office 2007 появились форматы Office Open XML, а также новый графический модуль Office, который был полностью интегрирован в PowerPoint и Excel. В Word 2007 поддерживается только часть этого модуля, обновленный модуль диаграмм Excel, графические объекты SmartArt и расширенные средства работы с рисунками. Для фигур и текстовых полей Word 2007 продолжает использовать старые объекты рисунков (VML). Только в Word 2010 были реализованы дополнительные возможности для поддержки обновленных средств работы с фигурами и рисунками.

  Как правило, как вы видите для примеров фигур и текстовых полей, включенных в пример кода для загрузки и записи Open XML в Word надстройки, резервную разметку можно удалить. Word автоматически добавляет недостающую резервную разметку к фигурам при сохранении документа. Но если вы хотите сохранить резервную разметку для поддержки всех пользовательских сценариев, никто не помешает вам это сделать.

  После группировки объектов-рисунков в содержимом вы увидите дополнительную разметку (очевидно, повторяющуюся), но ее нужно сохранить. Части разметки для отображения фигур дублируются, если объект добавляется в группу.

  При работе с текстовыми полями и фигурами тщательно проверяйте пространства имен перед их удалением из document.xml. (Or, if you’re reusing markup from another object type, be sure to add back any required namespaces you might have previously removed from document.xml.) A substantial portion of the namespaces included by default in document.xml are there for drawing object requirements.

  О размещении рисунков

  В примерах кода Загрузка и запись Open XML в надстройке Word и Word-Add-in-Get-Set-EditOpen-XML настраиваются с помощью различных типов параметров упаковки и позиционирования текста. (Также имейте в виду, что примеры изображений в этих примерах кода настраиваются с использованием форматирования текста, которое размещает графический объект в текстовом базовом плане.)

  Фигура в этих примерах кода размещается относительно правого и нижнего полей страницы. Относительное расположение упрощает согласование с неизвестной конфигурацией пользователя, так как оно адаптируется к полям пользователя, а риск неудачно расположить содержимое из-за неизвестного размера, ориентации или полей страницы значительно уменьшается. Чтобы сохранить параметры относительного размещения при вставке графического объекта, необходимо сохранить знак абзаца (w:p), в котором хранятся данные о расположении (в приложении Word это называется привязкой). Если вставить содержимое в существующий знак абзаца, а не добавить собственный знак абзаца, вы сможете сохранить исходный внешний вид документа, но многие типы относительных ссылок, позволяющие автоматически адаптировать размещение содержимого в соответствии с пользовательской структурой, могут быть потеряны.

  Работа с элементами управления содержимым

  Элементы управления содержимым — это полезный компонент Word, который может значительно расширить возможности надстройки для Word различными способами, в том числе позволить ей вставлять содержимое в указанном, а не только в выделенном месте.

  В Word элементы управления содержимым можно найти на вкладке «Разработчик» на ленте, как показано на рисунке 15.

  Рисунок 15. Группа Элементы управления на вкладке Разработчик в Word

  

  В Word доступны такие элементы управления содержимым, как форматированный текст, простой текст, изображение, коллекция стандартных блоков, флажок, раскрывающийся список, поле со списком, компонент выбора даты и повторяющийся раздел.

  • Используйте команду Свойства, как показано на рис. 15, чтобы изменить заголовок элемента управления и задать настройки, например чтобы скрыть контейнер элемента управления.
  • Включите режим конструктора, чтобы изменить содержимое заполнителя в элементе управления.

  Если ваша надстройка работает с шаблоном Word, вы можете добавить элементы управления в этот шаблон, чтобы улучшить поведение содержимого. Вы также можете использовать привязку данных XML в документе Word, чтобы связать элементы управления содержимым с данными, например свойствами документа, и упростить заполнение форм и выполнение аналогичных задач. (Элементы управления, которые уже привязаны к встроенным свойствам документа в Word, можно найти на вкладке Вставка в разделе Экспресс-блоки.)

  При использовании элементов управления содержимым в надстройке вы можете расширить ее возможности с помощью другого типа привязки. Вы можете создать привязку к элементу управления содержимым из надстройки, а затем записывать содержимое в привязку, а не выделенное место.

  Не путайте привязку к данным XML в Word с возможностью привязки к элементу управления через надстройку. Это совершенно разные функции. Однако вы можете добавить именованные элементы управления содержимым во вставляемое содержимое через надстройку, используя приведение OOXML, а затем с помощью кода в надстройке создать привязку к этим элементам управления.

  Кроме того, имейте в виду, что привязка xml-данных и Office.js могут взаимодействовать с пользовательскими XML-частями в приложении, поэтому можно интегрировать эти мощные средства. Сведения о работе с пользовательскими XML-частями в API JavaScript для Office см. в разделе См. также раздел этой статьи.

  Работа с привязками в надстройке Word рассматривается в следующем разделе этого раздела. Сначала рассмотрим пример Office Open XML, необходимый для вставки элемента управления с содержимым в формате форматированного текста, к которому можно привязаться с помощью надстройки.

  Элементы управления форматированным текстом — это единственный тип элементов управления содержимым, которые можно использовать для привязки к элементу управления содержимым в надстройке.

                       [This text is inside a content control that has its container hidden. You can bind to a content control to add or interact with content at a specified location in the document.]          

  Как уже было сказано, элементам управления содержимым, как и форматированному тексту, не требуются дополнительные части документа, поэтому здесь указаны только измененные части, RELS и document.xml.

  Тег w:sdt, который вы видите в document.xml, представляет элемент управления содержимым. Если создать разметку Office Open XML для элемента управления содержимым, вы увидите, что несколько атрибутов удалены из этого примера, в том числе данный тег и свойства части документа. Сохранились только необходимые элементы (и пара рекомендуемых), включая следующие:

  • Псевдоним — это свойство title из диалогового окна Свойства элемента управления содержимым в Word. Данное свойство (представляющее имя элемента) является обязательным, если вы планируете привязать элемент управления в надстройке.
  • id — это уникальное свойство. Если привязать элемент управления в надстройке, ID будет свойством, которое привязка использует, чтобы определить соответствующий именованный элемент управления.
  • Атрибут внешнего вида используется для скрытия контейнера элемента управления для более чистого внешнего вида. Эта функция появилась в Word 2013 году, как вы видите, используя пространство имен w15. Так как это свойство используется, пространство имен w15 сохраняется в начале части document.xml.
  • Атрибут showingPlcHdr является необязательным параметром, который задает содержимое по умолчанию, которое вы включаете в элемент управления (текст в этом примере) в качестве заполнителя. Поэтому если пользователь щелкнет область элемента управления, будет выбрано все содержимое, что отличается от редактируемого содержимого.
  • Хотя пустая метка абзаца ( w:p/ ), которая предшествует тегу sdt, не требуется для добавления элемента управления содержимым (и добавляет вертикальное пространство над элементом управления в документе Word), он гарантирует, что элемент управления помещается в собственный абзац. Это может быть важно в зависимости от типа и форматирования содержимого, которое будет добавлено в элемент управления.
  • Для привязки к элементу управления содержимое по умолчанию (в теге sdtContent) должно включать по крайней мере один полный абзац (как в этом абзаце), чтобы ваша привязка принимала мультимедиа из нескольких абзацев.

  Атрибут части документа, удаленный из тега w:sdt этого примера, может быть указан в элементе управления содержимым для указания ссылки на отдельную часть в пакете, где может храниться контент заполнителя (части, расположенные в каталоге глоссария пакета Office Open XML). Хотя часть документа — это термин, используемый для XML-частей (то есть файлов) в пакете Office Open XML, термин «части документа», используемый в свойстве sdt, относится к тому же термину в Word, который используется для описания некоторых типов контента, включая стандартные блоки и быстрые части свойств документа (например, встроенные элементы управления с привязкой к данным XML). If you see parts under a glossary directory in your Office Open XML package, you may need to retain them if the content you’re inserting includes these features. Для типичного элемента управления содержимым, к которому вы планируете привязаться из надстройки, они не требуются. Just remember that, if you do delete the glossary parts from the package, you must also remove the document part attribute from the w:sdt tag.

  В следующем разделе мы расскажем, как создавать и использовать привязки в надстройке Word.

  Вставка содержимого в указанное место

  Вы уже рассмотрели, как вставлять содержимое в активный выделенный фрагмент в документе Word. Если создать привязку к именованному элементу управления содержимым в документе, вы сможете вставлять такие же типы содержимого в этот элемент управления.

  Итак, когда этот подход может потребоваться?

  • Если необходимо добавить или заменить содержимое в указанных расположениях шаблона, например для заполнения частей документа из базы данных.
  • Если вы хотите заменить содержимое, которое вы вставляете в активном выделенном фрагменте, например, чтобы предоставить пользователю параметры элемента конструктора.
  • Если вы хотите, чтобы пользователь добавил в документ данные, к которым можно получить доступ для использования с надстройкой, например для заполнения полей в области задач на основе информации, которую пользователь добавляет в документ.

  Скачайте пример кода Word-Add-in-JavaScript-AddPopulateBindings— это рабочий пример вставки элемента управления содержимым и привязки к нему, а также заполнения привязки.

  Добавление именованного элемента управления содержимым и привязка к нему

  При изучении представленного ниже кода JavaScript учитывайте следующие требования:

  • Как отмечалось ранее, для привязки к элементу управления в надстройке Word необходимо использовать элемент управления форматированным текстом.
  • Элемент управления содержимым должен иметь имя (это поле Title в диалоговом окне Свойства элемента управления содержимым, которое соответствует тегу Alias в разметке Office Open XML). Так код определяет, где следует разместить привязку.
  • Можно использовать и привязать несколько именованных элементов управления. Укажите уникальное имя элемента управления содержимым, уникальный код элемента управления и уникальный код привязки.

  function addAndBindControl() < Office.context.document.bindings.addFromNamedItemAsync("MyContentControlTitle", "text", < id: 'myBinding' >, function (result) < if (result.status == "failed") < if (result.error.message == "The named item does not exist.") const myOOXMLRequest = new XMLHttpRequest(); let myXML; myOOXMLRequest.open('GET', '../../Snippets_BindAndPopulate/ContentControl.xml', false); myOOXMLRequest.send(); if (myOOXMLRequest.status === 200) < myXML = myOOXMLRequest.responseText; >Office.context.document.setSelectedDataAsync(myXML, < coercionType: 'ooxml' >, function (result) < Office.context.document.bindings.addFromNamedItemAsync("MyContentControlTitle", "text", < id: 'myBinding' >); >); > >); > 

  Приведенный здесь код выполняет следующие действия.

  • Пытается создать привязку к именованному элементу управления содержимым с помощью метода addFromNamedItemAsync. Сначала выполните этот шаг, если для надстройки существует возможный сценарий, в котором именованный элемент управления уже может существовать в документе при выполнении кода. Например, это может понадобиться, если шаблон, в который была добавлена надстройка и с которым она была сохранена, предназначен для работы с надстройкой, уже содержащей элемент управления. Это также может понадобиться для привязки к элементу управления, ранее размещенному надстройкой.
  • Обратный вызов в первом вызове addFromNamedItemAsync метода проверяет состояние результата, чтобы увидеть, не произошло ли сбой привязки, так как именованный элемент не существует в документе (то есть элемент управления с именем MyContentControlTitle в этом примере). Если это так, код добавляет элемент управления в активную точку выделения (с помощью setSelectedDataAsync ) и привязывается к нему.

  Как было сказано ранее и показано в предыдущем примере кода, имя элемента управления содержимым используется для определения места, где будет создана привязка. Однако в разметке Office Open XML код добавляет привязку к документу, используя имя и атрибут ID элемента управления содержимым.

  После выполнения кода, если вы изучите разметку документа, в котором надстройка создала привязки, вы увидите две части каждой привязки. В разметке элемента управления содержимым, куда была добавлена привязка (в document.xml), вы увидите атрибут w15:webExtensionLinked/.

  В части документа с именем webExtensions1.xml вы увидите список созданных привязок. Каждый из них идентифицируется с помощью идентификатора привязки и атрибута ID применимого элемента управления, например следующего, где атрибутом appref является идентификатор элемента управления содержимым: we:binding type=»text» appref=»1382295294″/.

  Привязку нужно добавить тогда, когда вы собираетесь использовать ее. Не добавляйте разметку привязки в разметку Office Open XML для вставки элемента управления, так как этот процесс приведет к удалению привязки.

  Заполнение привязки

  Код для записи контента в привязку похож на код для записи контента в выделение.

  function populateBinding(filename) < const myOOXMLRequest = new XMLHttpRequest(); let myXML; myOOXMLRequest.open('GET', filename, false); myOOXMLRequest.send(); if (myOOXMLRequest.status === 200) < myXML = myOOXMLRequest.responseText; >Office.select("bindings#myBinding").setDataAsync(myXML, < coercionType: 'ooxml' >); > 

  Как и в случае с setSelectedDataAsync , вы указываете вставляемый контент и тип приведения. Единственное дополнительное требование для записи в привязку — определение привязки по идентификатору. Обратите внимание, что идентификатор привязки, используемый в этом примере (bindings#myBinding), соответствует идентификатору (myBinding), заданному при создании в предыдущей функции.

  Предыдущий пример кода — все, что вам нужно при первоначальном заполнении или замене контента в привязке. При вставке в привязку новое содержимого автоматически заменяет существующее. Изучите пример Word-Add-in-JavaScript-AddPopulateBindings, где представлено два отдельных примера содержимого, которые можно использовать для заполнения одной привязки.

  Добавление объектов, использующих дополнительные части Office Open XML

  Для многих типов контента требуются дополнительные части документа пакета Office Open XML. Это значит, что они ссылаются на информацию в другой части или сам контент хранится в одной или нескольких частях и указывается в document.xml.

  Так, например, необходимо учитывать следующее:

  • Для контента, использующего стили для форматирования (например, текст, показанный ранее на рис. 2, или таблица на рис. 9), требуется часть styles.xml.
  • Изображения (например, на рис. 3 и 4) содержат двоичные данные изображений в одной, а иногда двух дополнительных частях.
  • Для диаграмм SmartArt (например, на рис. 10) требуется несколько дополнительных частей для описания структуры и контента.
  • Для диаграмм (как на рис. 11) требуется несколько дополнительных частей, в том числе собственная часть связей (RELS).

  Измененные примеры разметки для всех этих типов контента можно увидеть в приведенном ранее примере кода Load and write Open XML in your Word add-in in your Word. Эти типы содержимого можно вставить, используя код JavaScript, показанный ранее (и представленный в примерах кода) для вставки содержимого в выделенное место и записи содержимого в указанное расположение с помощью привязок.

  Помните, что если вы сохраняете какие-либо дополнительные части, указанные в document.xml, вам потребуется сохранить document.xml.rels и определения связей для соответствующих частей, которые вы храните, например styles.xml или файла образа.

  Прежде чем изучить примеры, ознакомьтесь с несколькими советами по работе с каждым из этих типов контента.

  Работа со стилями

  Тот же подход к редактированию разметки, который вы рассмотрели в предыдущем примере с текстом с прямым форматированием, применяется при использовании стилей абзацев или таблиц для форматирования содержимого. Однако разметка для работы со стилями абзацев значительно проще, поэтому это пример, описанный здесь.

  Редактирование разметки для контента с использованием стилей абзацев

  Приведенная ниже разметка представляет содержимое для примера текста со стилем, показанного на рис. 2.

       This text is formatted using the Heading 1 paragraph style.    

  Как видите, разметка для форматированного текста в document.xml намного проще при использовании стиля, так как стиль содержит все параметры форматирования абзаца и шрифтов, которые в противном случае потребовалось бы указывать отдельно. Но, как упоминалось ранее, стили или прямое форматирование можно использовать для разных целей: прямое форматирование для определения внешнего вида независимо от форматирования в документе пользователя, а стиль абзаца (в частности, встроенный стиль абзаца, например «Заголовок 1», как показано здесь) для автоматического согласования форматирования текста с документом пользователя.

  Использование стиля является хорошим примером того, насколько важно читать и понимать разметку для вставляемого содержимого, так как здесь нет явных ссылок на другую часть документа. Если в разметку добавить определение стиля и не добавлять styles.xml, информация о стиле в document.xml будет игнорироваться независимо от того, используется ли этот стиль в документе пользователя.

  Но если внимательно посмотреть на часть styles.xml, вы заметите, что только небольшая часть этой объемной разметки необходима при редактировании разметки, которая будет использоваться в надстройке:

  • Часть styles.xml по умолчанию содержит несколько пространств имен. Если вы сохраняете только сведения о стиле, требуемые для вашего контента, в большинстве случаев вам понадобится сохранить только пространство имен xmlns:w.
  • Содержимое тега w:docDefaults в начале части стилей будет игнорироваться, когда ваша разметка вставляется с помощью надстройки, и его можно удалить.
  • Наибольшая доля разметки в части styles.xml предназначена для тега w:latentStyles, который идет после части docDefaults, содержащего сведения для каждого доступного стиля (например, атрибуты внешнего вида области стилей и коллекция стилей). Эти сведения также игнорируются при вставке содержимого с помощью надстройки, и их можно удалить.
  • После сведений о стилях можно увидеть определение каждого стиля, используемого документом, на основе которого была создана разметка. В эти данные входят некоторые стили по умолчанию, используемые при создании нового документа, и они могут не относиться к вашему документу. Вы можете удалить определения стилей, которые не используются содержимым. Каждый встроенный стиль заголовка имеет связанный стиль Char, который является версией стиля символа того же формата заголовка. Если вы не применили стиль заголовка как стиль знака, его можно удалить. Если стиль используется как стиль знака, он отображается в document.xml в теге свойств прогона (w:rPr), а не в теге свойств абзаца (w:pPr). Последнее происходит, только если вы применили стиль только к части абзаца, но также может произойти, если стиль был применен неправильно.
  • Если вы используете встроенный стиль для содержимого, добавлять полное определение не требуется. Необходимо только указать имя стиля, код стиля и по крайней мере один атрибут форматирования для приведенного Office Open XML, чтобы применить стиль к содержимому после вставки. Тем не менее рекомендуется добавить полное определение стиля, даже если оно используется по умолчанию для встроенных стилей. Если стиль уже используется в конечном документе, к содержимому будет применяться резидентное определение стиля, независимо от того что указано в styles.xml. Если в конечном документе стиль еще не используется, к содержимому будет применяться определение стиля, указанное в разметке.

  Например, единственное содержимое, необходимое для сохранения из styles.xml части для примера текста, показанного на рисунке 2, который отформатирован в стиле Заголовок 1, будет следующим:

  В этом примере сохранено полное определение Word для стиля «Заголовок 1».

  Изменение разметки для содержимого с помощью стилей таблиц

  Если ваш контент использует стиль таблицы, вам нужна та же относительная часть styles.xml, которая была описана в разделе, посвященном работе со стилями абзацев Т. е. То есть вам нужно только сохранить сведения о стиле, используемом в содержимом, и указать имя, идентификатор и хотя бы один атрибут форматирования, но лучше включить полное определение стиля для всех потенциальных пользовательских сценариев.

  Но если посмотреть на разметку для таблицы в document.xml и определения стиля таблицы в styles.xml, вы увидите намного больше разметки, чем при работе со стилями абзацев.

  • В document.xml форматирование применяется ячейкой, даже если оно включено в стиль. Использование стиля таблицы не уменьшит размер разметки. Преимущество применения стилей таблиц для содержимого состоит в простоте обновления и согласования внешнего вида нескольких таблиц.
  • В файле styles.xml вы также увидите разметку большого размера, так как стили таблиц включают несколько типов возможных атрибутов форматирования для всех областей таблицы, таких как вся таблица, строки заголовков, четные и нечетные строки и столбцы (отдельно), первый столбец и т. д.

  Работа с изображениями

  Разметка изображения включает ссылку по крайней мере на одну часть, которая содержит двоичные данные изображения. Для сложного изображения разметка может состоять из сотен страниц, при этом изменить ее нельзя. Так как вам никогда не нужно касаться двоичных частей, вы можете просто свернуть их, если вы используете структурированный редактор, например Visual Studio, чтобы вы могли легко просматривать и редактировать остальную часть пакета.

  Если вы проверка пример разметки для простого изображения, показанного ранее на рисунке 3, который доступен в приведенном ранее примере кода Загрузка и запись Open XML в надстройке Word, вы увидите, что разметка для изображения в document.xml содержит сведения о размере и положении, а также ссылку на связь с частью, содержащей двоичные данные изображения. Эта ссылка входит в тег a:blip следующим образом:

  Имейте в виду, что, поскольку ссылка на связь явно используется ( r:embed=»rID4″ ) и эта связанная часть требуется для отрисовки изображения, если не включить двоичные данные в пакет Office Open XML, вы получите сообщение об ошибке. Это отличается от styles.xml, описанных ранее, который не вызовет ошибку, если опущен, так как связь не указана явным образом, а связь связана с частью, которая предоставляет атрибуты содержимого (форматирование), а не является частью самого содержимого.

  При изучении разметки обратите внимание на дополнительные пространства имен, используемые в теге a:blip. В document.xml вы увидите, что пространство имен xlmns:a (пространство имен main drawingML) динамически размещается в начале использования ссылок drawingML, а не в верхней части document.xml. Однако пространство имен связей (r) необходимо сохранить в начале части document.xml. Проверьте разметку изображения на наличие дополнительных пространств имен. Remember that you don’t have to memorize which types of content require what namespaces, you can easily tell by reviewing the prefixes of the tags throughout document.xml.

  Сведения о дополнительных частях и форматировании изображений

  Если вы используете эффекты форматирования изображений Office, например как для изображения на рисунке 4, где применяются параметры яркости и контрастности (помимо стиля рисунка), может потребоваться вторая часть двоичных данных для копии изображения в формате высокой четкости. Это необходимо для форматирования с эффектом наложения, ссылка на эту копию содержится в document.xml и выглядит следующим образом:

  См. требуемую разметку для отформатированного изображения, показанного на рис. 4 (в котором используются эффекты наложения) в примере кода загрузки и записи Open XML в надстройке Word.

  Работа со схемами SmartArt

  Со схемой SmartArt связано четыре части, но только две из них являются обязательными. Пример разметки SmartArt можно изучить в разделе Загрузка и записать Open XML в примере кода надстройки Word. Во-первых, ознакомьтесь с кратким описанием каждой из частей и почему они являются или не требуются:

  Если содержимое содержит несколько схем, они будут нумерованы последовательно, заменив «1» в именах файлов, перечисленных здесь.

  • layout1.xml: это обязательная часть. Она содержит определение разметки для внешнего вида и функциональности структуры.
  • data1.xml: это обязательная часть. Она содержит данные, используемые вашим экземпляром диаграммы.
  • drawing1.xml. Эта часть не всегда является обязательной, но при применении настраиваемого форматирования к элементам в экземпляре схемы, например непосредственному форматированию отдельных фигур, ее может потребоваться сохранить.
  • colors1.xml. Эта часть не является обязательной. Она содержит сведения о цвете стиля, но цвета диаграммы по умолчанию будут соответствовать цветам активной темы форматирования в целевом документе в зависимости от стиля цвета SmartArt, применяемого на вкладке «Работа с рисунками SmartArt» в Word перед сохранением разметки Office Open XML.
  • quickStyles1.xml. Эта часть не является обязательной. Как и в части цветов, ее можно удалить, так как схема будет принимать на себя определение примененного стиля SmartArt, доступного в целевом документе (то есть он будет автоматически координироваться с темой форматирования в целевом документе).

  Файл layout1.xml SmartArt является хорошим примером мест, где вы можете дополнительно обрезать разметку, но может не стоить дополнительного времени для этого (так как он удаляет такой небольшой объем разметки по отношению ко всему пакету). Если вы хотите избавиться от всей возможной разметки, можно удалить тег dgm:sampData и его содержимое. Следующий пример определяет, как эскиз диаграммы отображается в коллекциях стилей SmartArt. Но если его опустить, будут использоваться данные по умолчанию.

  Помните, что разметка схемы SmartArt в файле document.xml содержит ссылки на коды связей с частями структуры, данных, цветов и экспресс-стилей. Вы можете удалить ссылки на части цветов и стилей в файле document.xml, если вы удаляете данные части и определения их связей (и это совершенно точно рекомендуемый подход, так как вы удаляете эти связи), но если их сохранить, ошибки не будет, так как они не требуются для вставки диаграммы в документ. Эти ссылки можно найти в document.xml в теге dgm:relIds. Независимо от того, выполняете ли вы это действие, сохраните ссылки на коды связи для обязательных частей структуры и данных.

  Работа с диаграммами

  Как и диаграммы SmartArt, обычные диаграммы содержат несколько дополнительных частей. Но настройка для них немного отличается от SmartArt, так как у диаграммы есть собственный файл связей. Ниже приведено описание обязательных и съемных частей документа для диаграммы.

  Как и в случае с диаграммами SmartArt, если содержимое содержит несколько диаграмм, они будут нумерованы последовательно, заменив «1» в именах файлов, перечисленных здесь.

  • В файле document.xml.rels вы увидите ссылку на обязательную часть, который содержат данные, описывающие диаграмму (chart1.xml).
  • Вы также увидите отдельный файл связей для каждой диаграммы в пакете Office Open XML, например chart1.xml.rels. chart1.xml.rels ссылается на три файла, но требуется только один из них. Эти файлы включают двоичные данные книги Excel (обязательны), а также цвета и стили (colors1.xml и styles1.xml), которые можно удалить.

  Диаграммы, которые можно создавать и редактировать в Word, являются диаграммами Excel, а их данные хранятся на листе Excel, внедренном в пакет Office Open XML в виде двоичных данных. Как и двоичные части данных для изображений, эти двоичные данные Excel являются обязательными, но в этой части ничего не нужно редактировать. Поэтому вы можете просто свернуть часть в редакторе, чтобы избежать необходимости вручную прокручивать все это, чтобы изучить остальную часть пакета Office Open XML.

  Но, как и в случае со SmartArt, вы можете удалить части цветов и стилей. Если вы использовали доступные в диаграмме стили и цветовые стили для форматирования диаграммы, то при вставке в целевой документ диаграмма автоматически примет применимое форматирование.

  Пример диаграммы, показанной на рисунке 11, см. в отредактируемой разметке в примере кода надстройки Word.

  Изменение Office Open XML для использования в надстройке области задач

  Вы уже знаете, как определить и изменить содержимое в разметке. Если задача по-прежнему кажется сложной при просмотре массивного пакета Office Open XML, созданного для вашего документа, ниже приведена краткая сводка рекомендуемых действий, которые помогут вам быстро изменить этот пакет.

  Помните, что вы можете использовать все RELS-части в пакете как карту, чтобы быстро узнать, какие части документа можно удалить.

  1. Откройте плоский XML-файл в Visual Studio и нажмите клавиши CTRL+K, CTRL+D, чтобы отформатировать файл. Затем с помощью кнопок свертывания и развертывания в левой части сверните части, которые нужно удалить. Вы также можете свернуть длинные части, которые нужно сохранить, но которые не требуется изменять (например, двоичные данные в формате Base64 для файла изображения), чтобы упростить и ускорить чтение разметки.
  2. При подготовке кода Office Open XML для использования в надстройке вы почти всегда можете удалить несколько частей пакета документов. Вы можете сначала удалить их и связанные определения связей, что сразу значительно уменьшит пакет. Они включают theme1, fontTable, параметры, webSettings, эскиз, основной файл свойств и файл свойств надстройки, части taskpane или webExtension .
  3. Удалите все части, не связанные с содержимым, такие как сноски, верхние и нижние колонтитулы, которые вам не требуются. Опять же, не забудьте удалить соответствующие связи.
  4. Изучите часть document.xml.rels, чтобы узнать, требуются ли какие-либо файлы, указанный в ней, для содержимого, например файл изображения, часть стилей или части схемы SmartArt. Удалите связи для всех частей, которые не требуются для содержимого, и удалите связанную часть. Если для содержимого не нужны части документа, указанные в document.xml.rels, вы можете удалить и этот файл.
  5. Если у вашего контента есть дополнительная RELS-часть (например, chart#.xml.rels), изучите ее, чтобы узнать, существуют ли другие части, которые можно удалить (например, экспресс-стили для диаграмм), и удалите связь из файла и соответствующую часть.
  6. Измените document.xml, чтобы удалить пространства имен, не указанные в части, свойства раздела, если содержимое не содержит разрыв раздела, и любую разметку, которая не связана с содержимым, которое вы хотите вставить. При вставке фигур или текстовых полей вы также можете удалить резервную разметку.
  7. Измените все другие обязательные части, разметку которых можно удалить без влияния на ваш контент, например часть стилей.

  После выполнения предыдущих семи шагов вы удалите около 90–100 % разметки, которую можно удалить, в зависимости от содержимого. В большинстве случаев далее удалять разметку не требуется.

  Независимо от того, остановитесь ли вы на этом или решите удалить все возможные строки разметки, помните, что вы можете использовать пример кода Word-Add-in-Get-Set-EditOpen-XML для быстрой проверки измененной разметки.

  Если вы обновляете фрагмент Office Open XML в существующем решении во время разработки, удалите временные файлы Интернета перед повторным запуском решения, чтобы обновить Office Open XML, используемый кодом. Разметка, которая входит в состав решения в XML-файлах, кэшируется на компьютере. Вы можете удалить временные файлы Интернета в веб-браузере по умолчанию. Чтобы получить доступ к параметрам браузера и удалить эти параметры из Visual Studio 2019, в меню Отладка выберите пункт Параметры. Затем в поле Среда выберите Браузер, а затем выберите Параметры Internet Explorer.

  Создание надстройки как для шаблона, так и для автономного использования

  В этом разделе вы ознакомились с несколькими примерами того, что можно сделать с помощью Office Open XML в надстройках. Вы рассмотрели широкий спектр примеров многофункциональных типов контента, которые можно вставить в документы с помощью типа приведения Office Open XML вместе с методами JavaScript для вставки этого содержимого в выделенное или в указанное (привязанное) расположение.

  Итак, что еще нужно знать, если вы создаете надстройку как для автономного использования (то есть для вставки из Магазина или в защищенном расположении сервера), так и для использования в предварительно созданном шаблоне, предназначенном для работы с надстройкой? Возможно, вы уже знаете все, что нужно.

  Разметка для определенного типа контента и методы его вставки одинаковы независимо от того, предназначена ли ваша надстройка для автономной работы или работы с шаблоном. Если вы используете шаблоны, созданные для работы с надстройкой, убедитесь, что код JavaScript включает обратные вызовы, учитывающие ситуации, в которых содержимое уже существует в документе (как показано в примере привязки в разделе Добавление именованного элемента управления содержимым и привязка к нему).

  При использовании шаблонов с приложением, независимо от того, будет ли надстройка находиться в шаблоне во время создания документа пользователем или надстройка будет вставлять шаблон, вам также может потребоваться включить другие элементы API, чтобы помочь вам создать более надежный интерактивный интерфейс. Например, вы можете добавить идентифицирующие данные в часть customXML, которые будут использоваться для определения типа шаблона и предоставления пользователю связанных с шаблоном параметров. Дополнительные сведения о работе с пользовательским XML-кодом в надстройках см. в следующих дополнительных ресурсах.

  См. также

  • API JavaScript для Office
  • Полный справочник по языку и соответствующая документация по Open XML: Standard ECMA-376: Office Open XML File Formats
  • Изучение API JavaScript для Office с помощью Script Lab
  • Изучение API JavaScript для Office: привязка данных и пользовательские xml-части
  • Пример кода-компаньона. Загрузка и запись Open XML в надстройке Word
  • Другие примеры кода, указанные в этой статье:
    • Word-Add-in-Get-Set-EditOpen-XML
    • Word-add-in-JavaScript-AddPopulateBindings
    Похожие публикации:

    1. Как вернуть закрытую вкладку в мозиле
    2. Как изменить иконку приложения в windows 7
    3. Как с карты памяти телефона перенести фото на компьютер
    4. Как свой номер телефона добавить в ватсап