Compartilhar via

Adicionar atalhos de teclado personalizados aos seus Suplementos do Office

  • Artigo

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.

  1. Configure o manifesto do suplemento para utilizar um runtime partilhado.
  2. Defina atalhos de teclado personalizados e as ações que serão executadas.
  3. 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

    Observação

    A funcionalidade de atalho de teclado está a ser implementada para Word na Web. Se testar a funcionalidade no Word na Web neste momento, os atalhos poderão não funcionar se estiverem ativados a partir do painel de tarefas do suplemento. Recomendamos que marcar periodicamente os conjuntos de requisitos de Atalhos de Teclado para saber quando a funcionalidade é totalmente suportada.

  • 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.

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.

Definir atalhos de teclado personalizados

O processo para definir atalhos de teclado personalizados para o suplemento varia consoante o tipo de manifesto utilizado pelo suplemento. Selecione o separador para o tipo de manifesto que está a utilizar.

Dica

Para saber mais sobre manifestos para Suplementos do Office, consulte Manifesto de Suplementos do Office.

Observação

A implementação de atalhos de teclado com o manifesto de aplicação unificada para o Microsoft 365 está em pré-visualização pública para programadores. Isto não deve ser utilizado em suplementos de produção. Convidamo-lo a experimentá-lo em ambientes de teste ou de desenvolvimento. Para obter mais informações, veja o esquema de manifesto da aplicação de pré-visualização do programador público.

Se o seu suplemento utilizar o manifesto de aplicação unificado para o Microsoft 365, os atalhos de teclado personalizados e as respetivas ações serão definidos no manifesto.

  1. No seu projeto de suplemento, abra o ficheiro manifest.json .

  2. Adicione o seguinte objeto à matriz "extensions.runtimes". Observe o seguinte sobre esta marcação.

    • Os objetos "actions" especificam as funções que o suplemento pode executar. No exemplo seguinte, um suplemento poderá mostrar e ocultar um painel de tarefas. Irá criar estas funções numa secção posterior. Atualmente, os atalhos de teclado personalizados só podem executar ações do tipo "executeFunction".
    • Embora a propriedade "actions.displayName" seja opcional, é necessário se for criado um atalho de teclado personalizado para a ação. Esta propriedade é utilizada para 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.
    "runtimes": [
    {
        "id": "TaskPaneRuntime",
        "type": "general",
        "code": {
            "page": "https://localhost:3000/taskpane.html"
        },
        "lifetime": "long",
        "actions": [
            {
                "id": "ShowTaskpane",
                "type": "executeFunction",
                "displayName": "Show task pane (Contoso Add-in)"
            },
            {
                "id": "HideTaskpane",
                "type": "executeFunction",
                "displayName": "Hide task pane (Contoso Add-in)"
            }
        ],
    }
]

  3. Adicione o seguinte à matriz "extensions". Tenha em atenção o seguinte sobre a marcação.

    • O conjunto de requisitos sharedRuntime 1.1 é especificado no objeto "requirements.capabilities" para suportar atalhos de teclado personalizados.
    • Cada objeto de "atalhos" representa uma única ação que é invocada por um atalho de teclado. Especifica as combinações de teclas suportadas para várias plataformas, como Office na Web, no Windows e no Mac. Para obter orientações sobre como criar combinações de teclas personalizadas, veja Diretrizes para combinações de teclas personalizadas.
    • Tem de ser especificada uma combinação de teclas predefinida. É utilizado em todas as plataformas suportadas se não existir uma combinação específica configurada para uma determinada plataforma.
    • O valor da propriedade "actionId" tem de corresponder ao valor especificado na propriedade "id" do objeto "extensions.runtimes.actions" aplicável.
    "keyboardShortcuts": [
    {
        "requirements": {
            "capabilities": [
                {
                    "name": "SharedRuntime",
                    "minVersion": "1.1"
                }
            ]
        },
        "shortcuts": [
            {
                "key": {
                    "default": "Ctrl+Alt+Up",
                    "mac": "Command+Shift+Up",
                    "web": "Ctrl+Alt+1",
                    "windows": "Ctrl+Alt+Up"
                },
                "actionId": "ShowTaskpane"
            },
            {
                "key": {
                    "default": "Ctrl+Alt+Down",
                    "mac": "Command+Shift+Down",
                    "web": "Ctrl+Alt+2",
                    "windows": "Ctrl+Alt+Up"
                },
                "actionId": "HideTaskpane"
            }
        ]
    }
]

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

  1. No seu projeto, abra o ficheiro JavaScript carregado pela sua página HTML no <elemento FunctionFile> .

  2. No ficheiro JavaScript, utilize a API Office.actions.associate para mapear cada ação que especificou num passo anterior 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 é o nome de uma ação que mapeou para um atalho de teclado. A localização do nome da ação depende do tipo de manifesto que o suplemento utiliza.
      • Manifesto de aplicação unificada para o Microsoft 365: o valor da propriedade "extensions.keyboardShortcuts.shortcuts.actionId" no ficheiro manifest.json .
      • Manifesto apenas de suplemento: o valor da propriedade "actions.id" no ficheiro JSON de atalhos.
    • O segundo parâmetro é a função que é executada quando um utilizador prime a combinação de teclas mapeada para uma ação.
    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 (OpçãoAlt/, Ctrl/Cmd, Shift) e apenas uma outra tecla. Estas teclas têm de ser associadas com um + caráter.
  • A chave modificadora de cmd é suportada na plataforma macOS.
  • No macOS, a tecla Alt é mapeada para a tecla Opção . No Windows, a tecla Cmd é mapeada para a tecla Ctrl .
  • A tecla Shift não pode ser utilizada como a única tecla modificadora. Tem de ser combinado com aOpçãoAlt/ ou Ctrl/Cmd.
  • 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 a origem do texto para a opção de suplemento apresentada nesta caixa de diálogo varia consoante o tipo de manifesto que o suplemento utiliza. - Manifesto de aplicação unificada para o Microsoft 365: o valor da propriedade "extensions.runtimes.actions.displayName" no ficheiro manifest.json . - Manifesto apenas de suplemento: o valor 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:
  • Quando o foco do teclado estiver dentro da IU do suplemento, CtrlEspaç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.

As orientações sobre como localizar os atalhos de teclado variam consoante o tipo de manifesto utilizado pelo suplemento.

Para saber como localizar os atalhos de teclado personalizados com o manifesto da aplicação unificada para o Microsoft 365, consulte Localizar cadeias no manifesto da aplicação.

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, o valor devolvido varia consoante o tipo de manifesto que o suplemento utiliza.
    • Manifesto de aplicação unificada para o Microsoft 365: o atalho especificado no ficheiro manifest.json do suplemento.
    • Manifesto apenas de suplemento: o atalho especificado no ficheiro JSON de atalhos do suplemento.

Apresentamos um exemplo a seguir.

Office.actions.getShortcuts()
    .then((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);
}
...

Confira também