Добавление настраиваемых сочетаний клавиш в надстройки Office

Статья
02/14/2025

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

Добавить сочетания клавиш в надстройку можно тремя шагами.

Настройте манифест надстройки для использования общей среды выполнения.
Определите пользовательские сочетания клавиш и выполняемые ими действия.
Сопоставлять пользовательские действия с их функциями с помощью API Office.actions.associate .

Предварительные условия

В настоящее время сочетания клавиш поддерживаются только на следующих платформах и сборках Excel и Word.

Office в Интернете

Примечание.

Функция сочетания клавиш в настоящее время развертывается для Word в Интернете. Если вы протестируете эту функцию в Word в Интернете в настоящее время, сочетания клавиш могут не работать, если они активируются в области задач надстройки. Мы рекомендуем периодически проверка наборы обязательных наборов сочетаний клавиш, чтобы узнать, когда функция полностью поддерживается.
Office для Windows
- Excel: версия 2102 (сборка 13801.20632) и более поздние версии
- Word: версия 2408 (сборка 17928.20114) и более поздние версии
Office для Mac
- Excel: версия 16.55 (21111400) и более поздние версии
- Word: версия 16.88 (24081116) и более поздние версии

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

SharedRuntime 1.1
KeyboardShortcuts 1.1 (требуется, если надстройка предоставляет пользователям возможность настройки сочетаний клавиш)

Совет

Чтобы начать с рабочей версии надстройки с уже настроенными сочетаниями клавиш, клонируйте и запустите пример Использование сочетаний клавиш для надстроек Office . Когда вы будете готовы добавлять сочетания клавиш в собственную надстройку, перейдите к этой статье.

Определение пользовательских сочетаний клавиш

Процесс определения настраиваемых сочетаний клавиш для надстройки зависит от типа манифеста, используемого надстройкой. Выберите вкладку для типа манифеста, который вы используете.

Совет

Дополнительные сведения о манифестах надстроек Office см. в разделе Манифест надстроек Office.

Манифест единого приложения для Microsoft 365
Манифест только надстройки

Примечание.

Реализация сочетаний клавиш в манифесте унифицированного приложения для Microsoft 365 доступна в общедоступной предварительной версии для разработчиков. Его не следует использовать в рабочих надстройках. Мы приглашаем вас опробовать его в средах тестирования или разработки. Дополнительные сведения см. в статье Схема манифеста общедоступной предварительной версии приложения для разработчиков.

Если надстройка использует манифест унифицированного приложения для Microsoft 365, в манифесте определяются пользовательские сочетания клавиш и их действия.

В проекте надстройки откройте файл manifest.json .
Добавьте следующий объект в массив extensions.runtimes. Обратите внимание на следующие особенности этой разметки.
- Объекты actions указывают функции, которые может выполнять надстройка. В следующем примере надстройка сможет отображать и скрывать область задач. Эти функции будут созданы в следующем разделе. В настоящее время пользовательские сочетания клавиш могут выполнять только действия типа "executeFunction".
- Хотя свойство actions.displayName является необязательным, оно обязательно, если для действия будет создано пользовательское сочетание клавиш. Это свойство используется для описания действия сочетания клавиш. Предоставленное вами описание отображается в диалоговом окне, которое отображается пользователю при конфликте сочетаний клавиш между несколькими надстройками или с Microsoft 365. Office добавляет имя надстройки в круглые скобки в конце описания. Дополнительные сведения о том, как обрабатываются конфликты с сочетаниями клавиш, см. в статье Предотвращение использования сочетаний клавиш другими надстройками.
```
"runtimes": [
    {
        "id": "TaskPaneRuntime",
        "type": "general",
        "code": {
            "page": "https://localhost:3000/taskpane.html"
        },
        "lifetime": "long",
        "actions": [
            {
                "id": "ShowTaskpane",
                "type": "executeFunction",
                "displayName": "Show task pane (Contoso Add-in)"
            },
            {
                "id": "HideTaskpane",
                "type": "executeFunction",
                "displayName": "Hide task pane (Contoso Add-in)"
            }
        ],
    }
]
```
Добавьте следующий код в массив extensions. Обратите внимание на следующее о разметке.
- Набор обязательных элементов SharedRuntime 1.1 указан в объекте requirements.capabilities для поддержки пользовательских сочетаний клавиш.
- Каждый объект сочетаний клавиш представляет собой одно действие, вызываемое сочетанием клавиш. Он задает поддерживаемые сочетания ключей для различных платформ, таких как Office в Интернете, в Windows и Mac. Инструкции по созданию пользовательских сочетаний ключей см. в статье Руководство по пользовательским сочетаниям ключей.
- Необходимо указать сочетание ключей по умолчанию. Он используется на всех поддерживаемых платформах, если для определенной платформы не настроено определенное сочетание.
- Значение свойства actionId должно соответствовать значению, указанному в свойстве id применимого объекта extensions.runtimes.actions.
```
"keyboardShortcuts": [
    {
        "requirements": {
            "capabilities": [
                {
                    "name": "SharedRuntime",
                    "minVersion": "1.1"
                }
            ]
        },
        "shortcuts": [
            {
                "key": {
                    "default": "Ctrl+Alt+Up",
                    "mac": "Command+Shift+Up",
                    "web": "Ctrl+Alt+1",
                    "windows": "Ctrl+Alt+Up"
                },
                "actionId": "ShowTaskpane"
            },
            {
                "key": {
                    "default": "Ctrl+Alt+Down",
                    "mac": "Command+Shift+Down",
                    "web": "Ctrl+Alt+2",
                    "windows": "Ctrl+Alt+Up"
                },
                "actionId": "HideTaskpane"
            }
        ]
    }
]
```

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

Чтобы настроить сочетания клавиш для надстройки, сначала необходимо настроить манифест надстройки для использования общей среды выполнения. Инструкции по настройке надстройки для использования общей среды выполнения см. в статье Настройка надстройки для использования общей среды выполнения.

Создание или изменение JSON-файла сочетаний клавиш

Если надстройка использует только манифест надстройки, пользовательские сочетания клавиш определяются в JSON-файле. В этом файле описываются сочетания клавиш и действия, которые они будут вызывать. Полная схема json-файла находится на extended-manifest.schema.json.

В проекте надстройки создайте JSON-файл.
Добавьте в файл следующую разметку. Обратите внимание на следующие сведения о коде.
- Массив actions содержит объекты, определяющие вызываемые действия. Требуются свойства "actions.id" и "actions.name".
- Свойство "actions.id" однозначно идентифицирует действие для вызова с помощью сочетания клавиш.
- Свойство "actions.name" должно описывать действие сочетания клавиш. Предоставленное вами описание отображается в диалоговом окне, которое отображается пользователю при конфликте сочетаний клавиш между несколькими надстройками или с Microsoft 365. Office добавляет имя надстройки в круглые скобки в конце описания. Дополнительные сведения о том, как обрабатываются конфликты с сочетаниями клавиш, см. в статье Предотвращение использования сочетаний клавиш другими надстройками.
- Свойство type является необязательным. В настоящее время поддерживается только тип ExecuteFunction.
- Указанные действия будут сопоставлены с функциями, которые вы создадите на следующем шаге. В этом примере вы позже сопоставите ShowTaskpane с функцией, которая вызывает Office.addin.showAsTaskpane метод, и HideTaskpane с функцией, которая вызывает Office.addin.hide метод .
- Массив ярлыков содержит объекты, которые сопоставляют сочетания клавиш с действиями. Требуются свойства "ярлыки.action", "shortcuts.key" и "shortcuts.key.default".
- Значение свойства "shortcuts.action" должно соответствовать свойству "actions.id" применимого объекта действия.
- Ярлыки можно настроить для конкретной платформы. В этом примере объект "ярлыки" настраивает ярлыки для каждой из следующих платформ: "windows", "mac" и "web". Необходимо определить сочетание клавиш по умолчанию для каждого сочетания клавиш. Он используется в качестве резервного ключа, если сочетание ключей не указано для определенной платформы.
Совет

Инструкции по созданию пользовательских сочетаний ключей см. в статье Руководство по пользовательским сочетаниям ключей.
```
{
    "actions": [
        {
            "id": "ShowTaskpane",
            "type": "ExecuteFunction",
            "name": "Show task pane"
        },
        {
            "id": "HideTaskpane",
            "type": "ExecuteFunction",
            "name": "Hide task pane"
        }
    ],
    "shortcuts": [
        {
            "action": "ShowTaskpane",
            "key": {
                "default": "Ctrl+Alt+Up",
                "mac": "Command+Shift+Up",
                "web": "Ctrl+Alt+1",
                "windows": "Ctrl+Alt+Up"
            }
        },
        {
            "action": "HideTaskpane",
            "key": {
                "default": "Ctrl+Alt+Down",
                "mac": "Command+Shift+Down",
                "web": "Ctrl+Alt+2",
                "windows": "Ctrl+Alt+Up"
            }
        }
    ]
}
```

Связывание файла сопоставления с манифестом

В проекте надстройки откройте файлmanifest.xml .
Непосредственно под элементом <VersionOverrides> (не внутри) в манифесте добавьте элемент ExtendedOverrides . Задайте для атрибута Url полный URL-адрес JSON-файла, созданного на предыдущем шаге.

    ...
    </VersionOverrides>
    <ExtendedOverrides Url="https://contoso.com/addin/shortcuts.json"></ExtendedOverrides>
</OfficeApp>

Сопоставление пользовательских действий с их функциями

В проекте откройте файл JavaScript, загруженный html-страницей, в элементе <FunctionFile> .
В файле JavaScript используйте API Office.actions.associate , чтобы сопоставить каждое действие, указанное на предыдущем шаге, с функцией JavaScript. Добавьте следующий Код JavaScript в файл. Обратите внимание на следующие сведения о коде.
- Первый параметр — это имя действия, сопоставленного с сочетанием клавиш. Расположение имени действия зависит от типа манифеста, используемого надстройкой.
  - Манифест единого приложения для Microsoft 365: значение свойства extensions.keyboardShortcuts.shortcuts.actionId в файле manifest.json .
  - Манифест только надстройки. Значение свойства "actions.id" в JSON-файле ярлыков.
- Второй параметр — это функция, которая выполняется, когда пользователь нажимает сочетание клавиш, сопоставленное с действием.
```
Office.actions.associate("ShowTaskpane", () => {
    return Office.addin.showAsTaskpane()
        .then(() => {
            return;
        })
        .catch((error) => {
            return error.code;
        });
});
```
```
Office.actions.associate("HideTaskpane", () => {
    return Office.addin.hide()
        .then(() => {
            return;
        })
        .catch((error) => {
            return error.code;
        });
});
```

Локализация описания сочетания клавиш

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

Надстройка поддерживает несколько языковых стандартов.
Надстройка поддерживает различные алфавиты, системы письма или раскладки клавиатуры.

Рекомендации по локализации сочетаний клавиш зависят от типа манифеста, используемого надстройкой.

Манифест единого приложения для Microsoft 365
Манифест только надстройки

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

ResourceUrl Используйте атрибут элемента ExtendedOverrides, чтобы указать Microsoft 365 на файл локализованных ресурсов. Ниже приведен пример.

    ...
    </VersionOverrides>  
    <ExtendedOverrides Url="https://contoso.com/addin/extended-overrides.json" 
                       ResourceUrl="https://contoso.com/addin/my-resources.json">
    </ExtendedOverrides>
</OfficeApp>

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

Пример не совсем допустим. (Мы добавим к нему дополнительное свойство на следующем шаге.)
Маркеры должны иметь формат ${resource.name-of-resource}.

{
    "actions": [
        {
            "id": "ShowTaskpane",
            "type": "ExecuteFunction",
            "name": "${resource.ShowTaskpane_action_name}"
        }
    ],
    "shortcuts": [
        {
            "action": "ShowTaskpane",
            "key": {
                "default": "${resource.ShowTaskpane_default_shortcut}"
            }
        }
    ] 
}

Файл ресурсов, который также имеет формат JSON, имеет свойство верхнего уровня resources , разделенное на вложенные свойства по языковому стандарту. Для каждого языкового стандарта каждому маркеру, который использовался в файле расширенных переопределений, назначается строка. Ниже приведен пример со строками для en-us и fr-fr. В этом примере сочетание клавиш одинаково в обоих языковых стандартах, но это не всегда так, особенно при локализации языковых стандартов с другим алфавитом или системой записи и, следовательно, другой клавиатурой.

{
    "resources":{ 
        "en-us": { 
            "ShowTaskpane_default_shortcut": { 
                "value": "CTRL+SHIFT+A", 
            }, 
            "ShowTaskpane_action_name": {
                "value": "Show task pane for add-in",
            }, 
        },
        "fr-fr": { 
            "ShowTaskpane_default_shortcut": { 
                "value": "CTRL+SHIFT+A", 
            }, 
            "ShowTaskpane_action_name": {
                "value": "Afficher le volet de tâche pour add-in",
              } 
        }
    }
}

В файле нет default свойства, который является одноранговым en-us элементом для разделов и fr-fr . Это связано с тем, что строки по умолчанию, которые используются, когда языковой стандарт ведущего приложения Microsoft 365 не соответствует ни одному из свойств ll-cc в файле ресурсов, должны быть определены в самом файле расширенных переопределений. Определение строк по умолчанию непосредственно в файле расширенных переопределений гарантирует, что Microsoft 365 не скачивает файл ресурсов, если языковой стандарт приложения Microsoft 365 соответствует языковому стандарту надстройки по умолчанию (как указано в манифесте). Ниже приведена исправленная версия предыдущего примера файла расширенных переопределений, использующего маркеры ресурсов.

{
    "actions": [
        {
            "id": "ShowTaskpane",
            "type": "ExecuteFunction",
            "name": "${resource.ShowTaskpane_action_name}"
        }
    ],
    "shortcuts": [
        {
            "action": "ShowTaskpane",
            "key": {
                "default": "${resource.ShowTaskpane_default_shortcut}"
            }
        }
    ],
    "resources": { 
        "default": { 
            "ShowTaskpane_default_shortcut": { 
                "value": "CTRL+SHIFT+A", 
            }, 
            "ShowTaskpane_action_name": {
                "value": "Show task pane for add-in",
            } 
        }
    }
}

Включение настройки ярлыка для определенных пользователей

Примечание.

Для API, описанных в этом разделе, требуется набор обязательных элементов KeyboardShortcuts 1.1 .

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

Используйте метод Office.actions.replaceShortcuts , чтобы назначить пользовательские сочетания клавиатуры действиям надстроек. Метод принимает параметр типа {[actionId:string]: string|null}, где actionIds — это подмножество идентификаторов действий, которые должны быть определены в json расширенного манифеста надстройки. Значения — это предпочтительная комбинация ключей пользователя. Значение также может быть null, что приведет к удалению любой настройки для этого actionId и отменить изменения указанной комбинации клавиатуры по умолчанию.

Если пользователь вошел в Microsoft 365, пользовательские сочетания сохраняются в параметрах перемещения пользователя для каждой платформы. Настройка ярлыков в настоящее время не поддерживается для анонимных пользователей.

const userCustomShortcuts = {
    ShowTaskpane: "Ctrl+Shift+1",
    HideTaskpane: "Ctrl+Shift+2"
};

Office.actions.replaceShortcuts(userCustomShortcuts)
    .then(() => {
        console.log("Successfully registered shortcut.");
    })
    .catch((error) => {
        if (error.code == "InvalidOperation") {
            console.log("ActionId doesn't exist or shortcut combination is invalid.");
        }
    });

Чтобы узнать, какие сочетания клавиш уже используются для пользователя, вызовите метод Office.actions.getShortcuts . Этот метод возвращает объект типа [actionId:string]:string|null}, где значения представляют текущую комбинацию клавиатуры, которую пользователь должен использовать для вызова указанного действия. Значения могут поступать из трех разных источников.

Если произошел конфликт с сочетанием клавиш и пользователь решил использовать другое действие (собственное действие или другую надстройку) для этой комбинации клавиатуры, возвращаемое значение будет null иметь значение , так как сочетание клавиш переопределено и пользователь не может использовать для вызова этого действия надстройки.
Если сочетание клавиш было настроено с помощью метода Office.actions.replaceShortcuts , возвращаемым значением будет настроенная комбинация клавиатуры.
Если ярлык не переопределен или настроен, возвращаемое значение зависит от типа манифеста, используемого надстройкой.
- Манифест единого приложения для Microsoft 365: ярлык, указанный в файле manifest.json надстройки.
- Только манифест надстройки: ярлык, указанный в JSON-файле ярлыков надстройки.

Ниже приведен пример.

Office.actions.getShortcuts()
    .then((userShortcuts) => {
       for (const action in userShortcuts) {
           let shortcut = userShortcuts[action];
           console.log(action + ": " + shortcut);
       }
    });

Как описано в разделе Избегайте сочетаний клавиш, используемых другими надстройками, рекомендуется избегать конфликтов в сочетаниях клавиш. Чтобы узнать, используется ли одно или несколько сочетаний ключей, передайте их в виде массива строк в метод Office.actions.areShortcutsInUse . Метод возвращает отчет, содержащий сочетания ключей, которые уже используются в виде массива объектов типа {shortcut: string, inUse: boolean}. Свойство shortcut представляет собой сочетание клавиш, например CTRL+SHIFT+1. Если сочетание уже зарегистрировано в другом действии, свойству inUse присваивается значение true. Например, [{shortcut: "Ctrl+Shift+1", inUse: true}, {shortcut: "Ctrl+Shift+2", inUse: false}]. Примером является следующий фрагмент кода.

const shortcuts = ["Ctrl+Shift+1", "Ctrl+Shift+2"];
Office.actions.areShortcutsInUse(shortcuts)
    .then((inUseArray) => {
        const availableShortcuts = inUseArray.filter((shortcut) => {
            return !shortcut.inUse;
        });
        console.log(availableShortcuts);
        const usedShortcuts = inUseArray.filter((shortcut) => {
            return shortcut.inUse;
        });
        console.log(usedShortcuts);
    });

Реализация пользовательских сочетаний клавиш в поддерживаемых приложениях Microsoft 365

Вы можете реализовать пользовательское сочетание клавиш для использования в поддерживаемых приложениях Microsoft 365, таких как Excel и Word. Если реализация для выполнения одной и той же задачи в каждом приложении отличается, необходимо использовать Office.actions.associate метод для вызова разных функций обратного вызова для каждого приложения. Ниже приведен код в качестве примера.

const host = Office.context.host;
if (host === Office.HostType.Excel) {
    Office.actions.associate("ChangeFormat", changeFormatExcel);
} else if (host === Office.HostType.Word) {
    Office.actions.associate("ChangeFormat", changeFormatWord);
}
...

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

Добавление настраиваемых сочетаний клавиш в надстройки Office

Предварительные условия

Определение пользовательских сочетаний клавиш

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

Создание или изменение JSON-файла сочетаний клавиш

Связывание файла сопоставления с манифестом

Сопоставление пользовательских действий с их функциями

Рекомендации по пользовательским сочетаниям ключей

Сочетания клавиш браузера, которые не могут быть переопределены

Избегайте сочетаний клавиш, используемых другими надстройками

Локализация описания сочетания клавиш

Включение настройки ярлыка для определенных пользователей

Реализация пользовательских сочетаний клавиш в поддерживаемых приложениях Microsoft 365

См. также

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