Office.Context interface

Пакет:
office

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

Комментарии

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

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

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

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

Примеры

// Get the Office host, version, and platform in which the add-in is running.
const contextInfo = Office.context.diagnostics;
console.log("Office application: " + contextInfo.host);
console.log("Office version: " + contextInfo.version);
console.log("Platform: " + contextInfo.platform);

Свойства

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

Комментарии

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

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

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

Примеры

// Detect iPad users so your add-in can switch to an iPad-specific experience.
const isTouchEnabled = Office.context.touchEnabled;
const allowCommerce = Office.context.commerceAllowed;

// On iPad, touchEnabled returns true and commerceAllowed returns false.
if (isTouchEnabled && !allowCommerce) {
        enableIPadInterface();
        hideCommerceFeatures();
}

contentLanguage

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

contentLanguage: string;

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

string

Комментарии

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

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

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

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

Office в Интернете Office для Windows Office для Mac Office для iPad Outlook на мобильных устройствах
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 Language, например en-US.

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

При использовании в Outlook применимы режимы Compose или чтения.

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

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

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

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

Примеры

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

Комментарии

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

Применимый режим Outlook: Compose или чтение

Основные свойства:

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

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

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

Дополнительные сведения об Mailbox этом объекте см. в статье API надстроек 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

Комментарии

Важно! В Outlook officeTheme поддерживается начиная с требования к почтовому ящику 1.14. Она не поддерживается в надстройках Outlook, реализующих активацию на основе событий.

Примеры

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

Комментарии

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

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

Применимый режим Outlook: Compose или чтение

Примеры

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

Примеры

// 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 можно определить, выполняется ли надстройка на сенсорном устройстве, и при необходимости настроить типы элементов управления, а также размер и интервал между элементами пользовательского интерфейса надстройки для поддержки взаимодействия с сенсорным экраном.

Примеры

// 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 в Интернете и Windows (новые и классические клиенты)

Набор API: почтовый ящик 1.14

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

Применимый режим Outlook: Compose или чтение

Важно!

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