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. É acedido através Office.context
de .
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 |
commerce |
Verdadeiro, se a plataforma atual permitir que o suplemento apresente uma IU para venda ou atualização; caso contrário, devolve Falso. |
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 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. |
office |
Fornece acesso às propriedades de cores de temas do Office. |
partition |
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 |
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. |
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 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. |
touch |
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. |
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.
}
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;
}
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
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;
}
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
object
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
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);
}
}
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
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.
}
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]}`);
Comentários do Office Add-ins
O Office Add-ins é um projeto código aberto. Selecione um link para fornecer comentários: