Adicionar atalhos de teclado personalizados aos suplementos do Office

Artigo
08/18/2023

Os atalhos de teclado, também conhecidos como combinações de chaves, permitem que os usuários do suplemento funcionem com mais eficiência. Os atalhos de teclado também melhoram a acessibilidade do suplemento para usuários com deficiências, fornecendo uma alternativa ao mouse.

Importante

Atualmente, os atalhos de teclado só têm suporte no Excel e somente nessas plataformas e builds:

Excel Online
Excel no Windows: versão 2102 (Build 13801.20632) e posterior
Excel no Mac: versão 16.48 e posterior

Observação

Os atalhos de teclado funcionam apenas em plataformas que dão suporte aos seguintes conjuntos de requisitos. Para saber mais sobre os conjuntos de requisitos e como trabalhar com eles, consulte Especificar aplicativos do Office e requisitos de API.

SharedRuntime 1.1
Também necessário se o suplemento permitir que o usuário personalize atalhos de teclado: TecladoShortcuts 1.1

Observação

Para começar com uma versão de trabalho de um suplemento com atalhos de teclado já habilitados, clone e execute o exemplo de Atalhos de Teclado do Excel. Quando estiver pronto para adicionar atalhos de teclado ao seu próprio suplemento, continue com este artigo.

Há três etapas para adicionar atalhos de teclado a um suplemento.

Configure o manifesto do suplemento.
Create ou edite o arquivo JSON de atalhos para definir ações e seus atalhos de teclado.
Adicione uma ou mais chamadas de runtime da API office.actions.associate para mapear uma função para cada ação.

Configurar o manifesto

Há duas pequenas alterações a serem feitas no manifesto. Uma é habilitar o suplemento para usar um runtime compartilhado e a outra é apontar para um arquivo formatado por JSON em que você definiu os atalhos de teclado.

Configurar o suplemento para usar um runtime compartilhado

Adicionar atalhos de teclado personalizados requer que seu suplemento use o runtime compartilhado. Para obter mais informações, consulte Configurar um suplemento para usar um runtime compartilhado.

Vincular o arquivo de mapeamento ao manifesto

Imediatamente abaixo (não dentro) do <elemento VersionOverrides> no manifesto, adicione um elemento ExtendedOverrides . Defina o Url atributo como a URL completa de um arquivo JSON em seu projeto que você criará em uma etapa posterior.

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

Create ou editar o arquivo JSON de atalhos

Create um arquivo JSON em seu projeto. Certifique-se de que o caminho do arquivo corresponda ao local especificado para o Url atributo do elemento ExtendedOverrides . Este arquivo descreverá seus atalhos de teclado e as ações que eles invocarão.

Dentro do arquivo JSON, há duas matrizes. A matriz de ações conterá objetos que definem as ações a serem invocadas e a matriz de atalhos conterá objetos que mapeiam combinações de chaves em ações. Veja um exemplo.
```
{
    "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"
            }
        }
    ]
}
```
Para obter mais informações sobre os objetos JSON, consulte Construir os objetos de ação e Construir os objetos de atalho. O esquema completo para os atalhos JSON está em extended-manifest.schema.json.

Observação

Você pode usar "CONTROL" no lugar de "Ctrl" ao longo deste artigo.

Em uma etapa posterior, as ações serão mapeadas para funções que você grava. Neste exemplo, você posteriormente mapeará 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.

Create um mapeamento de ações para suas funções

Em seu projeto, abra o arquivo JavaScript carregado pela página HTML no <elemento FunctionFile> .
No arquivo JavaScript, use a API Office.actions.associate para mapear cada ação especificada no arquivo JSON para uma função JavaScript. Adicione o JavaScript a seguir ao arquivo. Observe o seguinte sobre o código.
- O primeiro parâmetro é uma das ações do arquivo JSON.
- O segundo parâmetro é a função que é executada quando um usuário pressiona a combinação de teclas mapeada para a ação no arquivo JSON.
```
Office.actions.associate('-- action ID goes here--', function () {

});
```
Para continuar o exemplo, use 'SHOWTASKPANE' como o primeiro parâmetro.

Para o corpo da função, use o método Office.addin.showAsTaskpane para abrir o painel de tarefas do suplemento. Quando terminar, o código deve ser semelhante ao seguinte:

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

Adicione uma segunda chamada de Office.actions.associate função para mapear a ação HIDETASKPANE para uma função que chama Office.addin.hide. Apresentamos um exemplo a seguir.

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

Seguir as etapas anteriores permite que o suplemento alterne a visibilidade do painel de tarefas pressionando Ctrl+Alt+Up e Ctrl+Alt+Down. O mesmo comportamento é mostrado no exemplo de atalhos de teclado do Excel no repositório Exemplos de Suplemento do Office no GitHub.

Detalhes e restrições

Construir os objetos de ação

Use as diretrizes a seguir ao especificar os objetos na actions matriz do shortcuts.json.

Os nomes id da propriedade e name são obrigatórios.
A id propriedade é usada para identificar exclusivamente a ação para invocar usando um atalho de teclado.
A name propriedade deve ser uma cadeia de caracteres amigável ao usuário que descreve a ação. Deve ser uma combinação dos caracteres A - Z, a - z, 0 a 9 e as marcas de pontuação "-", "_", e "+".
A propriedade do type é opcional. Atualmente, há suporte apenas ExecuteFunction para o tipo.

Apresentamos um exemplo a seguir.

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

O esquema completo para os atalhos JSON está em extended-manifest.schema.json.

Construir os objetos de atalho

Use as diretrizes a seguir ao especificar os objetos na shortcuts matriz do shortcuts.json.

Os nomes actionda propriedade , keye default são necessários.
O valor da action propriedade é uma cadeia de caracteres e deve corresponder a id uma das propriedades no objeto de ação.
A default propriedade pode ser qualquer combinação dos caracteres A - Z, a -z, 0 a 9 e as marcas de pontuação "-", "_", e "+". (Por convenção, as letras minúsculas não são usadas nessas propriedades.)
A default propriedade deve conter o nome de pelo menos uma chave modificadora (Alt, Ctrl, Shift) e apenas uma outra chave.
O shift não pode ser usado como a única chave modificadora. Combine Shift com Alt ou Ctrl.
Para Macs, também oferecemos suporte à chave do modificador de comando.
Para Macs, Alt é mapeado para a chave Opção. Para Windows, o comando é mapeado para a chave Ctrl.
Quando dois caracteres são vinculados à mesma chave física em um teclado padrão, então eles são sinônimos na default propriedade; por exemplo, Alt+a e Alt+A são o mesmo atalho, assim como Ctrl+- e Ctrl+_ porque "-" e "_" são a mesma chave física.
O caractere "+" indica que as teclas de ambos os lados são pressionadas simultaneamente.

Apresentamos um exemplo a seguir.

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

O esquema completo para os atalhos JSON está em extended-manifest.schema.json.

Observação

As KeyTips, também conhecidas como atalhos de chave sequenciais, como o atalho do Excel para escolher uma cor de preenchimento Alt+H, H, não têm suporte em Suplementos do Office.

Evitar combinações de chaves em uso por outros suplementos

Há muitos atalhos de teclado que já estão em uso pelo Office. Evite registrar atalhos de teclado para seu suplemento que já estão em uso. No entanto, pode haver algumas instâncias em que é necessário substituir atalhos de teclado existentes ou lidar com conflitos entre vários suplementos que registraram o mesmo atalho de teclado.

No caso de um conflito, o usuário verá uma caixa de diálogo na primeira vez que tentar usar um atalho de teclado conflitante. Observe que o texto da opção de suplemento exibida nesta caixa de diálogo vem da name propriedade no objeto de ação no shortcuts.json arquivo.

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

O usuário pode selecionar qual ação o atalho de teclado tomará. Depois de fazer a seleção, a preferência é salva para usos futuros do mesmo atalho. As preferências de atalho são salvas por usuário, por plataforma. Se o usuário quiser alterar suas preferências, ele poderá invocar o comando Redefinir preferências de atalho de suplementos do Office da caixa de pesquisa Diga-me . Invocar o comando limpa todas as preferências de atalho de suplemento do usuário e o usuário será novamente solicitado com a caixa de diálogo de conflito na próxima vez que tentar usar um atalho conflitante.

A caixa de pesquisa Diga-me no Excel mostrando a ação redefinir preferências de atalho do Suplemento do Office.

Para obter a melhor experiência do usuário, recomendamos minimizar conflitos com o Excel com essas boas práticas.

Use apenas atalhos de teclado com o seguinte padrão: Ctrl+Shift+Alt+x, em que x é alguma outra chave.
Se você precisar de mais atalhos de teclado, marcar a lista de atalhos de teclado do Excel e evite usar qualquer um deles no suplemento.
Quando o foco do teclado estiver dentro da interface do usuário do suplemento, Ctrl+Barra de Espaços e Ctrl+Shift+F10 não funcionarão, pois são atalhos essenciais de acessibilidade.
Em um computador Windows ou Mac, se o comando "Redefinir preferências de atalho de suplementos do Office" não estiver disponível no menu de pesquisa, o usuário poderá adicionar manualmente o comando à faixa de opções personalizando a faixa de opções por meio do menu de contexto.

Personalizar os atalhos de teclado por plataforma

É possível personalizar atalhos para serem específicos da plataforma. Veja a seguir um exemplo do shortcuts objeto que personaliza os atalhos para cada uma das seguintes plataformas: windows, mac, web. Observe que você ainda deve ter uma default chave de atalho para cada atalho.

No exemplo a seguir, a default chave é a chave de fallback para qualquer plataforma que não seja especificada. A única plataforma não especificada é o Windows, portanto, a default chave só se aplicará ao 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"
            }
        }
    ]

Localizar os atalhos de teclado JSON

Se o suplemento der suporte a várias localidades, você precisará localizar a name propriedade dos objetos de ação. Além disso, se qualquer uma das localidades compatíveis com o suplemento tiver alfabetos ou sistemas de gravação diferentes e, portanto, teclados diferentes, talvez seja necessário localizar os atalhos também. Para obter informações sobre como localizar os atalhos de teclado JSON, consulte Localize substituições estendidas.

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

Ao usar atalhos de teclado personalizados na Web, alguns atalhos de teclado usados pelo navegador não podem ser substituídos por suplementos. Esta lista é um trabalho em andamento. Se você descobrir outras combinações que não podem ser substituídas, avise-nos usando a 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

Habilitar atalhos de teclado personalizados para usuários específicos

Seu suplemento pode permitir que os usuários reatribuam as ações do suplemento para combinações alternativas de teclado.

Observação

As APIs descritas nesta seção exigem o conjunto de requisitos KeyboardShortcuts 1.1 .

Use o método Office.actions.replaceShortcuts para atribuir as combinações de teclado personalizadas de um usuário às ações de suplementos. O método usa um parâmetro do tipo {[actionId:string]: string|null}, em que os actionIds são um subconjunto das IDs de ação que devem ser definidas no JSON de manifesto estendido do suplemento. Os valores são as combinações de chave preferidas do usuário. O valor também pode ser null, que removerá qualquer personalização para isso actionId e reverter à combinação de teclado padrão definida no JSON de manifesto estendido do suplemento.

Se o usuário estiver conectado ao Office, as combinações personalizadas serão salvas nas configurações de roaming do usuário por plataforma. Atualmente, não há suporte para personalizar atalhos para usuários anônimos.

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

Para descobrir quais atalhos já estão em uso para o usuário, chame o método Office.actions.getShortcuts . Esse método retorna um objeto do tipo [actionId:string]:string|null}, em que os valores representam a combinação de teclado atual que o usuário deve usar para invocar a ação especificada. Os valores podem vir de três fontes diferentes:

Se houve um conflito com o atalho e o usuário optou por usar uma ação diferente (nativa ou outro suplemento) para essa combinação de teclado, o valor retornado será null porque o atalho foi substituído e não há nenhuma combinação de teclado que o usuário possa usar no momento para invocar essa ação de suplemento.
Se o atalho tiver sido personalizado usando o método Office.actions.replaceShortcuts , o valor retornado será a combinação de teclado personalizada.
Se o atalho não tiver sido substituído ou personalizado, ele retornará o valor do JSON de manifesto estendido 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 chaves em uso por outros suplementos, é uma boa prática evitar conflitos em atalhos. Para descobrir se uma ou mais combinações de chaves já estão em uso, passe-as como uma matriz de cadeias de caracteres para o método Office.actions.areShortcutsInUse . O método retorna um relatório que contém combinações de chaves que já estão em uso na forma de uma matriz de objetos do tipo {shortcut: string, inUse: boolean}. A shortcut propriedade é uma combinação de chaves, como "CTRL+SHIFT+1". Se a combinação já estiver registrada em outra ação, a inUse propriedade será definida como true. Por exemplo, [{shortcut: "CTRL+SHIFT+1", inUse: true}, {shortcut: "CTRL+SHIFT+2", inUse: false}]. O snippet de código a seguir é um exemplo:

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

Próximas etapas

Consulte o suplemento de exemplo de atalhos de teclado do Excel .
Obtenha uma visão geral do trabalho com substituições estendidas no Trabalho com substituições estendidas do manifesto.

Share via

Adicionar atalhos de teclado personalizados aos suplementos do Office

Configurar o manifesto

Configurar o suplemento para usar um runtime compartilhado

Vincular o arquivo de mapeamento ao manifesto

Create ou editar o arquivo JSON de atalhos

Create um mapeamento de ações para suas funções

Detalhes e restrições

Construir os objetos de ação

Construir os objetos de atalho

Evitar combinações de chaves em uso por outros suplementos

Personalizar os atalhos de teclado por plataforma

Localizar os atalhos de teclado JSON

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

Habilitar atalhos de teclado personalizados para usuários específicos

Próximas etapas

Comentários

Recursos adicionais