Modelo de objeto comum de API JavaScript para Office

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 fornecem 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 Caixa de Correio dá a um suplemento do Outlook acesso a mensagens, compromissos e perfis de usuário. Compreender 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 obtém acesso a muitos objetos diferentes no ambiente de runtime. O objeto Context reflete o contexto de tempo de execução do suplemento na API. O Context é o objeto principal que fornece acesso aos objetos mais importantes da API, como os objetos Document e Mailbox . Esses objetos fornecem acesso ao conteúdo de documentos e de 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 os métodos do objeto Document para interagir com o conteúdo de documentos do Word, planilhas do Excel ou agendas de projeto. Da mesma forma, nos suplementos do Outlook, você pode usar a propriedade mailbox do objeto Context para acessar as propriedades e os métodos do objeto Mailbox para interagir com a mensagem, a solicitação de reunião ou o conteúdo do compromisso.

O objeto Context também fornece acesso às propriedades contentLanguage e displayLanguage que permitem determinar a localidade (idioma) usado 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. Use Document os 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 "adicionar" 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 projeto da 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 objeto quando o Document painel de tarefas ou o suplemento de conteúdo é 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 objeto para documentos do CustomXmlParts Word.

O Document objeto suporta quatro maneiras para 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 funcionam os métodos de acesso a dados baseados em seleção e associação, este artigo explica primeiro como as APIs de acesso a dados fornecem acesso consistente a dados em 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 da capacidade de forçar 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 principais.

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 sem formatação. No Word, há suporte para três formatos de texto: texto sem formatação, HTML e Office Open XML (OOXML). 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 de dados baseado 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 da Matrix tem suporte apenas no Excel e no Word.
Tabela 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 and rows . O acesso a dados da tabela tem suporte apenas no Excel e no Word.

Coerção de tipo de dados

Os métodos de acesso a dados nos objetos e Binding dão suporte à Document 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 que os dados tabulares cresçam dinamicamente quando linhas e colunas forem adicionadas e precisar trabalhar com cabeçalhos de tabela, deverá usar o tipo de dados tabela (especificando o parâmetro coercionType de um Document método de acesso a 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 está planejando adicionar linhas e colunas e seus dados não exigem a funcionalidade de cabeçalho, você deve usar o tipo de dados matrix (especificando o parâmetro coercionType do método de acesso a 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 ao tipo especificado, a propriedade AsyncResult.status no retorno de chamada retornará "failed". Use a propriedade AsyncResult.error para acessar um objeto Error com informações sobre por que a chamada de método falhou.

Trabalhar com seleções usando o objeto Documento

O Document objeto tem métodos que você pode usar para ler e gravar na seleção atual do usuário de uma forma "obter e definir". Para fazer isso, o Document objeto fornece os getSelectedDataAsync métodos and 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 Bindings e Binding

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 seguinte valor ao seu suplemento.

  • Permite o acesso a estruturas de dados comuns 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 persistem no documento e os usuários podem acessá-las mais tarde.

Ao estabelecer uma vinculação, você pode assinar eventos de alteração de dados e seleção com escopo para essa região específica do documento ou 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 fornece acesso ao conjunto de todas as associações estabelecidas no documento ou planilha. Você pode acessar uma associação individual por sua ID usando o método Bindings.getBindingByIdAsync ou a função Office.select . Estabeleça novas associações e remova as existentes usando um dos seguintes métodos do Bindings objeto: addFromSelectionAsync, addFromPromptAsync, addFromNamedItemAsync ou releaseByIdAsync.

Ao criar uma associação usando os addFromSelectionAsyncmétodos , addFromPromptAsync, ou addFromNamedItemAsync , você especifica o tipo de associação usando o parâmetro bindingType .

Tipo de vinculação Descrição Suporte ao aplicativo de host
Vinculaçã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 headers e rows . 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 de criar uma associação usando um dos três métodos "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. Esses três objetos herdam os métodos getDataAsync e setDataAsync do objeto Binding, o que permite interagir com os dados associados.

Para obter exemplos de código que demonstram como executar tarefas usando associações, consulte Associar a regiões em um documento ou planilha.

Trabalhar 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 como trabalhar com os CustomXmlParts objetos andCustomXmlPart, consulte o exemplo de código do Word-add-in-Work-with-custom-XML-parts.

Trabalhar com o documento inteiro 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 funcionalidade para obter arquivos inteiros de documentos do Word e do PowerPoint em fatias (partes) 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 para uso nos suplementos do Outlook, como o objeto Item no modo de redação ou leitura, use a propriedade mailbox do objeto Context para acessar o objeto Mailbox . O código a seguir é um exemplo.

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

Importante

Ao chamar Office.context.mailbox.item uma mensagem, observe que o Painel de Leitura no cliente Outlook deve estar ativado. Para obter orientações sobre como configurar o Painel de Leitura, confira Usar e configurar o Painel de Leitura para visualizar mensagens.

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

  • Objeto Office: para inicialização.

  • Objeto Context: para acesso a propriedades de conteúdo e idioma de exibição.

Para obter informações sobre como usar JavaScript em suplementos do Outlook, consulte Suplementos do Outlook. Para explorar a API JavaScript do Outlook, consulte a página de referência da API do Outlook .

  • Last updated on