使用 Microsoft 365 的统一清单创建外接程序命令

  • 项目

加载项命令提供了使用执行操作的特定 UI 元素来自定义默认的 Office 用户界面 (UI) 的简单方法。 有关外接程序命令的简介，请参阅 外接程序命令。

本文介绍如何 为 Microsoft 365 (预览版配置统一清单) 以定义外接程序命令，以及如何为 函数命令创建代码。

提示

有关使用 XML 清单创建外接程序命令的说明，请参阅 使用 XML 清单创建外接程序命令。

注意

统一清单目前仅支持 Windows 上的 Outlook 外接程序。 它处于预览阶段，尚不支持生产加载项。

起点和主要步骤

使用统一清单创建外接程序项目的这两个工具（ Office Yeoman 生成器 和 Teams 工具包 ）都使用一个或多个外接程序命令创建项目。 唯一一次没有加载项命令是更新以前没有加载项的加载项。

两个决定

  • 确定需要以下两种类型的外接程序命令： 任务窗格或函数。
  • 确定所需的 UI 元素类型：按钮或菜单项。 然后执行下面与你的决策对应的部分和小节中的步骤。

添加任务窗格命令

以下小节说明如何在外接程序中包含 任务窗格命令 。

为任务窗格命令配置运行时

  1. 打开统一清单并找到“extensions.runtimes”数组。

  2. 确保运行时对象具有值为“openPage”的“actions.type”属性。 这种类型的运行时将打开任务窗格。

  3. 确保“requirements.capabilities”数组包含一个对象，该对象指定支持外接程序命令 的要求集 。 对于 Outlook，加载项命令的最低要求集为 Mailbox 1.3。

    注意

    当对统一清单的支持扩展到其他 Office 主机应用程序时，为其他主机中的外接程序命令设置的最低要求将是 AddinCommands 1.1。

  4. 确保运行时对象的“id”具有描述性名称，例如“TaskPaneRuntime”。

  5. 确保运行时对象的“code.page”属性设置为应在任务窗格中打开的页面的 URL，例如“https://localhost:3000/taskpane.html"”。

  6. 确保运行时对象的“actions.view”名称描述在上一步中设置的页面的内容，例如“主页”或“仪表板”。

  7. 确保运行时对象的“actions.id”具有描述性名称，例如“ShowTaskPane”，指示当用户选择外接程序命令按钮或菜单项时发生的情况。

  8. 设置运行时对象的其他属性和子属性，如以下已完成的运行时对象示例所示。 “type”和“lifetime”属性是必需的，在 Outlook 外接程序 (这是当前唯一支持统一清单的主机，) 它们始终具有此示例中显示的值。

    "runtimes": [
    {
        "requirements": {
            "capabilities": [
                {
                    "name": "Mailbox",
                    "minVersion": "1.3"
                }
            ]
        },
        "id": "TaskPaneRuntime",
        "type": "general",
        "code": {
            "page": "https://localhost:3000/taskpane.html"
        },
        "lifetime": "short",
        "actions": [
            {
                "id": "ShowTaskPane",
                "type": "openPage",
                "view": "homepage"
            }
        ]
    }        
]

配置任务窗格命令的 UI

  1. 确保为其配置运行时的扩展对象具有“功能区”数组属性作为“运行时”数组的对等方。 “extensions”数组中通常只有一个扩展对象。

  2. 确保数组具有名为“contexts”和“tabs”的数组属性的对象，如以下示例所示。

    "ribbons": [
    {
        "contexts": [
            // child objects omitted
        ],
        "tabs": [
            // child objects omitted
        ]
    }
]

  3. 确保“contexts”数组包含字符串，这些字符串指定任务窗格命令的 UI 应在其中显示窗口或窗格。 例如，“mailRead”表示在打开电子邮件时，它将出现在阅读窗格或邮件窗口中，但“mailCompose”表示在撰写新邮件或答复时会显示它。 以下是允许的值：

    • “mailRead”
    • “mailCompose”
    • “meetingDetailsOrganizer”
    • “meetingDetailsAttendee”

    示例如下。

    "contexts": [
    "mailRead"
],

  4. 确保“tabs”数组具有一个具有“builtInTabId”字符串属性的对象，该属性设置为要在其中显示任务窗格命令的功能区选项卡的 ID。 此外，请确保有一个“groups”数组，其中包含至少一个 对象。 示例如下。

    "tabs": [
    {
        "builtInTabID": "TabDefault",
        "groups": [
            {
                // properties omitted                
            }
        ]
    }
]

    注意

    “builtInTabID”属性的唯一允许值为“TabDefault”，在 Outlook 中，该选项卡可以是“ 开始”、“ 邮件”或“ 会议 ”选项卡。将统一清单的支持添加到其他 Office 主机应用程序时，将有其他可能的值。

  5. 确保“groups”数组有一个 对象，用于定义将保存外接程序命令 UI 控件的自定义控件组。 示例如下。 请注意有关此 JSON 的以下事项：

    • “id”在清单中的所有功能区对象中的所有组中必须是唯一的。 最大长度为 64 个字符。
    • “标签”显示在功能区上的组上。 最大长度为 64 个字符。
    • 仅当用户对 Office 应用程序窗口和功能区的大小过小，无法显示组中的任何控件时，组才会显示其中一个“图标”。 Office 根据窗口大小和设备分辨率决定何时使用这些图标之一以及要使用哪个图标。 无法控制这一点。 必须提供 16、32 和 80 像素的图像文件，同时支持其他 5 个大小 (20、24、40、48 和 64 像素) 。 必须对所有 URL 使用安全套接字层 (SSL) 。
    "groups": [
    {
        "id": "msgReadGroup",
        "label": "Contoso Add-in",
        "icons": [
            {
                "size": 16,
                "url": "https://localhost:3000/assets/icon-16.png"
            },
            {
                "size": 32,
                "url": "https://localhost:3000/assets/icon-32.png"
            },
            {
                "size": 80,
                "url": "https://localhost:3000/assets/icon-80.png"
            }
        ],
        "controls": [
            {
                // properties omitted 
            }
        ]
    }
]

  6. 确保所需的每个按钮或自定义菜单的“controls”数组中都有一个控件对象。 示例如下。 请注意有关此 JSON 的以下事项：

    • “id”、“label”和“icons”属性与组对象的相应属性具有相同的用途和限制，只是它们应用于组中的特定按钮或菜单。
    • “type”属性设置为“button”，这意味着控件将是功能区按钮。 还可以将任务窗格命令配置为从菜单项运行。 请参阅 菜单和菜单项。
    • “supertip.title” (最大长度：) 64 个字符，“supertip.description” (最大长度：光标悬停在按钮或菜单上时，) 显示 128 个字符。
    • “actionId”必须与在 配置任务窗格命令的运行时中设置的“runtimes.actions.id”完全匹配。
    {
    "id": "msgReadOpenPaneButton",
    "type": "button",
    "label": "Show Task Pane",
    "icons": [
        {
            "size": 16,
            "url": "https://localhost:3000/assets/icon-16.png"
        },
        {
            "size": 32,
            "url": "https://localhost:3000/assets/icon-32.png"
        },
        {
            "size": 80,
            "url": "https://localhost:3000/assets/icon-80.png"
        }
    ],
    "supertip": {
        "title": "Show Contoso Task Pane",
        "description": "Opens the Contoso task pane."
    },
    "actionId": "ShowTaskPane"
}

现已完成向外接程序添加任务窗格命令。 旁加载并测试它。

添加函数命令

以下小节说明如何在外接程序中包含 函数命令 。

为函数命令创建代码

  1. 确保源代码包含 JavaScript 或 Typescript 文件，其中包含要通过函数命令运行的函数。 示例如下。 由于本文介绍如何创建外接程序命令，而不是教授 Office JavaScript 库，因此我们为其提供了最少的注释，但请注意以下事项：

    • 就本文而言，该文件名为 commands.js。
    • 函数将导致打开的电子邮件上显示一个小通知，其文本为“执行的操作”。
    • 与在 Office JavaScript 库中调用 API 的所有代码一样，它必须从 初始化库开始。 它通过调用 Office.onReady来执行此操作。
    • 代码调用的最后一件事是 Office.actions.associate ，以告知 Office 在调用函数命令的 UI 时应运行文件中的哪个函数。 函数将函数名称映射到在后续步骤的清单中配置的操作 ID。 如果在同一文件中定义多个函数命令，则必须为每个函数命令调用 associate 代码。
    • 函数必须采用 类型为 Office.AddinCommands.Event 的参数。 函数的最后一行必须调用 event.completed。
    Office.onReady(function() {
// Add any initialization code here.
});

function setNotification(event) {
const message = {
    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
    message: "Performed action.",
    icon: "Icon.80x80",
    persistent: true,
};

// Show a notification message.
Office.context.mailbox.item.notificationMessages.replaceAsync("ActionPerformanceNotification", message);

// Be sure to indicate when the add-in command function is complete.
event.completed();
}

// Map the function to the action ID in the manifest.
Office.actions.associate("SetNotification", setNotification);

  2. 确保源代码包含配置为加载创建的函数文件的 HTML 文件。 示例如下。 请注意有关此 JSON 的以下事项：

    • 就本文而言，该文件名为 commands.html。

    • 元素 <body> 为空，因为该文件没有 UI。 它的唯一用途是加载 JavaScript 文件。

    • 将显式加载在上一步中创建的 Office JavaScript 库和 commands.js 文件。

      注意

      在 Office 外接程序开发中，通常使用 Webpack 及其插件等工具在生成时自动将标记注入 <script> HTML 文件。 如果使用此类工具，则不应在源文件中包含要由该工具插入的任何 <script> 标记。

    <!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <meta http-equiv="X-UA-Compatible" content="IE=Edge" />

        <!-- Office JavaScript Library -->
        <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js"></script>
        <!-- Function command file -->
        <script src="commands.js" type="text/javascript"></script>
    </head>
    <body>        
    </body>
</html>

为函数命令配置运行时

  1. 打开统一清单并找到“extensions.runtimes”数组。

  2. 确保运行时对象具有值为“executeFunction”的“actions.type”属性。

  3. 确保“requirements.capabilities”数组包含指定支持 API 外接程序命令所需的任何 要求集 的对象。 对于 Outlook，加载项命令的最低要求设置为 Mailbox 1.3。 但是，如果函数命令调用属于更高 邮箱 要求集（例如 Mailbox 1.5）的 API，则需要将更高版本的 (例如“1.5”) 指定为“minVersion”值。

    注意

    当对统一清单的支持扩展到其他 Office 主机应用程序时，为其他主机中的外接程序命令设置的最低要求将是 AddinCommands 1.1。

  4. 确保运行时对象的“id”具有描述性名称，例如“CommandsRuntime”。

  5. 确保将运行时对象的“code.page”属性设置为加载函数文件的无 UI HTML 页的 URL，例如“https://localhost:3000/commands.html"”。

  6. 确保运行时对象的“actions.id”具有描述性名称，例如“SetNotification”，指示当用户选择外接程序命令按钮或菜单项时发生的情况。

    重要

    “actions.id”的值必须与函数文件中调用 Office.actions.associate 的第一个参数完全匹配。

  7. 设置运行时对象的其他属性和子属性，如以下已完成的运行时对象示例所示。 “type”和“lifetime”属性是必需的，它们始终具有 Outlook 外接程序中显示的值，后者是当前唯一支持统一清单的主机。

    "runtimes": [
    {
        "id": "CommandsRuntime",
        "type": "general",
        "code": {
            "page": "https://localhost:3000/commands.html"
        },
        "lifetime": "short",
        "actions": [
            {
                "id": "SetNotification",
                "type": "executeFunction",
            }
        ]
    }       
]

配置函数命令的 UI

  1. 确保为其配置运行时的扩展对象具有“功能区”数组属性作为“运行时”数组的对等方。 “extensions”数组中通常只有一个扩展对象。

  2. 确保数组具有名为“contexts”和“tabs”的数组属性的对象，如以下示例所示。

    "ribbons": [
    {
        "contexts": [
            // child objects omitted
        ],
        "tabs": [
            // child objects omitted
        ]
    }
]

  3. 确保“contexts”数组具有字符串，这些字符串指定函数命令的 UI 应在其中显示窗口或窗格。 例如，“mailRead”表示在打开电子邮件时，它将出现在阅读窗格或邮件窗口中，但“mailCompose”表示在撰写新邮件或答复时会显示它。 以下是允许的值：

    • mailRead
    • mailCompose
    • meetingDetailsOrganizer
    • meetingDetailsAttendee

    示例如下。

    "contexts": [
    "mailRead"
],

  4. 确保“tabs”数组具有具有“builtInTabId”字符串属性的对象，该属性设置为要在其中显示函数命令的功能区选项卡的 ID，以及包含至少一个对象的“groups”数组。 示例如下。

    "tabs": [
    {
        "builtInTabID": "TabDefault",
        "groups": [
            {
                // properties omitted                
            }
        ]
    }
]

    注意

    “builtInTabID”属性的唯一允许值为“TabDefault”，在 Outlook 中，该选项卡可以是“ 开始”、“ 邮件”或“ 会议 ”选项卡。将统一清单的支持添加到其他 Office 主机应用程序时，将有其他可能的值。

  5. 确保“groups”数组有一个 对象，用于定义将保存外接程序命令 UI 控件的自定义控件组。 示例如下。 请注意有关此 JSON 的以下事项：

    • “id”在清单中的所有功能区对象中的所有组中必须是唯一的。 最大长度为 64 个字符。
    • “标签”显示在功能区上的组上。 最大长度为 64 个字符。
    • 仅当用户对 Office 应用程序窗口和功能区的大小过小，无法显示组中的任何控件时，组才会显示其中一个“图标”。 Office 根据窗口大小和设备分辨率决定何时使用这些图标之一以及要使用哪个图标。 无法控制这一点。 必须提供 16、32 和 80 像素的图像文件，同时支持其他 5 个大小 (20、24、40、48 和 64 像素) 。 必须对所有 URL 使用安全套接字层 (SSL) 。
    "groups": [
    {
        "id": "msgReadGroup",
        "label": "Contoso Add-in",
        "icons": [
            {
                "size": 16,
                "url": "https://localhost:3000/assets/icon-16.png"
            },
            {
                "size": 32,
                "url": "https://localhost:3000/assets/icon-32.png"
            },
            {
                "size": 80,
                "url": "https://localhost:3000/assets/icon-80.png"
            }
        ],
        "controls": [
            {
                // properties omitted 
            }
        ]
    }
]

  6. 确保所需的每个按钮或自定义菜单的“controls”数组中都有一个控件对象。 示例如下。 请注意有关此 JSON 的以下事项：

    • “id”、“label”和“icons”属性与组对象的相应属性具有相同的用途和限制，只是它们应用于组中的特定按钮或菜单。
    • “type”属性设置为“button”，这意味着控件将是功能区按钮。 还可以将函数命令配置为从菜单项运行。 请参阅 菜单和菜单项。
    • “supertip.title” (最大长度：) 64 个字符，“supertip.description” (最大长度：光标悬停在按钮或菜单上时，) 显示 128 个字符。
    • “actionId”必须与在 配置函数命令的运行时中设置的“runtime.actions.id”完全匹配。
    {
    "id": "msgReadSetNotificationButton",
    "type": "button",
    "label": "Set Notification",
    "icons": [
        {
            "size": 16,
            "url": "https://localhost:3000/assets/icon-16.png"
        },
        {
            "size": 32,
            "url": "https://localhost:3000/assets/icon-32.png"
        },
        {
            "size": 80,
            "url": "https://localhost:3000/assets/icon-80.png"
        }
    ],
    "supertip": {
        "title": "Set Notification",
        "description": "Displays a notification message on the current message."
    },
    "actionId": "SetNotification"
}

现已完成向外接程序添加函数命令。 旁加载并测试它。

除了自定义按钮，还可以将自定义下拉菜单添加到 Office 功能区。 本部分介绍如何使用包含两个菜单项的示例。 一个调用任务窗格命令。 另一个调用函数命令。

配置运行时和代码

执行以下部分的步骤：

配置菜单的 UI

  1. 确保为其配置运行时的扩展对象具有“功能区”数组属性作为“运行时”数组的对等方。 “extensions”数组中通常只有一个扩展对象。

  2. 确保数组具有名为“contexts”和“tabs”的数组属性的对象，如以下示例所示。

    "ribbons": [
    {
        "contexts": [
            // child objects omitted
        ],
        "tabs": [
            // child objects omitted
        ]
    }
]

  3. 确保“contexts”数组包含指定菜单显示在功能区上的窗口或窗格的字符串。 例如，“mailRead”表示在打开电子邮件时，它将出现在阅读窗格或邮件窗口中，但“mailCompose”表示在撰写新邮件或答复时会显示它。 以下是允许的值：

    • mailRead
    • mailCompose
    • meetingDetailsOrganizer
    • meetingDetailsAttendee

    示例如下。

    "contexts": [
    "mailRead"
],

  4. 确保“tabs”数组具有具有“builtInTabId”字符串属性的对象，该属性设置为要在其中显示任务窗格命令的功能区选项卡的 ID，以及包含至少一个对象的“groups”数组。 示例如下。

    "tabs": [
    {
        "builtInTabID": "TabDefault",
        "groups": [
            {
                // properties omitted                
            }
        ]
    }
]

    注意

    “builtInTabID”属性的唯一允许值为“TabDefault”，在 Outlook 中，该选项卡可以是“ 开始”、“ 邮件”或“ 会议 ”选项卡。将统一清单的支持添加到其他 Office 主机应用程序时，将有其他可能的值。

  5. 确保“groups”数组有一个 对象，用于定义用于保存下拉菜单控件的自定义控件组。 示例如下。 请注意有关此 JSON 的以下事项：

    • “id”在清单中的所有功能区对象中的所有组中必须是唯一的。 最大长度为 64 个字符。
    • “标签”显示在功能区上的组上。 最大长度为 64 个字符。
    • 仅当用户对 Office 应用程序窗口和功能区的大小过小，无法显示组中的任何控件时，组才会显示其中一个“图标”。 Office 根据窗口大小和设备分辨率决定何时使用这些图标之一以及要使用哪个图标。 无法控制这一点。 必须提供 16、32 和 80 像素的图像文件，同时支持其他 5 个大小 (20、24、40、48 和 64 像素) 。 必须对所有 URL 使用安全套接字层 (SSL) 。
    "groups": [
    {
        "id": "msgReadGroup",
        "label": "Contoso Add-in",
        "icons": [
            {
                "size": 16,
                "url": "https://localhost:3000/assets/icon-16.png"
            },
            {
                "size": 32,
                "url": "https://localhost:3000/assets/icon-32.png"
            },
            {
                "size": 80,
                "url": "https://localhost:3000/assets/icon-80.png"
            }
        ],
        "controls": [
            {
                // properties omitted 
            }
        ]
    }
]

  6. 确保“controls”数组中有一个控件对象。 示例如下。 请注意有关此 JSON 的以下事项：

    • “id”、“label”和“icons”属性与组对象的相应属性具有相同的用途和限制，只是它们应用于组中的下拉菜单。
    • “type”属性设置为“menu”，这意味着控件将是下拉菜单。
    • “supertip.title” (最大长度：) 64 个字符，“supertip.description” (最大长度：光标悬停在菜单上时，) 显示 128 个字符。
    • “items”属性包含两个菜单选项的 JSON。 这些值将在后续步骤中添加。
    {
    "id": "msgReadMenu",
    "type": "menu",
    "label": "Contoso Menu",
    "icons": [
        {
            "size": 16,
            "url": "https://localhost:3000/assets/icon-16.png"
        },
        {
            "size": 32,
            "url": "https://localhost:3000/assets/icon-32.png"
        },
        {
            "size": 80,
            "url": "https://localhost:3000/assets/icon-80.png"
        }
    ],
    "supertip": {
        "title": "Show Contoso Actions",
        "description": "Opens the Contoso menu."
    },
    "items": [
        {
            "id": "",
            "type": "",
            "label": "",
            "supertip": {},
            "actionId": ""
        },
        {
            "id": "",
            "type": "",
            "label": "",
            "supertip": {},
            "actionId": ""
        }
    ]
}

  7. 第一项显示任务窗格。 示例如下。 关于此代码，请注意以下几点：

    • “id”、“label”和“supertip”属性与父菜单对象的相应属性具有相同的用途和限制，只是它们仅应用于此菜单选项。
    • “icons”属性对于菜单项是可选的，此示例中没有属性。 如果包含该图标，则其用途和限制与父菜单的“icon”属性相同，只不过该图标显示在标签旁边的菜单项上。
    • “type”属性设置为“menuItem”。
    • “actionId”必须与在 配置任务窗格命令的运行时中设置的“runtimes.actions.id”完全匹配。
    {
    "id": "msgReadOpenPaneMenuItem",
    "type": "menuItem",
    "label": "Show Task Pane",
    "supertip": {
        "title": "Show Contoso Task Pane",
        "description": "Opens the Contoso task pane."
    },
    "actionId": "ShowTaskPane"
},

  8. 第二项运行函数命令。 示例如下。 关于此代码，请注意以下几点：

    {
    "id": "msgReadSetNotificationMenuItem",
    "type": "menuItem",
    "label": "Set Notification",
    "supertip": {
        "title": "Set Notification",
        "description": "Displays a notification message on the current message."
    },
    "actionId": "SetNotification"
}

现已完成向外接程序添加菜单。 旁加载并测试它。

另请参阅