标记兼容性简介 (Open XML SDK)Introduction to markup compatibility (Open XML SDK)

本主题介绍 Open XML SDK 2.5 for Office 中包括的标记兼容性功能。This topic introduces the markup compatibility features included in the Open XML SDK 2.5 for Office.


简介Introduction

假设你具有一个使用 Microsoft Office 2013 中引入的功能的 Microsoft Word 2013 文档。当你在较早版本的 Microsoft Word 2010 中打开该文档时,应该会发生什么情况?理想情况下,你希望该文档保持与 Word 2010 的可互操作性,即使 Word 2010 不能理解此新功能。Suppose you have a Microsoft Word 2013 document that employs a feature introduced in Microsoft Office 2013. When you open that document in Microsoft Word 2010, an earlier version, what should happen? Ideally, you want the document to remain interoperable with Word 2010, even though Word 2010 will not understand the new feature.

还应考虑,如果你在某个假定的更高版本的 Office 中打开该文档,应该会发生什么情况?Consider also what should happen if you open that document in a hypothetical later version of Office. 同样,你希望该文档按预期方式工作。Here too, you want the document to work as expected. 也就是说,你希望此更高版本的 Office 能理解和支持由 Word 2013 生成的文档中使用的功能。That is, you want the later version of Office to understand and support a feature employed in a document produced by Word 2013. 2013.

Open XML 预计到了这些情况。Office Open XML 文件格式规范在 ECMA-376 第二版的第 3 部分 - 标记兼容性和扩展性(该链接可能指向英文页面)中介绍了用于达到上述预期结果的工具。Open XML anticipates these scenarios. The Office Open XML File Formats specification describes facilities for achieving the above desired outcomes in ECMA-376, Second Edition, Part 3 - Markup Compatibility and Extensibility.

Open XML SDK 2.5 支持标记兼容性,从而使你能够轻松实现针对 和 Office 2013 的上述预期结果,而无需成为一名熟知规范细节的专家。The Open XML SDK 2.5 supports markup compatibility in a way that makes it easy for you to achieve the above desired outcomes for and Office 2013 without having to necessarily become an expert in the specification details.


什么是标记兼容性?What is Markup Compatibility?

Open XML 采用特定标记语言(即 WordprocessingML、SpreadsheetML 和 PresentationML)的形式,定义字处理文档、电子表格文档和演示文稿文档的格式。对于 Open XML 文件格式而言,标记兼容性是指以上述标记语言之一表示的文档能够促进应用程序之间或一个应用程序的不同版本(具有不同的功能集)之间进行互操作。通过使用 Open XML 规范的标记兼容性命名空间中的一组定义的 XML 元素和属性,可支持这一点。请注意,当文档格式中支持标记时,标记的生成者和使用者(如 Microsoft Word)也必须支持它。换句话说,互操作性是在文件格式和应用程序中均受支持的一项功能。Open XML defines formats for word-processing, spreadsheet and presentation documents in the form of specific markup languages, namely WordprocessingML, SpreadsheetML, and PresentationML. With respect to the Open XML file formats, markup compatibility is the ability for a document expressed in one of the above markup languages to facilitate interoperability between applications, or versions of an application, with different feature sets. This is supported through the use of a defined set of XML elements and attributes in the Markup Compatibility namespace of the Open XML specification. Notice that while the markup is supported in the document format, markup producers and consumers, such as Microsoft Word, must support it as well. In other words, interoperability is a function of support both in the file format and by applications.


Open XML 文件格式规范中的标记兼容性Markup Compatibility in the Open XML File Formats Specification

标记兼容性在 ECMA-376 第二版的第 3 部分 - 标记兼容性和扩展性(该链接可能指向英文页面)中进行了讨论,建议你阅读该文档以了解标记兼容性。该规范定义 XML 属性来表示兼容性规则并定义 XML 元素来指定替换内容。例如, Ignorable 属性指定一些命名空间,如果使用这些命名空间的应用程序无法理解它们,则可将其忽略。替换内容元素指定可由应用程序在运行时选择的替换标记。例如,Word 2013 只能选择它可识别的替换标记。该规范中提供了有关兼容性规则属性和替换内容元素及其详细信息的完整列表。Markup compatibility is discussed in ECMA-376, Second Edition, Part 3 - Markup Compatibility and Extensibility, which is recommended reading to understand markup compatibility. The specification defines XML attributes to express compatibility rules, and XML elements to specify alternate content. For example, the Ignorable attribute specifies namespaces that can be ignored when they are not understood by the consuming application. Alternate-Content elements specify markup alternatives that can be chosen by an application at run time. For example, Word 2013 can choose only the markup alternative that it recognizes. The complete list of compatibility-rule attributes and alternate-content elements and their details can be found in the specification.


Open XML SDK 2.5 支持标记兼容性Open XML SDK 2.5 Support for Markup Compatibility

Open XML SDK 2.5 针对标记兼容性所做的工作是详尽细微的。但是,其目标可以概述为,使用你在打开文档时分配的设置对文档进行预处理,从而:The work that the Open XML SDK 2.5 does for markup compatibility is detailed and subtle. However, the goal can be summarized as: using settings that you assign when you open a document, preprocess the document to:

  1. 从无法理解的命名空间(例如,在 Office 2010 上下文中打开的 Office 2013 文档)中筛选或移除任何元素Filter or remove any elements from namespaces that will not be understood (for example, Office 2013 document opened in Office 2010 context)

  2. 按照 Open XML 规范中的规定处理任何标记兼容性元素和属性。Process any markup compatibility elements and attributes as specified in the Open XML specification.

根据 ECMA-376 第二版的 3.13 部分执行预处理。The preprocessing performed is in accordance with ECMA-376, Second Edition: Part 3.13.

Open XML SDK 2.5 对标记兼容性的支持主要体现在两个类和依据 ECMA-376 第二版对内容进行预处理的方式上。这两个类分别为 OpenSettingsMarkupCompatibilityProcessSettings。使用前者可提供适用于 SDK 总体行为的设置。使用后者可提供这些设置的一部分,尤其是应用于标记兼容性的设置。The Open XML SDK 2.5 support for markup compatibility comes primarily in the form of two classes and in the manner in which content is preprocessed in accordance with ECMA-376, Second Edition. The two classes are OpenSettings and MarkupCompatibilityProcessSettings. Use the former to provide settings that apply to SDK behavior overall. Use the latter to supply one part of those settings, specifically those that apply to markup compatibility.


打开时做好准备Setting the stage when you Open

使用 Open XML SDK 2.5 打开文档时,可以选择使用一个带有接受 OpenSettings 类实例作为参数的签名的重载。When you open a document using the Open XML SDK 2.5, you have the option of using an overload with a signature that accepts an instance of the OpenSettings class as a parameter. 使用打开设置类可提供一些用于控制 SDK 行为的重要设置。You use the open settings class to provide certain important settings that govern the behavior of the SDK. 尤其是存储在 MarkupCompatibilityProcessSettings 属性中的一组设置可确定如何处理标记兼容性元素和属性。One set of settings in particular, stored in theMarkupCompatibilityProcessSettings property, determines how markup compatibility elements and attributes are processed. 在打开文档之前,将属性设置为 MarkupCompatibilityProcessSettings 类的一个实例。You set the property to an instance of theMarkupCompatibilityProcessSettings class prior to opening a document.

该类具有以下属性:The class has the following properties:

-
ProcessMode - 确定预处理的部件。ProcessMode - Determines the parts that are preprocessed.

-
TargetFileFormatVersions - 指定应用于预处理的上下文。TargetFileFormatVersions - Specifies the context that applies to preprocessing.

默认情况下,不对文档进行预处理。然而,如果你指定打开设置并提供标记兼容性处理设置,则将根据这些设置对文档进行预处理。By default, documents are not preprocessed. If however you do specify open settings and provide markup compatibility process settings, then the document is preprocessed in accordance with those settings.

下面的代码示例演示如何使用打开设置类的一个实例作为参数来调用 Open 方法。请注意, ProcessModeTargetFileFormatVersions 属性可作为 MarkupCompatiblityProcessSettings 构造函数的一部分进行初始化。The following code example demonstrates how to call the Open method with an instance of the open settings class as a parameter. Notice that the ProcessMode and TargetFileFormatVersions properties are initialized as part of the MarkupCompatiblityProcessSettings constructor.

    // Create instance of OpenSettings
    OpenSettings openSettings = new OpenSettings();

    // Add the MarkupCompatibilityProcessSettings
    openSettings.MarkupCompatibilityProcessSettings =
        new MarkupCompatibilityProcessSettings(
            MarkupCompatibilityProcessMode.ProcessAllParts, 
            FileFormatVersions.Office2007);

    // Open the document with OpenSettings
    using (WordprocessingDocument wordDocument = 
        WordprocessingDocument.Open(filename, 
            true,
            openSettings))
    {
        // ... more code here
    }

预处理过程中发生的情况What Happens During Preprocessing

在预处理过程中,Open XML SDK 2.5 会移除标记兼容性命名空间中的元素和属性,同时移除未选择的替换内容元素的内容,并根据需要解释兼容性规则属性。此工作由处理模式和目标文件格式版本属性进行引导。During preprocessing, the Open XML SDK 2.5 removes elements and attributes in the markup compatibility namespace, removing the contents of unselected alternate-content elements, and interpreting compatibility-rule attributes as appropriate. This work is guided by the process mode and target file format versions properties.

ProcessMode 属性确定要进行预处理的部件。The ProcessMode property determines the parts to be preprocessed. 这些 部件中的内容进行筛选,从而仅包含 TargetFileFormatVersions 属性中指示的应用程序版本可理解的元素。The content in those parts is filtered to contain only elements that are understood by the application version indicated in the TargetFileFormatVersions property.

警告

[!警告] 预处理操作会影响保存的内容。当保存文件时,唯一保存的标记就是在预处理后保留的标记。Preprocessing affects what gets saved. When you save a file, the only markup that is saved is that which remains after preprocessing.


了解处理模式Understanding Process Mode

处理模式指定应对哪些文档部件进行预处理。The process mode specifies which document parts should be preprocessed. 可将此属性设置为 MarkupCompatibilityProcessMode 枚举的一个成员。You set this property to a member of the MarkupCompatibilityProcessMode enumeration. 默认值 NoProcess 指示不需要执行预处理。The default value, NoProcess, indicates that no preprocessing is performed. 你的应用程序必须能够理解和处理文档标记中包含的任何元素和属性,包括标记兼容性命名空间中的任何元素和属性。Your application must be able to understand and handle any elements and attributes present in the document markup, including any of the elements and attributes in the Markup Compatibility namespace.

你可能希望处理特定的文档部件,同时保持其余部件不会更改。例如,你可能希望确保对文件进行最小程度的修改。在这种情况下,可为处理模式指定 ProcessLoadedPartsOnly。进行此设置后,预处理及关联的筛选将只应用到加载的文档部件,而不是整个文档。You might want to work on specific document parts while leaving the rest untouched. For example, you might want to ensure minimal modification to the file. In that case, specify ProcessLoadedPartsOnly for the process mode. With this setting, preprocessing and the associated filtering is only applied to the loaded document parts, not the entire document.

最后,还有一个 ProcessAllParts 值。正如其名称的含义一样,如果选择此值,则会对整个文档进行预处理。Finally, there is ProcessAllParts, which specifies what the name implies. When you choose this value, the entire document is preprocessed.


设置目标文件格式版本Setting the Target File Format Version

使用目标文件格式版本属性,可以选择在 Office 2010 或 Office 2013 上下文中处理标记兼容性内容。The target file format versions property lets you choose to process markup compatibility content in either Office 2010 or Office 2013 context. TargetFileFormatVersions 属性设置为 FileFormatVersions 枚举的一个成员。Set the TargetFileFormatVersions property to a member of theFileFormatVersions enumeration.

默认值 Office2010 意味着,SDK 将假定理解 Office 2010 中定义的命名空间,但不理解 Office 2013 中定义的命名空间。因此,在预处理的过程中,SDK 将忽略 Office 2013 中定义的命名空间,并选择 Office 2010 兼容的替换内容。The default value, Office2010, means the SDK will assume that namespaces defined in Office 2010 are understood, but not namespaces defined in Office 2013. Thus, during preprocessing, the SDK will ignore the namespaces defined in Office 2013 and choose the Office 2010 compatible alternate-content.

如果将目标文件格式版本属性设置为 Office2013,则 Open XML SDK 2.5 将假定理解 Office 2010 和 Office 2013 中定义的所有命名空间,不忽略在 Office 2013 下定义的任何内容,并将选择 Office 2013 兼容的替换内容。When you set the target file format versions property to Office2013, the Open XML SDK 2.5 assumes that all of the namespaces defined in Office 2010 and Office 2013 are understood, does not ignore any content defined under Office 2013, and will choose the Office 2013 compatible alternate-content.