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

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

  • Статья

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

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

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

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

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

  • Office в Интернете
  • 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 . Когда вы будете готовы добавлять сочетания клавиш в собственную надстройку, перейдите к этой статье.

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

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

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

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

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

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

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

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

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

  2. Добавьте в файл следующую разметку. Обратите внимание на следующие сведения о коде.

    • Массив 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"
            }
        }
    ]
}

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

  1. В проекте откройте файл JavaScript, загруженный html-страницей, в элементе <FunctionFile> .

  2. В файле JavaScript используйте API Office.actions.associate , чтобы сопоставить каждое действие, указанное в JSON-файле, с функцией JavaScript. Добавьте следующий Код JavaScript в файл. Обратите внимание на следующие сведения о коде.

    • Первый параметр является одним из действий из JSON-файла.
    • Второй параметр — это функция, которая выполняется, когда пользователь нажимает сочетание клавиш, сопоставленное с действием в 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;
        });
});

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

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

  • Сочетание клавиш должно включать по крайней мере одну клавишу-модификатор (ALT/OPTION, CTRL/COMMAND, SHIFT) и только одну другую клавишу. Эти ключи должны быть соединены с символом + .
  • Клавиша-модификатор command поддерживается на платформе macOS.
  • В macOS клавиша ALT сопоставляется с клавишей Option. В Windows клавиша Command сопоставляется с клавишей CTRL.
  • Клавишу SHIFT нельзя использовать в качестве единственной клавиши-модификатора. Его необходимо сочетать с ALT/OPTION или CTRL/COMMAND.
  • Сочетания клавиш могут включать символы "A-Z", "a-z", "0-9", а также знаки препинания "-", "_" и "+". По соглашению строчные буквы не используются в сочетаниях клавиш.
  • Если два символа связаны с одной физической клавишей на стандартной клавиатуре, они являются синонимами в пользовательском сочетании клавиш. Например, ALT+a и ALT+A являются одним и тем же сочетанием клавиш, а также ctrl+- и CTRL+_ ("-" и "_" связаны с одной физической клавишей).

Примечание.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Сведения о локализации сочетаний клавиш JSON см. в статье Локализация расширенных переопределений.

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

Примечание.

Для 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 , возвращаемым значением будет настроенная комбинация клавиатуры.
  • Если ярлык не переопределен или настроен, он вернет значение из 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((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);
}
...

См. также