通过可操作邮件调用 Outlook 加载项
借助可操作邮件，用户可以对电子邮件或连接器卡片快速执行操作；借助 Outlook 加载项，可以将 Outlook 扩展为添加新功能和新交互。 现在，借助 Action.InvokeAddInCommand 操作类型，可以将这两类集成相结合，打造更强大、更引人注目的体验。 例如，可以执行下列操作：
- 在新用户注册服务后，向他们发送可操作电子邮件形式的欢迎邮件，其中包含方便新用户快速安装并开始使用加载项的操作。
- 在简单的操作输入并不足够的情况下，使用加载项实现更为复杂的操作（即向用户显示窗体）。
- 在向用户显示 UI 前，在加载项中预填充 UI 元素。
无论用户是否已安装加载项，Action.InvokeAddInCommand 都适用。 如果未安装相应加载项，用户会看到提示，只需单击一下，即可安装加载项。
注意
仅当加载项在 AppSource 中发布时，才支持单击安装所需的加载项。
下面的示例展示了未安装加载项的用户看到的提示。
调用加载项
可操作邮件在邮件中指定 Action.InvokeAddInCommand 操作，从而调用加载项。 此操作指定了要调用的加载项，以及打开相应任务窗格的加载项按钮的标识符。
加载项清单中包含所需信息。 首先，需要 Id 元素中指定的加载项标识符。
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OfficeApp
xmlns="http://schemas.microsoft.com/office/appforoffice/1.1"
xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0"
xsi:type="MailApp">
<Id>527104a1-f1a5-475a-9199-7a968161c870</Id>
<Version>1.0.0.0</Version>
...
</OfficeApp>
对于此加载项，加载项标识符为 527104a1-f1a5-475a-9199-7a968161c870。
接下来，需要 Control 元素的 id 属性，它定义了打开相应任务窗格的加载项按钮。 请注意，Control 元素必须满足以下条件：
- 在 MessageReadCommandSurface 扩展点中定义
- 将
xsi:type属性设置为Button - 包含
ShowTaskpane类型的 Action 元素
<ExtensionPoint xsi:type="MessageReadCommandSurface">
<OfficeTab id="TabDefault">
<Group id="msgReadCmdGroup">
<Label resid="groupLabel"/>
<Control xsi:type="Button" id="showInitContext">
<Label resid="readButtonLabel"/>
<Supertip>
<Title resid="readButtonTitle"/>
<Description resid="readButtonDesc"/>
</Supertip>
<Icon>
<bt:Image size="16" resid="icon-16"/>
<bt:Image size="32" resid="icon-32"/>
<bt:Image size="80" resid="icon-80"/>
</Icon>
<Action xsi:type="ShowTaskpane">
<SourceLocation resid="readPaneUrl"/>
<SupportsPinning>true</SupportsPinning>
</Action>
</Control>
</Group>
</OfficeTab>
</ExtensionPoint>
对于此加载项按钮，ID 为 showInitContext。
综合这两条信息，可以创建如下的基本 Action.InvokeAddInCommand 操作：
{
"type": "AdaptiveCard",
"version": "1.0",
"body": [
{
"type": "TextBlock",
"text": "Invoking an add-in command from an Actionable Message card",
"size": "large"
}
],
"actions": [
{
"type": "Action.InvokeAddInCommand",
"title": "Invoke \"View Initialization Context\"",
"addInId": "527104a1-f1a5-475a-9199-7a968161c870",
"desktopCommandId": "showInitContext"
}
]
}
将初始化数据传递给加载项
Action.InvokeAddInCommand 操作还可以向加载项提供其他上下文，让加载项能够执行其他操作，而不仅仅是激活。 例如，此操作可以提供窗体的初始值，也可以提供相关信息，让加载项“深层链接”到后端服务中的特定项。
若要传递初始化数据，请在 Action.InvokeAddInCommand 操作中添加 initializationContext 属性。 initializationContext 属性没有既定架构，可以包含任何有效的 JSON 对象。
例如，若要扩展上文中的示例操作，可以按如下所示修改操作：
{
"type": "AdaptiveCard",
"version": "1.0",
"body": [
{
"type": "TextBlock",
"text": "Invoking an add-in command from an Actionable Message card",
"size": "large"
}
],
"actions": [
{
"type": "Action.InvokeAddInCommand",
"title": "Invoke \"View Initialization Context\"",
"addInId": "527104a1-f1a5-475a-9199-7a968161c870",
"desktopCommandId": "showInitContext",
"initializationContext": {
"property1": "Hello world",
"property2": 5,
"property3": true
}
}
]
}
在加载项中接收初始化数据
如果操作传递了初始化数据，加载项必须做好接收准备。 加载项可以通过调用 Office.context.mailbox.item.getInitializationContextAsync 方法，检索初始化数据。 每当任务窗格打开或加载新邮件，此操作就应当会完成。
// 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.
}
});