Modelo de objeto comum de API JavaScript para Office

Artigo
03/21/2023

Importante

Este artigo se aplica às APIs Comuns, o modelo de API JavaScript do Office que foi introduzido com o Office 2013. Essas APIs incluem recursos como interface de usuário, caixas de diálogo e configurações de cliente, que são comuns entre vários tipos de aplicativos do Office. Os suplementos do Outlook usam exclusivamente APIs comuns, especialmente o subconjunto de APIs expostos por meio do objetoCaixa de Correio.

Você só deve usar APIs comuns para cenários que não têm suporte por APIs específicas do aplicativo. Para saber quando usar APIs comuns em vez de APIs específicas do aplicativo, confira Entendendo a API de JavaScript do Office.

As APIs JavaScript do Office dão acesso à funcionalidade subjacente do aplicativo cliente do Office. A maioria desse acesso percorre alguns objetos importantes. O objeto contexto oferece acesso ao tempo de execução ambiente depois de inicialização. O objetodocumento oferece o controle do usuário a um documento do Excel, PowerPoint ou Word. O objeto Mailbox fornece um suplemento do Outlook acesso a mensagens, compromissos e perfis de usuário. Entender as relações entre esses objetos de alto nível é a base de um Suplemento do Office.

Objeto de contexto

Aplica-se a: todos os tipos de suplementos

Quando um suplemento é inicializado, ele possui diversos objetos diferentes com os quais pode interagir no ambiente do tempo de execução. O contexto do tempo de execução do suplemento é refletido na API por meio do objeto Contexto. OContexto é o principal objeto que fornece acesso aos objetos mais importantes da API, como os objetos Documento e Caixa de correio que, por sua vez, fornecem acesso ao conteúdo do documento e da caixa de correio.

Por exemplo, no painel de tarefas ou suplementos de conteúdo, você pode usar a propriedade document do objeto Context para acessar as propriedades e métodos do objeto Document para interagir com o conteúdo de documentos Word, planilhas do Excel ou agendamentos do Projeto. Da mesma forma, nos suplementos do Outlook, você pode usar a propriedade caixa de correio do objeto Context para acessar as propriedades e os métodos do objeto Mailbox para interagir com o conteúdo da mensagem, da solicitação de reunião ou do compromisso.

O objeto Context também fornece acesso às propriedades contentLanguage e displayLanguage que permitem determinar a localidade (linguagem) usada no documento ou item ou pelo aplicativo do Office. A propriedade roamingSettings permite que você acesse os membros do objeto RoamingSettings, que armazena configurações específicas para o suplemento para caixas de correio de usuários individuais. Por fim, o objeto Contexto fornece uma propriedade ui que permite que o suplemento inicie caixas de diálogo pop-up.

Objeto Document

Aplica-se a: tipos de suplemento de conteúdo e painel de tarefas

Para interagir com dados do documento no Excel, PowerPoint e Word, a API fornece o objeto Document. Você pode usar Document membros do objeto para acessar dados das seguintes maneiras.

Ler e gravar as seleções ativas na forma de texto, células contíguas (matrizes) ou tabelas.
Dados tabulares (matrizes ou tabelas).
Associações (criadas com os métodos "add" do Bindings objeto).
Partes XML personalizadas (somente para Word).
Configurações ou estado do suplemento persistido por suplemento no documento.

Você também pode usar o Document objeto para interagir com dados em documentos do Project. A funcionalidade específica do Project para a API está documentada nos membros da classe abstrata ProjectDocument. Para saber mais sobre a criação de suplementos de painel de tarefas, consulte Suplementos de painel de tarefas para o Project.

Todas essas formas de acesso a dados começam a partir de uma instância do objeto abstrato Document .

Você pode acessar uma instância do Document objeto quando o painel de tarefas ou o suplemento de conteúdo for inicializado usando a propriedade document do Context objeto. O Document objeto define métodos comuns de acesso a dados compartilhados entre documentos do Word e do Excel e também fornece acesso ao CustomXmlParts objeto para documentos Word.

O Document objeto dá suporte a quatro maneiras de os desenvolvedores acessarem o conteúdo do documento.

Acesso baseado em seleção
Acesso baseado em associação
Acesso baseado em partes personalizadas do XML (apenas para Word)
Acesso baseado em documento (somente para Word e PowerPoint)

Para ajudá-lo a entender como os métodos de acesso de dados baseados na seleção e na associação funcionam, explicaremos como as APIs de acesso aos dados proporcionam acesso consistente aos dados de diferentes aplicativos do Office.

Acesso consistente aos dados entre aplicativos do Office

Aplica-se a: tipos de suplemento de conteúdo e painel de tarefas

Para criar extensões que funcionam perfeitamente em diferentes documentos do Office, a API JavaScript do Office abstrai as particularidades de cada aplicativo do Office por meio de tipos de dados comuns e a capacidade de coagir diferentes conteúdos de documentos em três tipos de dados comuns.

Tipo comuns de dados

Nos acessos a dados baseados em seleção e em associação, os conteúdos dos documentos são expostos por meio dos tipos de dados comuns a todos os aplicativos compatíveis do Office. Há suporte para três tipos de dados main.

Tipo de dados	Descrição	Suporte ao aplicativo de host
Texto	Fornece uma representação, em uma cadeia de caracteres, dos dados na seleção ou associação.	No Excel, No Project e no PowerPoint, há suporte apenas para texto simples. Em Word, há suporte para três formatos de texto: texto sem formatação, HTML e OOXML (Office Open XML). Quando o texto é selecionado em uma célula no Excel, os métodos baseados em seleção realizam os processos de leitura e gravação para todo o conteúdo da célula, mesmo que apenas uma parte do texto esteja selecionada na célula. Quando texto é selecionado no Word e no PowerPoint, os métodos baseados em seleção realizam os processos de leitura e gravação apenas para os caracteres selecionados. O Project e o PowerPoint dão suporte apenas ao acesso a dados baseados em seleção.
Matriz	Fornece os dados na seleção ou associação como uma Array bidimensional, que, no JavaScript, é implementada como uma matriz de matrizes. Por exemplo, duas linhas de valores string em duas colunas seriam `[['a', 'b'], ['c', 'd']]`, e uma única coluna com três linhas seria `[['a'], ['b'], ['c']]`.	O acesso a dados de matriz só tem suporte no Excel e no Word.
Table	Fornece os dados na seleção ou associação como um objeto TableData. O `TableData` objeto expõe os dados por meio das `headers` propriedades e `rows` .	O acesso a dados de tabela só tem suporte no Excel e no Word.

Coerção de tipo de dados

Os métodos de acesso de Document dados nos objetos e Associação dão suporte à especificação do tipo de dados desejado usando o parâmetro coercionType desses métodos e os valores de enumeração coercionType correspondentes. Independentemente da forma real da associação, os diferentes aplicativos do Office dão suporte aos tipos de dados comuns ao tentar forçar os dados a usarem o tipo de dados solicitado. Por exemplo, se uma tabela ou um parágrafo do Word for selecionado, o desenvolvedor pode escolher se deseja lê-lo como texto sem formatação, Office Open XML ou tabela, e a implementação da API manipula as conversões de dados e as transformações necessárias.

Dica

Quando devo usar a matriz ou a tabela coercionType para o acesso aos dados? Se você precisar de seus dados tabulares para crescer dinamicamente quando linhas e colunas forem adicionadas e trabalhar com cabeçalhos de tabela, use o tipo de dados de tabela (especificando o parâmetro coercionType de um Document método de acesso de dados de objeto ou Binding como "table" ou Office.CoercionType.Table). A adição de linhas e colunas na estrutura de dados tem suporte nos dados de tabela e matriz, mas o acréscimo de linhas e colunas só tem suporte para dados de tabela. Se você não estiver planejando adicionar linhas e colunas e seus dados não exigirem funcionalidade de cabeçalho, use o tipo de dados de matriz (especificando o parâmetro coercionType do método de acesso de dados como "matrix" ou Office.CoercionType.Matrix), que fornece um modelo mais simples de interação com os dados.

Se os dados não puderem ser forçados para o tipo especificado, a propriedade AsyncResult.status presente nos retornos de chamada retorna "failed", e você pode usar a propriedade AsyncResult.error para acessar um objeto Error com informações sobre o motivo pelo qual a chamada de método falhou.

Trabalhar com seleções usando o objeto Document

O Document objeto expõe métodos que permitem ler e gravar na seleção atual do usuário de forma "obter e definir". Para fazer isso, o Document objeto fornece os getSelectedDataAsync métodos e setSelectedDataAsync .

Para obter exemplos de códigos que demostram como realizar tarefas com seleções, consulte Ler e gravar dados na seleção ativa em um documento ou uma planilha.

Trabalhar com associações usando os objetos Associações e Associação

O acesso a dados baseado em associação habilita os suplementos de conteúdo e painel de tarefas a acessarem de forma consistente determinada região de um documento ou uma planilha por meio de um identificador vinculado a uma associação. Primeiro, o suplemento precisa estabelecer a associação chamando um dos métodos que vinculam uma parte do documento a um identificador exclusivo: addFromPromptAsync, addFromSelectionAsync ou addFromNamedItemAsync. Depois que a associação é estabelecida, o suplemento pode usar o identificador fornecido para acessar os dados contidos na região vinculada do documento ou da planilha. A criação de associações fornece o valor a seguir para seu suplemento.

Permite o acesso a estruturas comuns de dados em aplicativos compatíveis do Office, como: tabelas, intervalos ou texto (uma execução contígua de caracteres).
Habilita operações de leitura/gravação sem exigir que o usuário realize uma seleção.
Estabelece uma relação entre o suplemento e os dados presentes no documento. As associações estão presentes no documento e podem ser acessadas em um momento posterior.

A criação de uma associação também permite que você se inscreva em eventos de alteração de seleção e de dados que apresentem um escopo definido para essa região específica do documento ou da planilha. Isso significa que o suplemento só é notificado sobre alterações que ocorrem dentro da região associada, e não sobre alterações gerais que ocorrem em todo o documento ou planilha.

O objeto Bindings expõe um método getAllAsync que dá acesso ao conjunto de todas as associações estabelecidas no documento ou planilha. Uma associação individual pode ser acessada por sua ID usando o método Bindings.getBindingByIdAsync ou a função Office.select . Você pode estabelecer novas associações, bem como remover as existentes usando um dos seguintes métodos do Bindings objeto: addFromSelectionAsync, addFromPromptAsync, addFromNamedItemAsync ou releaseByIdAsync.

Há três tipos diferentes de associações que você especifica com o parâmetro bindingType ao criar uma associação com os addFromSelectionAsyncmétodos ou addFromNamedItemAsync . addFromPromptAsync

Tipo de associação	Descrição	Suporte ao aplicativo de host
Associação de texto	Associa a uma região do documento que pode ser representada como um texto.	No Word, a maioria das seleções contíguas são válidas, enquanto no Excel apenas as seleções de células únicas podem ser usadas para uma associação de texto. No Excel, só há suporte para texto sem formatação. No Word, há suporte para três formatos: texto sem formatação, HTML e Open XML do Office.
Associação de matriz	Associa a uma região fixa de um documento que contém dados tabulares sem cabeçalhos. Os dados de uma associação de matriz são gravados ou lidos como uma Array bidimensional, que é implementada como uma matriz de matrizes no JavaScript. Por exemplo, duas linhas de valores string em duas colunas podem ser gravadas ou lidas como `[['a', 'b'], ['c', 'd']]`, e uma única coluna de três linhas pode ser gravada ou lida como `[['a'], ['b'], ['c']]`.	No Excel, qualquer seleção contígua de células pode ser usada para estabelecer uma associação de matriz. No Word, apenas as tabelas dão suporte à associação de matriz.
Associação de tabelas	Associa a uma região de um documento que contém uma tabela com cabeçalhos. Os dados em uma associação de tabela são gravados ou lidos como um objeto TableData. O `TableData` objeto expõe os dados por meio das propriedades cabeçalhos e linhas .	Qualquer tabela do Excel ou Word pode ser a base para uma associação de tabela. Após estabelecer uma associação de tabelas, as linhas ou colunas novas que um usuário adicionar à tabela são automaticamente incluídas na associação.

Depois que uma associação é criada usando um dos três métodos de "adicionar" do Bindings objeto, você pode trabalhar com os dados e as propriedades da associação usando os métodos do objeto correspondente: MatrixBinding, TableBinding ou TextBinding. Todos esses três objetos herdam os métodos getDataAsync e setDataAsync do Binding objeto que permitem interagir com os dados vinculados.

Para obter exemplos de códigos que demonstram como realizar tarefas com associações, consulte Associar a regiões em um documento ou uma planilha.

Trabalhe com partes XML personalizadas usando os objetos CustomXmlParts e CustomXmlPart

Aplica-se a: suplementos de painel de tarefas para Word

Os objetos CustomXmlParts e CustomXmlPart da API fornecem acesso a partes XML personalizadas de documentos do Word, que permitem a manipulação orientada por XML de conteúdo do documento. Para demonstrações de trabalho com os CustomXmlParts objetos eCustomXmlPart, consulte o exemplo de código Word-add-in-Work-with-custom-XML-parts.

Trabalhe com todo o documento usando o método getFileAsync

Aplica-se a: suplementos de painel de tarefas para Word e PowerPoint

O método Document.getFileAsync e os membros dos objetos File e Slice fornecem a funcionalidade necessária para obter documentos inteiros do Word e PowerPoint em fatias (frações) de até 4 MB por vez. Para saber mais, consulte Obter todo o documento por meio de um suplemento para PowerPoint ou Word.

Objeto Mailbox

Aplica-se a: suplementos do Outlook

Os suplementos do Outlook usam principalmente um subconjunto da API exposta no objeto Mailbox. Para acessar os objetos e membros especificamente para uso em suplementos do Outlook, como o objeto Item , use a propriedade caixa de correio do objeto Context para acessar o objeto Mailbox , conforme mostrado na linha de código a seguir.

// Access the Item object.
const item = Office.context.mailbox.item;

Além disso, os suplementos do Outlook podem usar os seguintes objetos.

Objeto Office: para inicialização.
Objeto Context: para acesso a propriedades de conteúdo e idioma de exibição.
Objeto RoamingSettings: para salvar as configurações personalizadas do suplemento do Outlook na caixa de correio do usuário em que o suplemento está instalado.

Para obter informações sobre como usar o JavaScript em suplementos do Outlook, confira Suplementos do Outlook .