Introdução à compatibilidade de marcação

Artigo
01/21/2025

Este tópico apresenta as funcionalidades de compatibilidade de markup incluídas no SDK Open XML para o Office.

Introdução

Suponha que tem um documento do Microsoft Word 365 que emprega uma funcionalidade introduzida no Microsoft Office 365. Quando abre esse documento no Microsoft Word 2016, uma versão anterior, o que deve acontecer? Idealmente, quer que o documento permaneça interoperável com Word 2016, embora Word 2016 não compreenda a nova funcionalidade.

Considere também o que deve acontecer se abrir esse documento numa versão hipotética posterior do Office. Também aqui, quer que o documento funcione conforme esperado. Ou seja, quer que a versão posterior do Office compreenda e suporte uma funcionalidade utilizada num documento produzido pelo Word 365.

O Open XML antecipa estes cenários. A especificação Formatos de Ficheiro Open XML do Office descreve as instalações para alcançar os resultados pretendidos acima em ECMA-376, Segunda Edição, Parte 3 – Compatibilidade e Extensibilidade de Markup.

O SDK Open XML suporta compatibilidade de markup de uma forma que facilita a obtenção dos resultados pretendidos acima para e Office 365 sem ter de se tornar necessariamente um especialista nos detalhes da especificação.

O que é a compatibilidade de markup?

O Open XML define formatos para processamento de palavras, folhas de cálculo e documentos de apresentação sob a forma de idiomas de marcação específicos, nomeadamente WordprocessingML, Folha de CálculoML e PresentationML. No que diz respeito aos formatos de ficheiro Open XML, a compatibilidade de markup é a capacidade de um documento expresso num dos idiomas de marcação acima para facilitar a interoperabilidade entre aplicações ou versões de uma aplicação, com conjuntos de funcionalidades diferentes. Isto é suportado através da utilização de um conjunto definido de elementos e atributos XML no espaço de nomes Markup Compatibility da especificação Open XML. Tenha em atenção que, embora a marcação seja suportada no formato do documento, os produtores e consumidores de marcação, como o Microsoft Word, também têm de a suportar. Por outras palavras, a interoperabilidade é uma função de suporte tanto no formato de ficheiro como nas aplicações.

Compatibilidade de marcações na especificação Open XML file formats (Especificação de formatos de ficheiro Open XML)

A compatibilidade de marcações é abordada no ECMA-376, Segunda Edição, Parte 3 – Compatibilidade e Extensibilidade de Markup, que é a leitura recomendada para compreender a compatibilidade de marcações. A especificação define atributos XML para expressar regras de compatibilidade e elementos XML para especificar conteúdo alternativo. Por exemplo, o Ignorable atributo especifica espaços de nomes que podem ser ignorados quando não são compreendidos pela aplicação que consome. Alternate-Content elementos especificam alternativas de marcação que podem ser escolhidas por uma aplicação no tempo de execução. Por exemplo, Word 2013 pode escolher apenas a alternativa de marcação que reconhece. A lista completa de atributos de regras de compatibilidade e elementos de conteúdo alternativo e os respetivos detalhes podem ser encontrados na especificação.

Open XML SDK support for markup compatibility (Suporte do SDK Open XML para compatibilidade de markup)

O trabalho que o SDK Open XML faz para compatibilidade de markup é detalhado e subtil. No entanto, o objetivo pode ser resumido como: ao utilizar as definições que atribui quando abre um documento, pré-processar o documento para:

Filtrar ou remover quaisquer elementos de espaços de nomes que não serão compreendidos (por exemplo, Office 365 documento aberto no contexto do Office 2016)
Processe quaisquer elementos e atributos de compatibilidade de markup, conforme especificado na especificação Open XML.

O pré-processamento efetuado está em conformidade com o ECMA-376, Segunda Edição: Parte 3.13.

O suporte do SDK Open XML para compatibilidade de markup vem principalmente sob a forma de duas classes e da forma como o conteúdo é pré-processado de acordo com o ECMA-376, Segunda Edição. As duas classes são OpenSettings e MarkupCompatibilityProcessSettings. Utilize o primeiro para fornecer definições que se aplicam ao comportamento geral do SDK. Utilize esta última opção para fornecer uma parte dessas definições, especificamente as que se aplicam à compatibilidade de markup.

Definir a fase ao abrir

Quando abre um documento com o SDK Open XML, tem a opção de utilizar uma sobrecarga com uma assinatura que aceita uma instância da OpenSettings classe como um parâmetro. Utilize a classe de definições abertas para fornecer determinadas definições importantes que regem o comportamento do SDK. Um conjunto de definições em particular, armazenadas na MarkupCompatibilityProcessSettings propriedade, determina como os elementos e atributos de compatibilidade de markup são processados. Defina a propriedade para uma instância da MarkupCompatibilityProcessSettings classe antes de abrir um documento.

A classe tem as seguintes propriedades:

ProcessMode - Determina as partes pré-processadas.
TargetFileFormatVersions - Especifica o contexto que se aplica ao pré-processamento.

Por predefinição, os documentos não são pré-processados. No entanto, se especificar definições abertas e fornecer definições do processo de compatibilidade de markup, o documento é pré-processado de acordo com essas definições.

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

    // 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 espaço de nomes de compatibilidade de markup, remove o conteúdo de elementos de conteúdo alternativo não selecionados e interpreta os atributos de regra de compatibilidade conforme adequado. Este trabalho é orientado pelas propriedades das versões do modo de processo e do formato de ficheiro de destino.

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

Aviso

O pré-processamento afeta o que é guardado. Quando guarda um ficheiro, a única marcação guardada é a que permanece após o pré-processamento.

Compreender o modo de processo

O modo de processo especifica as partes do documento que devem ser pré-processadas. Defina esta propriedade para um membro da MarkupCompatibilityProcessMode enumeração. O valor predefinido, NoProcess, indica que não é efetuada qualquer pré-processamento. A sua aplicação tem de conseguir compreender e processar quaisquer elementos e atributos presentes na marcação do documento, incluindo qualquer um dos elementos e atributos no espaço de nomes de Compatibilidade markup.

Poderá querer trabalhar em partes específicas do documento, deixando o resto inalterado. Por exemplo, poderá querer garantir uma modificação mínima ao ficheiro. Nesse caso, especifique ProcessLoadedPartsOnly para o modo de processo. Com esta definição, o pré-processamento e a filtragem associada só são aplicados às partes carregadas do documento e não a todo o documento.

Por fim, existe ProcessAllParts, que especifica o que o nome implica. Quando escolhe este valor, todo o documento é pré-processado.

Definir a versão do formato de ficheiro de destino

A propriedade de versões de formato de ficheiro de destino permite-lhe optar por processar conteúdos de compatibilidade de markup no contexto de uma versão específica do Office, por exemplo, Office 365. Defina a TargetFileFormatVersions propriedade para um membro da FileFormatVersions enumeração.

O valor predefinido, Office2007, significa que o SDK assumirá que os espaços de nomes definidos no Office 2007 são compreendidos, mas não os espaços de nomes definidos no Office 2010 ou posterior. Assim, durante o pré-processamento, o SDK irá ignorar os espaços de nomes definidos em versões mais recentes do Office e escolher o conteúdo alternativo compatível com o Office 2007.

Quando define a propriedade de formato de ficheiro de destino como Office2013, o SDK Open XML pressupõe que todos os espaços de nomes definidos no Office 2010 e no Office 2013 são compreendidos, não ignora quaisquer conteúdos definidos no Office 2013 e escolherá os conteúdos alternativos compatíveis com o Office 2013.

Compartilhar via