Office.Context interface

  • Ссылка
Пакет:
office

Представляет среду выполнения надстройки и открывает доступ к ключевым объектам API. Текущий контекст существует как свойство Office. Доступ к нему осуществляется с помощью Office.context.

Комментарии

Приложения: Excel, Outlook, PowerPoint, Project, Word

Свойства

auth

Предоставляет информацию и доступ вошедшему в систему пользователю.
commerceAllowed

True, если текущая платформа позволяет надстройке отображать пользовательский интерфейс для продажи или обновления; в противном случае возвращает значение False.
contentLanguage

Получает указанный пользователем языковой стандарт (язык) для редактирования документа или элемента.
diagnostics

Возвращает сведения о среде, в которой выполняется надстройка.
displayLanguage

Возвращает языковой стандарт (язык), заданный пользователем для пользовательского интерфейса приложения Office.
document

Получает объект, представляющий документ, с которым взаимодействует контентная надстройка или надстройка области задач.
host

Содержит приложение Office, в котором выполняется надстройка.
license

Возвращает сведения о лицензии для установки Office пользователя.
mailbox

Предоставляет доступ к объектной модели надстройки Microsoft Outlook.
officeTheme

Предоставляет доступ к свойствам цветов темы Office.
partitionKey

Возвращает ключ секции для локального хранилища. Надстройки должны использовать этот ключ секции как часть ключа хранилища для безопасного хранения данных. Ключ секции находится undefined в средах без секционирования, таких как элементы управления браузера для приложений Windows.
platform

Предоставляет платформу, на которой выполняется надстройка.
requirements

Предоставляет метод для определения того, какие наборы требований поддерживаются в текущем приложении и платформе Office.
roamingSettings

Получает объект, представляющий настраиваемые параметры или состояние надстройки почты, сохраненное в почтовом ящике пользователя.

Объект RoamingSettings позволяет хранить и получать доступ к данным для почтовой надстройки, хранящейся в почтовом ящике пользователя, поэтому она доступна этой надстройке при ее запуске из любого клиентского приложения, используемого для доступа к этому почтовому ящику.
sensitivityLabelsCatalog

Возвращает объект для проверка состояния каталога меток конфиденциальности в Outlook и получения всех доступных меток конфиденциальности, если каталог включен.
touchEnabled

Указывает, разрешено ли сенсорное взаимодействие между платформой и устройством. Значение true, если надстройка работает на сенсорном устройстве, например на iPad; Значение false в противном случае.
ui

Предоставляет объекты и методы, которые можно использовать для создания компонентов пользовательского интерфейса, например диалоговых окон, и управления ими.
urls

Возвращает объект для получения URL-адресов среды выполнения надстройки.

Сведения о свойстве

auth

Примечание

Этот API предоставляется в качестве предварительной версии для разработчиков и может быть изменен на основе полученных нами отзывов. Не используйте этот API в рабочей среде.

Предоставляет информацию и доступ вошедшему в систему пользователю.

auth: Auth;

Значение свойства

Office.Auth

commerceAllowed

True, если текущая платформа позволяет надстройке отображать пользовательский интерфейс для продажи или обновления; в противном случае возвращает значение False.

commerceAllowed: boolean;

Значение свойства

boolean

Комментарии

Приложения: Excel, Word

commerceAllowed поддерживается только в Office на iPad.

App Store для iOS не поддерживает apps с надстройками, которые предоставляют ссылки на дополнительные системы платежей. Однако надстройки Office, работающие в Office на рабочем столе Windows или в браузере, разрешают такие ссылки. Если вы хотите, чтобы пользовательский интерфейс надстройки предоставлял ссылку на внешнюю платежную систему на платформах, отличных от iOS, можно использовать свойство commerceAllowed для управления отображением этой ссылки.

contentLanguage

Получает указанный пользователем языковой стандарт (язык) для редактирования документа или элемента.

contentLanguage: string;

Значение свойства

string

Комментарии

Значение contentLanguage отражает параметр "Язык редактирования", указанный в параметре"Язык параметров файлов>"> в приложении Office.

Сведения о поддержке

Дополнительные сведения о требованиях к приложениям и серверам Office см. в разделе Требования для запуска надстроек Office.

Поддерживаемые приложения по платформам

Office для Windows Office в веб-браузере Office для iPad Outlook на мобильных устройствах Office для Mac
Excel Поддерживается Поддерживается Поддерживается
Outlook Поддерживается Поддерживается Поддерживается Поддерживается
Powerpoint Поддерживается Поддерживается Поддерживается
Проекта Поддерживается
Word Поддерживается Поддерживается Поддерживается

Примеры

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

Возвращает сведения о среде, в которой выполняется надстройка.

diagnostics: ContextInformation;

Значение свойства

Office.ContextInformation

Комментарии

Важно! В Outlook это свойство доступно в наборе обязательных для почтового ящика 1.5. Для всех наборов обязательных для почтовых ящиков можно использовать свойство Office.context.mailbox.диагностика, чтобы получить аналогичные сведения.

Примеры

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

displayLanguage

Возвращает языковой стандарт (язык), заданный пользователем для пользовательского интерфейса приложения Office.

displayLanguage: string;

Значение свойства

string

Комментарии

Возвращаемое значение представляет собой строку в формате тега языка RFC 1766, например en-US.

Значение displayLanguage отражает текущий параметр языка интерфейса, указанный в разделеЯзык параметров>файлов> в приложении Office.

При использовании в Outlook применимыми режимами являются Создание или Чтение.

Сведения о поддержке

Дополнительные сведения о требованиях к приложениям и серверам Office см. в разделе Требования для запуска надстроек Office.

Поддерживаемые приложения по платформам

Office для Windows Office в веб-браузере Office для iPad Outlook на мобильных устройствах Office для Mac
Excel Поддерживается Поддерживается Поддерживается Поддерживается
Outlook Поддерживается Поддерживается Поддерживается Поддерживается
Powerpoint Поддерживается Поддерживается Поддерживается Поддерживается
Проекта Поддерживается Поддерживается
Word Поддерживается Поддерживается Поддерживается

Примеры

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

Получает объект, представляющий документ, с которым взаимодействует контентная надстройка или надстройка области задач.

document: Office.Document;

Значение свойства

Office.Document

Примеры

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

Содержит приложение Office, в котором выполняется надстройка.

host: HostType;

Значение свойства

Office.HostType

Комментарии

Важно! В Outlook это свойство доступно в наборе обязательных для почтового ящика 1.5. Вы также можете использовать свойство для Office.context.diagnostics запуска приложения с набором требований 1.5. Для всех наборов обязательных для почтовых ящиков можно использовать свойство Office.context.mailbox.диагностика, чтобы получить аналогичные сведения.

license

Возвращает сведения о лицензии для установки Office пользователя.

license: string;

Значение свойства

string

mailbox

Предоставляет доступ к объектной модели надстройки Microsoft Outlook.

mailbox: Office.Mailbox;

Значение свойства

Office.Mailbox

Комментарии

Минимальный уровень разрешений: ограниченный

Применимый режим Outlook: создание или чтение

Ключевые свойства:

  • diagnostics: предоставляет диагностические сведения для надстройки Outlook.

  • item: предоставляет методы и свойства для доступа к сообщению или встрече в надстройке Outlook.

  • userProfile: предоставляет сведения о пользователе в надстройке Outlook.

Примеры

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

officeTheme

Предоставляет доступ к свойствам цветов темы Office.

officeTheme: OfficeTheme;

Значение свойства

Office.OfficeTheme

Примеры

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

Возвращает ключ секции для локального хранилища. Надстройки должны использовать этот ключ секции как часть ключа хранилища для безопасного хранения данных. Ключ секции находится undefined в средах без секционирования, таких как элементы управления браузера для приложений Windows.

partitionKey: string;

Значение свойства

string

Комментарии

Дополнительные сведения см. в статье Сохранение состояния надстройки и параметров .

Примеры

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

Предоставляет платформу, на которой выполняется надстройка.

platform: PlatformType;

Значение свойства

Office.PlatformType

Комментарии

Важно!

  • В Outlook это свойство доступно в наборе обязательных для почтового ящика 1.5. Вы также можете использовать свойство , Office.context.diagnostics чтобы получить платформу, начиная с набора требований 1.5. Для всех наборов обязательных для почтовых ящиков можно использовать свойство Office.context.mailbox.диагностика, чтобы получить аналогичные сведения.

  • В Outlook возвращается, OfficeOnline если надстройка выполняется в Outlook в Интернете или в новом Outlook в Windows (предварительная версия).

requirements

Предоставляет метод для определения того, какие наборы требований поддерживаются в текущем приложении и платформе Office.

requirements: RequirementSetSupport;

Значение свойства

Office.RequirementSetSupport

roamingSettings

Получает объект, представляющий настраиваемые параметры или состояние надстройки почты, сохраненное в почтовом ящике пользователя.

Объект RoamingSettings позволяет хранить и получать доступ к данным для почтовой надстройки, хранящейся в почтовом ящике пользователя, поэтому она доступна этой надстройке при ее запуске из любого клиентского приложения, используемого для доступа к этому почтовому ящику.

roamingSettings: Office.RoamingSettings;

Значение свойства

Office.RoamingSettings

Комментарии

Минимальный уровень разрешений: ограниченный

Применимый режим Outlook: создание или чтение

Примеры

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

Возвращает объект для проверка состояния каталога меток конфиденциальности в Outlook и получения всех доступных меток конфиденциальности, если каталог включен.

sensitivityLabelsCatalog: Office.SensitivityLabelsCatalog;

Значение свойства

Office.SensitivityLabelsCatalog

Комментарии

[ Набор API: Почтовый ящик 1.13 ]

Минимальный уровень разрешений: чтение и запись элемента

Применимый режим Outlook: Создание

Примеры

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

Указывает, разрешено ли сенсорное взаимодействие между платформой и устройством. Значение true, если надстройка работает на сенсорном устройстве, например на iPad; Значение false в противном случае.

touchEnabled: boolean;

Значение свойства

boolean

Комментарии

Приложения: Excel, PowerPoint, Word

touchEnabled поддерживается только в Office на iPad.

Используйте свойство touchEnabled, чтобы определить, когда надстройка работает на сенсорном устройстве, и при необходимости настроить тип элементов управления, а также размер и интервалы элементов в пользовательском интерфейсе надстройки, чтобы обеспечить взаимодействие с сенсорным вводом.

ui

Предоставляет объекты и методы, которые можно использовать для создания компонентов пользовательского интерфейса, например диалоговых окон, и управления ими.

ui: UI;

Значение свойства

Office.UI

urls

Примечание

Этот API предоставляется в качестве предварительной версии для разработчиков и может быть изменен на основе полученных нами отзывов. Не используйте этот API в рабочей среде.

Возвращает объект для получения URL-адресов среды выполнения надстройки.

urls: Urls;

Значение свойства

Office.Urls

Комментарии

[ Набор API: предварительная версия почтового ящика ]

Минимальный уровень разрешений: ограниченный

Применимый режим Outlook: создание или чтение

Примеры

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