在 Outlook 中管理撰写窗体中的项目附件
当用户撰写邮件或约会时，Office JavaScript API 提供了多个用于管理项目附件的 API。
附加文件或 Outlook 项目
使用适用于附件类型的 方法将文件或 Outlook 项目附加到撰写窗体。
addFileAttachmentAsync：附加文件。
addFileAttachmentFromBase64Async：使用其 Base64 编码字符串附加文件。
addItemAttachmentAsync：附加 Outlook 项目。
这些是异步方法，这意味着无需等待操作完成即可继续执行。 根据要添加的附件的原始位置和大小，异步调用可能需要一段时间才能完成。
如果某些任务依赖于要完成的操作，则应在回调函数中执行这些任务。 此回调函数是可选的，在附件上传完成后调用。 回调函数采用 AsyncResult 对象作为输出参数，该参数提供添加附件的任何状态、错误和返回值。 如果此回调需要任何额外参数，则可以在可选的 options.asyncContext 参数中指定它们。
options.asyncContext 可以是回调函数预期的任意类型。
例如，可以将 定义为 options.asyncContext 包含一个或多个键值对的 JSON 对象。 有关在 Office 外接程序平台中将可选参数传递给异步方法的更多示例，请参阅 Office 外接程序中的异步编程。以下示例演示如何使用 asyncContext 参数将两个参数传递给回调函数。
const options = { asyncContext: { var1: 1, var2: 2 } };
Office.context.mailbox.item.addFileAttachmentAsync("https://contoso.com/rtm/icon.png", "icon.png", options, callback);
若要检查回调函数中异步方法调用的结果，请使用 status 对象的 和 error 属性AsyncResult。 如果附加成功完成，请使用 AsyncResult.value 属性获取附件 ID。 附件 ID 是一个证书，您稍后可使用附件 ID 删除附件。
注意
附件 ID 仅在同一会话中有效，不保证跨会话映射到同一附件。 会话结束的示例包括当用户关闭加载项时，或者用户开始在内联窗体中撰写，然后弹出内联窗体以在单独的窗口中继续。
提示
可以附加到邮件项目的文件或 Outlook 项目有限制，例如附件数量及其大小。 有关进一步的指导，请参阅 JavaScript API 的限制。
附加文件
可以使用 方法并指定文件的 URI，在撰写窗体 addFileAttachmentAsync 中将文件附加到邮件或约会。 还可以使用 addFileAttachmentFromBase64Async 方法，将 Base64 编码的字符串指定为输入。 如果文件受保护，您可以包括相应的标识或身份验证令牌作为 URI 查询字符串参数。 Exchange 将向 URI 发出调用以获取附件，保护文件的 Web 服务将需要使用令牌作为进行身份验证的一种方式。
注意
要附加的文件的 URI 必须支持生产中的缓存。 托管映像的服务器不应返回在 Cache-Control HTTP 响应中指定 no-cache、 no-store或类似选项的标头。 但是，当你开发加载项并更改文件时，缓存可能会阻止你看到所做的更改。 建议在开发期间使用 Cache-Control 标头。
以下 JavaScript 示例是一个撰写加载项，用于将文件 （picture.png）从 Web 服务器附加到正在撰写的邮件或约会。 回调函数采用 asyncResult 作为参数，检查结果状态，并在方法成功时获取附件 ID。
// Add the specified file attachment to the item
// being composed.
// When the attachment finishes uploading, the
// callback function is invoked and gets the attachment ID.
// You can optionally pass any object that you would
// access in the callback function as an argument to
// the asyncContext parameter.
Office.context.mailbox.item.addFileAttachmentAsync(
"https://webserver/picture.png",
"picture.png",
{ asyncContext: { var1: 1, var2: 2 } },
(asyncResult) => {
if (asyncResult.status === Office.AsyncResultStatus.Failed) {
console.error(asyncResult.error.message);
return;
}
// Get the ID of the attached file.
const attachmentID = asyncResult.value;
console.log(`ID of added attachment: ${attachmentID}`);
}
);
若要将 Base64 编码的图像内联添加到正在撰写的邮件或约会的正文，必须先使用 Office.context.mailbox.item.body.getAsync 方法获取当前项目正文，然后使用 方法插入图像 addFileAttachmentFromBase64Async 。 否则，图像在插入后不会呈现在正文中。 有关指导，请参阅以下 JavaScript 示例，该示例将内联 Base64 图像添加到项正文的开头。
const mailItem = Office.context.mailbox.item;
const base64String =
"iVBORw0KGgoAAAANSUhEUgAAAGAAAABgCAMAAADVRocKAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAnUExURQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAN0S+bUAAAAMdFJOUwAQIDBAUI+fr7/P7yEupu8AAAAJcEhZcwAADsMAAA7DAcdvqGQAAAF8SURBVGhD7dfLdoMwDEVR6Cspzf9/b20QYOthS5Zn0Z2kVdY6O2WULrFYLBaLxd5ur4mDZD14b8ogWS/dtxV+dmx9ysA2QUj9TQRWv5D7HyKwuIW9n0vc8tkpHP0W4BOg3wQ8wtlvA+PC1e8Ao8Ld7wFjQtHvAiNC2e8DdqHqKwCrUPc1gE1AfRVgEXBfB+gF0lcCWoH2tYBOYPpqQCNwfT3QF9i+AegJfN8CtAWhbwJagtS3AbIg9o2AJMh9M5C+SVGBvx6zAfmT0r+Bv8JMwP4kyFPir+cswF5KL3WLv14zAFBCLf56Tw9cparFX4upgaJUtPhrOS1QlY5W+vWTXrGgBFB/b72ev3/0igUdQPppP/nfowfKUUEFcP207y/yxKmgAYQ+PywoAFOfCH3A2MdCFzD3kdADBvq10AGG+pXQBgb7pdAEhvuF0AIc/VtoAK7+JciAs38KIuDugyAC/v4hiMCE/i7IwLRBsh68N2WQjMVisVgs9i5bln8LGScNcCrONQAAAABJRU5ErkJggg==";
// Get the current body of the message or appointment.
mailItem.body.getAsync(Office.CoercionType.Html, (bodyResult) => {
if (bodyResult.status === Office.AsyncResultStatus.Failed) {
console.error(bodyResult.error.message);
return;
}
// Insert the Base64-encoded image at the beginning of the body.
const options = { isInline: true, asyncContext: bodyResult.value };
mailItem.addFileAttachmentFromBase64Async(base64String, "sample.png", options, (attachResult) => {
if (attachResult.status === Office.AsyncResultStatus.Failed) {
console.error(attachResult.error.message);
return;
}
let body = attachResult.asyncContext;
body = body.replace("<p class=MsoNormal>", `<p class=MsoNormal><img src="cid:sample.png">`);
mailItem.body.setAsync(body, { coercionType: Office.CoercionType.Html }, (setResult) => {
if (setResult.status === Office.AsyncResultStatus.Failed) {
console.error(setResult.error.message);
return;
}
console.log("Inline Base64 image added to the body.");
});
});
});
附加 Outlook 项目
若要将 Outlook 项目 (例如电子邮件、日历或联系人项目) 附加到撰写窗体中的邮件或约会，请指定项目的 Exchange Web Services (EWS) ID，并使用 addItemAttachmentAsync 方法。 若要获取项目的 EWS ID，请使用 item.itemId 属性。
以下 JavaScript 函数 addItemAttachment扩展了前面的示例，并将项目作为附件添加到正在撰写的电子邮件或约会。 函数采用要附加的项的 EWS ID 作为参数。 如果附加成功，它将获取附件 ID 以供进一步处理。
// Adds the specified item as an attachment to the composed item.
// ID is the EWS ID of the item to be attached.
function addItemAttachment(itemId) {
// When the attachment finishes uploading, the
// callback function is invoked. Here, the callback
// function uses only asyncResult as a parameter,
// and if the attaching succeeds, gets the attachment ID.
// You can optionally pass any other object you wish to
// access in the callback function as an argument to
// the asyncContext parameter.
Office.context.mailbox.item.addItemAttachmentAsync(
itemId,
"Welcome email",
{ asyncContext: { var1: 1, var2: 2 } },
(asyncResult) => {
if (asyncResult.status === Office.AsyncResultStatus.Failed) {
console.error(asyncResult.error.message);
return;
}
const attachmentID = asyncResult.value;
console.log(`ID of added attachment: ${attachmentID}`);
}
);
}
注意
你可以使用撰写加载项在Outlook 网页版、移动设备或新的 Outlook on Windows 中附加定期约会的实例。 但是，在 Windows 或 Mac 上支持 Outlook 客户端中，尝试附加实例会导致将定期系列附加到父约会 () 。
获取附件
在撰写模式下获取附件的以下 API 可从 要求集 1.8 获取。
使用 getAttachmentsAsync 方法获取正在撰写的邮件或约会的附件。
若要获取附件的内容，请使用 getAttachmentContentAsync 方法。 AttachmentContentFormat 枚举中列出了支持的格式。
应使用AsyncResult输出参数对象提供回调函数，以检查状态和任何错误。 还可以使用可选 asyncContext 参数将任何其他参数传递给回调函数。
以下 JavaScript 示例获取附件，并允许你为每个受支持的附件格式设置不同的处理。
const item = Office.context.mailbox.item;
const options = { asyncContext: { currentItem: item } };
item.getAttachmentsAsync(options, callback);
function callback(result) {
if (result.value.length > 0) {
for (let i = 0 ; i < result.value.length ; i++) {
result.asyncContext.currentItem.getAttachmentContentAsync(result.value[i].id, handleAttachmentsCallback);
}
}
}
function handleAttachmentsCallback(result) {
// Parse string to be a url, an .eml file, a Base64-encoded string, or an .icalendar file.
switch (result.value.format) {
case Office.MailboxEnums.AttachmentContentFormat.Base64:
// Handle file attachment.
break;
case Office.MailboxEnums.AttachmentContentFormat.Eml:
// Handle email item attachment.
break;
case Office.MailboxEnums.AttachmentContentFormat.ICalendar:
// Handle .icalender attachment.
break;
case Office.MailboxEnums.AttachmentContentFormat.Url:
// Handle cloud attachment.
break;
default:
// Handle attachment formats that are not supported.
}
}
提示
如果运行加载项的 Outlook 客户端不支持邮箱要求集 1.8，则你仍然可以从使用 Microsoft Graph 或 EWS 撰写的项目获取附件及其内容。 若要了解详细信息，请参阅 从 Exchange 获取 Outlook 项目的附件。
删除附件
若要从撰写窗体中的邮件或约会项目中删除文件或项目附件，请在 removeAttachmentAsync 方法中指定相应的附件 ID。
重要
如果使用要求集 1.7 或更低版本，则只应删除同一个加载项在同一会话中添加的附件。
与 addFileAttachmentAsync、 addItemAttachmentAsync和 getAttachmentsAsync 方法类似， removeAttachmentAsync 是一种异步方法。 应使用AsyncResult输出参数对象提供回调函数，以检查状态和任何错误。 还可以使用可选 asyncContext 参数将任何其他参数传递给回调函数。
以下 JavaScript 函数 removeAttachment继续扩展上述示例，并从撰写的电子邮件或约会中删除指定的附件。 此函数将要删除的附件的 ID 作为实参。 可以在成功 addFileAttachmentAsync调用 、 addFileAttachmentFromBase64Async或 addItemAttachmentAsync 方法后获取附件的 ID，并在后续 removeAttachmentAsync 方法调用中使用它。 还可以调用 getAttachmentsAsync 要求集 1.8) 中引入 (以获取该外接程序会话的附件及其 ID。
// Removes the specified attachment from the composed item.
function removeAttachment(attachmentId) {
// When the attachment is removed, the callback function is invoked.
// Here, the callback function uses an asyncResult parameter and
// gets the ID of the removed attachment if the removal succeeds.
// You can optionally pass any object you wish to access in the
// callback function as an argument to the asyncContext parameter.
Office.context.mailbox.item.removeAttachmentAsync(
attachmentId,
{ asyncContext: null },
(asyncResult) => {
if (asyncResult.status === Office.AsyncResultStatus.Failed) {
console.error(asyncResult.error.message);
return;
}
console.log(`Removed attachment with the ID: ${asyncResult.value}`);
}
);
}
提示
方法 removeAttachmentAsync 不会从邮件项中删除内联附件。 若要删除内联附件，请先获取项目的正文，然后从其内容中删除附件的任何引用。 使用 Office.Body API 获取和设置项的正文。