Modificar comandos de menu para um visual de relatório

  • Artigo

Os visuais no Power BI têm menus que permitem que os usuários do aplicativo alterem a maneira como veem seus dados. Por exemplo, usando o menu Contexto , os pontos de dados podem ser incluídos ou excluídos de um visual. O menu Opções pode ser usado para exportar os dados contidos em um visual para uma planilha.

Abra o menu Contexto clicando com o botão direito do mouse em um visual ou em um ponto de dados específico em um visual.

Captura de tela que mostra um visual do Power BI com o menu de contexto aberto e realçado no canto superior direito.

Abra o menu Opções selecionando as reticências no canto superior direito do visual.

Observação

Se o cabeçalho visual de um visual estiver oculto, as reticências não serão exibidas.

Captura de tela que mostra um visual do Power BI com o menu de opções aberto e realçado no canto superior direito.

Essa API fornece uma maneira de estender esses menus, para que você adicione comandos para seus usuários e aprimore a experiência do aplicativo. Você pode personalizar ainda mais os menus ocultando ou desabilitando ações. Por exemplo, você pode ocultar o comando interno Destaque para o menu de opções.

Como modificar comandos de menu

Modifique os menus usando extensions para adicionar comandos e commands para alterar como os comandos internos são exibidos.

Você pode configurar a API para trabalhar no carregamento do relatório (configuração de inserção) ou pode chamar o método de relatório updateSettings para atualizar os itens adicionados após o carregamento de um relatório. Confira Definir configurações de relatório e Ocultar ou mostrar cabeçalhos visuais para saber mais.

As novas configurações de menu são aplicadas em todos os visuais no relatório. Para aplicar uma configuração a um visual específico, use Seletores.

Estender comandos de menu

Use os seguintes parâmetros para criar uma definição de comando:

  • name - O nome do comando.
  • title – o título do comando. Isso será usado como padrão, se não houver substituição dentro visualContextMenu de e visualOptionsMenu.
  • icon(opcional) – a imagem que você deseja exibir como um ícone. Só há suporte para ícones no menu de opções.
  • extend – defina o menu que o comando estende. Você pode adicionar o comando ao menu de contexto visual, ao menu de opções visuais ou a ambos. Também é possível personalizar as propriedades em cada menu, como o título do menu ou o local do ícone.

Adicione a definição de comando à matriz de comandos no objeto extensions, que é passado para as configurações de relatório. Commands é uma matriz de ICommandExtension dentro de extensões, que é do tipo IExtensions.

let embedConfig = {
    ...
    settings: {
        extensions: {
            commands: [...]
        }
    }
};

Você também deve manipular o commandTriggered evento para o novo comando. Esse evento é disparado especificamente para o commandName.

report.on("commandTriggered", function(event) {
    let commandName = event.detail.command;
    ...
    if (commandName === "command name") {
        // Handler code
    }
});

Para obter mais informações sobre como lidar com eventos, consulte Como lidar com eventos.

Os ícones são opcionais. Se você optar por usar um, ele deverá ser convertido em Base 64. Consulte o código a seguir para obter um exemplo de um ícone base 64 válido.

"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAMAAAD04JH5AAACcFBMVEUAAAAAAAAAAAAAAAA/Pz8zMzMqKiokJCQfHx8cHBwZGRkuLi4qKionJyckJCQiIiIfHx8cHBwoKCgmJiYkJCQiIiIhISEfHx8eHh4nJyclJSUkJCQjIyMiIiIgICAfHx8mJiYlJSUkJCQjIyMhISEgICAfHx8lJSUkJCQiIiIhISElJSUjIyMjIyMiIiIhISEhISElJSUkJCQjIyMiIiIhISEkJCQiIiIhISEkJCQjIyMjIyMiIiIiIiIhISEhISEjIyMjIyMjIyMiIiIiIiIhISEjIyMiIiIhISEkJCQjIyMiIiIiIiIiIiIhISEkJCQjIyMjIyMiIiIiIiIhISEkJCQjIyMjIyMiIiIiIiIiIiIkJCQjIyMjIyMiIiIiIiIiIiIjIyMjIyMjIyMiIiIiIiIiIiIiIiIjIyMjIyMjIyMiIiIiIiIiIiIjIyMjIyMjIyMjIyMiIiIiIiIiIiIiIiIhISEiIiIiIiIjIyMhISEiIiIiIiIiIiIjIyMjIyMjIyMjIyMhISEiIiIiIiIjIyMjIyMiIiIiIiIjIyMjIyMhISEiIiIiIiIjIyMjIyMjIyMjIyMjIyMjIyMhISEhISEiIiIjIyMjIyMhISEiIiIiIiIjIyMjIyMjIyMhISEhISEiIiIjIyMjIyMjIyMhISEhISEiIiIjIyMjIyMjIyMjIyMhISEhISEhISEiIiIjIyMjIyMjIyMhISEhISEhISEiIiIjIyMjIyMjIyMjIyMhISEhISEhISEjIyMjIyMjIyMhISEhISEhISEiIiIjIyMjIyMjIyMhISEhISEhISEhISEjIyMjIyMjIyMjIyNZpHNAAAAAz3RSTlMAAQIDBAUGBwgJCgsMDQ4PEBITFBUWFxgZGhscHR4fICEiIyQmJygpKiwtMDIzNDU2Nzg5Oz0/QkVGR0hJSktMTk9QUVJTVllbXF5fYGFiY2VmZ2hpamtsbm9wcXN0dXd4eXp7fH1+f4CBg4SFhoeIiYqLjI2OkpOUl5mam5ydnp+goaKjpKapqqyusLGys7W2uru9vr/AwsTGx8jJysvNzs/Q0dLU1dbX2Nna29zd3t/g4eLj5OXm5+jp6uvs7e7v8fLz9PX29/j5+vv8/f5uCdcaAAADyklEQVQYGe3B+0NTZQAG4NftsKFotUBFY5XiBexehnbTCEtLKaVMrKhhmVciTcuszIiiMivNUrNC0RTE1KC4RyACbrDz/ksxQISxs53z7Zzz/bLnQUJCQkJCLEmedE8yhCR70j1JEDf/xT2H6/0M6Tx3cNuyW6Fb2tPbv6u+whB/3aEPCubBKGVJeSPDqKc2ZUGH7C2nVYZpKHvcCf28u5oZ2YmVLkSV/PzvjKxp523QJ3NfgNr+XueCJvf6BmrzfzwLsaXsCDC62qXQkHuR0flLJiKGJfWM7atURDD1G8b216OIJmkXdWlehHEeaaMeaqkCTdN+oU79RQizIUidjqVBw+w/qd8eB0ZxfkT9zt+BiBY00YgvHBjhrKARjVmI4M4mGrN/AoZNKKcx/3gxztQLNGorhpXSqJpUhHEepXHLMeg5GnfEgbG2U0DXHAyY300BmzHGIpUiKhVAqaKIYA5GcddSzBvABoqpduGGjRTUk+HtpaBijJjRQ1Fln1NU93Rct5vCgkEK24Fhqd2UosuDIW9SEh+G1FKScxj0IKW5FyG7Kc1OhJyhNCcxIE2lNEEPgDxKlAvgLUpUDKCcEn0G4FdKdBzAJUp0AUAbJWoB0EuJegBco0R9AOooUQeAE5SoHsABSnQGwIeU6ACATZToPQCrKVEBgGxKdA8GNFKaqwoGlFGaHxGygtIUI2SaSlmyMKiKkpzHkC2UpARDZvZRCjUTwyooxU+4biGlWI4RlZSgTsGIVZTgFdzgbqXt2lMwSiFt58NoSg1t1jARYyylzQoQ5jBt9YeCMAv6aaccjLOXNvoS46W10jYdMxBBLm2zChHto02+R2RTLtEW/82EhoeDtMMyaHqXNtgLba5KWu7sJEThbaXFOuciqpw+WisPMbxMS5Uipk9ooYMOxOQ6TsucngwdptfTIs1e6DKvjZa4cjd0uq+LFggshm6L/TSd+iwMeCZIs62FIS/RZMUwyEdTbYNhRTRRCQSsp2negZC1Ks2xFYJWqzSDD8Ly+xk3tRBxeLKHcQqsQFwe+pdxufoY4jT3MuPQcj/iln6KwmpmwQRTDlHQUQ9MobxPIZ+6YJYX/DQsWAQTLWymQR1PwFQZJ2nI2UyYbNJ+GlAxGebL76FOgUJYIruaulx+ABZJKacOX98C66zsZAzda2Cp239mVL/NgcUcr12jpsBGBdbLrqSGqrtgC+erXYyg16fALhnfcpwfZsNOT9VyjIt5sFnSujaOaH/dDfvd9HYLB7VvvhlyuPOPdAePrUmBRIobCQkJCQnx+R9iLyo0N1V+hgAAAABJRU5ErkJggg=="

O código a seguir é um exemplo de código completo para adicionar uma extensão de comando de menu.

// Get models. Models contain enums that can be used.
let models = window['powerbi-client'].models;

let embedConfiguration = {
    type: 'report',
    id: '5dac7a4a-4452-46b3-99f6-a25915e0fe55',
    embedUrl: 'https://app.powerbi.com/reportEmbed',
    tokenType: models.TokenType.Aad,
    accessToken: 'e4...rf',
    settings: {
        ...
        extensions: {
            commands: [{
                name: "command name",
                title: "command title",
                icon: "data:image/png;base64,iVBORw0KGgoAAAANSUhEU...AAABJRU5ErkJggg==",
                extend: {
                    visualContextMenu: {
                        title: "context menu title",
                    },
                    visualOptionsMenu: {
                        title: "options menu title",
                    }
                }
            }]
        }
    }
};

...

// Embed the report and display it within the div container.
let report = powerbi.embed(embedContainer, embedConfiguration);

// Report.on will add an event handler to commandTriggered event which prints to console window.
report.on("commandTriggered", function (command) {
    console.log(command);
});

Definir o local do item de menu

Os comandos são adicionados à parte inferior do menu por padrão. Para comandos não agrupados, você pode usar a menuLocation propriedade para selecionar se um comando é colocado na parte superior ou inferior do menu.

Observação

Ao adicionar mais de uma extensão à parte superior do menu, a última extensão adicionada estará na parte superior.

Captura de tela que mostra uma tabela do Power BI com um comando de menu

Por exemplo, o código a seguir permite definir a extensão de comando do menu de opções na parte superior do menu e o comando de menu de contexto na parte inferior do menu.

extensions: {
    commands: [{
       name: "command name",
       title: "command title",
       icon: "data:image/png;base64,iVBORw0KGgoAAAANSUhEU...AAABJRU5ErkJggg==",
       extend:
       {
           visualContextMenu: {
               title: "context menu title",
               menuLocation: models.MenuLocation.Bottom
           },
           visualOptionsMenu: {
               title: "options menu title",
               menuLocation: models.MenuLocation.Top
           }
       }
    }]
}

Comandos de grupo em um submenu

Você pode criar um submenu para agrupar comandos com os seguintes parâmetros:

  • name - O nome do grupo. Esse é o identificador exclusivo do grupo.
  • title – o título a ser exibido no menu.
  • menuLocation(opcional) – escolha se o grupo é colocado na parte superior ou inferior do menu.

A definição de grupo deve ser adicionada à matriz de grupos, que é uma matriz de IMenuGroupExtension, dentro do objeto de extensões.

Captura de tela que mostra um visual do Power BI com dois comandos adicionados no novo submenu.

Se você optar por usar um valor de local de menu, Top colocará o grupo na parte superior do menu no momento da adição do primeiro comando do grupo. Se não for usado ou ao usar o Bottom valor , o grupo será adicionado na parte inferior do menu no momento da adição do primeiro comando do grupo.

Para adicionar um comando a um grupo que foi definido na matriz de grupo, adicione a groupName propriedade ao comando .

O código a seguir é um exemplo de código completo de como adicionar um submenu ao menu de opções com dois comandos dentro dele.

extensions: {
    commands: [
        {
            name: "Command 1",
            title: "Command 1",
            extend: {
                visualOptionsMenu: {
                    groupName: "group-unique-identifier"
                }
            }
        },
        {
            name: "Command 2",
            title: "Command 2",
            extend: {
                visualOptionsMenu: {
                    groupName: "group-unique-identifier"
                }
            }
        }
    ],
    groups: [{
        name: "group-unique-identifier",
        title: "Group title",
        menuLocation: models.MenuLocation.Top
    }]
}

Personalizar comandos de menu

A exibição de comandos internos tem três modos de exibição.

  • Habilitado – o comando será exibido se estiver disponível para o visual.
  • Desabilitado – o comando será exibido se estiver disponível para o visual, mas estiver esmaecido (o usuário não pode selecionar o comando).
  • Oculto – o comando não aparece.

Os comandos internos disponíveis no momento são:

  • copy – copiar valor, seleção ou visual. Disponível somente no menu de contexto (o visual está disponível apenas no modo de edição).
  • drill – use o modo de análise. Disponível somente no menu de contexto.
  • detalhamento – use o recurso de detalhamento . Disponível somente no menu de contexto.
  • expandCollapse – expanda ou recolha a seleção, o nível inteiro ou a hierarquia inteira. Disponível somente no menu de contexto.
  • exportData – exporte os dados que foram usados para criar uma visualização. Disponível somente no menu de opções.
  • includeExclude – incluir ou excluir pontos de dados. Disponível somente no menu de contexto.
  • removeVisual – exclua o visual. Disponível somente no menu de opções no modo de edição.
  • search – alterne a opção de pesquisa para uma segmentação de dados. Disponível somente no modo de edição.
  • seeData – exibe os dados que foram usados para criar uma visualização (também conhecido como Mostrar como uma tabela).
  • classificar – classifique e selecione a ordem de classificação dos valores por um campo de dados selecionado. Disponível somente no menu de opções.
  • destaque – destacar um visual. Disponível somente no menu de opções.
  • insightsAnalysis – exibir insights sobre o visual. Disponível somente no menu opções.
  • addComment - Adicione um comentário ao visual. Disponível somente no menu opções.
  • groupVisualContainers - Disponível somente no menu de contexto no modo de edição.
  • summarize – exibir um resumo da visualização. Disponível somente no menu de contexto.
  • clearSelection - Disponível somente no menu de contexto.

Para personalizar a exibição de comandos internos, defina e passe um objeto de comando nas definições de configuração de inserção. Os comandos são uma matriz de ICommandsSettings.

let embedConfig = {
    ...
    settings: {
        commands: [...]
    }
};

O código a seguir é um exemplo de código completo para adicionar comandos internos.

// The new settings that you want to apply to the report.
const newSettings = {
    commands: [
        {
            spotlight: {
                displayOption: models.CommandDisplayOption.Hidden,
            },
            drill: {
                displayOption: models.CommandDisplayOption.Disabled,
            }
        }
    ]
};

// Update the settings by passing in the new settings you have configured.
await report.updateSettings(newSettings);

Conteúdo relacionado