在 Outlook 中撰写约会时获取或设置位置

了解如何生成可有效管理约会位置的 Outlook 加载项。

为方案选择适当的 API

可以使用两个 API 来管理约会的位置。

• item.enhancedLocation
• item.location

下表比较了两个位置 API，以帮助你选择正确的方法。

试用

请尝试交互式示例，查看位置 API 在作中。 安装 Outlook 加载项Script Lab，然后试用以下示例代码片段。

• 获取位置 (读取) - 实现 location API
• 获取并设置 (约会组织者) 的位置 - 实现 location API
• 管理约会的位置 - 实现 enhancedLocation API

若要了解详细信息，请参阅使用 Script Lab 探索 Office JavaScript API。

按模式提供的 API 可用性

下表列出了位置 API 及其在撰写和读取模式下的可用性。

使用 enhancedLocation API

在支持要求集 1.8 或更高版本的 Outlook 客户端上 enhancedLocation ，使用 API 添加、 获取和 删除 位置。

添加位置

以下示例演示如何通过在 mailbox.item.enhancedLocation 上调用 addAsync 来添加位置。

let item;
const locations = [
    {
        "id": "Contoso",
        "type": Office.MailboxEnums.LocationType.Custom
    }
];

Office.initialize = function () {
    item = Office.context.mailbox.item;
    // Check for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Add to the location of the item being composed.
        item.enhancedLocation.addAsync(locations);
    });
}

获取位置

以下示例演示如何通过在 mailbox.item.enhancedLocation 上调用 getAsync 来获取位置。

let item;

Office.initialize = function () {
    item = Office.context.mailbox.item;
    // Checks for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Get the location of the item being composed.
        item.enhancedLocation.getAsync(callbackFunction);
    });
}

function callbackFunction(asyncResult) {
    asyncResult.value.forEach(function (place) {
        console.log("Display name: " + place.displayName);
        console.log("Type: " + place.locationIdentifier.type);
        if (place.locationIdentifier.type === Office.MailboxEnums.LocationType.Room) {
            console.log("Email address: " + place.emailAddress);
        }
    });
}

删除位置

以下示例演示如何通过在 mailbox.item.enhancedLocation 上调用 removeAsync 来删除位置。

let item;

Office.initialize = function () {
    item = Office.context.mailbox.item;
    // Checks for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Get the location of the item being composed.
        item.enhancedLocation.getAsync(callbackFunction);
    });
}

function callbackFunction(asyncResult) {
    asyncResult.value.forEach(function (currentValue) {
        // Remove each location from the item being composed.
        item.enhancedLocation.removeAsync([currentValue.locationIdentifier]);
    });
}

使用位置 API

在不支持要求集 1.8 或更高版本的 Outlook 客户端上 location ，使用 API 获取 和 设置 位置。 如果不需要高级功能来管理多个位置， location 还可以在最新版本的 Outlook 客户端上使用 API。

获取位置

此部分显示了一个代码示例，用于获取用户正在撰写的约会的位置，并显示该位置。

若要使用 item.location.getAsync，请提供一个回调函数，用于检查异步调用的状态和结果。 可以通过可选参数向回调函数 asyncContext 提供任何必要的参数。 可以使用回调的输出参数 asyncResult 获取状态、结果和任何错误。 如果异步调用成功，可以使用 AsyncResult.value 属性获取作为字符串的位置。

let item;

Office.initialize = function () {
    item = Office.context.mailbox.item;
    // Checks for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Get the location of the item being composed.
        getLocation();
    });
}

// Get the location of the item that the user is composing.
function getLocation() {
    item.location.getAsync(
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed){
                write(asyncResult.error.message);
            }
            else {
                // Successfully got the location, display it.
                write ('The location is: ' + asyncResult.value);
            }
        });
}

// Write to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

设置位置

此部分显示了一个代码示例，用于设置用户正在撰写的约会的位置。

若要使用 item.location.setAsync，请在数据参数中指定一个最多 255 个字符的字符串。 （可选）可以在参数中 asyncContext 为回调函数提供回调函数和任何参数。 应在回调的输出参数中asyncResult检查状态、结果和任何错误消息。 如果异步调用成功，setAsync 会将指定位置字符串作为纯文本插入，同时覆盖相应项的任何现有位置。

let item;

Office.initialize = function () {
    item = Office.context.mailbox.item;
    // Check for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Set the location of the item being composed.
        setLocation();
    });
}

// Set the location of the item that the user is composing.
function setLocation() {
    item.location.setAsync(
        'Conference room A',
        { asyncContext: { var1: 1, var2: 2 } },
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed){
                write(asyncResult.error.message);
            }
            else {
                // Successfully set the location.
                // Do whatever is appropriate for your scenario,
                // using the arguments var1 and var2 as applicable.
            }
        });
}

// Write to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

另请参阅

• 创建第一个 Outlook 加载项
• Office 外接程序中的异步编程
• 获取和设置约会的重复周期