Office.Context interface
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
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 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. |
commerce |
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. |
content |
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. |
display |
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. |
office |
Fornece acesso às propriedades de cores de temas do Office. |
partition |
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á |
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. |
roaming |
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 |
sensitivity |
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. |
touch |
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
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 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
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 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
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
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
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
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
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
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
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
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
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
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]}`);
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de