Agregar métodos abreviados de teclado personalizados a los complementos de Office

Los métodos abreviados de teclado, también conocidos como combinaciones de teclas, permiten que los usuarios del complemento funcionen de forma más eficaz. Los métodos abreviados de teclado también mejoran la accesibilidad del complemento para los usuarios con discapacidades al proporcionar una alternativa al mouse.

Hay tres pasos para agregar métodos abreviados de teclado a un complemento.

1. Configure el manifiesto del complemento.
2. Cree o edite el archivo JSON de accesos directos para definir acciones y sus métodos abreviados de teclado.
3. Asigne acciones personalizadas a sus funciones mediante la API Office.actions.associate .

Requisitos previos

Actualmente, los métodos abreviados de teclado solo se admiten en las siguientes plataformas y en la compilación de Excel y Word.

• Office en la web
• Office en Windows
  • Excel: versión 2102 (compilación 13801.20632) y versiones posteriores
  • Word: versión 2408 (compilación 17928.20114) y versiones posteriores
• Office en Mac
  • Excel: versión 16.55 (21111400) y versiones posteriores
  • Word: versión 16.88 (24081116) y posteriores

Además, los métodos abreviados de teclado solo funcionan en plataformas que admiten los siguientes conjuntos de requisitos. Para obtener información sobre los conjuntos de requisitos y cómo trabajar con ellos, vea Especificar aplicaciones de Office y requisitos de API.

• SharedRuntime 1.1
• KeyboardShortcuts 1.1 (obligatorio si el complemento proporciona a sus usuarios la opción de personalizar métodos abreviados de teclado)

Configuración del manifiesto

Hay dos pequeños cambios que realizar en el manifiesto. Una es habilitar el complemento para que use un entorno de ejecución compartido y el otro es apuntar a un archivo con formato JSON donde definió los métodos abreviados de teclado.

Configuración del complemento para usar un entorno de ejecución compartido

La adición de métodos abreviados de teclado personalizados requiere que el complemento use el entorno de ejecución compartido. Para obtener más información, consulte Configuración de un complemento para usar un entorno de ejecución compartido.

Vinculación del archivo de asignación al manifiesto

Inmediatamente debajo (no dentro) del <elemento VersionOverrides> en el manifiesto, agregue un elemento ExtendedOverrides . Establezca el Url atributo en la dirección URL completa de un archivo JSON del proyecto que creará en un paso posterior.

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

Creación o edición del archivo JSON de accesos directos

Los métodos abreviados de teclado personalizados se definen en un archivo JSON. En este archivo se describen los métodos abreviados de teclado y las acciones que invocarán. El esquema completo del archivo JSON está en extended-manifest.schema.json.

1. En el proyecto del complemento, cree un archivo JSON. Asegúrese de que la ruta de acceso del archivo coincide con la ubicación especificada para el Url atributo del elemento ExtendedOverrides .

2. Agregue el siguiente marcado al archivo. Tenga en cuenta lo siguiente sobre el código.

   • La matriz "actions" contiene objetos que definen las acciones que se van a invocar. Se requieren las propiedades "actions.id" y "actions.name".
   • La propiedad "actions.id" identifica de forma única la acción que se va a invocar mediante un método abreviado de teclado.
   • La propiedad "actions.name" debe describir la acción de un método abreviado de teclado. La descripción que proporcione aparece en el cuadro de diálogo que se muestra a un usuario cuando hay un conflicto de acceso directo entre varios complementos o con Microsoft 365. Office anexa el nombre del complemento entre paréntesis al final de la descripción. Para obtener más información sobre cómo se controlan los conflictos con los métodos abreviados de teclado, vea Evitar combinaciones de teclas en uso por otros complementos.
   • La propiedad "type" es opcional. Actualmente, solo se admite el tipo "ExecuteFunction".
   • Las acciones especificadas se asignarán a las funciones que cree en un paso posterior. En el ejemplo, más adelante asignará "ShowTaskpane" a una función que llama al Office.addin.showAsTaskpane método y "HideTaskpane" a una función que llama al Office.addin.hide método .
   • La matriz de "accesos directos" contiene objetos que asignan combinaciones de teclas a acciones. Se requieren las propiedades "shortcuts.action", "shortcuts.key" y "shortcuts.key.default".
   • El valor de la propiedad "shortcuts.action" debe coincidir con la propiedad "actions.id" del objeto de acción aplicable.
   • Es posible personalizar los accesos directos para que sean específicos de la plataforma. En el ejemplo, el objeto "shortcuts" personaliza los accesos directos para cada una de las siguientes plataformas: "windows", "mac" y "web". Debe definir una tecla de método abreviado predeterminada para cada acceso directo. Esto se usa como clave de reserva si no se especifica una combinación de teclas para una plataforma determinada.

   Sugerencia

   Para obtener instrucciones sobre cómo crear combinaciones de teclas personalizadas, consulte Directrices para combinaciones de teclas personalizadas.

   {
       "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"
               }
           }
       ]
   }
   

Asignación de acciones personalizadas a sus funciones

1. En el proyecto, abra el archivo JavaScript cargado por la página HTML en el <elemento FunctionFile> .

2. En el archivo JavaScript, use la API Office.actions.associate para asignar cada acción especificada en el archivo JSON a una función de JavaScript. Agregue el siguiente Código JavaScript al archivo. Tenga en cuenta lo siguiente sobre el código.

   • El primer parámetro es una de las acciones del archivo JSON.
   • El segundo parámetro es la función que se ejecuta cuando un usuario presiona la combinación de teclas asignada a la acción en el archivo 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;
           });
   });
   

Directrices para combinaciones de teclas personalizadas

Use las siguientes directrices para crear combinaciones de teclas personalizadas para los complementos.

• Un método abreviado de teclado debe incluir al menos una tecla modificadora (Alt/Opción, Ctrl/Comando, Mayús) y solo otra tecla. Estas claves deben estar unidas con un + carácter.
• La clave modificadora Command se admite en la plataforma macOS.
• En macOS, la tecla Alt se asigna a la clave Option. En Windows, la tecla Comando se asigna a la tecla Ctrl.
• La tecla Mayús no se puede usar como la única tecla modificadora. Debe combinarse con Alt/Opción o Ctrl/Comando.
• Las combinaciones de teclas pueden incluir caracteres "A-Z", "a-z", "0-9" y las marcas de puntuación "-", "_" y "+". Por convención, las letras minúsculas no se usan en los métodos abreviados de teclado.
• Cuando dos caracteres están vinculados a la misma tecla física en un teclado estándar, son sinónimos de un método abreviado de teclado personalizado. Por ejemplo, Alt+a y Alt+A son el mismo acceso directo, así como Ctrl+- y Ctrl+_ ("-" y "_" están vinculados a la misma clave física).

Accesos directos del explorador que no se pueden invalidar

Cuando se usan métodos abreviados de teclado personalizados en la web, algunos métodos abreviados de teclado que usa el explorador no se pueden invalidar mediante complementos. La lista siguiente es un trabajo en curso. Si detecta otras combinaciones que no se pueden invalidar, háganoslo saber mediante la herramienta de comentarios en la parte inferior de esta página.

• Ctrl+N
• Ctrl+Mayús+N
• Ctrl+T
• Ctrl+Mayús+T
• Ctrl+W
• Ctrl+PgUp/PgDn

Evitar combinaciones de teclas en uso por otros complementos

Hay muchos métodos abreviados de teclado que Microsoft 365 ya usa. Evite registrar métodos abreviados de teclado para el complemento que ya están en uso. Sin embargo, puede haber algunas instancias en las que sea necesario invalidar los métodos abreviados de teclado existentes o controlar los conflictos entre varios complementos que han registrado el mismo método abreviado de teclado.

En el caso de un conflicto, el usuario verá un cuadro de diálogo la primera vez que intente usar un método abreviado de teclado en conflicto. Tenga en cuenta que el texto de la opción de complemento que se muestra en este cuadro de diálogo procede de la propiedad "actions.name" del archivo JSON de accesos directos.

El usuario puede seleccionar qué acción realizará el método abreviado de teclado. Después de realizar la selección, la preferencia se guarda para futuros usos del mismo acceso directo. Las preferencias de acceso directo se guardan por usuario y por plataforma. Si el usuario desea cambiar sus preferencias, puede invocar el comando Reset Office Add-ins shortcut preferences (Restablecer preferencias de acceso directo de complementos de Office ) desde el cuadro de búsqueda Cuéntame . Al invocar el comando, se borran todas las preferencias de acceso directo del complemento del usuario y se volverá a solicitar al usuario con el cuadro de diálogo de conflicto la próxima vez que intente usar un acceso directo en conflicto.

Para obtener la mejor experiencia de usuario, se recomienda minimizar los conflictos de métodos abreviados de teclado con estos procedimientos recomendados.

• Use solo métodos abreviados de teclado con el siguiente patrón: Ctrl+Mayús+Alt+x, donde x es otra tecla.
• Evite usar métodos abreviados de teclado establecidos en Excel y Word. Para obtener una lista, consulte lo siguiente:
  • Métodos abreviados de teclado en Excel
  • Métodos abreviados de teclado en Word
• Cuando el foco del teclado está dentro de la interfaz de usuario del complemento, Ctrl+Barra espaciadora y Ctrl+Mayús+F10 no funcionarán, ya que se trata de accesos directos de accesibilidad esenciales.
• En un equipo Windows o Mac, si el comando Restablecer preferencias de acceso directo de complementos de Office no está disponible en el menú de búsqueda, el usuario puede agregar manualmente el comando a la cinta personalizando la cinta a través del menú contextual.

Localizar la descripción de un método abreviado de teclado

Es posible que tenga que localizar los métodos abreviados de teclado personalizados en los siguientes escenarios.

• El complemento admite varias configuraciones regionales.
• El complemento admite diferentes alfabetos, sistemas de escritura o diseños de teclado.

Para obtener información sobre cómo localizar los métodos abreviados de teclado JSON, consulte Localización de invalidaciones extendidas.

Activar la personalización de accesos directos para usuarios específicos

Los usuarios del complemento pueden reasignar las acciones del complemento a combinaciones de teclado alternativas.

Use el método Office.actions.replaceShortcuts para asignar las combinaciones de teclado personalizadas de un usuario a las acciones de los complementos. El método toma un parámetro de tipo {[actionId:string]: string|null}, donde los actionIds son un subconjunto de los identificadores de acción que se deben definir en el JSON de manifiesto extendido del complemento. Los valores son las combinaciones de teclas preferidas del usuario. El valor también puede ser null, que quitará cualquier personalización para eso actionId y revertirá a la combinación de teclado predeterminada especificada.

Si el usuario ha iniciado sesión en Microsoft 365, las combinaciones personalizadas se guardan en la configuración de itinerancia del usuario por plataforma. La personalización de accesos directos no se admite actualmente para usuarios anónimos.

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.");
        }
    });

Para averiguar qué métodos abreviados ya están en uso para el usuario, llame al método Office.actions.getShortcuts . Este método devuelve un objeto de tipo [actionId:string]:string|null}, donde los valores representan la combinación de teclado actual que el usuario debe usar para invocar la acción especificada. Los valores pueden proceder de tres orígenes diferentes.

• Si hubo un conflicto con el acceso directo y el usuario ha elegido usar una acción diferente (ya sea nativa u otro complemento) para esa combinación de teclado, el valor devuelto será null puesto que el acceso directo se ha invalidado y no hay ninguna combinación de teclado que el usuario pueda usar actualmente para invocar esa acción de complemento.
• Si el acceso directo se ha personalizado mediante el método Office.actions.replaceShortcuts , el valor devuelto será la combinación de teclado personalizada.
• Si el acceso directo no se ha invalidado ni personalizado, devolverá el valor del JSON de manifiesto extendido del complemento.

A continuación se muestra un ejemplo.

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

Como se describe en Evitar combinaciones de teclas en uso por otros complementos, se recomienda evitar conflictos en los accesos directos. Para detectar si una o varias combinaciones de teclas ya están en uso, páselas como una matriz de cadenas al método Office.actions.areShortcutsInUse . El método devuelve un informe que contiene combinaciones de teclas que ya están en uso en forma de una matriz de objetos de tipo {shortcut: string, inUse: boolean}. La shortcut propiedad es una combinación de teclas, como "Ctrl+Mayús+1". Si la combinación ya está registrada en otra acción, la inUse propiedad se establece en true. Por ejemplo, [{shortcut: "Ctrl+Shift+1", inUse: true}, {shortcut: "Ctrl+Shift+2", inUse: false}]. El siguiente fragmento de código es un ejemplo.

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);
    });

Implementación de métodos abreviados de teclado personalizados en aplicaciones compatibles de Microsoft 365

Puede implementar un método abreviado de teclado personalizado que se usará en aplicaciones de Microsoft 365 compatibles, como Excel y Word. Si la implementación para realizar la misma tarea es diferente en cada aplicación, debe usar el Office.actions.associate método para llamar a una función de devolución de llamada diferente para cada aplicación. A continuación puede ver un ejemplo del código.

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);
}
...

Vea también

• Ejemplo de complemento de Office: Uso de métodos abreviados de teclado para acciones de complemento de Office
• Conjuntos de requisitos de tiempo de ejecución compartido
• Conjuntos de requisitos de métodos abreviados de teclado