通过

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

  • 项目

Office JavaScript API 提供用于管理用户正在撰写的约会位置的属性和方法。 目前，有两个属性提供约会的位置：

  • item.location：用于获取和设置位置的基本 API。
  • item.enhancedLocation：用于获取和设置位置的增强 API，包括指定 位置类型。 如果使用 设置位置item.location，则类型为 LocationType.Custom 。

下表列出了位置 API 以及 (模式，即“撰写”或“读取”) （如果它们可用）。

API 适用的约会模式
item.location 与会者/读取
item.location.getAsync Organizer/Compose
item.location.setAsync Organizer/Compose
item.enhancedLocation.getAsync Organizer/Compose、
与会者/读取
item.enhancedLocation.addAsync Organizer/Compose
item.enhancedLocation.removeAsync Organizer/Compose

若要使用仅可用于撰写加载项的方法，请将外接程序 XML 清单配置为在管理器/撰写模式下激活加载项。 有关更多详细信息，请参阅Create Outlook 加载项撰写窗体。 使用 Microsoft 365 统一清单的加载项不支持激活规则。

使用 enhancedLocation API

可以使用 API enhancedLocation 获取和设置约会的位置。 位置字段支持多个位置，并且对于每个位置，可以设置显示名称、类型和会议室电子邮件地址（如果适用) (）。 有关支持的位置类型，请参阅 LocationType 。

添加位置

以下示例演示如何通过在 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);
        }
    });
}

注意

enhancedLocation.getAsync 方法不会返回添加为约会位置的个人联系人组。

删除位置

以下示例演示如何通过在 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]);
    });
}

使用 location API

可以使用 API location 获取和设置约会的位置。

获取位置

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

若要使用 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 会将指定位置字符串作为纯文本插入，同时覆盖相应项的任何现有位置。

注意

可以通过使用分号作为分隔符 (设置多个位置，例如“会议室 A”会议室 B') 。

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;
}

另请参阅