Office.Context interface

Ссылка

Пакет:: office

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

	Office в Интернете	Office для Windows	Office для Mac	Office для iPad	Outlook на мобильных устройствах
Превосходить	Поддерживается	Поддерживается	Поддерживается	Поддерживается	Неприменимо
Вид	Поддерживается	Поддерживается	Поддерживается	Поддерживается	Поддерживается
PowerPoint	Поддерживается	Поддерживается	Поддерживается	Поддерживается	Неприменимо
Проект	Не поддерживается	Поддерживается	Поддерживается	Не поддерживается	Неприменимо
Word	Поддерживается	Поддерживается	Поддерживается	Поддерживается	Неприменимо

Свойства

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-адресов среды выполнения надстройки.

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

commerceAllowed

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

commerceAllowed: boolean;

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

boolean

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

Примеры

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

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

contentLanguage: string;

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

string

	Office в Интернете	Office для Windows	Office для Mac	Office для iPad	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

	Office в Интернете	Office для Windows	Office для Mac	Office для iPad	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.диагностика, чтобы получить аналогичные сведения.

Примеры

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

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

license: object;

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

object

Примеры

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

mailbox

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

mailbox: Office.Mailbox;

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

Office.Mailbox

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() {
    // 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

Возвращает ключ секции для локального хранилища. Надстройки должны использовать этот ключ секции как часть ключа хранилища для безопасного хранения данных. Ключ секции находится 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.

Примеры

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

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

requirements: RequirementSetSupport;

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

Office.RequirementSetSupport

Примеры

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

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

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

roamingSettings: Office.RoamingSettings;

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

Office.RoamingSettings

Примеры

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

Примеры

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

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

Примеры

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

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

ui: UI;

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

Office.UI

Примеры

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

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

urls: Urls;

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

Office.Urls

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

Примеры

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

Поделиться через

Office.Context interface

Комментарии

Свойства

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

commerceAllowed

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

Комментарии

Примеры

contentLanguage

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

Комментарии

Примеры

diagnostics

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

Комментарии

Примеры

displayLanguage

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

Комментарии

Примеры

document

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

Примеры

host

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

Комментарии

Примеры

license

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

Примеры

mailbox

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

Комментарии

Примеры

officeTheme

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

Примеры

partitionKey

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

Комментарии

Примеры

platform

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

Комментарии

Примеры

requirements

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

Примеры

roamingSettings

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

Комментарии

Примеры

sensitivityLabelsCatalog

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

Комментарии

Примеры

touchEnabled

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

Комментарии

Примеры

ui

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

Примеры

urls

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

Комментарии

Примеры

Дополнительные ресурсы