Modelo de objeto comum de API JavaScript para Office

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, obtém acesso a muitos objetos diferentes no ambiente de runtime. O objeto De contexto reflete o contexto de runtime do suplemento na API. O Contexto é o objeto principal que fornece acesso aos objetos mais importantes da API, como os objetos Documento e Caixa de Correio . Estes objetos 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 documento do objeto Contexto para aceder às propriedades e métodos do objeto Documento para interagir com o conteúdo de Word documentos, 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. Utilize 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 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 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 inicializar com a propriedade documental do Context objeto. O Document objeto define métodos comuns de acesso a dados partilhados entre Word e documentos do Excel e também fornece acesso ao CustomXmlParts objeto para Word documentos.

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 o ajudar a compreender como funcionam os métodos de acesso a dados baseados em seleção e enlace, este artigo explica primeiro como as APIs de acesso a dados fornecem acesso consistente a dados em diferentes aplicações 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 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 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 coagidos ao tipo especificado, a propriedade AsyncResult.status na chamada de retorno devolve "failed". Utilize a propriedade AsyncResult.error para aceder a um objeto Error com informações sobre o motivo pelo qual a chamada do método falhou.

Trabalhar com seleções com o objeto Documento

O Document objeto tem métodos que pode utilizar para 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 de dados comuns em aplicações suportadas do Office, como tabelas, intervalos ou texto (uma execução contígua de carateres).

• 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. Os enlaces persistem no documento e os utilizadores podem aceder-lhes mais tarde.

Quando estabelece um enlace, pode subscrever eventos de alteração de dados e seleção que estão no âmbito dessa região específica do documento ou folha de cálculo. 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. Pode aceder a um enlace individual através do respetivo ID através do método Bindings.getBindingByIdAsync ou da função Office.select . Estabeleça novos enlaces e remova os existentes com um dos seguintes métodos do Bindings objeto: addFromSelectionAsync, addFromPromptAsync, addFromNamedItemAsync ou releaseByIdAsync.

Quando cria um enlace com os addFromSelectionAsyncmétodos , addFromPromptAsyncou addFromNamedItemAsync , especifica o tipo de enlace com 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 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 criar um enlace com 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. 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 realizar tarefas com enlaces, veja Vincular a regiões num documento ou folha de cálculo.

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 eCustomXmlPart, 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 Ficheiro e Setor fornecem funcionalidades para obter ficheiros de documentos completos do Word e do PowerPoint em setores (segmentos) de até 4 MB de cada 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 a utilizar nos suplementos do Outlook, como o objeto Item no modo de composição ou leitura, utilize a propriedade caixa de correio do objeto Contexto para aceder ao objeto Caixa de Correio . 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, tenha em atenção que o Painel de Leitura no cliente do Outlook tem de estar ativado. Para obter orientações sobre como configurar o Painel de Leitura, consulte Utilizar e configurar o Painel de Leitura para pré-visualizar mensagens.

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.

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