Compartilhar via

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. É acedido através Office.contextde .

Comentários

Detalhes do suporte

Para obter mais informações sobre os requisitos de aplicações e servidores do Office, consulte Requisitos para executar Suplementos do Office.

Aplicações suportadas, por plataforma

Office na Web Office no Windows Office no Mac Office no iPad Outlook em dispositivos móveis
Excel Com suporte Com suporte Com suporte Com suporte Não aplicável
Outlook Com suporte Com suporte Com suporte Com suporte Com suporte
PowerPoint Com suporte Com suporte Com suporte Com suporte Não aplicável
Projeto Sem suporte Com suporte Com suporte Sem suporte Não aplicável
Word Com suporte Com suporte Com suporte Com suporte Não aplicável

Propriedades

auth

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

Verdadeiro, se a plataforma atual permitir que o suplemento apresente uma IU para venda ou atualização; caso contrário, devolve Falso.
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 região (idioma) especificada pelo utilizador para a IU da aplicação 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 a aplicação do Office na qual o suplemento está em execução.
license

Obtém as informações de licença para a instalação do Office do utilizador.
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 o armazenamento local. Os suplementos devem utilizar esta chave de partição como parte da chave de armazenamento para armazenar dados de forma segura. A chave de partição encontra-se undefined em ambientes sem criação de partições, como os controlos do browser para aplicações do Windows.
platform

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

Fornece um método para determinar que conjuntos de requisitos são suportados na aplicação e 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-lhe armazenar e aceder a dados de um suplemento de correio armazenado na caixa de correio de um utilizador, para que esteja disponível para esse suplemento quando estiver em execução a partir de qualquer aplicação cliente utilizada para aceder a essa caixa de correio.
sensitivityLabelsCatalog

Obtém o objeto para marcar a status do catálogo de etiquetas de confidencialidade no Outlook e obter todas as etiquetas de confidencialidade disponíveis se o catálogo estiver ativado.
touchEnabled

Especifica se a plataforma e o dispositivo permitem a interação por toque. Verdadeiro se o suplemento estiver em execução num dispositivo tátil, como um iPad; falso, 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 obter os 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

Verdadeiro, se a plataforma atual permitir que o suplemento apresente uma IU para venda ou atualização; caso contrário, devolve Falso.

commerceAllowed: boolean;

Valor da propriedade

boolean

Comentários

Aplicações: Excel, Word

commerceAllowed só é suportado 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 no ambiente de trabalho do Windows ou no browser permitem essas ligações. Se quiser que a IU do seu suplemento forneça uma ligação para um sistema de pagamento externo em plataformas que não sejam iOS, pode utilizar a propriedade commerceAllowed para controlar quando essa ligação é apresentada.

Exemplos

// Check if the add-in is running on an iPad.
const allowCommerce = Office.context.commerceAllowed;
const isTouchEnabled = Office.context.touchEnabled;
if (!allowCommerce && isTouchEnabled) {
    // Add-in is running on an iPad.
    // Do something.
}

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 definição Idioma de Edição especificada como Idioma deOpções> de Ficheiro> na aplicação do Office.

Detalhes do suporte

Para obter mais informações sobre os requisitos de aplicações e servidores do Office, consulte Requisitos para executar Suplementos do Office.

Aplicações suportadas, por plataforma

Office na Web Office no Windows Office no Mac Office no iPad Outlook em dispositivos móveis
Excel Com suporte Com suporte Sem suporte Com suporte Não aplicável
Outlook Com suporte Com suporte Com suporte Com suporte Com suporte
PowerPoint Com suporte Com suporte Sem suporte Com suporte Não aplicável
Projeto Sem suporte Com suporte Sem suporte Sem suporte Não aplicável
Word Com suporte Com suporte Sem suporte Com suporte Não aplicável

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, esta propriedade está disponível no conjunto de requisitos da Caixa de Correio 1.5. Para todos os conjuntos de requisitos da Caixa de Correio, pode utilizar 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 região (idioma) especificada pelo utilizador para a IU da aplicação do Office.

displayLanguage: string;

Valor da propriedade

string

Comentários

O valor devolvido é uma cadeia no formato de etiqueta de Idioma RFC 1766, como en-US.

O displayLanguage valor reflete a definição atual de Idioma de Apresentação especificada como Idioma deOpções> de Ficheiro> na aplicação do Office.

Ao utilizar no Outlook, os modos aplicáveis são Compose ou Ler.

Detalhes do suporte

Para obter mais informações sobre os requisitos de aplicações e servidores do Office, consulte Requisitos para executar Suplementos do Office.

Aplicações suportadas, por plataforma

Office na Web Office no Windows Office no Mac Office no iPad Outlook em dispositivos móveis
Excel Com suporte Com suporte Com suporte Com suporte Não aplicável
Outlook Com suporte Com suporte Com suporte Com suporte Com suporte
PowerPoint Com suporte Com suporte Com suporte Com suporte Não aplicável
Projeto Sem suporte Com suporte Com suporte Sem suporte Não aplicável
Word Sem suporte Com suporte Com suporte Com suporte Não aplicável

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 a aplicação do Office na qual o suplemento está em execução.

host: HostType;

Valor da propriedade

Office.HostType

Comentários

Importante: no Outlook, esta propriedade está disponível no conjunto de requisitos da Caixa de Correio 1.5. Também pode utilizar a Office.context.diagnostics propriedade para que a aplicação comece com o requisito definido 1.5. Para todos os conjuntos de requisitos da Caixa de Correio, pode utilizar a propriedade Office.context.mailbox.diagnóstico para obter informações semelhantes.

Exemplos

const host = Office.context.host;
if (host === Office.HostType.Excel || host === Office.HostType.PowerPoint || host === Office.HostType.Word) {
    // Do something.
} else if (host === Office.HostType.Outlook) {
    // Do something.
}

license

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

license: object;

Valor da propriedade

object

Exemplos

const license = Office.context.license;
console.log(`Office license: ${license}`);

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: Compose ou Leitura

Propriedades da chave:

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

  • item : fornece métodos e propriedades para aceder a uma mensagem ou compromisso num suplemento do Outlook.

  • userProfile : fornece informações sobre o utilizador num 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() {
    // Identify the current Office theme in use.
    const currentOfficeTheme = Office.context.officeTheme.themeId;

    if (currentOfficeTheme === Office.ThemeId.Colorful || currentOfficeTheme === Office.ThemeId.White) {
        console.log("No changes required.");
    }

    // Get the colors of the current Office theme.
    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 theme colors to a CSS class.
    $("body").css("background-color", bodyBackgroundColor);

    if (Office.context.officeTheme.isDarkTheme()) {
        $("h1").css("color", controlForegroundColor);
    }
}

partitionKey

Obtém uma chave de partição para o armazenamento local. Os suplementos devem utilizar esta chave de partição como parte da chave de armazenamento para armazenar dados de forma segura. A chave de partição encontra-se undefined em ambientes sem criação de partições, como os controlos do browser para aplicações do Windows.

partitionKey: string;

Valor da propriedade

string

Comentários

Consulte o artigo Manter o estado e as definições do suplemento 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, esta propriedade está disponível no conjunto de requisitos da Caixa de Correio 1.5. Também pode utilizar a Office.context.diagnostics propriedade para que a plataforma comece com o requisito definido 1.5. Para todos os conjuntos de requisitos da Caixa de Correio, pode utilizar a propriedade Office.context.mailbox.diagnóstico para obter informações semelhantes.

  • No Outlook, OfficeOnline é devolvido se um suplemento estiver em execução no Outlook na Web ou no novo Outlook no Windows.

Exemplos

// Request permission from a user to access their devices from Office on the web.
if (Office.context.platform === Office.PlatformType.OfficeOnline) {
    const deviceCapabilities = [
        Office.DevicePermissionType.camera,
        Office.DevicePermissionType.microphone
    ];
    Office.devicePermission
        .requestPermissions(deviceCapabilities)
        .then((isGranted) => {
            if (isGranted) {
                // Do something with device capabilities.
            }
        })
        .catch((error) => {
            console.log("Permission denied.");
            console.error(error);
        });
}

requirements

Fornece um método para determinar que conjuntos de requisitos são suportados na aplicação e plataforma atuais do Office.

requirements: RequirementSetSupport;

Valor da propriedade

Office.RequirementSetSupport

Exemplos

// To use the setCellProperties API, check if ExcelApi 1.9 is supported.
if (Office.context.requirements.isSetSupported("ExcelApi", "1.9")) {
    const cellProperties: Excel.SettableCellProperties[][] =
    colors2D.map(row =>
        row.map(color =>
            ({
                format: {
                    fill: {
                        color: color
                    }
                }
            })
        )
    );
    sheet.getRangeByIndexes(1, 1, originalSize, originalSize).setCellProperties(cellProperties);
}
...

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-lhe armazenar e aceder a dados de um suplemento de correio armazenado na caixa de correio de um utilizador, para que esteja disponível para esse suplemento quando estiver em execução a partir de qualquer aplicação cliente utilizada para aceder a 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: Compose ou Leitura

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 a status do catálogo de etiquetas de confidencialidade no Outlook e obter todas as etiquetas de confidencialidade disponíveis se o catálogo estiver ativado.

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/escrita

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 a interação por toque. Verdadeiro se o suplemento estiver em execução num dispositivo tátil, como um iPad; falso, caso contrário.

touchEnabled: boolean;

Valor da propriedade

boolean

Comentários

Aplicações: Excel, PowerPoint Word

touchEnabled só é suportado no Office no iPad.

Utilize a propriedade touchEnabled para determinar quando o suplemento está em execução num dispositivo tátil e, se necessário, ajuste o tipo de controlos e o tamanho e espaçamento dos elementos na IU do suplemento para acomodar interações táteis.

Exemplos

// Check if the add-in is running on an iPad.
const allowCommerce = Office.context.commerceAllowed;
const isTouchEnabled = Office.context.touchEnabled;
if (!allowCommerce && isTouchEnabled) {
    // Add-in is running on an iPad.
    // Do something.
}

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

Exemplos

// Open a dialog and register an event handler.
Office.context.ui.displayDialogAsync(
    "https://www.contoso.com/myDialog.html",
    { height: 30, width: 20 },
    (asyncResult) => {
        const dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg) => {
            dialog.close();
            processMessage(arg);
        });
    }
);

urls

Obtém o objeto para obter os URLs de runtime de um suplemento.

urls: Urls;

Valor da propriedade

Office.Urls

Comentários

Aplicações: Outlook na Web e no Windows (clientes novos e clássicos)

[ Conjunto de API: Caixa de Correio 1.14 ]

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

Modo Outlook aplicável: Compose ou Leitura

Importante:

  • No Outlook na Web e no novo Outlook no Windows, esta API não é suportada em suplementos que implementam um painel de tarefas. Nestes clientes, a API só é suportada em suplementos que implementam a ativação baseada em eventos ou relatórios de spam integrados.

  • No Outlook clássico no Windows, esta API é suportada em suplementos que implementam um painel de tarefas, ativação baseada em eventos ou relatórios de spam integrados.

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]}`);