Office.Context interface

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

auth: Auth;

Valor da propriedade

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

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.
}

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

contentLanguage: string;

Valor da propriedade

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

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; 
}

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

diagnostics: ContextInformation;

Valor da propriedade

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);

Obtém a região (idioma) especificada pelo utilizador para a IU da aplicação do Office.

displayLanguage: string;

Valor da propriedade

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

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; 
}

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

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

Contém a aplicação do Office na qual o suplemento está em execução.

host: HostType;

Valor da propriedade

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.
}

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

license: object;

Valor da propriedade

Exemplos

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

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

mailbox: Office.Mailbox;

Valor da propriedade

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;

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

officeTheme: OfficeTheme;

Valor da propriedade

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

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

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

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

platform: PlatformType;

Valor da propriedade

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

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

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);
}
...

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

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();

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

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

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

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.
}

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

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

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

urls: Urls;

Valor da propriedade

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