Introdução à compatibilidade de marcação

Artigo
11/16/2023

Este tópico apresenta os recursos de compatibilidade de marcação incluídos no SDK do Open XML para Office.

Introdução

Suponha que você tenha um documento Microsoft Word 2013 que emprega um recurso introduzido no Microsoft Office 2013. Quando você abre esse documento no Microsoft Word 2010, uma versão anterior, o que deve acontecer? Idealmente, você deseja que o documento permaneça interoperável com Word 2010, embora Word 2010 não entenda o novo recurso.

Considere também o que deve acontecer se você abrir esse documento em uma versão posterior hipotética do Office. Aqui também, você deseja que o documento funcione conforme o esperado. Ou seja, você deseja que a versão posterior do Office entenda e dê suporte a um recurso empregado em um documento produzido pelo Word 2013.

O Open XML antecipa esses cenários. A especificação Formatos de Arquivo XML do Office Open descreve as instalações para obter os resultados desejados acima no ECMA-376, Segunda Edição, Parte 3 – Compatibilidade de Marcação e Extensibilidade.

O SDK do Open XML dá suporte à compatibilidade de marcação de uma forma que facilite para você alcançar os resultados desejados acima para e o Office 2013 sem precisar necessariamente se tornar um especialista nos detalhes da especificação.

O que é compatibilidade de marcação?

Open XML define formatos para processamento de palavras, planilha e documentos de apresentação na forma de linguagens de marcação específicas, ou seja, WordprocessingML, SpreadsheetML e PresentationML. Em relação aos formatos de arquivo Open XML, a compatibilidade de marcação é a capacidade de um documento expresso em um dos idiomas de marcação acima para facilitar a interoperabilidade entre aplicativos ou versões de um aplicativo, com conjuntos de recursos diferentes. Isso é suportado por meio do uso de um conjunto definido de elementos XML e atributos no namespace de compatibilidade de marcação da especificação Open XML. Observe que, embora a marcação tenha suporte no formato de documento, produtores e consumidores de marcação, como o Microsoft Word, também devem dar suporte a ele. Em outras palavras, a interoperabilidade é uma função de suporte tanto no formato de arquivo quanto por aplicativos.

Compatibilidade de marcação na especificação de formatos de arquivo Open XML

A compatibilidade de marcação é discutida no ECMA-376, Segunda Edição, Parte 3 – Compatibilidade de Marcação e Extensibilidade, que é recomendável ler para entender a compatibilidade de marcação. A especificação define atributos XML para expressar regras de compatibilidade e elementos XML para especificar conteúdo alternativo. Por exemplo, o atributo Ignorável especifica namespaces que podem ser ignorados quando não são compreendidos pelo aplicativo consumidor. Alternate-Content elementos especificam alternativas de marcação que podem ser escolhidas por um aplicativo em tempo de execução. Por exemplo, Word 2013 pode escolher apenas a alternativa de marcação que reconhece. A lista completa de atributos de regra de compatibilidade e elementos de conteúdo alternativo e seus detalhes podem ser encontrados na especificação.

Abrir suporte ao SDK XML para compatibilidade de marcação

O trabalho que o SDK do Open XML faz para a compatibilidade de marcação é detalhado e sutil. No entanto, a meta pode ser resumida como: usando as configurações que você atribui ao abrir um documento, pré-processe o documento para:

Filtrar ou remover elementos de namespaces que não serão compreendidos (por exemplo, documento do Office 2013 aberto no contexto do Office 2010)
Processe todos os elementos e atributos de compatibilidade de marcação conforme especificado na especificação Open XML.

O pré-processamento executado está de acordo com o ECMA-376, Segunda Edição: Parte 3.13.

O suporte do SDK Open XML para compatibilidade de marcação vem principalmente na forma de duas classes e na maneira como o conteúdo é pré-processado de acordo com o ECMA-376, Second Edition. As duas classes são OpenSettings e MarkupCompatibilityProcessSettings. Use o primeiro para fornecer configurações que se aplicam ao comportamento do SDK em geral. Use este último para fornecer uma parte dessas configurações, especificamente aquelas que se aplicam à compatibilidade de marcação.

Defina o estágio quando você abrir

Ao abrir um documento usando o SDK Open XML, você tem a opção de usar uma sobrecarga com uma assinatura que aceita uma instância da classe OpenSettings como um parâmetro. Você usa a classe de configurações abertas para fornecer determinadas configurações importantes que regem o comportamento do SDK. Um conjunto de configurações em particular, armazenado na propriedade MarkupCompatibilityProcessSettings , determina como os elementos e atributos de compatibilidade de marcação são processados. Você define a propriedade como uma instância da classe MarkupCompatibilityProcessSettings antes de abrir um documento.

A classe tem as seguintes propriedades:

ProcessMode – determina as partes que são pré-processadas.
TargetFileFormatVersions – Especifica o contexto que se aplica ao pré-processamento.

Por padrão, os documentos não são pré-processados. No entanto, se você especificar configurações abertas e fornecer configurações de processo de compatibilidade de marcação, o documento será pré-processado de acordo com essas configurações.

O exemplo de código a seguir demonstra como chamar o método Open com uma instância da classe de configurações abertas como um parâmetro. Observe que as propriedades ProcessMode e TargetFileFormatVersions são inicializadas como parte do construtor MarkupCompatiblityProcessSettings .

    // 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
    }

O que acontece durante o pré-processamento

Durante o pré-processamento, o SDK Open XML remove elementos e atributos no namespace de compatibilidade de marcação, removendo o conteúdo de elementos de conteúdo alternativo não selecionados e interpretando atributos de regra de compatibilidade conforme apropriado. Esse trabalho é guiado pelo modo de processo e pelas propriedades de versões de formato de arquivo de destino.

A propriedade ProcessMode determina as partes a serem pré-processadas. O conteúdo nessas partes é filtrado para conter apenas elementos que são compreendidos pela versão do aplicativo indicada na propriedade TargetFileFormatVersions .

Aviso

O pré-processamento afeta o que é salvo. Quando você salva um arquivo, a única marcação salva é a que permanece após o pré-processamento.

Entender o modo de processo

O modo de processo especifica quais partes do documento devem ser pré-processadas. Você define essa propriedade como um membro da enumeração MarkupCompatibilityProcessMode . O valor padrão, NoProcess, indica que nenhum pré-processamento é executado. Seu aplicativo deve ser capaz de entender e manipular quaisquer elementos e atributos presentes na marcação do documento, incluindo qualquer um dos elementos e atributos no namespace de compatibilidade de marcação.

Talvez você queira trabalhar em partes específicas do documento, deixando o restante intocado. Por exemplo, talvez você queira garantir uma modificação mínima no arquivo. Nesse caso, especifique ProcessLoadedPartsOnly para o modo de processo. Com essa configuração, o pré-processamento e a filtragem associada só são aplicados às partes carregadas do documento, não ao documento inteiro.

Por fim, há ProcessAllParts, que especifica o que o nome implica. Quando você escolhe esse valor, o documento inteiro é pré-processado.

Definir a versão do formato de arquivo de destino

A propriedade de versões de formato de arquivo de destino permite que você escolha processar o conteúdo de compatibilidade de marcação no contexto do Office 2010 ou do Office 2013. Defina a propriedade TargetFileFormatVersions como um membro da enumeração FileFormatVersions .

O valor padrão, Office2010, significa que o SDK assumirá que os namespaces definidos no Office 2010 são compreendidos, mas não namespaces definidos no Office 2013. Assim, durante o pré-processamento, o SDK ignorará os namespaces definidos no Office 2013 e escolherá o conteúdo alternativo compatível com o Office 2010.

Quando você define a propriedade de versões de formato de arquivo de destino como Office2013, o SDK Open XML pressupõe que todos os namespaces definidos no Office 2010 e Office 2013 sejam compreendidos, não ignore nenhum conteúdo definido no Office 2013 e escolha o conteúdo alternativo compatível com o Office 2013.