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

2025-05-19

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

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

Примечание.

Унифицированный манифест для Microsoft 365 можно использовать в рабочих надстройках Outlook. Он доступен только в качестве предварительной версии для надстроек Excel, PowerPoint и Word.

Совет

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

Примечание.

Сведения о клиентах и платформах, которые непосредственно поддерживают надстройки Office, использующие единый манифест для Microsoft 365, см. в статье Надстройки Office с манифестом унифицированного приложения для Microsoft 365.

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

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

Два решения

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

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

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

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

Откройте унифицированный манифест и найдите "extensions.runtimes" массив.
Убедитесь, что имеется объект среды выполнения со свойством "actions.type" со значением "openPage". Этот тип среды выполнения открывает область задач.
Убедитесь, что "requirements.capabilities" массив содержит объект, указывающий набор требований , поддерживающий команды надстройки. Для Outlook минимальными требованиями к командам надстройки является Почтовый ящик 1.3. Для других ведущих приложений Office минимальное требование для команд надстроек — AddinCommands 1.1.
Убедитесь, что "id" объект среды выполнения имеет описательное имя, "TaskPaneRuntime"например .
Убедитесь, что для "code.page" свойства объекта среды выполнения задан URL-адрес страницы, которая должна открыться в области задач, например "https://localhost:3000/taskpane.html".
Убедитесь, что "actions.view" объект среды выполнения имеет имя, описывающее содержимое страницы, заданной на предыдущем шаге, например "homepage" или "dashboard".
Убедитесь, что "actions.id" объект среды выполнения имеет описательное имя, например "ShowTaskPane" , которое указывает, что происходит, когда пользователь нажимает кнопку или пункт меню команды надстройки.

Задайте другие свойства и вложенные свойства объекта среды выполнения, как показано в следующем примере объекта среды выполнения. Свойства "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"
            }
        ]
    }
]

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

Убедитесь, что объект расширения, для которого настроена среда выполнения, "ribbons" имеет свойство массива в качестве однорангового узла массива "runtimes" . Обычно в "extensions" массиве есть только один объект расширения.
Убедитесь, что массив содержит объект со свойствами массива с именами "contexts" и "tabs", как показано в следующем примере.
```
"ribbons": [
    {
        "contexts": [
            // child objects omitted
        ],
        "tabs": [
            // child objects omitted
        ]
    }
]
```
Убедитесь, что "contexts" массив содержит строки, указывающие окна или области, в которых должен отображаться пользовательский интерфейс для команды области задач. Например, означает, "mailRead" что оно будет отображаться в области чтения или окне сообщения при открытии сообщения электронной почты, но "mailCompose" означает, что оно появится при создании нового сообщения или ответа. Ниже приведены допустимые значения.
- "mailRead"
- "mailCompose"
- "meetingDetailsOrganizer"
- "meetingDetailsAttendee"
Ниже приведен пример.
```
"contexts": [
    "mailRead"
],
```
Убедитесь, что массив "tabs" содержит объект со строковым свойством "builtInTabId" , для которого задан идентификатор вкладки ленты, на которой должна отображаться команда области задач. Кроме того, убедитесь, что имеется "groups" массив с хотя бы одним объектом. Ниже приведен пример.
```
"tabs": [
    {
        "builtInTabID": "TabDefault",
        "groups": [
            {
                // properties omitted
            }
        ]
    }
]
```
Примечание.

Список возможных значений свойства см. в "builtInTabID" разделе Поиск идентификаторов встроенных вкладок ленты Office.
Убедитесь, что массив "groups" содержит объект для определения настраиваемой группы элементов управления, в которой будут содержаться элементы управления пользовательского интерфейса команд надстройки. Ниже приведен пример. Обратите внимание на следующие сведения об этом JSON:
- Объект "id" должен быть уникальным для всех групп во всех объектах ленты в манифесте. Максимальная длина: 64 символа.
- Отображается "label" в группе на ленте. Хотя его максимальная длина составляет 64 символа, для правильного размещения группы элементов управления на ленте рекомендуется ограничить "label" до 16 символов.
- Один из "icons" отображается в группе только в том случае, если окно приложения 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
            }
        ]
    }
]
```
Убедитесь, что в массиве "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"
}
```

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

Добавление команды функции

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

Создание кода для команды функции

Убедитесь, что исходный код содержит файл 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);
```
Убедитесь, что исходный код содержит 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" />

        
        <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
        
        <script src="commands.js" type="text/javascript"></script>
    </head>
    <body>
    </body>
</html>
```

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

Откройте унифицированный манифест и найдите "extensions.runtimes" массив.
Убедитесь, что имеется объект среды выполнения со свойством "actions.type" со значением "executeFunction".
Убедитесь, что "requirements.capabilities" массив содержит объекты, указывающие все наборы требований , необходимые для поддержки команд надстроек API. Для Outlook минимальное требование для команд надстроек — почтовый ящик 1.3. Но если команда функции вызывает этот API, который входит в более поздний набор обязательных почтовых ящиков , например Почтовый ящик 1.5, необходимо указать в качестве "minVersion" значения более позднюю версию (например, "1.5"). Для других ведущих приложений Office минимальное требование для команд надстроек — AddinCommands 1.1.
Убедитесь, что "id" объект среды выполнения имеет описательное имя, например CommandsRuntime.
Убедитесь, что для "code.page" свойства объекта среды выполнения задан URL-адрес HTML-страницы без пользовательского интерфейса, которая загружает файл функции, например "https://localhost:3000/commands.html".
Убедитесь, что "actions.id" объект среды выполнения имеет описательное имя, например SetNotification, которое указывает, что происходит, когда пользователь нажимает кнопку или пункт меню надстройки.

Важно!

Значение "actions.id" должно точно соответствовать первому параметру вызова в Office.actions.associate файле функции.

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

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

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

Убедитесь, что объект расширения, для которого настроена среда выполнения, "ribbons" имеет свойство массива в качестве однорангового узла массива "runtimes" . Обычно в "extensions" массиве есть только один объект расширения.
Убедитесь, что массив содержит объект со свойствами массива с именами "contexts" и "tabs", как показано в следующем примере.
```
"ribbons": [
    {
        "contexts": [
            // child objects omitted
        ],
        "tabs": [
            // child objects omitted
        ]
    }
]
```
Убедитесь, что "contexts" массив содержит строки, указывающие окна или области, в которых должен отображаться пользовательский интерфейс для команды функции. Например, означает, "mailRead" что оно будет отображаться в области чтения или окне сообщения при открытии сообщения электронной почты, но "mailCompose" означает, что оно появится при создании нового сообщения или ответа. Ниже приведены допустимые значения.
- "mailRead"
- "mailCompose"
- "meetingDetailsOrganizer"
- "meetingDetailsAttendee"
Ниже приведен пример.
```
"contexts": [
    "mailRead"
],
```
Убедитесь, что "tabs" массив содержит объект со строковым свойством "builtInTabId" , для которого задан идентификатор вкладки ленты, на которой должна отображаться команда функции, и "groups" массив с хотя бы одним объектом. Ниже приведен пример.
```
"tabs": [
    {
        "builtInTabID": "TabDefault",
        "groups": [
            {
                // properties omitted
            }
        ]
    }
]
```
Примечание.

Список возможных значений свойства см. в "builtInTabID" разделе Поиск идентификаторов встроенных вкладок ленты Office.
Убедитесь, что массив "groups" содержит объект для определения настраиваемой группы элементов управления, в которой будут содержаться элементы управления пользовательского интерфейса команд надстройки. Ниже приведен пример. Обратите внимание на следующие сведения об этом JSON:
- Объект "id" должен быть уникальным для всех групп во всех объектах ленты в манифесте. Максимальная длина: 64 символа.
- Отображается "label" в группе на ленте. Хотя его максимальная длина составляет 64 символа, для правильного размещения группы элементов управления на ленте рекомендуется ограничить "label" до 16 символов.
- Один из "icons" отображается в группе только в том случае, если окно приложения 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
            }
        ]
    }
]
```
Убедитесь, что в массиве "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. В этом разделе объясняется, как использовать пример с двумя пунктами меню. Один вызывает команду области задач. Другой вызывает команду функции.

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

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

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

Убедитесь, что объект расширения, для которого настроена среда выполнения, "ribbons" имеет свойство массива в качестве однорангового узла массива "runtimes" . Обычно в "extensions" массиве есть только один объект расширения.
Убедитесь, что массив содержит объект со свойствами массива с именами "contexts" и "tabs", как показано в следующем примере.
```
"ribbons": [
    {
        "contexts": [
            // child objects omitted
        ],
        "tabs": [
            // child objects omitted
        ]
    }
]
```
Убедитесь, что "contexts" массив содержит строки, указывающие окна или области, в которых меню должно отображаться на ленте. Например, означает, "mailRead" что оно будет отображаться в области чтения или окне сообщения при открытии сообщения электронной почты, но "mailCompose" означает, что оно появится при создании нового сообщения или ответа. Ниже приведены допустимые значения.
- "mailRead"
- "mailCompose"
- "meetingDetailsOrganizer"
- "meetingDetailsAttendee"
Ниже приведен пример.
```
"contexts": [
    "mailRead"
],
```
Убедитесь, что "tabs" массив содержит объект со строковым свойством "builtInTabId" , для которого задан идентификатор вкладки ленты, на которой должна отображаться команда области задач, и "groups" массив с хотя бы одним объектом. Ниже приведен пример.
```
"tabs": [
    {
        "builtInTabID": "TabDefault",
        "groups": [
            {
                // properties omitted
            }
        ]
    }
]
```
Примечание.

Список возможных значений свойства см. в "builtInTabID" разделе Поиск идентификаторов встроенных вкладок ленты Office.
Убедитесь, что массив "groups" содержит объект для определения настраиваемой группы элементов управления, в которую будет входить элемент управления раскрывающимся меню. Ниже приведен пример. Обратите внимание на следующие сведения об этом JSON:
- Объект "id" должен быть уникальным для всех групп во всех объектах ленты в манифесте. Максимальная длина: 64 символа.
- Отображается "label" в группе на ленте. Хотя его максимальная длина составляет 64 символа, для правильного размещения группы элементов управления на ленте рекомендуется ограничить "label" до 16 символов.
- Один из "icons" отображается в группе только в том случае, если окно приложения 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
            }
        ]
    }
]
```
Убедитесь, что в "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": ""
        }
    ]
}
```
Первый элемент отображает область задач. Ниже приведен пример. Обратите внимание на следующие особенности этого кода:
- Свойства "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"
},
```
Второй элемент выполняет команду функции. Ниже приведен пример. Обратите внимание на следующие особенности этого кода:
- Объект "actionId" должен точно соответствовать объекту , заданному "runtimes.actions.id" в разделе Настройка среды выполнения для команды функции.
```
{
    "id": "msgReadSetNotificationMenuItem",
    "type": "menuItem",
    "label": "Set Notification",
    "supertip": {
        "title": "Set Notification",
        "description": "Displays a notification message on the current message."
    },
    "actionId": "SetNotification"
}
```

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

Поделиться через

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

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

Два решения

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

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

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

Добавление команды функции

Создание кода для команды функции

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

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

Меню и пункты меню

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

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

См. также

Обратная связь

Дополнительные ресурсы