Adicionar atalhos de teclado personalizados aos seus Suplementos do Office

Artigo
09/27/2024

Os atalhos de teclado, também conhecidos como combinações de teclas, permitem que os utilizadores do suplemento trabalhem de forma mais eficiente. Os atalhos de teclado também melhoram a acessibilidade do suplemento para utilizadores portadores de deficiência, fornecendo uma alternativa ao rato.

Existem três passos para adicionar atalhos de teclado a um suplemento.

Configure o manifesto do suplemento.
Crie ou edite o ficheiro JSON de atalhos para definir ações e os respetivos atalhos de teclado.
Mapeie as ações personalizadas para as respetivas funções com a API Office.actions.associate .

Pré-requisitos

Atualmente, os atalhos de teclado só são suportados nas seguintes plataformas e compilação do Excel e Word.

Office na Web
Office no Windows
- Excel: Versão 2102 (Compilação 13801.20632) e posterior
- Word: Versão 2408 (Compilação 17928.20114) e posterior
Office no Mac
- Excel: Versão 16.55 (21111400) e posterior
- Word: Versão 16.88 (24081116) e posterior

Além disso, os atalhos de teclado só funcionam em plataformas que suportam os seguintes conjuntos de requisitos. Para obter informações sobre os conjuntos de requisitos e como trabalhar com os mesmos, consulte Especificar as aplicações do Office e os requisitos da API.

SharedRuntime 1.1
KeyboardShortcuts 1.1 (necessário se o suplemento fornecer aos seus utilizadores a opção de personalizar atalhos de teclado)

Dica

Para começar com uma versão funcional de um suplemento com atalhos de teclado já configurados, clone e execute o exemplo Utilizar atalhos de teclado para ações de Suplemento do Office . Quando estiver pronto para adicionar atalhos de teclado ao seu próprio suplemento, continue com este artigo.

Configurar o manifesto

Existem duas pequenas alterações a fazer ao manifesto. Uma é ativar o suplemento para utilizar um runtime partilhado e o outro é apontar para um ficheiro formatado em JSON onde definiu os atalhos de teclado.

Configurar o suplemento para utilizar um runtime partilhado

Adicionar atalhos de teclado personalizados requer que o suplemento utilize o runtime partilhado. Para obter mais informações, veja Configurar um suplemento para utilizar um runtime partilhado.

Ligar o ficheiro de mapeamento ao manifesto

Imediatamente abaixo (não dentro) do <elemento VersionOverrides> no manifesto, adicione um elemento ExtendedOverrides . Defina o Url atributo para o URL completo de um ficheiro JSON no projeto que irá criar num passo posterior.

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

Criar ou editar o ficheiro JSON de atalhos

Os atalhos de teclado personalizados são definidos num ficheiro JSON. Este ficheiro descreve os atalhos de teclado e as ações que irão invocar. O esquema completo para o ficheiro JSON está em extended-manifest.schema.json.

No seu projeto de suplemento, crie um ficheiro JSON. Certifique-se de que o caminho do ficheiro corresponde à localização que especificou para o Url atributo do elemento ExtendedOverrides .
Adicione a seguinte marcação ao ficheiro. Tenha em atenção o seguinte sobre o código.
- A matriz "actions" contém objetos que definem as ações a invocar. As propriedades "actions.id" e "actions.name" são necessárias.
- A propriedade "actions.id" identifica exclusivamente a ação a invocar através de um atalho de teclado.
- A propriedade "actions.name" tem de descrever a ação de um atalho de teclado. A descrição que fornecer é apresentada na caixa de diálogo apresentada a um utilizador quando existe um conflito de atalhos entre vários suplementos ou com o Microsoft 365. O Office acrescenta o nome do suplemento entre parênteses no final da descrição. Para obter mais informações sobre como os conflitos com atalhos de teclado são processados, consulte Evitar combinações de teclas em utilização por outros suplementos.
- A propriedade "type" é opcional. Atualmente, apenas o tipo "ExecuteFunction" é suportado.
- As ações especificadas serão mapeadas para funções que criar num passo posterior. No exemplo, irá mapear mais tarde "ShowTaskpane" para uma função que chama o Office.addin.showAsTaskpane método e "HideTaskpane" para uma função que chama o Office.addin.hide método .
- A matriz "atalhos" contém objetos que mapeiam combinações de teclas para ações. São necessárias as propriedades "shortcuts.action", "shortcuts.key" e "shortcuts.key.default".
- O valor da propriedade "shortcuts.action" tem de corresponder à propriedade "actions.id" do objeto de ação aplicável.
- É possível personalizar atalhos para serem específicos da plataforma. No exemplo, o objeto "atalhos" personaliza os atalhos para cada uma das seguintes plataformas: "windows", "mac" e "web". Tem de definir uma tecla de atalho predefinida para cada atalho. Isto é utilizado como uma chave de contingência se não for especificada uma combinação de teclas para uma determinada plataforma.
Dica

Para obter orientações sobre como criar combinações de teclas personalizadas, veja Diretrizes para combinações 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"
            }
        }
    ]
}
```

Mapear ações personalizadas para as respetivas funções

No seu projeto, abra o ficheiro JavaScript carregado pela sua página HTML no <elemento FunctionFile> .
No ficheiro JavaScript, utilize a API Office.actions.associate para mapear cada ação que especificou no ficheiro JSON para uma função JavaScript. Adicione o seguinte JavaScript ao ficheiro. Tenha em atenção o seguinte sobre o código.
- O primeiro parâmetro é uma das ações do ficheiro JSON.
- O segundo parâmetro é a função que é executada quando um utilizador prime a combinação de teclas mapeada para a ação no ficheiro 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;
        });
});
```

Diretrizes para combinações de teclas personalizadas

Utilize as seguintes diretrizes para criar combinações de teclas personalizadas para os seus suplementos.

Um atalho de teclado tem de incluir, pelo menos, uma tecla modificadora (Alt/Opção, Ctrl/Comando, Shift) e apenas uma outra tecla. Estas teclas têm de ser associadas com um + caráter.
A chave modificadora de comandos é suportada na plataforma macOS.
No macOS, a tecla Alt é mapeada para a tecla Opção. No Windows, a tecla Comando é mapeada para a tecla Ctrl.
A tecla Shift não pode ser utilizada como a única tecla modificadora. Tem de ser combinado com Alt/Opção ou Ctrl/Comando.
As combinações de teclas podem incluir carateres "A-Z", "a-z", "0-9" e as marcas de pontuação "-", "_" e "+". Por convenção, as letras minúsculas não são utilizadas em atalhos de teclado.
Quando dois carateres estão ligados à mesma tecla física num teclado padrão, são sinónimos num atalho de teclado personalizado. Por exemplo, Alt+a e Alt+A são o mesmo atalho, bem como Ctrl+- e Ctrl+_ ("-" e "_" estão ligados à mesma tecla física).

Observação

Os atalhos de teclado personalizados têm de ser premidos em simultâneo. As Informações de Teclas de Atalho, também conhecidas como atalhos de tecla sequencial (por exemplo, Alt+H, H), não são suportadas nos Suplementos do Office.

Atalhos do browser que não podem ser substituídos

Ao utilizar atalhos de teclado personalizados na Web, alguns atalhos de teclado utilizados pelo browser não podem ser substituídos por suplementos. A lista seguinte é um trabalho em curso. Se descobrir outras combinações que não podem ser substituídas, informe-nos através da ferramenta de comentários na parte inferior desta página.

Ctrl+N
Ctrl+Shift+N
Ctrl+T
Ctrl+Shift+T
Ctrl+W
Ctrl+PgUp/PgDn

Evitar combinações de teclas em utilização por outros suplementos

Existem muitos atalhos de teclado que já estão a ser utilizados pelo Microsoft 365. Evite registar atalhos de teclado para o suplemento que já estão a ser utilizados. No entanto, podem existir algumas instâncias em que é necessário substituir atalhos de teclado existentes ou lidar com conflitos entre vários suplementos que registaram o mesmo atalho de teclado.

Em caso de conflito, o utilizador verá uma caixa de diálogo na primeira vez que tentar utilizar um atalho de teclado em conflito. Tenha em atenção que o texto da opção de suplemento apresentada nesta caixa de diálogo provém da propriedade "actions.name" no ficheiro JSON de atalhos.

Um modal de conflito com duas ações diferentes para um único atalho.

O utilizador pode selecionar a ação que o atalho de teclado irá efetuar. Depois de efetuar a seleção, a preferência é guardada para utilizações futuras do mesmo atalho. As preferências de atalho são guardadas por utilizador, por plataforma. Se o utilizador quiser alterar as suas preferências, pode invocar o comando Repor preferências de atalho de Suplementos do Office a partir da caixa de pesquisa Diga-me o que pretende fazer. Invocar o comando limpa todas as preferências de atalho do suplemento do utilizador e o utilizador será novamente solicitado com a caixa de diálogo conflito da próxima vez que tentar utilizar um atalho em conflito.

A caixa de pesquisa Diga-me o que pretende fazer no Excel a mostrar a ação repor as preferências de atalho do Suplemento do Office.

Para obter a melhor experiência de utilizador, recomendamos que minimize os conflitos de atalhos de teclado com estas boas práticas.

Utilize apenas atalhos de teclado com o seguinte padrão: Ctrl+Shift+Alt+x, em que x é outra tecla.
Evite utilizar atalhos de teclado estabelecidos no Excel e Word. Para obter uma lista, veja o seguinte:
- Atalhos de teclado no Excel
- Atalhos de teclado no Word
Quando o foco do teclado estiver dentro da IU do suplemento, Ctrl+Barra de Espaço e Ctrl+Shift+F10 não funcionarão, uma vez que estes são atalhos de acessibilidade essenciais.
Num computador Windows ou Mac, se o comando Repor preferências de atalho de Suplementos do Office não estiver disponível no menu de pesquisa, o utilizador pode adicionar manualmente o comando ao friso ao personalizar o friso através do menu de contexto.

Localizar a descrição de um atalho de teclado

Poderá ter de localizar os atalhos de teclado personalizados nos seguintes cenários.

O suplemento suporta várias regiões.
O seu suplemento suporta alfabetos diferentes, sistemas de escrita ou esquemas de teclado.

Para obter informações sobre como localizar os atalhos de teclado JSON, consulte Localizar substituições expandidas.

Ativar a personalização de atalhos para utilizadores específicos

Observação

As APIs descritas nesta secção requerem o conjunto de requisitos KeyboardShortcuts 1.1 .

Os utilizadores do seu suplemento podem reatribuir as ações do suplemento a combinações de teclado alternativas.

Utilize o método Office.actions.replaceShortcuts para atribuir combinações de teclado personalizadas de um utilizador às suas ações de suplementos. O método utiliza um parâmetro do tipo {[actionId:string]: string|null}, em que os actionIds são um subconjunto dos IDs de ação que têm de ser definidos no JSON do manifesto expandido do suplemento. Os valores são as combinações de chaves preferenciais do utilizador. O valor também pode ser null, o que removerá qualquer personalização para esse actionId e reverter para a combinação de teclado predefinida especificada.

Se o utilizador tiver sessão iniciada no Microsoft 365, as combinações personalizadas são guardadas nas definições de roaming do utilizador por plataforma. Atualmente, a personalização de atalhos não é suportada para utilizadores 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 saber que atalhos já estão a ser utilizados para o utilizador, chame o método Office.actions.getShortcuts . Este método devolve um objeto do tipo [actionId:string]:string|null}, em que os valores representam a combinação de teclado atual que o utilizador tem de utilizar para invocar a ação especificada. Os valores podem ser provenientes de três origens diferentes.

Se tiver ocorrido um conflito com o atalho e o utilizador tiver optado por utilizar uma ação diferente (nativa ou outro suplemento) para essa combinação de teclado, o valor devolvido será null uma vez que o atalho foi substituído e não existe nenhuma combinação de teclado que o utilizador possa utilizar atualmente para invocar essa ação de suplemento.
Se o atalho tiver sido personalizado com o método Office.actions.replaceShortcuts , o valor devolvido será a combinação de teclado personalizada.
Se o atalho não tiver sido substituído ou personalizado, devolverá o valor do JSON do manifesto expandido do suplemento.

Apresentamos um exemplo a seguir.

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

Conforme descrito em Evitar combinações de teclas em utilização por outros suplementos, é uma boa prática evitar conflitos nos atalhos. Para descobrir se uma ou mais combinações de teclas já estão a ser utilizadas, transmita-as como uma matriz de cadeias para o método Office.actions.areShortcutsInUse . O método devolve um relatório que contém combinações de teclas que já estão a ser utilizadas sob a forma de uma matriz de objetos do tipo {shortcut: string, inUse: boolean}. A shortcut propriedade é uma combinação de teclas, como "Ctrl+Shift+1". Se a combinação já estiver registada noutra ação, a inUse propriedade está definida como true. Por exemplo, [{shortcut: "Ctrl+Shift+1", inUse: true}, {shortcut: "Ctrl+Shift+2", inUse: false}]. O fragmento de código seguinte é um exemplo.

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

Implementar atalhos de teclado personalizados em aplicações suportadas do Microsoft 365

Pode implementar um atalho de teclado personalizado para ser utilizado em aplicações suportadas do Microsoft 365, como o Excel e Word. Se a implementação para executar a mesma tarefa for diferente em cada aplicação, tem de utilizar o Office.actions.associate método para chamar uma função de chamada de retorno diferente para cada aplicação. O código a seguir é um exemplo.

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

Compartilhar via