Office.Context interface

  • 参考
包:
office

表示外接程序的运行时环境，并提供对 API 的关键对象的访问。 当前上下文作为 Office 的属性存在。 它使用 Office.context进行访问。

注解

支持详细信息

有关 Office 应用程序和服务器要求的详细信息，请参阅 运行 Office 外接程序的要求。

支持的应用程序（按平台）

Office 网页版 Windows 版 Office Mac 版 Office iPad 版 Office 移动设备上的 Outlook
Excel 支持 支持 支持 支持 不适用
前景 支持 支持 支持 支持 支持
幻灯片 支持 支持 支持 支持 不适用
项目 不支持 支持 支持 不支持 不适用
Word 支持 支持 支持 支持 不适用

属性

auth

向登录用户提供信息和访问权限。
commerceAllowed

如果当前平台允许加载项显示用于销售或升级的 UI，则为 True;否则返回 False。
contentLanguage

获取用户指定的区域设置（语言）以编辑文档或项目。
diagnostics

获取有关运行加载项的环境的信息。
displayLanguage

获取用户为 Office 应用程序的 UI 指定的区域设置 (语言) 。
document

获取表示正与内容或任务窗格外接程序交互的文档的对象。
host

包含运行加载项的 Office 应用程序。
license

获取用户的 Office 安装的许可证信息。
mailbox

提供对 Microsoft Outlook 外接程序对象模型的访问权限。
officeTheme

提供了访问 Office 主题颜色的属性。
partitionKey

获取本地存储的分区键。 加载项应将此分区键用作存储键的一部分，以安全地存储数据。 分区键位于 undefined 没有分区的环境中，例如 Windows 应用程序的浏览器控件。
platform

提供运行加载项的平台。
requirements

提供一种方法，用于确定当前 Office 应用程序和平台支持哪些要求集。
roamingSettings

获取一个对象，它表示保存到用户邮箱的邮件外接程序的自定义设置或状态。

通过 RoamingSettings 对象，可以存储和访问存储在用户邮箱中的邮件加载项的数据，因此当加载项从用于访问该邮箱的任何客户端应用程序运行时，该外接程序可以使用该加载项。
sensitivityLabelsCatalog

获取要检查 Outlook 中敏感度标签目录的状态的 对象，并在启用目录时检索所有可用的敏感度标签。
touchEnabled

指定平台和设备是否允许触摸交互。 如果加载项在触摸设备（如 iPad）上运行，则为 True;否则为 false。
ui

提供可用于创建和操作 UI 组件（如对话框）的对象和方法。
urls

获取用于检索外接程序的运行时 URL 的 对象。

属性详细信息

auth

注意

此 API 以预览状态提供给开发者，可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。

向登录用户提供信息和访问权限。

auth: Auth;

属性值

Office.Auth

commerceAllowed

如果当前平台允许加载项显示用于销售或升级的 UI，则为 True;否则返回 False。

commerceAllowed: boolean;

属性值

boolean

注解

应用程序：Excel、Word

commerceAllowed 仅在 iPad 上的 Office 中受支持。

iOS 应用商店不支持提供其他付款系统的链接的应用程序和外接程序。 但是，在 Windows 桌面或浏览器中的 Office 中运行的 Office 加载项允许此类链接。 如果希望外接程序的 UI 在 iOS 以外的平台上提供指向外部支付系统的链接，可以使用 commerceAllowed 属性来控制显示该链接的日期。

contentLanguage

获取用户指定的区域设置（语言）以编辑文档或项目。

contentLanguage: string;

属性值

string

注解

该值contentLanguage反映 Office 应用程序中使用“文件>选项语言”>指定的“编辑语言”设置。

支持详细信息

有关 Office 应用程序和服务器要求的详细信息，请参阅 运行 Office 外接程序的要求。

支持的应用程序（按平台）

Office 网页版 Windows 版 Office Mac 版 Office iPad 版 Office 移动设备上的 Outlook
Excel 支持 支持 不支持 支持 不适用
前景 支持 支持 支持 支持 支持
幻灯片 支持 支持 不支持 支持 不适用
项目 不支持 支持 不支持 不支持 不适用
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 应用程序的 UI 指定的区域设置 (语言) 。

displayLanguage: string;

属性值

string

注解

返回的值是 RFC 1766 Language 标记格式的字符串，例如 en-US。

该值displayLanguage反映 Office 应用程序中使用“文件选项语言”>>指定的当前“显示语言”设置。

在 Outlook 中使用时，适用的模式为“撰写”或“读取”。

支持详细信息

有关 Office 应用程序和服务器要求的详细信息，请参阅 运行 Office 外接程序的要求。

支持的应用程序（按平台）

Office 网页版 Windows 版 Office Mac 版 Office iPad 版 Office 移动设备上的 Outlook
Excel 支持 支持 支持 支持 不适用
前景 支持 支持 支持 支持 支持
幻灯片 支持 支持 支持 支持 不适用
项目 不支持 支持 支持 不支持 不适用
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

注解

重要说明：

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 set： Mailbox 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

指定平台和设备是否允许触摸交互。 如果加载项在触摸设备（如 iPad）上运行，则为 True;否则为 false。

touchEnabled: boolean;

属性值

boolean

注解

应用程序：Excel、PowerPoint Word

touchEnabled 仅在 iPad 上的 Office 中受支持。

使用 touchEnabled 属性可确定加载项何时在触摸设备上运行，并在必要时调整外接程序 UI 中控件的类型以及元素的大小和间距，以适应触摸交互。

ui

提供可用于创建和操作 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]}`);