Office.Context interface

  • Referência
Pacote:
office

Representa o ambiente de tempo de execução do suplemento e fornece acesso a objetos de chave da API. O contexto atual existe como uma propriedade do Office. Ele é acessado usando Office.context.

Comentários

Aplicativos: Excel, Outlook, PowerPoint, Project, Word

Propriedades

auth

Fornece informações e acesso ao usuário conectado.
commerceAllowed

True, se a plataforma atual permitir que o suplemento exiba uma interface do usuário para venda ou atualização; caso contrário, retorna False.
contentLanguage

Obtém a localidade (idioma) especificada pelo usuário para editar o documento ou item.
diagnostics

Obtém informações sobre o ambiente em que o suplemento está em execução.
displayLanguage

Obtém a localidade (idioma) especificada pelo usuário para a interface do usuário do aplicativo do Office.
document

Obtém um objeto que representa o documento com o qual o suplemento de conteúdo ou painel de tarefas está interagindo.
host

Contém o aplicativo do Office no qual o suplemento está em execução.
license

Obtém as informações de licença para a instalação do Office do usuário.
mailbox

Fornece acesso ao modelo de objeto de suplemento do Microsoft Outlook.
officeTheme

Fornece acesso às propriedades de cores de temas do Office.
partitionKey

Obtém uma chave de partição para armazenamento local. Os suplementos devem usar essa chave de partição como parte da chave de armazenamento para armazenar dados com segurança. A chave de partição está undefined em ambientes sem partição, como os controles do navegador para aplicativos Windows.
platform

Fornece a plataforma na qual o suplemento está em execução.
requirements

Fornece um método para determinar quais conjuntos de requisitos têm suporte no aplicativo e na plataforma atuais do Office.
roamingSettings

Obtém um objeto que representa as configurações personalizadas ou o estado de um suplemento de email do Outlook salvos na caixa de correio do usuário.

O RoamingSettings objeto permite armazenar e acessar dados de um suplemento de email que é armazenado na caixa de correio de um usuário, portanto, ele está disponível para esse suplemento quando ele está em execução de qualquer aplicativo cliente usado para acessar essa caixa de correio.
sensitivityLabelsCatalog

Obtém o objeto para marcar o status do catálogo de rótulos de confidencialidade no Outlook e recuperar todos os rótulos de confidencialidade disponíveis se o catálogo estiver habilitado.
touchEnabled

Especifica se a plataforma e o dispositivo permitem interação com toque. True se o suplemento estiver em execução em um dispositivo touch, como um iPad; false caso contrário.
ui

Fornece objetos e métodos que você pode usar para criar e manipular componentes da interface do usuário, como caixas de diálogo.
urls

Obtém o objeto para recuperar as URLs de runtime de um suplemento.

Detalhes da propriedade

auth

Observação

Esta API é fornecida como uma versão prévia para desenvolvedores e pode ser alterada com base nos comentários que recebemos. Não use esta API em um ambiente de produção.

Fornece informações e acesso ao usuário conectado.

auth: Auth;

Valor da propriedade

Office.Auth

commerceAllowed

True, se a plataforma atual permitir que o suplemento exiba uma interface do usuário para venda ou atualização; caso contrário, retorna False.

commerceAllowed: boolean;

Valor da propriedade

boolean

Comentários

Aplicativos: Excel, Word

commerceAllowed só há suporte no Office no iPad.

A App Store do iOS não dá suporte a aplicativos com suplementos que fornecem links para sistemas de pagamento adicionais. No entanto, os suplementos do Office em execução no Office na área de trabalho do Windows ou no navegador permitem esses links. Se você quiser que a interface do usuário do seu suplemento forneça um link para um sistema de pagamento externo em plataformas diferentes do iOS, você pode usar a propriedade commerceAllowed para controlar quando esse link for exibido.

contentLanguage

Obtém a localidade (idioma) especificada pelo usuário para editar o documento ou item.

contentLanguage: string;

Valor da propriedade

string

Comentários

O contentLanguage valor reflete a configuração de Linguagem de Edição especificada comLinguagem deOpções> de Arquivo> no aplicativo do Office.

Detalhes do suporte

Para obter mais informações sobre os requisitos de aplicativo e servidor do Office, consulte Requisitos para executar suplementos do Office.

Aplicativos com suporte, por plataforma

Office no Windows Office no navegador da Web Office no iPad Outlook em dispositivos móveis Office no Mac
Excel Com suporte Com suporte Com suporte
Outlook Com suporte Com suporte Com suporte Com suporte
Powerpoint Com suporte Com suporte Com suporte
Projeto Com suporte
Word Com suporte Com suporte Com suporte

Exemplos

function sayHelloWithContentLanguage() {
    const myContentLanguage = Office.context.contentLanguage;
    switch (myContentLanguage) {
        case 'en-US':
            write('Hello!');
            break;
        case 'en-NZ':
            write('G\'day mate!');
            break;
    }
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

diagnostics

Obtém informações sobre o ambiente em que o suplemento está em execução.

diagnostics: ContextInformation;

Valor da propriedade

Office.ContextInformation

Comentários

Importante: no Outlook, essa propriedade está disponível no conjunto de requisitos da caixa de correio 1.5. Para todos os conjuntos de requisitos da caixa de correio, você pode usar a propriedade Office.context.mailbox.diagnóstico para obter informações semelhantes.

Exemplos

const contextInfo = Office.context.diagnostics;
console.log("Office application: " + contextInfo.host);
console.log("Office version: " + contextInfo.version);
console.log("Platform: " + contextInfo.platform);

displayLanguage

Obtém a localidade (idioma) especificada pelo usuário para a interface do usuário do aplicativo do Office.

displayLanguage: string;

Valor da propriedade

string

Comentários

O valor retornado é uma cadeia de caracteres no formato de marca de linguagem RFC 1766, como en-US.

O displayLanguage valor reflete a configuração atual da Linguagem de Exibição especificada comLinguagemde Opções> de Arquivo> no aplicativo do Office.

Ao usar no Outlook, os modos aplicáveis são Compose ou Read.

Detalhes do suporte

Para obter mais informações sobre os requisitos de aplicativo e servidor do Office, consulte Requisitos para executar suplementos do Office.

Aplicativos com suporte, por plataforma

Office no Windows Office no navegador da Web Office no iPad Outlook em dispositivos móveis Office no Mac
Excel Com suporte Com suporte Com suporte Com suporte
Outlook Com suporte Com suporte Com suporte Com suporte
Powerpoint Com suporte Com suporte Com suporte Com suporte
Projeto Com suporte Com suporte
Word Com suporte Com suporte Com suporte

Exemplos

function sayHelloWithDisplayLanguage() {
    const myDisplayLanguage = Office.context.displayLanguage;
    switch (myDisplayLanguage) {
        case 'en-US':
            write('Hello!');
            break;
        case 'en-NZ':
            write('G\'day mate!');
            break;
    }
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

document

Obtém um objeto que representa o documento com o qual o suplemento de conteúdo ou painel de tarefas está interagindo.

document: Office.Document;

Valor da propriedade

Office.Document

Exemplos

// Extension initialization code.
let _document;

// The initialize function is required for all add-ins.
Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
    // After the DOM is loaded, code specific to the add-in can run.
    // Initialize instance variables to access API objects.
    _document = Office.context.document;
    });
}

host

Contém o aplicativo do Office no qual o suplemento está em execução.

host: HostType;

Valor da propriedade

Office.HostType

Comentários

Importante: no Outlook, essa propriedade está disponível no conjunto de requisitos da caixa de correio 1.5. Você também pode usar a Office.context.diagnostics propriedade para obter o aplicativo começando com o conjunto de requisitos 1.5. Para todos os conjuntos de requisitos da caixa de correio, você pode usar a propriedade Office.context.mailbox.diagnóstico para obter informações semelhantes.

license

Obtém as informações de licença para a instalação do Office do usuário.

license: string;

Valor da propriedade

string

mailbox

Fornece acesso ao modelo de objeto de suplemento do Microsoft Outlook.

mailbox: Office.Mailbox;

Valor da propriedade

Office.Mailbox

Comentários

Nível mínimo de permissão: restrito

Modo outlook aplicável: compor ou ler

Propriedades principais:

  • diagnostics: fornece informações de diagnóstico para um suplemento do Outlook.

  • item: fornece métodos e propriedades para acessar uma mensagem ou compromisso em um suplemento do Outlook.

  • userProfile: fornece informações sobre o usuário em um suplemento do Outlook.

Exemplos

// The following line of code access the item object of the JavaScript API for Office.
const item = Office.context.mailbox.item;

officeTheme

Fornece acesso às propriedades de cores de temas do Office.

officeTheme: OfficeTheme;

Valor da propriedade

Office.OfficeTheme

Exemplos

function applyOfficeTheme(){
    // Get office theme colors.
    const bodyBackgroundColor = Office.context.officeTheme.bodyBackgroundColor;
    const bodyForegroundColor = Office.context.officeTheme.bodyForegroundColor;
    const controlBackgroundColor = Office.context.officeTheme.controlBackgroundColor;
    const controlForegroundColor = Office.context.officeTheme.controlForegroundColor;

    // Apply body background color to a CSS class.
    $('.body').css('background-color', bodyBackgroundColor);
}

partitionKey

Obtém uma chave de partição para armazenamento local. Os suplementos devem usar essa chave de partição como parte da chave de armazenamento para armazenar dados com segurança. A chave de partição está undefined em ambientes sem partição, como os controles do navegador para aplicativos Windows.

partitionKey: string;

Valor da propriedade

string

Comentários

Consulte o artigo Persistir estado de suplemento e configurações para obter mais informações.

Exemplos

// Store the value "Hello" in local storage with the key "myKey1".
setInLocalStorage("myKey1", "Hello");

// ... 

// Retrieve the value stored in local storage under the key "myKey1".
const message = getFromLocalStorage("myKey1");
console.log(message);

// ...

function setInLocalStorage(key: string, value: string) {
    const myPartitionKey = Office.context.partitionKey;

    // Check if local storage is partitioned. 
    // If so, use the partition to ensure the data is only accessible by your add-in.
    if (myPartitionKey) {
        localStorage.setItem(myPartitionKey + key, value);
    } else {
        localStorage.setItem(key, value);
    }
}

function getFromLocalStorage(key: string) {
    const myPartitionKey = Office.context.partitionKey;

    // Check if local storage is partitioned.
    if (myPartitionKey) {
        return localStorage.getItem(myPartitionKey + key);
    } else {
        return localStorage.getItem(key);
    }
}

platform

Fornece a plataforma na qual o suplemento está em execução.

platform: PlatformType;

Valor da propriedade

Office.PlatformType

Comentários

Importante:

  • No Outlook, essa propriedade está disponível no conjunto de requisitos da caixa de correio 1.5. Você também pode usar a Office.context.diagnostics propriedade para obter a plataforma começando com o conjunto de requisitos 1.5. Para todos os conjuntos de requisitos da caixa de correio, você pode usar a propriedade Office.context.mailbox.diagnóstico para obter informações semelhantes.

  • No Outlook, OfficeOnline será retornado se um suplemento estiver em execução no Outlook na Web ou no novo Outlook no Windows (versão prévia).

requirements

Fornece um método para determinar quais conjuntos de requisitos têm suporte no aplicativo e na plataforma atuais do Office.

requirements: RequirementSetSupport;

Valor da propriedade

Office.RequirementSetSupport

roamingSettings

Obtém um objeto que representa as configurações personalizadas ou o estado de um suplemento de email do Outlook salvos na caixa de correio do usuário.

O RoamingSettings objeto permite armazenar e acessar dados de um suplemento de email que é armazenado na caixa de correio de um usuário, portanto, ele está disponível para esse suplemento quando ele está em execução de qualquer aplicativo cliente usado para acessar essa caixa de correio.

roamingSettings: Office.RoamingSettings;

Valor da propriedade

Office.RoamingSettings

Comentários

Nível mínimo de permissão: restrito

Modo outlook aplicável: compor ou ler

Exemplos

// Get the current value of the 'myKey' setting.
const value = Office.context.roamingSettings.get('myKey');
// Update the value of the 'myKey' setting.
Office.context.roamingSettings.set('myKey', 'Hello World!');
// Persist the change.
Office.context.roamingSettings.saveAsync();

sensitivityLabelsCatalog

Obtém o objeto para marcar o status do catálogo de rótulos de confidencialidade no Outlook e recuperar todos os rótulos de confidencialidade disponíveis se o catálogo estiver habilitado.

sensitivityLabelsCatalog: Office.SensitivityLabelsCatalog;

Valor da propriedade

Office.SensitivityLabelsCatalog

Comentários

[ Conjunto de API: Caixa de correio 1.13 ]

Nível mínimo de permissão: item de leitura/gravação

Modo outlook aplicável: compose

Exemplos

// Check if the catalog of sensitivity labels is enabled on the current mailbox.
Office.context.sensitivityLabelsCatalog.getIsEnabledAsync((asyncResult) => {
    // If the catalog is enabled, get all available sensitivity labels.
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value == true) {
        Office.context.sensitivityLabelsCatalog.getAsync((asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                const catalog = asyncResult.value;
                console.log("Sensitivity Labels Catalog:");
                console.log(JSON.stringify(catalog));
            } else {
                console.log("Action failed with error: " + asyncResult.error.message);
            }
        });
    } else {
        console.log("Action failed with error: " + asyncResult.error.message);
    }
});

touchEnabled

Especifica se a plataforma e o dispositivo permitem interação com toque. True se o suplemento estiver em execução em um dispositivo touch, como um iPad; false caso contrário.

touchEnabled: boolean;

Valor da propriedade

boolean

Comentários

Aplicativos: Excel, PowerPoint, Word

touchEnabled só há suporte no Office no iPad.

Use a propriedade touchEnabled para determinar quando seu suplemento está em execução em um dispositivo touch e, se necessário, ajuste o tipo de controles e o tamanho e espaçamento de elementos na interface do usuário do suplemento para acomodar interações de toque.

ui

Fornece objetos e métodos que você pode usar para criar e manipular componentes da interface do usuário, como caixas de diálogo.

ui: UI;

Valor da propriedade

Office.UI

urls

Observação

Esta API é fornecida como uma versão prévia para desenvolvedores e pode ser alterada com base nos comentários que recebemos. Não use esta API em um ambiente de produção.

Obtém o objeto para recuperar as URLs de runtime de um suplemento.

urls: Urls;

Valor da propriedade

Office.Urls

Comentários

[ Conjunto de API: visualização da caixa de correio ]

Nível mínimo de permissão: restrito

Modo outlook aplicável: compor ou ler

Exemplos

// Get the value of the first parameter of the JavaScript runtime URL.
// For example, if the URL is https://wwww.contoso.com/training?key1=value1&key2=value2,
// the following function logs "First parameter value: value1" to the console.
const url = Office.context.urls.javascriptRuntimeUrl;
const regex = /=([^&]+)/;
console.log(`First parameter value: ${url.match(regex)[1]}`);