Modelo de objeto comum de API JavaScript para Office

  • Artigo

Importante

Este artigo aplica-se às APIs Comuns, o modelo da 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 da aplicação 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 utilizador. Compreender as relações entre estes 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 nos suplementos de conteúdo, pode utilizar a propriedade documental do objeto Contexto para aceder às propriedades e métodos do objeto Documento para interagir com o conteúdo de documentos do Word, folhas de cálculo do Excel ou agendas do Project. Da mesma forma, nos suplementos do Outlook, pode utilizar a propriedade caixa de correio do objeto Contexto para aceder às propriedades e métodos do objeto Caixa de Correio para interagir com a mensagem, o pedido de reunião ou o conteúdo do compromisso.

O objeto De contexto também fornece acesso às propriedades contentLanguage e displayLanguage que lhe permitem determinar a região (idioma) utilizada no documento ou item, ou pela aplicação 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. Pode utilizar Document membros do objeto para aceder aos dados das seguintes formas.

  • Ler e gravar as seleções ativas na forma de texto, células contíguas (matrizes) ou tabelas.

  • Dados tabulares (matrizes ou tabelas).

  • Enlaces (criados 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.

Também pode utilizar 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 estas formas de acesso a dados começam a partir de uma instância do objeto abstrato Document .

Pode aceder a uma instância do Document objeto quando o painel de tarefas ou o suplemento de conteúdo é inicializado com a propriedade do documento do Context objeto. O Document objeto define métodos comuns de acesso a dados partilhados em documentos do Word e do Excel e também fornece acesso ao objeto para documentos do CustomXmlParts Word.

O Document objeto suporta quatro formas de os programadores acederem aos conteúdos 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 de forma totalmente integrada em diferentes documentos do Office, a API JavaScript do Office abstrai as particularidades de cada aplicação do Office através 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. São suportados 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, Project e PowerPoint, só é suportado texto simples. No Word, são suportados três formatos de texto: texto simples, 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 só suportam o acesso a dados baseados na 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ó é suportado 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 através das headers propriedades e rows . O acesso a dados de tabela só é suportado no Excel e no Word.

Coerção de tipo de dados

Os métodos de acesso a dados nos Document objetos e Enlace suportam a especificação do tipo de dados pretendido com o parâmetro coercionType destes 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 precisar que os seus dados tabulares cresçam dinamicamente quando são adicionadas linhas e colunas e tiver de trabalhar com cabeçalhos de tabela, deve utilizar o tipo de dados da tabela (ao especificar 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 não estiver a planear adicionar linhas e colunas e os seus dados não necessitarem de funcionalidades de cabeçalho, deve utilizar o tipo de dados de matriz (ao especificar o parâmetro coercionType do método de acesso a dados como "matrix" ou Office.CoercionType.Matrix), que fornece um modelo mais simples de interagir 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 com o objeto Documento

O Document objeto expõe métodos que lhe permitem ler e escrever na seleção atual do utilizador de forma "obter e definir". Para tal, 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 enlaces com os objetos Enlaces e Enlaces

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 enlaces fornece o seguinte valor ao 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 todos os enlaces estabelecidos no documento ou folha de cálculo. Um enlace individual pode ser acedido pelo respetivo ID através do método Bindings.getBindingByIdAsync ou da função Office.select . Pode estabelecer novos enlaces, bem como remover os existentes através de um dos seguintes métodos do Bindings objeto: addFromSelectionAsync, addFromPromptAsync, addFromNamedItemAsync ou releaseByIdAsync.

Existem três tipos diferentes de enlaces que especifica com o parâmetro bindingType quando cria um enlace com os addFromSelectionAsyncmétodos ou addFromPromptAsyncaddFromNamedItemAsync .

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 através das propriedades de 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 de um enlace ser criado através de um dos três métodos "adicionar" do Bindings objeto, pode trabalhar com os dados e propriedades do enlace com os métodos do objeto correspondente: MatrixBinding, TableBinding ou TextBinding. Todos estes três objetos herdam os métodos getDataAsync e setDataAsync do Binding objeto que lhe 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.

Trabalhar com peças XML personalizadas com 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 obter demonstrações de como trabalhar com os CustomXmlParts objetos e CustomXmlPart , veja o exemplo de código Word-add-in-Work-with-custom-XML-parts .

Trabalhar com todo o documento com 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 aceder aos objetos e membros especificamente para utilização nos suplementos do Outlook, como o objeto Item , utilize a propriedade caixa de correio do objeto Contexto para aceder ao objeto Caixa de Correio , conforme mostrado na seguinte linha de código.

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

Além disso, os suplementos do Outlook podem utilizar 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 .