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

Office.Context interface

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

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

Комментарии

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

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

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

Office в Интернете Office для Windows Office для Mac Office для iPad Outlook на мобильных устройствах
Превосходить Поддерживается Поддерживается Поддерживается Поддерживается Неприменимо
Вид Поддерживается Поддерживается Поддерживается Поддерживается Поддерживается
PowerPoint Поддерживается Поддерживается Поддерживается Поддерживается Неприменимо
Проект Не поддерживается Поддерживается Поддерживается Не поддерживается Неприменимо
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 для управления отображением этой ссылки.

Примеры

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

Комментарии

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

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

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

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

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

Комментарии

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

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

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

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

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

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

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

Комментарии

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

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

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

  • 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

Комментарии

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

Применимый режим 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 ]

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

Применимый режим 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]}`);