Office.MessageCompose interface

获取一个 对象，该对象提供获取或更新密 件抄送 (密件抄 送) 行收件人的方法。

根据客户端/平台 (（即 Windows、Mac 等 ) ），可能会对可以获取或更新的收件人数施加限制。 有关更多详细信息，请参阅 Recipients 对象。

bcc: Recipients;

属性值

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-set-bcc-message-compose.yaml

Office.context.mailbox.item.bcc.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const msgBcc = asyncResult.value;
    console.log("Message being blind-copied to:");
    for (let i = 0; i < msgBcc.length; i++) {
      console.log(msgBcc[i].displayName + " (" + msgBcc[i].emailAddress + ")");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

const email = (document.getElementById("emailBcc") as HTMLInputElement).value;
const emailArray = [email];
Office.context.mailbox.item.bcc.setAsync(emailArray, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Succeeded in setting Bcc field.");
  } else {
    console.error(asyncResult.error);
  }
});

获取一个提供用于处理项目正文的方法的对象。

body: Body;

属性值

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

示例

// This example gets the body of the item as plain text.
Office.context.mailbox.item.body.getAsync(
    "text",
    { asyncContext: "This is passed to the callback" },
    function callback(result) {
        // Do something with the result.
    });

// The following is an example of the result parameter passed to the callback function.
{
    "value": "TEXT of whole body (including threads below)",
    "status": "succeeded",
    "asyncContext": "This is passed to the callback"
}

获取一个 对象，该对象提供用于管理项类别的方法。

categories: Categories;

属性值

注解

[ API set： Mailbox 1.8 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

重要提示：在 Outlook 网页版 和新的 Outlook on Windows 中，不能使用 API 在Compose模式下管理邮件的类别。

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/45-categories/work-with-categories.yaml

Office.context.mailbox.item.categories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const categories = asyncResult.value;
    if (categories && categories.length > 0) {
      console.log("Categories assigned to this item:");
      console.log(JSON.stringify(categories));
    } else {
      console.log("There are no categories assigned to this item.");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

// Note: In order for you to successfully add a category,
// it must be in the mailbox categories master list.

Office.context.mailbox.masterCategories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const masterCategories = asyncResult.value;
    if (masterCategories && masterCategories.length > 0) {
      // Grab the first category from the master list.
      const categoryToAdd = [masterCategories[0].displayName];
      Office.context.mailbox.item.categories.addAsync(categoryToAdd, function(asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
          console.log(`Successfully assigned category '${categoryToAdd}' to item.`);
        } else {
          console.log("categories.addAsync call failed with error: " + asyncResult.error.message);
        }
      });
    } else {
      console.log("There are no categories in the master list on this mailbox. You can add categories using Office.context.mailbox.masterCategories.addAsync.");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

Office.context.mailbox.item.categories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const categories = asyncResult.value;
    if (categories && categories.length > 0) {
      // Grab the first category assigned to this item.
      const categoryToRemove = [categories[0].displayName];
      Office.context.mailbox.item.categories.removeAsync(categoryToRemove, function(asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
          console.log(`Successfully unassigned category '${categoryToRemove}' from this item.`);
        } else {
          console.log("categories.removeAsync call failed with error: " + asyncResult.error.message);
        }
      });
    } else {
      console.log("There are no categories assigned to this item.");
    }
  } else {
    console.error(asyncResult.error);
  }
});

提供对邮件的抄送 (Cc) 收件人的访问权限。 对象的类型和访问级别取决于当前项的模式。

cc 属性返回一个 Recipients 对象，该对象提供用于获取或更新邮件的“抄送”行上收件人的方法。 但是，根据客户端/平台 (（即 Windows、Mac 等 ) ），可能会对可以获取或更新的收件人数施加限制。 有关更多详细信息，请参阅 Recipients 对象。

cc: Recipients;

属性值

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-set-cc-message-compose.yaml

Office.context.mailbox.item.cc.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const msgCc = asyncResult.value;
    console.log("Message being copied to:");
    for (let i = 0; i < msgCc.length; i++) {
      console.log(msgCc[i].displayName + " (" + msgCc[i].emailAddress + ")");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

const email = (document.getElementById("emailCc") as HTMLInputElement).value;
const emailArray = [email];
Office.context.mailbox.item.cc.setAsync(emailArray, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Succeeded in setting Cc field.");
  } else {
    console.error(asyncResult.error);
  }
});

获取包含特定消息的电子邮件会话的标识符。

如果在阅读窗体或撰写窗体的回复中激活邮件应用程序，则此属性可以获得一个整数值。 如果用户随后更改了回复邮件的主题（若发送回复），则该邮件的对话 ID 将改变且之前获取的值将不适用。

对于撰写窗体的新项目，此属性获得一个 null 值。 如果用户设置一个主题并保存该项目，conversationId 属性将返回一个值。

conversationId: string;

属性值

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-conversation-id-message.yaml

console.log(`Conversation ID: ${Office.context.mailbox.item.conversationId}`);

获取邮件发件人的电子邮件地址。

属性 from 返回一个 From 对象，该对象提供从值获取 的方法。

from: From;

属性值

注解

[ API set： Mailbox 1.7 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

重要提示：Android 版和 iOS 版 Outlook 支持此属性。 有关示例方案，请参阅 在 Outlook 移动加载项中实现基于事件的激活。

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-from-message-compose.yaml

Office.context.mailbox.item.from.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const msgFrom = asyncResult.value;
    console.log("Message from: " + msgFrom.displayName + " (" + msgFrom.emailAddress + ")");
  } else {
    console.error(asyncResult.error);
  }
});

获取或设置消息的自定义 Internet 标头。

属性 internetHeaders 返回一个 InternetHeaders 对象，该对象提供管理消息上的 Internet 标头的方法。

若要了解详细信息，请参阅在 Outlook 外接程序中获取和设置邮件的 Internet 标头。

internetHeaders: InternetHeaders;

属性值

注解

[ API set： Mailbox 1.8 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

重要提示：从版本 4.2405.0 开始，Android 版 Outlook 和 iOS 上支持 Internet 标头 API。 若要详细了解移动设备上的 Outlook 支持的功能，请参阅移动设备上的 Outlook 支持的 Outlook JavaScript API。

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/70-mime-headers/manage-custom-internet-headers-message-compose.yaml

Office.context.mailbox.item.internetHeaders.getAsync(
  ["preferred-fruit", "preferred-vegetable", "best-vegetable", "nonexistent-header"],
  function (asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
      console.log("Selected headers: " + JSON.stringify(asyncResult.value));
    } else {
      console.log("Error getting selected headers: " + JSON.stringify(asyncResult.error));
    }
  }
);

获取实例表示的项的类型。

属性 itemType 返回枚举值之 ItemType 一，指示项目对象实例是消息还是约会。

itemType: MailboxEnums.ItemType | string;

属性值

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-item-type.yaml

const itemType = Office.context.mailbox.item.itemType;
switch (itemType) {
    case Office.MailboxEnums.ItemType.Appointment:
        console.log(`Current item is an ${itemType}.`);
        break;
    case Office.MailboxEnums.ItemType.Message:
        console.log(`Current item is a ${itemType}. A message could be an email, meeting request, meeting response, or meeting cancellation.`);
        break;
}

获取项目的通知邮件。

notificationMessages: NotificationMessages;

属性值

注解

[ API 集：邮箱 1.3 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

重要提示：若要了解可实现的不同类型的通知消息，请参阅 为 Outlook 加载项创建通知。

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/35-notifications/add-getall-remove.yaml

// Adds a progress indicator to the mail item.
const id = (document.getElementById("notificationId") as HTMLInputElement).value;
const details =
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.ProgressIndicator,
    message: "Progress indicator with id = " + id
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);

...

// Adds an informational notification to the mail item.
const id = (document.getElementById("notificationId") as HTMLInputElement).value;
const details =
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
    message: "Non-persistent informational notification message with id = " + id,
    icon: "PG.Icon.16",
    persistent: false
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);

...

// Adds a persistent information notification to the mail item.
const id = (document.getElementById("notificationId") as HTMLInputElement).value;
const details =
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
    message: "Persistent informational notification message with id = " + id,
    icon: "PG.Icon.16",
    persistent: true
  };
Office.context.mailbox.item.notificationMessages.addAsync(id, details, handleResult);

...

// Gets all the notification messages and their keys for the current mail item.
Office.context.mailbox.item.notificationMessages.getAllAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log(asyncResult.error.message);
    return;
  }

  console.log(asyncResult.value);
});

...

// Replaces a notification message of a given key with another message.
const id = (document.getElementById("notificationId") as HTMLInputElement).value;
Office.context.mailbox.item.notificationMessages.replaceAsync(
  id,
  {
    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
    message: "Notification message with id = " + id + " has been replaced with an informational message.",
    icon: "icon2",
    persistent: false
  },
  handleResult);

...

// Removes a notification message from the current mail item.
const id = (document.getElementById("notificationId") as HTMLInputElement).value;
Office.context.mailbox.item.notificationMessages.removeAsync(id, handleResult);

获取实例所属的序列的 ID。

在 Outlook 网页版 中，在 Windows (新) 和经典) ，在 Mac 上，seriesId返回此项目所属的父 (系列) 的 Exchange Web Services (EWS) ID。 但是，在 Outlook on Android 和 iOS 中，seriesId 返回父项的 REST ID。

seriesId: string;

属性值

注解

[ API set： Mailbox 1.7 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

重要提示：属性返回的 seriesId 标识符与 Exchange Web Services 项标识符相同。 属性 seriesId 与 Outlook REST API 使用的 Outlook ID 不同。 在使用此值进行 REST API 调用之前，应使用 Office.context.mailbox.convertToRestId进行转换。 有关详细信息，请参阅 使用 Outlook 外接程序中的 Outlook REST API。

对于没有父项（如单个约会、系列项目或会议请求）的项目，属性seriesIdnull返回 ，对于不是会议请求的任何其他项目，则返回 undefined 。

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/50-recurrence/get-series-id.yaml

const seriesId = Office.context.mailbox.item.seriesId;

if (seriesId === undefined) {
  console.log("This is a message that's not a meeting request.");
} else if (seriesId === null) {
  console.log("This is a single appointment, a parent series, or a meeting request for a series or single meeting.");
} else {
  console.log("This is an instance belonging to series with ID " + seriesId);
}

在Compose模式下管理项的 SessionData。

重要提示：每个外接程序的整个 SessionData 对象限制为 50,000 个字符。

sessionData: SessionData;

属性值

注解

[ API set： Mailbox 1.11 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/session-data-apis.yaml

Office.context.mailbox.item.sessionData.getAllAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("The sessionData is " + JSON.stringify(asyncResult.value));
  } else {
    console.log("Failed to get all sessionData. Error: " + JSON.stringify(asyncResult.error));
  }
});

获取或设置显示在项目的主题字段中的说明。

subject 属性获取或设置由电子邮件服务器发送项目时的整个主题。

subject 属性返回一个 Subject 对象，该对象提供用于获取和设置主题的方法。

subject: Subject;

属性值

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-set-subject-compose.yaml

Office.context.mailbox.item.subject.getAsync((result) => {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Action failed with message ${result.error.message}`);
    return;
  }
  console.log(`Subject: ${result.value}`);
});

...

let subject = "Hello World!";
Office.context.mailbox.item.subject.setAsync(subject, (result) => {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Action failed with message ${result.error.message}`);
    return;
  }
  console.log(`Successfully set subject to ${subject}`);
});

提供对邮件的“收件人”行上的收件人的访问权限。 对象的类型和访问级别取决于当前项的模式。

to 属性返回一个 Recipients 对象，该对象提供用于获取或更新邮件的“收件人”行上收件人的方法。 但是，根据客户端/平台 (（即 Windows、Mac 等 ) ），可能会对可以获取或更新的收件人数施加限制。 有关更多详细信息，请参阅 Recipients 对象。

to: Recipients;

属性值

注解

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/30-recipients-and-attendees/get-set-to-message-compose.yaml

Office.context.mailbox.item.to.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const msgTo = asyncResult.value;
    console.log("Message being sent to:");
    for (let i = 0; i < msgTo.length; i++) {
      console.log(msgTo[i].displayName + " (" + msgTo[i].emailAddress + ")");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

const email = (document.getElementById("emailTo") as HTMLInputElement).value;
const emailArray = [email];
Office.context.mailbox.item.to.setAsync(emailArray, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Succeeded in setting To field.");
  } else {
    console.error(asyncResult.error);
  }
});

将文件作为附件添加到邮件或约会。

addFileAttachmentAsync 方法在指定的 URI 上载文件并将其附加到撰写窗体中的项目。

addFileAttachmentAsync(uri: string, attachmentName: string, options: Office.AsyncContextOptions & { isInline: boolean }, callback?: (asyncResult: Office.AsyncResult<string>) => void): void;

参数

返回

注解

[ API 集：邮箱 1.1 for Outlook on Windows (经典) 和 Mac，Mailbox 1.8 for Outlook 网页版 和新的 Outlook on Windows ]

最低权限级别： 读/写项

适用的 Outlook 模式：邮件Compose

重要说明：

• iOS 或 Android 版 Outlook 不支持此方法。 有关 Outlook mobile 中支持的 API 的详细信息，请参阅移动设备上的 Outlook 中支持的 Outlook JavaScript API。

• 如果图像作为内联附件添加，则不支持位图 (BMP) 图像。

• 在最新版本的经典 Outlook on Windows 中，引入了一个 bug，该 bug 错误地将标头追加 Authorization: Bearer 到此作 (是使用此 API 还是 Outlook UI) 。 若要解决此问题，请使用 addFileAttachmentFromBase64 要求集 1.8 中引入的 API。

• 要附加的文件的 URI 必须支持生产中的缓存。 托管映像的服务器不应返回在 Cache-Control HTTP 响应中指定 no-cache、 no-store或类似选项的标头。 但是，当你开发加载项并更改文件时，缓存可能会阻止你看到所做的更改。 建议在开发期间使用 Cache-Control 标头。

• 可以将同一 URI 与 方法一起使用 removeAttachmentAsync ，以删除同一会话中的附件。

错误：

• AttachmentSizeExceeded ：附件大于允许的大小。

• FileTypeNotSupported ：附件具有不允许的扩展名。

• NumberOfAttachmentsExceeded ：邮件或约会的附件过多。

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/40-attachments/attachments-compose.yaml

const attachmentUrl = (document.getElementById("attachmentUrl") as HTMLInputElement).value;
Office.context.mailbox.item.addFileAttachmentAsync(
  attachmentUrl,
  getFileName(attachmentUrl),
  { isInline: false },
  (result) => {
    console.log(result);
  }
);

将文件作为附件添加到邮件或约会。

addFileAttachmentAsync 方法在指定的 URI 上载文件并将其附加到撰写窗体中的项目。

addFileAttachmentAsync(uri: string, attachmentName: string, callback?: (asyncResult: Office.AsyncResult<string>) => void): void;

参数

返回

注解

[ API 集：邮箱 1.1 for Outlook on Windows (经典) 和 Mac，Mailbox 1.8 for Outlook 网页版 和新的 Outlook on Windows ]

最低权限级别： 读/写项

适用的 Outlook 模式：邮件Compose

重要说明：

• iOS 或 Android 版 Outlook 不支持此方法。 有关 Outlook mobile 中支持的 API 的详细信息，请参阅移动设备上的 Outlook 中支持的 Outlook JavaScript API。

• 如果图像作为内联附件添加，则不支持位图 (BMP) 图像。

• 在最新版本的经典 Outlook on Windows 中，引入了一个 bug，该 bug 错误地将标头追加 Authorization: Bearer 到此作 (是使用此 API 还是 Outlook UI) 。 若要解决此问题，请使用 addFileAttachmentFromBase64 要求集 1.8 中引入的 API。

• 要附加的文件的 URI 必须支持生产中的缓存。 托管映像的服务器不应返回在 Cache-Control HTTP 响应中指定 no-cache、 no-store或类似选项的标头。 但是，当你开发加载项并更改文件时，缓存可能会阻止你看到所做的更改。 建议在开发期间使用 Cache-Control 标头。

• 可以将同一 URI 与 方法一起使用 removeAttachmentAsync ，以删除同一会话中的附件。

错误：

• AttachmentSizeExceeded ：附件大于允许的大小。

• FileTypeNotSupported ：附件具有不允许的扩展名。

• NumberOfAttachmentsExceeded ：邮件或约会的附件过多。

将文件作为附件添加到邮件或约会。

方法 addFileAttachmentFromBase64Async 从 Base64 编码上传文件，并将其附加到撰写窗体中的项目。 此方法返回 对象中的 asyncResult.value 附件标识符。

随后可以将该标识符与 removeAttachmentAsync 方法一同使用，以删除同一个会话中的附件。

addFileAttachmentFromBase64Async(base64File: string, attachmentName: string, options: Office.AsyncContextOptions & { isInline: boolean }, callback?: (asyncResult: Office.AsyncResult<string>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.8 ]

最低权限级别： 读/写项

适用的 Outlook 模式：邮件Compose

重要说明：

• Android 版和 iOS 版 Outlook 支持在撰写模式下将内联 Base64 文件添加到邮件。 有关 Outlook mobile 中支持的 API 的详细信息，请参阅移动设备上的 Outlook 中支持的 Outlook JavaScript API。

• 如果使用数据 URL API (例如 readAsDataURL) ，则需要去除数据 URL 前缀，然后将字符串的其余部分发送到此 API。 例如，如果完整字符串由 data:image/svg+xml;base64,<rest of Base64 string>表示，则删除 data:image/svg+xml;base64,。

• 若要将内联 Base64 编码的图像添加到正在撰写的邮件或约会的正文，请使用 正文 API 方法，例如 prependAsync、 setSignatureAsync或 setAsync。 如果使用 Office.context.mailbox.item.body.setAsync 插入图像，请首先调用 Office.context.mailbox.item.body.getAsync 以获取项的当前正文。 否则，图像在插入后不会呈现在正文中。 有关示例，请参阅 Script Lab 中的将内联 Base64 编码的图像添加到邮件或约会正文 (Compose) 示例。

错误：

• AttachmentSizeExceeded ：附件大于允许的大小。

• FileTypeNotSupported ：附件具有不允许的扩展名。

• NumberOfAttachmentsExceeded ：邮件或约会的附件过多。

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/40-attachments/attachments-compose.yaml

const base64String =
  "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAACXBIWXMAAAsSAAALEgHS3X78AAACRUlEQVRYw82XzXHbMBCFP2F8tzsQc8Ixyh0zoiuIXIGdCsxUYKqC0B04FdiuwMoM7mGOOIXqQGoAymXhgSX+itJM9kIRFLAP+3YXD5Pdbscx5oxaAIW8Ztr6l2PWmQwF4IyaieP53qdfAqQ8CwBn1JU4vpWhrbxXQA5MZfynANmcDIAzKgcy4FKGXsVJFf3nLgKyBQptfT4KQMRz2N0fcbxqmRMDWXflx0VPnrdArq0vekQ1Dv0UeHZGNebHhwjU8AzwKM43RyZnbAf58Q6ghudeWd0Aus0+5EcMIIRi3beua0D3Nm39BEAx3i7HTK4DEBJn5YxKOnaRA5+ErpMBWMpzDvx1RuXCcxOISlufAjfC7zgAsqsvUvMAD0ApPaEtGi9AIlUzKgJo60tt/SyKRkzLrAXERluf7W1gOICWaMyB386oooOWsIHvXbSoHuUSFovtHqicUVnH3EJoeT0aQEf5/XBGlc6otIOWBXAtPeZkAIJ9Bt6cUU9tZautX2nrk3MACHYr1ZKProKRtDw4o8pzAPjWo+NtpXTTvoteDDg8noDAcwbcRedAkGdFXyk2GEDcegVAFp2gyVDHjRQ4o6q2smoqtR5Hd+qMqtoALCWUUymr1m43QMZfOaMK4C0SrMsDANJ2E5FNcbdbjHC+ENl+H0myJFbLtaq4Rt8dyPBYRQV1E40nMv9rl7xrOw3DGb+Whcqu3i/OM6CUOWvgRlufNmnLYy4m77uJI7AXtdNcTDrU71LEyv7v01/N/ovL6bmu5/8A1tNWZldH0W4AAAAASUVORK5CYII=";
Office.context.mailbox.item.addFileAttachmentFromBase64Async(
  base64String,
  "logo.png",
  { isInline: false },
  (result) => {
    console.log(result);
  }
);

...

// Set the signature for the current item with inline image.
const modIcon1Base64 = "iVBORw0KGgoAAAANSUhEUgAAABwAAAAcCAYAAAByDd+UAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAA2ZpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMC1jMDYxIDY0LjE0MDk0OSwgMjAxMC8xMi8wNy0xMDo1NzowMSAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wTU09Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9tbS8iIHhtbG5zOnN0UmVmPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvc1R5cGUvUmVzb3VyY2VSZWYjIiB4bWxuczp4bXA9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC8iIHhtcE1NOk9yaWdpbmFsRG9jdW1lbnRJRD0ieG1wLmRpZDpDRDMxMDg1MjBCNDZFMTExODE2MkM1RUI2M0M4MDYxRCIgeG1wTU06RG9jdW1lbnRJRD0ieG1wLmRpZDpFMTUxQjgyRjQ2MEQxMUUxODlFMkQwNTYzQ0YwMTUxMiIgeG1wTU06SW5zdGFuY2VJRD0ieG1wLmlpZDpFMTUxQjgyRTQ2MEQxMUUxODlFMkQwNTYzQ0YwMTUxMiIgeG1wOkNyZWF0b3JUb29sPSJBZG9iZSBQaG90b3Nob3AgQ1M1LjEgV2luZG93cyI+IDx4bXBNTTpEZXJpdmVkRnJvbSBzdFJlZjppbnN0YW5jZUlEPSJ4bXAuaWlkOkQxMzEwODUyMEI0NkUxMTE4MTYyQzVFQjYzQzgwNjFEIiBzdFJlZjpkb2N1bWVudElEPSJ4bXAuZGlkOkNEMzEwODUyMEI0NkUxMTE4MTYyQzVFQjYzQzgwNjFEIi8+IDwvcmRmOkRlc2NyaXB0aW9uPiA8L3JkZjpSREY+IDwveDp4bXBtZXRhPiA8P3hwYWNrZXQgZW5kPSJyIj8+uC/WfAAAAehJREFUeNpilCzfwEAEkAbiECA2A2J1IOaHin8E4ptAfBaIVwLxU0IGMRKw0B6IW4DYhoE4cASIK6E0VsCEQ1wUiNcB8QESLGOAqj0MxBuhZhBloS4QnwHiQAbygR/UDF1CFupCXSjHQDmQg5qli8tCUBBsQUoQ1AD8UDNFsVk4n0o+w+bT+egWglKjNymmeGhLkqLcG2oHAwtUoIuQDj5OVgZPLUmwRe5aEmAxqYqNpFgKssOcCeplM0KqdST5GfpDDRm0JfkYrj3/SE7QguyQY4ImYYLgCtAS10kHGMw6dzNsv/qC7OwCClJXYlR++v6b4er3j5QmIFcmaNlIL6AOslCIjhYKMTHQGTBBqxh6gXcgC6/R0cKbIAv30dHCfaAKGJTxHxJSqS3Fz9DkowNmywpyMcgA8fF7b8D8VWcfM6w8+4gYC+VB+RCk8hSh0gaUD4/dewvlvUWRe/z+GzGWgex4BGtiOAHxXhoHpzMoSGHZAhSPW2lo2VZYWkHOh4nEtLrIAE+hZmNUwK+B2BOIv1PRsu9QM1/jatNcBtVZ0IREKXgENesyoVYbzNIdFFi2A5tl+NqlL6BB4QBNzsSCU1A9nlAzMAALAQMOQl0qB23qWwKxIlIrDBQ394H4OBCvISYqAAIMACVibHDqsO7zAAAAAElFTkSuQmCC";
Office.context.mailbox.item.addFileAttachmentFromBase64Async(
  modIcon1Base64,
  "myImage.png",
  { isInline: true },
  function(result) {
    if (result.status == Office.AsyncResultStatus.Succeeded) {
      const signature = (document.getElementById("signature") as HTMLInputElement).value + "<img src='cid:myImage.png'>";
      console.log(`Setting signature to "${signature}".`);
      Office.context.mailbox.item.body.setSignatureAsync(
        signature,
        { coercionType: "html" },
        function(asyncResult) {
          console.log(`setSignatureAsync: ${asyncResult.status}`);
        }
      );
    } else {
      console.error(`addFileAttachmentFromBase64Async: ${result.error}`);
    }
  }
);

将文件作为附件添加到邮件或约会。

方法 addFileAttachmentFromBase64Async 从 Base64 编码上传文件，并将其附加到撰写窗体中的项目。 此方法返回 对象中的 asyncResult.value 附件标识符。

随后可以将该标识符与 removeAttachmentAsync 方法一同使用，以删除同一个会话中的附件。

addFileAttachmentFromBase64Async(base64File: string, attachmentName: string, callback?: (asyncResult: Office.AsyncResult<string>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.8 ]

最低权限级别： 读/写项

适用的 Outlook 模式：邮件Compose

重要说明：

• Android 版和 iOS 版 Outlook 支持在撰写模式下将内联 Base64 文件添加到邮件。 有关 Outlook mobile 中支持的 API 的详细信息，请参阅移动设备上的 Outlook 中支持的 Outlook JavaScript API。

• 如果使用数据 URL API (例如 readAsDataURL) ，则需要去除数据 URL 前缀，然后将字符串的其余部分发送到此 API。 例如，如果完整字符串由 data:image/svg+xml;base64,<rest of Base64 string>表示，则删除 data:image/svg+xml;base64,。

• 若要将内联 Base64 编码的图像添加到正在撰写的邮件或约会的正文，请使用 正文 API 方法，例如 prependAsync、 setSignatureAsync或 setAsync。 如果使用 Office.context.mailbox.item.body.setAsync 插入图像，请首先调用 Office.context.mailbox.item.body.getAsync 以获取项的当前正文。 否则，图像在插入后不会呈现在正文中。 有关示例，请参阅 Script Lab 中的将内联 Base64 编码的图像添加到邮件或约会正文 (Compose) 示例。

错误：

• AttachmentSizeExceeded ：附件大于允许的大小。

• FileTypeNotSupported ：附件具有不允许的扩展名。

• NumberOfAttachmentsExceeded ：邮件或约会的附件过多。

添加支持事件的事件处理程序。 注意：事件仅适用于任务窗格实现。

有关支持的事件，请参阅 Item 对象模型 事件部分。

addHandlerAsync(eventType: Office.EventType | string, handler: any, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.7 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

示例

function myHandlerFunction(eventarg) {
    if (eventarg.attachmentStatus === Office.MailboxEnums.AttachmentStatus.Added) {
        const attachment = eventarg.attachmentDetails;
        console.log("Event Fired and Attachment Added!");
        getAttachmentContentAsync(attachment.id, options, callback);
    }
}

Office.context.mailbox.item.addHandlerAsync(Office.EventType.AttachmentsChanged, myHandlerFunction, myCallback);

添加支持事件的事件处理程序。 注意：事件仅适用于任务窗格实现。

有关支持的事件，请参阅 Item 对象模型 事件部分。

addHandlerAsync(eventType: Office.EventType | string, handler: any, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.7 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

将 Exchange 项目（如邮件）作为附件添加到邮件或约会。

addItemAttachmentAsync 方法将包含指定 Exchange 标识符的项目附加到撰写窗体中的项目。 如果指定回调函数，则会使用一个参数调用 方法， asyncResult该参数包含附件标识符或指示附加项时发生的任何错误的代码。 如果需要，可以使用 options 参数将状态信息传递给回调函数。

随后可以将该标识符与 removeAttachmentAsync 方法一同使用，以删除同一个会话中的附件。

如果你的 Office 加载项在 Outlook 网页版 或新的 Outlook on Windows 中运行，则 addItemAttachmentAsync 该方法可以将项目附加到您正在编辑的项目以外的项目。 但是，这不受支持，不建议这样做。

addItemAttachmentAsync(itemId: any, attachmentName: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<string>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读/写项

适用的 Outlook 模式：邮件Compose

错误：

• NumberOfAttachmentsExceeded ：邮件或约会的附件过多。

示例

// The following example adds an existing Outlook item as an attachment
// with the name "My Attachment".
function addAttachment() {
    // EWS ID of item to attach (shortened for readability).
    const itemId = "AAMkADI1...AAA=";

    // The values in asyncContext can be accessed in the callback.
    const options = { asyncContext: { var1: 1, var2: 2 } };

    Office.context.mailbox.item.addItemAttachmentAsync(itemId, "My Attachment", options, (result) => {
        if (result.status === Office.AsyncResultStatus.Failed) {
            console.error("Failed to add attachment: " + result.error.message);
            return;
        }

        console.log("Attachment added successfully.");
        console.log("var1: " + result.asyncContext.var1);
        console.log("var2: " + result.asyncContext.var2);
    });
}

将 Exchange 项目（如邮件）作为附件添加到邮件或约会。

addItemAttachmentAsync 方法将包含指定 Exchange 标识符的项目附加到撰写窗体中的项目。 如果指定回调函数，则会使用一个参数调用 方法， asyncResult该参数包含附件标识符或指示附加项时发生的任何错误的代码。 如果需要，可以使用 options 参数将状态信息传递给回调函数。

随后可以将该标识符与 removeAttachmentAsync 方法一同使用，以删除同一个会话中的附件。

如果你的 Office 加载项在 Outlook 网页版 或新的 Outlook on Windows 中运行，则 addItemAttachmentAsync 该方法可以将项目附加到您正在编辑的项目以外的项目。 但是，这不受支持，不建议这样做。

addItemAttachmentAsync(itemId: any, attachmentName: string, callback?: (asyncResult: Office.AsyncResult<string>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读/写项

适用的 Outlook 模式：邮件Compose

错误：

• NumberOfAttachmentsExceeded ：邮件或约会的附件过多。

关闭当前正在撰写的项目。

close 方法的行为取决于要撰写的项目的当前状态。 如果项有未保存的更改，客户端会提示用户保存、放弃或关闭作。

在 Outlook on Windows (经典) 和 Mac 中， close 该方法对阅读窗格中的回复没有任何影响。

close(): void;

返回

注解

[ API 集：邮箱 1.3 ]

最低权限级别： 受限

适用的 Outlook 模式：邮件Compose

重要提示：在 Outlook 网页版 和新的 Outlook on Windows 中，如果项目是约会，并且以前使用 saveAsync保存过，则即使自上次保存项目以来未发生任何更改，也会提示用户保存、放弃或取消。

提示：close如果希望外接程序：

• 自动放弃正在撰写的消息，而不会提示用户使用保存对话框。

• 确定用户何时取消正在撰写的邮件上的保存项目对话框。

• 关闭阅读窗格或现有草稿中的回复。

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/25-item-save-and-close/close.yaml

Office.context.mailbox.item.close();

禁用 Outlook 客户端签名。

此方法的行为取决于加载项运行的客户端。

• 在 Outlook 网页版 和新的 Outlook on Windows 中，将禁用新邮件、答复和转发的签名选项。 方法也会禁用所选的签名。

• 在 Outlook on Windows (经典) 和 Mac 中，发送帐户的 “新建邮件 ”和 “答复/转发 ”部分下的签名设置为 (无) 。

• 在 Android 版和 iOS 版 Outlook 中，将清除移动设备上保存的签名。

disableClientSignatureAsync(options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.10 ]

最低权限级别： 读/写项

适用的 Outlook 模式：邮件Compose

重要提示：从版本 4.2352.0 开始，Android 版 Outlook 和 iOS 上的邮件Compose支持此方法。 有关 Outlook mobile 中支持的 API 的详细信息，请参阅移动设备上的 Outlook 中支持的 Outlook JavaScript API。

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/work-with-client-signatures.yaml

// Disable the client signature.
Office.context.mailbox.item.disableClientSignatureAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("disableClientSignatureAsync succeeded");
  } else {
    console.error(asyncResult.error);
  }
});

禁用 Outlook 客户端签名。

此方法的行为取决于加载项运行的客户端。

• 在 Outlook 网页版 和新的 Outlook on Windows 中，将禁用新邮件、答复和转发的签名选项。 方法也会禁用所选的签名。

• 在 Outlook on Windows (经典) 和 Mac 中，发送帐户的 “新建邮件 ”和 “答复/转发 ”部分下的签名设置为 (无) 。

• 在 Android 版和 iOS 版 Outlook 中，将清除移动设备上保存的签名。

disableClientSignatureAsync(callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.10 ]

最低权限级别： 读/写项

适用的 Outlook 模式：邮件Compose

重要提示：从版本 4.2352.0 开始，Android 版 Outlook 和 iOS 上的邮件Compose支持此方法。 有关 Outlook mobile 中支持的 API 的详细信息，请参阅移动设备上的 Outlook 中支持的 Outlook JavaScript API。

从邮件或约会中获取附件，并将其作为 AttachmentContent 对象返回。

getAttachmentContentAsync(attachmentId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<AttachmentContent>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.8 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

重要说明：

• 方法 getAttachmentContentAsync 从项中获取具有指定标识符的附件。 最佳做法是，应从通话中获取附件的标识符，然后在同一 getAttachmentsAsync 会话中使用该标识符检索附件。

• 在Outlook 网页版和新的 Outlook on Windows 中，getAttachmentContentAsync不支持使用“上传和共享”选项添加的附件。

• 在 Outlook 网页版、移动设备和新的 Outlook on Windows 中，附件标识符仅在同一会话中有效。 当用户关闭应用时，会话结束，或者如果用户开始撰写内联窗体，然后弹出窗体以在单独的窗口中继续。

错误：

• AttachmentTypeNotSupported ：不支持附件类型。 不支持的类型包括 RTF 格式的嵌入图像，或者电子邮件或日历项目以外的项目附件类型 (，例如联系人或任务项) 。

• InvalidAttachmentId ：附件标识符不存在。

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/40-attachments/get-attachment-content.yaml

// Gets the attachments of the current message or appointment in compose mode. The getAttachmentsAsync call can only be used in compose mode.
Office.context.mailbox.item.getAttachmentsAsync((result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.log(result.error.message);
    return;
  }

  if (result.value.length <= 0) {
    console.log("Mail item has no attachments.");
    return;
  }

  for (let i = 0; i < result.value.length; i++) {
    // Log the attachment type and its contents to the console.
    Office.context.mailbox.item.getAttachmentContentAsync(result.value[i].id, handleAttachmentsCallback);
  }
});

从邮件或约会中获取附件，并将其作为 AttachmentContent 对象返回。

getAttachmentContentAsync(attachmentId: string, callback?: (asyncResult: Office.AsyncResult<AttachmentContent>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.8 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

重要说明：

• 方法 getAttachmentContentAsync 从项中获取具有指定标识符的附件。 最佳做法是，应从通话中获取附件的标识符，然后在同一 getAttachmentsAsync 会话中使用该标识符检索附件。

• 在Outlook 网页版和新的 Outlook on Windows 中，getAttachmentContentAsync不支持使用“上传和共享”选项添加的附件。

• 在 Outlook 网页版、移动设备和新的 Outlook on Windows 中，附件标识符仅在同一会话中有效。 当用户关闭应用时，会话结束，或者如果用户开始撰写内联窗体，然后弹出窗体以在单独的窗口中继续。

错误：

• AttachmentTypeNotSupported ：不支持附件类型。 不支持的类型包括 RTF 格式的嵌入图像，或者电子邮件或日历项目以外的项目附件类型 (，例如联系人或任务项) 。

• InvalidAttachmentId ：附件标识符不存在。

获取项的附件作为数组。

getAttachmentsAsync(options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<AttachmentDetailsCompose[]>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.8 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

重要提示：在Outlook 网页版和新的 Outlook on Windows 中，用户可以选择“上传和共享”选项，将附件上传到 OneDrive，并在邮件项中包含指向文件的链接。 但是，由于仅包含链接， getAttachmentsAsync 因此不会返回此附件。

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/40-attachments/attachments-compose.yaml

Office.context.mailbox.item.getAttachmentsAsync((result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error(result.error.message);
    return;
  }

  if (result.value.length > 0) {
    for (let i = 0; i < result.value.length; i++) {
      const attachment = result.value[i];
      let attachmentType;
      switch (attachment.attachmentType) {
        case Office.MailboxEnums.AttachmentType.Cloud:
          attachmentType = "Attachment is stored in a cloud location";
          break;
        case Office.MailboxEnums.AttachmentType.File:
          attachmentType = "Attachment is a file";
          break;
        case Office.MailboxEnums.AttachmentType.Item:
          attachmentType = "Attachment is an Exchange item";
          break;
      }
      console.log(
        "ID: " +
          attachment.id +
          "\n" +
          "Type: " +
          attachmentType +
          "\n" +
          "Name: " +
          attachment.name +
          "\n" +
          "Size: " +
          attachment.size +
          "\n" +
          "isInline: " +
          attachment.isInline
      );
    }
  } else {
    console.log("No attachments on this message.");
  }
});

获取项的附件作为数组。

getAttachmentsAsync(callback?: (asyncResult: Office.AsyncResult<AttachmentDetailsCompose[]>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.8 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

重要提示：在Outlook 网页版和新的 Outlook on Windows 中，用户可以选择“上传和共享”选项，将附件上传到 OneDrive，并在邮件项中包含指向文件的链接。 但是，由于仅包含链接， getAttachmentsAsync 因此不会返回此附件。

指定邮件撰写的类型及其强制类型。 邮件可以是新邮件，也可以是答复或转发。 强制类型可以是 HTML 或纯文本。

getComposeTypeAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<any>) => void): void;

参数

返回

具有 ComposeType 消息项的 和 CoercionType 枚举值的对象。

注解

[ API set： Mailbox 1.10 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

重要提示：从版本 4.2352.0 开始，Android 版 Outlook 和 iOS 支持此方法。 有关 Outlook mobile 中支持的 API 的详细信息，请参阅移动设备上的 Outlook 中支持的 Outlook JavaScript API。

指定邮件撰写的类型及其强制类型。 邮件可以是新邮件，也可以是答复或转发。 强制类型可以是 HTML 或纯文本。

getComposeTypeAsync(callback: (asyncResult: Office.AsyncResult<any>) => void): void;

参数

返回

具有 ComposeType 消息项的 和 CoercionType 枚举值的对象。

注解

[ API set： Mailbox 1.10 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

重要提示：从版本 4.2352.0 开始，Android 版 Outlook 和 iOS 支持此方法。 有关 Outlook mobile 中支持的 API 的详细信息，请参阅移动设备上的 Outlook 中支持的 Outlook JavaScript API。

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/work-with-client-signatures.yaml

// Get the compose type of the current message.
Office.context.mailbox.item.getComposeTypeAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log(
      "getComposeTypeAsync succeeded with composeType: " +
        asyncResult.value.composeType +
        " and coercionType: " +
        asyncResult.value.coercionType
    );
  } else {
    console.error(asyncResult.error);
  }
});

获取当 加载项被可作消息激活时传递的初始化数据。

getInitializationContextAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<string>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.8 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

示例

// Get the initialization context (if present).
Office.context.mailbox.item.getInitializationContextAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
        if (asyncResult.value.length > 0) {
            // The value is a string, parse to an object.
            const context = JSON.parse(asyncResult.value);
            // Do something with context.
        } else {
            // Empty context, treat as no context.
        }
    } else {
        // Handle the error.
    }
});

获取当 加载项被可作消息激活时传递的初始化数据。

getInitializationContextAsync(callback: (asyncResult: Office.AsyncResult<string>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.8 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

异步获取已保存 项的 Exchange Web Services (EWS) 项标识符 。

调用时，此方法通过回调函数返回项 ID。

getItemIdAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<string>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.8 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

重要说明：

• 返回的项目 ID 与 Outlook 条目 ID 或 Outlook REST API 使用的 ID 不同。 在使用此值进行 REST API 调用之前，应使用 Office.context.mailbox.convertToRestId进行转换。

• 例如，如果你的外接程序调用 getItemIdAsync (获取用于 EWS 或 REST API) 的项目 ID，请注意，当 Outlook 处于缓存模式时，可能需要一段时间才能将项目同步到服务器。 在项目同步之前，无法识别项目 ID，并且使用它将返回错误。

错误：

• ItemNotSaved ：在保存项目之前，无法检索 ID。

异步获取已保存 项的 Exchange Web Services (EWS) 项标识符 。

调用时，此方法通过回调函数返回项 ID。

getItemIdAsync(callback: (asyncResult: Office.AsyncResult<string>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.8 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

重要说明：

• 返回的项目 ID 与 Outlook 条目 ID 或 Outlook REST API 使用的 ID 不同。 在使用此值进行 REST API 调用之前，应使用 Office.context.mailbox.convertToRestId进行转换。

• 例如，如果你的外接程序调用 getItemIdAsync (获取用于 EWS 或 REST API) 的项目 ID，请注意，当 Outlook 处于缓存模式时，可能需要一段时间才能将项目同步到服务器。 在项目同步之前，无法识别项目 ID，并且使用它将返回错误。

错误：

• ItemNotSaved ：在保存项目之前，无法检索 ID。

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/item-id-compose.yaml

Office.context.mailbox.item.getItemIdAsync((result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.error(`getItemIdAsync failed with message: ${result.error.message}`);
        return;
    }

    console.log(result.value);
});

以异步方式返回邮件的主题或正文中选定的数据。

如果没有选择，但光标位于正文或主题中，该方法将返回所选数据的空字符串。 如果选定的是字段，而不是正文或主题，则此方法返回 InvalidSelection 错误。

若要从回调函数访问所选数据，请调用 asyncResult.value.data。 若要访问所选内容来自的源属性，请调用 asyncResult.value.sourceProperty，它将为 body 或 subject。

getSelectedDataAsync(coercionType: Office.CoercionType | string, options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<any>) => void): void;

参数

返回

所选数据作为字符串，格式由 coercionType确定。

注解

[ API set： Mailbox 1.2 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

示例

// Get selected data.
Office.context.mailbox.item.getSelectedDataAsync(Office.CoercionType.Text, { option1: "option1"}, getCallback);

function getCallback(asyncResult) {
    const text = asyncResult.value.data;
    const prop = asyncResult.value.sourceProperty;

    console.log(`Selected text in ${prop}: ${text}`);
}

以异步方式返回邮件的主题或正文中选定的数据。

如果没有选择，但光标位于正文或主题中，该方法将返回所选数据的空字符串。 如果选定的是字段，而不是正文或主题，则此方法返回 InvalidSelection 错误。

若要从回调函数访问所选数据，请调用 asyncResult.value.data。 若要访问所选内容来自的源属性，请调用 asyncResult.value.sourceProperty，它将为 body 或 subject。

getSelectedDataAsync(coercionType: Office.CoercionType | string, callback: (asyncResult: Office.AsyncResult<any>) => void): void;

参数

返回

所选数据作为字符串，格式由 coercionType确定。

注解

[ API set： Mailbox 1.2 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/20-item-body/get-selected-data.yaml

Office.context.mailbox.item.getSelectedDataAsync(Office.CoercionType.Text, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const text = asyncResult.value.data;
    const prop = asyncResult.value.sourceProperty;
    console.log("Selected text in " + prop + ": " + text);
  } else {
    console.error(asyncResult.error);
  }
});

获取共享文件夹或共享邮箱中约会或邮件的属性。

有关使用此 API 的详细信息，请参阅 在 Outlook 外接程序中启用共享文件夹和共享邮箱方案。

getSharedPropertiesAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<SharedProperties>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.8 for shared folder support， Mailbox 1.13 for shared mailbox support ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

注意：iOS 版或 Android 版 Outlook 不支持此方法。

重要提示：在消息Compose模式下，Outlook 网页版或 Windows (新) 和经典) 不支持此 API，除非满足以下条件。

a. 委托访问权限/共享文件夹

1. 邮箱所有者启动邮件。 这可以是新邮件、答复或转发。

2. 他们保存邮件，然后将其从自己的 Drafts 文件夹移动到与委托共享的文件夹。

3. 委托从共享文件夹中打开草稿，然后继续撰写。

b. 在与用户的主邮箱相同的面板中打开的共享邮箱 (Web、经典 Windows) 或尚未提升为完整帐户的共享邮箱 (新的 Windows)

1. 共享邮箱用户启动邮件。 这可以是新邮件、答复或转发。

2. 他们保存邮件，然后将其从自己的 Drafts 文件夹移动到共享邮箱中的文件夹。

3. 另一个共享邮箱用户打开共享邮箱中的草稿，然后继续撰写。

满足这些条件后，该消息将在共享上下文中可用，支持这些共享方案的加载项可以获取项目的共享属性。 邮件发送后，通常位于发件人个人邮箱的 “已发送邮件” 文件夹中。

方法 getSharedPropertiesAsync 在以下平台上受支持，无需附加条件。

• 使用“打开另一个邮箱”选项在单独的选项卡或窗口中打开共享邮箱时，Outlook 网页版。

• 将共享邮箱提升为完整帐户时，新的 Windows 版 Outlook。

获取共享文件夹或共享邮箱中约会或邮件的属性。

有关使用此 API 的详细信息，请参阅 在 Outlook 外接程序中启用共享文件夹和共享邮箱方案。

getSharedPropertiesAsync(callback: (asyncResult: Office.AsyncResult<SharedProperties>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.8 for shared folder support， Mailbox 1.13 for shared mailbox support ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

注意：iOS 版或 Android 版 Outlook 不支持此方法。

重要提示：在消息Compose模式下，Outlook 网页版或 Windows (新) 和经典) 不支持此 API，除非满足以下条件。

a. 委托访问权限/共享文件夹

1. 邮箱所有者启动邮件。 这可以是新邮件、答复或转发。

2. 他们保存邮件，然后将其从自己的 Drafts 文件夹移动到与委托共享的文件夹。

3. 委托从共享文件夹中打开草稿，然后继续撰写。

b. 在与用户的主邮箱相同的面板中打开的共享邮箱 (Web、经典 Windows) 或尚未提升为完整帐户的共享邮箱 (新的 Windows)

1. 共享邮箱用户启动邮件。 这可以是新邮件、答复或转发。

2. 他们保存邮件，然后将其从自己的 Drafts 文件夹移动到共享邮箱中的文件夹。

3. 另一个共享邮箱用户打开共享邮箱中的草稿，然后继续撰写。

满足这些条件后，该消息将在共享上下文中可用，支持这些共享方案的加载项可以获取项目的共享属性。 邮件发送后，通常位于发件人个人邮箱的 “已发送邮件” 文件夹中。

方法 getSharedPropertiesAsync 在以下平台上受支持，无需附加条件。

• 使用“打开另一个邮箱”选项在单独的选项卡或窗口中打开共享邮箱时，Outlook 网页版。

• 将共享邮箱提升为完整帐户时，新的 Windows 版 Outlook。

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/65-delegates-and-shared-folders/get-shared-properties.yaml

Office.context.mailbox.item.getSharedPropertiesAsync((result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error("The current folder or mailbox isn't shared.");
    return;
  }
  const sharedProperties = result.value;
  console.log(`Owner: ${sharedProperties.owner}`);
  console.log(`Permissions: ${sharedProperties.delegatePermissions}`);
  console.log(`Target mailbox: ${sharedProperties.targetMailbox}`);
});

获取是否启用了客户端签名。

在 Outlook on Windows (经典) 和 Mac 中，如果新邮件、答复或转发的默认签名设置为发送 Outlook 帐户的模板，则 API 调用将返回 true 。 在 Outlook 网页版 和新的 Windows 版 Outlook 中，如果为撰写类型 newMail、 或 forward启用了签名，reply则 API 调用将返回 。true 如果在 Windows 上的 Outlook (经典) 或 Mac 中将设置设置为“ (无) ”，或者在 Outlook 网页版 或新的 Windows 版 Outlook 中禁用这些设置，则 API 调用将返回 false。

isClientSignatureEnabledAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<boolean>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.10 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/work-with-client-signatures.yaml

// Check if the client signature is currently enabled.
Office.context.mailbox.item.isClientSignatureEnabledAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("isClientSignatureEnabledAsync succeeded with result: " + asyncResult.value);
  } else {
    console.error(asyncResult.error);
  }
});

获取是否启用了客户端签名。

在 Outlook on Windows (经典) 和 Mac 中，如果新邮件、答复或转发的默认签名设置为发送 Outlook 帐户的模板，则 API 调用将返回 true 。 在 Outlook 网页版 和新的 Windows 版 Outlook 中，如果为撰写类型 newMail、 或 forward启用了签名，reply则 API 调用将返回 。true 如果在 Windows 上的 Outlook (经典) 或 Mac 中将设置设置为“ (无) ”，或者在 Outlook 网页版 或新的 Windows 版 Outlook 中禁用这些设置，则 API 调用将返回 false。

isClientSignatureEnabledAsync(callback: (asyncResult: Office.AsyncResult<boolean>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.10 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

异步加载所选项目上此外接程序的自定义属性。

自定义属性以键值对的形式存储在每个应用、每个项目的基础上。 此方法在回调中返回 CustomProperties 对象，该对象提供访问特定于当前项和当前加载项的自定义属性的方法。 自定义属性不会对项进行加密，因此不应将其用作安全存储。

自定义属性作为 asyncResult.value 属性中的 CustomProperties 对象提供。 此对象可用于从邮件项获取、设置、保存和删除自定义属性。

loadCustomPropertiesAsync(callback: (asyncResult: Office.AsyncResult<CustomProperties>) => void, userContext?: any): void;

参数

返回

注解

[ API set： Mailbox 1.1 ]

若要了解有关自定义属性的详细信息，请参阅 获取和设置 Outlook 外接程序的外接程序元数据。

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

Office.context.mailbox.item.loadCustomPropertiesAsync((result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error(`loadCustomPropertiesAsync failed with message ${result.error.message}`);
    return;
  }

  customProps = result.value;
  console.log("Loaded the CustomProperties object.");
});

将附件从邮件或约会中删除。

removeAttachmentAsync 方法删除项目中带指定标识符的附件。 最佳做法是，仅当同一个邮件应用程序在同一会话中添加了一个附件时，你才应使用该附件标识符来删除该附件。 在 Outlook 网页版、移动设备和新的 Outlook on Windows 中，附件标识符仅在同一会话中有效。 当用户关闭应用时，会话结束，或者如果用户开始撰写内联窗体，然后弹出窗体以在单独的窗口中继续。

removeAttachmentAsync(attachmentId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读/写项

适用的 Outlook 模式：邮件Compose

重要说明*：该方法 removeAttachmentAsync 不会从邮件项中删除内联附件。 若要删除内联附件，请先获取项目的正文，然后从其内容中删除附件的任何引用。 使用 Office.Body API 获取和设置项的正文。

错误：

• InvalidAttachmentId ：附件标识符不存在。

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/40-attachments/attachments-compose.yaml

Office.context.mailbox.item.removeAttachmentAsync(
  (document.getElementById("attachmentId") as HTMLInputElement).value,
  (result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
      console.error(result.error.message);
      return;
    }

    console.log(`Attachment removed successfully.`);
  }
);

将附件从邮件或约会中删除。

removeAttachmentAsync 方法删除项目中带指定标识符的附件。 最佳做法是，仅当同一个邮件应用程序在同一会话中添加了一个附件时，你才应使用该附件标识符来删除该附件。 在 Outlook 网页版、移动设备和新的 Outlook on Windows 中，附件标识符仅在同一会话中有效。 当用户关闭应用时，会话结束，或者如果用户开始撰写内联窗体，然后弹出窗体以在单独的窗口中继续。

removeAttachmentAsync(attachmentId: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读/写项

适用的 Outlook 模式：邮件Compose

重要说明*：该方法 removeAttachmentAsync 不会从邮件项中删除内联附件。 若要删除内联附件，请先获取项目的正文，然后从其内容中删除附件的任何引用。 使用 Office.Body API 获取和设置项的正文。

错误：

• InvalidAttachmentId ：附件标识符不存在。

删除受支持事件类型的事件处理程序。 注意：事件仅适用于任务窗格实现。

有关支持的事件，请参阅 Item 对象模型 事件部分。

removeHandlerAsync(eventType: Office.EventType | string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.7 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

删除受支持事件类型的事件处理程序。 注意：事件仅适用于任务窗格实现。

有关支持的事件，请参阅 Item 对象模型 事件部分。

removeHandlerAsync(eventType: Office.EventType | string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.7 ]

最低权限级别： 读取项

适用的 Outlook 模式：邮件Compose

示例

Office.context.mailbox.item.removeHandlerAsync(Office.EventType.ItemChanged, (asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.error("Failed to remove event handler: " + asyncResult.error.message);
        return;
    }

    console.log("Event handler removed successfully.");
});

异步将当前消息保存为草稿。

saveAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<string>) => void): void;

参数

返回

注解

[ API 集：邮箱 1.3 ]

最低权限级别： 读/写项

适用的 Outlook 模式：邮件Compose

重要说明：

• 在 Outlook 网页版、新的 Outlook on Windows 或处于联机模式的经典 Outlook on Windows (非缓存模式) 中，项目将保存到服务器。 在 Outlook 缓存模式下，该项目被保存到本地缓存中。

• 使用 HTML 格式的内容时，请务必注意 Outlook 客户端可能会修改内容。 这意味着对 、 Body.setAsync甚至 saveAsync 等Body.getAsync方法的后续调用可能不会产生相同的内容。

• 返回的标识符与 Exchange Web Services (EWS) 项标识符相同。 返回的项目 ID 与 Outlook 条目 ID 或 Outlook REST API 使用的 ID 不同。 在使用此值进行 REST API 调用之前，应使用 Office.context.mailbox.convertToRestId进行转换。

• 如果外接程序调用 saveAsync 以获取用于 EWS 或 REST API 的项目 ID，请注意，当 Outlook 处于缓存模式时，可能需要一段时间才能将项目实际同步到服务器。 在项目同步之前，使用项 ID 将返回错误。

• 在 Outlook 网页版 和新 Outlook on Windows 中，将草稿保存到的邮箱帐户在从共享邮箱帐户发送的邮件上调用 时saveAsync会有所不同。 如果发件人从其个人邮箱创建新邮件并在“ 发件人 ”字段中选择共享邮箱帐户， saveAsync 请将草稿保存到用户个人邮箱的 “草稿 ”文件夹中。 如果发件人在单独的浏览器选项卡中打开共享邮箱帐户， (通过 “打开另一个邮箱 ”选项（例如，) 并在那里创建新邮件）， saveAsync 则会将草稿保存到共享邮箱的 “草稿 ”文件夹中。

错误：

• InvalidAttachmentId ：附件标识符不存在。

异步将当前消息保存为草稿。

saveAsync(callback: (asyncResult: Office.AsyncResult<string>) => void): void;

参数

返回

注解

[ API 集：邮箱 1.3 ]

最低权限级别： 读/写项

适用的 Outlook 模式：邮件Compose

重要说明：

• 在 Outlook 网页版、新的 Outlook on Windows 或处于联机模式的经典 Outlook on Windows (非缓存模式) 中，项目将保存到服务器。 在 Outlook 缓存模式下，该项目被保存到本地缓存中。

• 使用 HTML 格式的内容时，请务必注意 Outlook 客户端可能会修改内容。 这意味着对 、 Body.setAsync甚至 saveAsync 等Body.getAsync方法的后续调用可能不会产生相同的内容。

• 返回的标识符与 Exchange Web Services (EWS) 项标识符相同。 返回的项目 ID 与 Outlook 条目 ID 或 Outlook REST API 使用的 ID 不同。 在使用此值进行 REST API 调用之前，应使用 Office.context.mailbox.convertToRestId进行转换。

• 如果外接程序调用 saveAsync 以获取用于 EWS 或 REST API 的项目 ID，请注意，当 Outlook 处于缓存模式时，可能需要一段时间才能将项目实际同步到服务器。 在项目同步之前，使用项 ID 将返回错误。

• 在 Outlook 网页版 和新 Outlook on Windows 中，将草稿保存到的邮箱帐户在从共享邮箱帐户发送的邮件上调用 时saveAsync会有所不同。 如果发件人从其个人邮箱创建新邮件并在“ 发件人 ”字段中选择共享邮箱帐户， saveAsync 请将草稿保存到用户个人邮箱的 “草稿 ”文件夹中。 如果发件人在单独的浏览器选项卡中打开共享邮箱帐户， (通过 “打开另一个邮箱 ”选项（例如，) 并在那里创建新邮件）， saveAsync 则会将草稿保存到共享邮箱的 “草稿 ”文件夹中。

错误：

• InvalidAttachmentId ：附件标识符不存在。

示例

Office.context.mailbox.item.saveAsync(
    function callback(result) {
        // Process the result.
    });

// The following is an example of the
// `result` parameter passed to the
// callback function. The `value`
// property contains the item ID of
// the item.
{
    "value": "AAMkADI5...AAA=",
    "status": "succeeded"
}

以异步方式将数据插入到邮件的正文或主题中。

方法 setSelectedDataAsync 在项目的主题或正文的光标位置插入指定的字符串，或者，如果在编辑器中选择了文本，则替换所选文本。 如果光标不在正文或主题字段中，则返回错误。 插入后，光标将置于插入内容的末尾。

setSelectedDataAsync(data: string, options: Office.AsyncContextOptions & CoercionTypeOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.2 ]

最低权限级别： 读/写项

适用的 Outlook 模式：邮件Compose

错误：

• InvalidAttachmentId ：附件标识符不存在。

示例

Office.context.mailbox.item.setSelectedDataAsync("<b>Hello World!</b>", { coercionType : "html" });

Office.context.mailbox.item.setSelectedDataAsync("Hello World!");

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/set-selected-data.yaml

Office.context.mailbox.item.setSelectedDataAsync("Replaced", function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Selected text has been updated successfully.");
  } else {
    console.error(asyncResult.error);
  }
});

以异步方式将数据插入到邮件的正文或主题中。

方法 setSelectedDataAsync 在项目的主题或正文的光标位置插入指定的字符串，或者，如果在编辑器中选择了文本，则替换所选文本。 如果光标不在正文或主题字段中，则返回错误。 插入后，光标将置于插入内容的末尾。

setSelectedDataAsync(data: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

参数

返回

注解

[ API set： Mailbox 1.2 ]

最低权限级别： 读/写项

适用的 Outlook 模式：邮件Compose

错误：

• InvalidAttachmentId ：附件标识符不存在。