Создание команд надстроек с помощью унифицированного манифеста для Microsoft 365

  • Статья

Команды надстроек позволяют легко настроить пользовательский интерфейс Office по умолчанию, добавив конкретные элементы интерфейса, выполняющие действия. Общие сведения о командах надстроек см. в разделе Команды надстройки.

В этой статье описывается настройка унифицированного манифеста для Microsoft 365 (предварительная версия) для определения команд надстройки и создание кода для команд функций.

Совет

Инструкции по созданию команд надстроек с помощью XML-манифеста см. в статье Создание команд надстроек с помощью XML-манифеста.

Примечание.

В настоящее время унифицированный манифест поддерживается только для надстроек Outlook в Windows. Он находится в предварительной версии и пока не поддерживается для рабочих надстроек.

Отправная точка и основные шаги

Оба средства, создающие проекты надстроек с унифицированным манифестом ( генератор Office Yeoman и набор средств Teams), создают проекты с помощью одной или нескольких команд надстроек. Единственный раз, когда у вас еще не будет команды надстройки, это если вы обновляете надстройку, в которой ранее ее не было.

Два решения

  • Решите, какой из двух типов команд надстройки вам нужен: область задач или функция.
  • Определите, какой тип элемента пользовательского интерфейса вам нужен: кнопка или пункт меню. Затем выполните действия, описанные в разделах и подразделах ниже, которые соответствуют вашим решениям.

Добавление команды области задач

В следующих подразделах объясняется, как включить команду области задач в надстройку.

Настройка среды выполнения для команды области задач

  1. Откройте унифицированный манифест и найдите массив extensions.runtimes.

  2. Убедитесь, что имеется объект среды выполнения со свойством actions.type со значением openPage. Этот тип среды выполнения открывает область задач.

  3. Убедитесь, что массив requirements.capabilities содержит объект, указывающий набор требований , поддерживающий команды надстройки. Для Outlook минимальными требованиями к командам надстройки является Почтовый ящик 1.3.

    Примечание.

    Если поддержка унифицированного манифеста распространяется на другие ведущие приложения Office, минимальным требованием для команд надстроек на этих других узлах будет AddinCommands 1.1.

  4. Убедитесь, что идентификатор объекта среды выполнения имеет описательное имя, например 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"
            }
        ]
    }        
]

Настройка пользовательского интерфейса для команды области задач

  1. Убедитесь, что объект расширения, для которого настроена среда выполнения, имеет свойство массива ribbons в качестве однорангового узла массива runtimes. Обычно в массиве 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, для которого задан идентификатор вкладки ленты, в которой должна отображаться команда области задач. Кроме того, убедитесь, что имеется массив groups с хотя бы одним объектом. Ниже приведен пример.

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

    Примечание.

    Единственное допустимое значение для свойства builtInTabID — TabDefault, которое в Outlook является вкладкой Главная, Сообщение или Собрание . При добавлении поддержки унифицированного манифеста в другие ведущие приложения Office появятся другие возможные значения.

  5. Убедитесь, что массив groups содержит объект для определения настраиваемой группы управления, в которой будут содержаться элементы управления пользовательского интерфейса команд надстройки. Ниже приведен пример. Обратите внимание на следующие сведения об этом JSON:

    • Идентификатор должен быть уникальным для всех групп во всех объектах ленты в манифесте. Максимальная длина: 64 символа.
    • Метка отображается в группе на ленте. Максимальная длина: 64 символа.
    • Один из значков отображается в группе только в том случае, если размер окна приложения Office и, следовательно, ленты был слишком мал для любого элемента управления в группе. Office решает, когда использовать один из этих значков и какой из них следует использовать, в зависимости от размера окна и разрешения устройства. Вы не можете управлять этим. Необходимо предоставить файлы изображений размером 16, 32 и 80 пикселей, в то время как поддерживаются пять других размеров (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 с функцией, которую вы хотите запустить с помощью команды функции. Ниже приведен пример. Так как эта статья посвящена созданию команд надстроек, а не обучению библиотеке JavaScript для Office, мы предоставим ей минимальные комментарии, но обратите внимание на следующее:

    • Для целей этой статьи файл называется commands.js.
    • Функция приведет к отображению небольшого уведомления в открытом сообщении электронной почты с текстом "Выполнено действие".
    • Как и весь код, вызывающий API-интерфейсы в библиотеке JavaScript для Office, он должен начинаться с инициализации библиотеки. Это делается путем вызова Office.onReady.
    • Последнее, что вызывает код, это Office.actions.associate , чтобы сообщить Office, какая функция в файле должна быть запущена при вызове пользовательского интерфейса для команды функции. Функция сопоставляет имя функции с идентификатором действия, которое вы настроите в манифесте на следующем шаге. При определении нескольких команд функций в одном файле код должен вызывать 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> пуст, так как файл не имеет пользовательского интерфейса. Его единственное назначение — загрузка файлов JavaScript.

    • Библиотека JavaScript Для Office и файл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. Убедитесь, что объект среды выполнения имеет свойство actions.type со значением executeFunction.

  3. Убедитесь, что массив requirements.capabilities содержит объекты, указывающие все наборы требований , необходимые для поддержки команд надстроек API. Для Outlook минимальное требование для команд надстроек — почтовый ящик 1.3. Но если команда функции вызывает этот API, который входит в более поздний набор обязательных почтовых ящиков , например почтовый ящик 1.5, необходимо указать более позднюю версию (например, "1.5") в качестве значения minVersion.

    Примечание.

    Если поддержка унифицированного манифеста распространяется на другие ведущие приложения Office, минимальным требованием для команд надстроек на этих других узлах будет AddinCommands 1.1.

  4. Убедитесь, что идентификатор объекта среды выполнения имеет описательное имя, например CommandsRuntime.

  5. Убедитесь, что для свойства "code.page" объекта среды выполнения задан URL-адрес HTML-страницы без пользовательского интерфейса, которая загружает файл функции, например "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",
            }
        ]
    }       
]

Настройка пользовательского интерфейса для команды функции

  1. Убедитесь, что объект расширения, для которого настроена среда выполнения, имеет свойство массива ribbons в качестве однорангового узла массива runtimes. Обычно в массиве 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, для которого задан идентификатор вкладки ленты, в которой должна отображаться команда функции, и массив groups с хотя бы одним объектом. Ниже приведен пример.

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

    Примечание.

    Единственное допустимое значение для свойства builtInTabID — TabDefault, которое в Outlook является вкладкой Главная, Сообщение или Собрание . При добавлении поддержки унифицированного манифеста в другие ведущие приложения Office появятся другие возможные значения.

  5. Убедитесь, что массив groups содержит объект для определения настраиваемой группы управления, в которой будут содержаться элементы управления пользовательского интерфейса команд надстройки. Ниже приведен пример. Обратите внимание на следующие сведения об этом JSON:

    • Идентификатор должен быть уникальным для всех групп во всех объектах ленты в манифесте. Максимальная длина: 64 символа.
    • Метка отображается в группе на ленте. Максимальная длина: 64 символа.
    • Один из значков отображается в группе только в том случае, если размер окна приложения Office и, следовательно, ленты был слишком мал для любого элемента управления в группе. Office решает, когда использовать один из этих значков и какой из них следует использовать, в зависимости от размера окна и разрешения устройства. Вы не можете управлять этим. Необходимо предоставить файлы изображений размером 16, 32 и 80 пикселей, в то время как поддерживаются пять других размеров (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. В этом разделе объясняется, как использовать пример с двумя пунктами меню. Один вызывает команду области задач. Другой вызывает команду функции.

Настройка среды выполнения и кода

Выполните действия, описанные в следующих разделах:

Настройка пользовательского интерфейса для меню

  1. Убедитесь, что объект расширения, для которого настроена среда выполнения, имеет свойство массива ribbons в качестве однорангового узла массива runtimes. Обычно в массиве 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, для которого задан идентификатор вкладки ленты, в которой должна отображаться команда области задач, и массив groups с хотя бы одним объектом. Ниже приведен пример.

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

    Примечание.

    Единственное допустимое значение для свойства builtInTabID — TabDefault, которое в Outlook является вкладкой Главная, Сообщение или Собрание . При добавлении поддержки унифицированного манифеста в другие ведущие приложения Office появятся другие возможные значения.

  5. Убедитесь, что массив groups содержит объект для определения настраиваемой группы управления, в которую будет входить элемент управления раскрывающегося меню. Ниже приведен пример. Обратите внимание на следующие сведения об этом JSON:

    • Идентификатор должен быть уникальным для всех групп во всех объектах ленты в манифесте. Максимальная длина: 64 символа.
    • Метка отображается в группе на ленте. Максимальная длина: 64 символа.
    • Один из значков отображается в группе только в том случае, если размер окна приложения Office и, следовательно, ленты был слишком мал для любого элемента управления в группе. Office решает, когда использовать один из этих значков и какой из них следует использовать, в зависимости от размера окна и разрешения устройства. Вы не можете управлять этим. Необходимо предоставить файлы изображений размером 16, 32 и 80 пикселей, в то время как поддерживаются пять других размеров (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" является необязательным для элементов меню, и в этом примере его нет. Если он включен, он имеет те же цели и ограничения, что и свойство icons родительского меню, за исключением того, что значок отображается в пункте меню рядом с меткой.
    • Для свойства 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"
}

Теперь вы завершили добавление меню в надстройку. Загрузка и тестирование неопубликованного приложения.

См. также