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

Статья
08/18/2023

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

Важно!

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

Excel в Windows: версия 2102 (сборка 13801.20632) и более поздние версии
Excel на Mac: 16.48 и более поздних версий
Excel в Интернете

Примечание.

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

SharedRuntime 1.1
Также необходимо, если надстройка позволяет пользователю настраивать сочетания клавиш: KeyboardShortcuts 1.1

Примечание.

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

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

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

Настройка манифеста

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

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

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

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

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

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

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

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

Внутри JSON-файла есть два массива. Массив actions будет содержать объекты, определяющие вызываемые действия, а массив сочетаний клавиш будет содержать объекты, сопоставляющие сочетания ключей с действиями. Пример:
```
{
    "actions": [
        {
            "id": "SHOWTASKPANE",
            "type": "ExecuteFunction",
            "name": "Show task pane for add-in"
        },
        {
            "id": "HIDETASKPANE",
            "type": "ExecuteFunction",
            "name": "Hide task pane for add-in"
        }
    ],
    "shortcuts": [
        {
            "action": "SHOWTASKPANE",
            "key": {
                "default": "Ctrl+Alt+Up"
            }
        },
        {
            "action": "HIDETASKPANE",
            "key": {
                "default": "Ctrl+Alt+Down"
            }
        }
    ]
}
```
Дополнительные сведения об объектах JSON см. в разделах Создание объектов действия и Создание ярлыков объектов. Полная схема для json сочетаний клавиш находится в файле extended-manifest.schema.json.

Примечание.

В этой статье вместо ctrl можно использовать "CONTROL".

На следующем шаге сами действия будут сопоставлены с функциями, которые вы создаете. В этом примере позже вы будете сопоставлять SHOWTASKPANE с функцией, которая вызывает Office.addin.showAsTaskpane метод , а HIDETASKPANE — с функцией, вызывающей Office.addin.hide метод .

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

В проекте откройте файл JavaScript, загруженный html-страницей, в элементе <FunctionFile> .
В файле JavaScript используйте API Office.actions.associate , чтобы сопоставить каждое действие, указанное в JSON-файле, с функцией JavaScript. Добавьте следующий Код JavaScript в файл. Обратите внимание на следующие сведения о коде.
- Первый параметр является одним из действий из JSON-файла.
- Второй параметр — это функция, которая выполняется, когда пользователь нажимает сочетание клавиш, сопоставленное с действием в JSON-файле.
```
Office.actions.associate('-- action ID goes here--', function () {

});
```
Чтобы продолжить пример, используйте 'SHOWTASKPANE' в качестве первого параметра.

В тексте функции используйте метод Office.addin.showAsTaskpane , чтобы открыть область задач надстройки. По завершении код должен выглядеть следующим образом:

Office.actions.associate('SHOWTASKPANE', function () {
    return Office.addin.showAsTaskpane()
        .then(function () {
            return;
        })
        .catch(function (error) {
            return error.code;
        });
});

Добавьте второй вызов Office.actions.associate функции, чтобы сопоставить HIDETASKPANE действие с функцией, которая вызывает Office.addin.hide. Ниже приведен пример.

Office.actions.associate('HIDETASKPANE', function () {
    return Office.addin.hide()
        .then(function () {
            return;
        })
        .catch(function (error) {
            return error.code;
        });
});

Следуя приведенным выше шагам, надстройка переключит видимость области задач, нажав клавиши CTRL+ALT+ВВЕРХ и CTRL+ALT+ВНИЗ. То же самое показано в примере сочетаний клавиш Excel в репозитории Примеры надстроек Office в GitHub.

Сведения и ограничения

Создание объектов действия

При указании объектов в массиве actions shortcuts.json используйте следующие рекомендации.

Имена свойств id и name являются обязательными.
Свойство id используется для уникальной идентификации действия для вызова с помощью сочетания клавиш.
Свойство name должно быть понятной для пользователя строкой, описывающей действие. Это должно быть сочетание символов A – Z, a – z, 0 – 9 и знаков препинания "-", "_" и "+".
Свойство type— необязательное. В настоящее время поддерживается только ExecuteFunction тип.

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

    "actions": [
        {
            "id": "SHOWTASKPANE",
            "type": "ExecuteFunction",
            "name": "Show task pane for add-in"
        },
        {
            "id": "HIDETASKPANE",
            "type": "ExecuteFunction",
            "name": "Hide task pane for add-in"
        }
    ]

Полная схема для json сочетаний клавиш находится в файле extended-manifest.schema.json.

Создание объектов ярлыка

При указании объектов в массиве shortcuts shortcuts.json используйте следующие рекомендации.

Требуются имена actionсвойств , keyи default .
Значение action свойства является строковым и должно соответствовать одному из id свойств объекта действия.
Свойство default может быть любым сочетанием символов A – Z, a - z, 0 – 9 и знаков препинания "-", "_" и "+". (По соглашению строчные буквы не используются в этих свойствах.)
Свойство default должно содержать имя по крайней мере одной клавиши-модификатора (ALT, CTRL, SHIFT) и только одной другой клавиши.
Shift нельзя использовать в качестве единственной клавиши-модификатора. Объедините shift с alt или CTRL.
Для компьютеров Mac также поддерживается клавиша-модификатор Command.
Для компьютеров Mac alt сопоставляется с ключом Option. Для Windows команда сопоставляется с клавишей CTRL.
Если два символа связаны с одной физической клавишей на стандартной клавиатуре, они являются синонимами в default свойстве; например, ALT+a и ALT+A являются одним и тем же сочетанием клавиш, так как сочетание клавиш CTRL+- и CTRL+_, так как "-" и "_" являются одинаковыми физическими клавишами.
Символ "+" указывает, что клавиши по обе стороны от него нажаты одновременно.

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

    "shortcuts": [
        {
            "action": "SHOWTASKPANE",
            "key": {
                "default": "Ctrl+Alt+Up"
            }
        },
        {
            "action": "HIDETASKPANE",
            "key": {
                "default": "Ctrl+Alt+Down"
            }
        }
    ]

Полная схема для json сочетаний клавиш находится в файле extended-manifest.schema.json.

Примечание.

Подсказки клавиш, также известные как сочетания последовательных клавиш, например сочетание клавиш Excel для выбора цвета заливки ALT+H, H, не поддерживаются в надстройках Office.

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

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

В случае конфликта пользователь увидит диалоговое окно при первой попытке использовать конфликтующее сочетание клавиш. Обратите внимание, что текст для параметра надстройки, отображаемого в этом диалоговом окне, поступает из name свойства в объекте действия в shortcuts.json файле.

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

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

Поле поиска Подскажите мне в Excel, в котором отображается действие сброса параметров сочетания параметров надстройки Office.

Для оптимального взаимодействия с пользователем рекомендуется свести к минимуму конфликты с Excel с помощью этих рекомендаций.

Используйте только сочетания клавиш в следующем формате: CTRL+SHIFT+ALT+x, где x — это другая клавиша.
Если вам нужно больше сочетаний клавиш, проверка список сочетаний клавиш Excel и не используйте их в надстройке.
Если фокус клавиатуры находится внутри пользовательского интерфейса надстройки, клавиши CTRL+ПРОБЕЛ и CTRL+SHIFT+F10 не будут работать, так как это важные сочетания специальных возможностей.
Если на компьютере с Windows или Mac команда "Сброс настроек сочетания надстроек Office" недоступна в меню поиска, пользователь может вручную добавить команду на ленту, настроив ленту с помощью контекстного меню.

Настройка сочетаний клавиш для каждой платформы

Ярлыки можно настроить для конкретной платформы. Ниже приведен пример shortcuts объекта, который настраивает сочетания клавиш для каждой из следующих платформ: windows, mac, web. Обратите внимание, что для каждого сочетания клавиш по-прежнему default требуется сочетание клавиш.

В следующем примере default ключ является резервным ключом для любой платформы, которая не указана. Единственная платформа не указана — Windows, поэтому default ключ будет применяться только к Windows.

    "shortcuts": [
        {
            "action": "SHOWTASKPANE",
            "key": {
                "default": "Ctrl+Alt+Up",
                "mac": "Command+Shift+Up",
                "web": "Ctrl+Alt+1",
            }
        },
        {
            "action": "HIDETASKPANE",
            "key": {
                "default": "Ctrl+Alt+Down",
                "mac": "Command+Shift+Down",
                "web": "Ctrl+Alt+2"
            }
        }
    ]

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

Если надстройка поддерживает несколько языковых стандартов, необходимо локализовать name свойство объектов действия. Кроме того, если какой-либо из языковых стандартов, поддерживаемых надстройкой, имеет разные алфавиты или системы письма и, следовательно, разные клавиатуры, вам также может потребоваться локализовать сочетания клавиш. Сведения о локализации сочетаний клавиш JSON см. в статье Локализация расширенных переопределений.

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

При использовании пользовательских сочетаний клавиш в Интернете некоторые сочетания клавиш, используемые браузером, не могут быть переопределены надстройками. Этот список выполняется. Если вы обнаружите другие сочетания, которые не могут быть переопределены, сообщите нам с помощью средства обратной связи в нижней части этой страницы.

CTRL+N
CTRL+SHIFT+N
CTRL+T
CTRL+SHIFT+T
CTRL+W
CTRL+PgUp/PgDn

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

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

Примечание.

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

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

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

const userCustomShortcuts = {
    SHOWTASKPANE:"CTRL+SHIFT+1", 
    HIDETASKPANE:"CTRL+SHIFT+2"
};
Office.actions.replaceShortcuts(userCustomShortcuts)
    .then(function () {
        console.log("Successfully registered.");
    })
    .catch(function (ex) {
        if (ex.code == "InvalidOperation") {
            console.log("ActionId does not exist or shortcut combination is invalid.");
        }
    });

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

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

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

Office.actions.getShortcuts()
    .then(function (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(function (inUseArray) {
        const availableShortcuts = inUseArray.filter(function (shortcut) { return !shortcut.inUse; });
        console.log(availableShortcuts);
        const usedShortcuts = inUseArray.filter(function (shortcut) { return shortcut.inUse; });
        console.log(usedShortcuts);
    });

Дальнейшие действия

См. пример надстройки сочетаний клавиш Excel .
Общие сведения о работе с расширенными переопределениями см . в статье Работа с расширенными переопределениями манифеста.

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

Настройка манифеста

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

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

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

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

Сведения и ограничения

Создание объектов действия

Создание объектов ярлыка

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

Настройка сочетаний клавиш для каждой платформы

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

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

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

Дальнейшие действия

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

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