Manipulando a navegação

As Tabelas de Navegação (ou tabelas de navegação) são uma parte fundamental do fornecimento de uma experiência amigável para o conector. A Power Query de dados os exibe ao usuário depois que ele inseriu os parâmetros necessários para a função de fonte de dados e se autenticou com a fonte de dados.

A tabela de navegação TripPin.

Nos bastidores, uma tabela de nav é apenas um valor de Tabela M regular com campos de metadados específicos definidos em seu Tipo. Quando a função de fonte de dados retornar uma tabela com esses campos definidos, Power Query exibirá a caixa de diálogo do navegador. Na verdade, você pode ver os dados subjacentes como um valor de Tabela clicando com o botão direito do mouse no nó raiz e selecionando Editar.

Table.ToNavigationTable

Você pode usar Table.ToNavigationTable a função para adicionar os metadados de tipo de tabela necessários para criar uma tabela de nav.

Observação

No momento, você precisa copiar e colar essa função em sua extensão M. No futuro, ele provavelmente será movido para a biblioteca padrão M.

A tabela a seguir descreve os parâmetros para essa função:

Parâmetro Detalhes
tabela Sua tabela de navegação.
Keycolumns Lista de nomes de coluna que atuam como a chave primária para sua tabela de navegação.
Namecolumn O nome da coluna que deve ser usada como o nome de exibição no navegador.
Datacolumn O nome da coluna que contém a Tabela ou Função a ser exibida.
itemKindColumn O nome da coluna a ser usada para determinar o tipo de ícone a ser exibido. Confira abaixo a lista de valores válidos para a coluna.
itemNameColumn O nome da coluna a ser usada para determinar o comportamento de visualização. Normalmente, isso é definido com o mesmo valor que itemKind.
isLeafColumn O nome da coluna usada para determinar se este é um nó folha ou se o nó pode ser expandido para conter outra tabela de navegação.

A função adiciona os seguintes metadados ao tipo de tabela:

Campo Parâmetro
NavigationTable.NameColumn Namecolumn
NavigationTable.DataColumn Datacolumn
NavigationTable.ItemKindColumn itemKindColumn
NavigationTable.IsLeafColumn isLeafColumn
Preview.DelayColumn itemNameColumn

Valores para ItemKind

Cada um dos valores de tipo de item a seguir fornece um ícone diferente na tabela de navegação.

  • Feed
  • Cubo
  • CubeDatabase
  • CubeView
  • CubeViewFolder
  • Banco de dados
  • DatabaseServer
  • Dimensão
  • Tabela
  • Pasta
  • Função
  • Visualizar
  • Folha
  • Subcubo
  • Definedname
  • Record

A imagem abaixo mostra os ícones para tipos de item Power BI Desktop.

Lista de ItemKinds da Tabela de Navegação.

Exemplos

Tabela de navegação simples

O exemplo de código a seguir exibe uma tabela de nav simples com três tabelas e uma função.

shared NavigationTable.Simple = () =>
    let
        objects = #table(
            {"Name",       "Key",        "Data",                           "ItemKind", "ItemName", "IsLeaf"},{
            {"Item1",      "item1",      #table({"Column1"}, {{"Item1"}}), "Table",    "Table",    true},
            {"Item2",      "item2",      #table({"Column1"}, {{"Item2"}}), "Table",    "Table",    true},
            {"Item3",      "item3",      FunctionCallThatReturnsATable(),  "Table",    "Table",    true},            
            {"MyFunction", "myfunction", AnotherFunction.Contents,       "Function", "Function", true}
            }),
        NavTable = Table.ToNavigationTable(objects, {"Key"}, "Name", "Data", "ItemKind", "ItemName", "IsLeaf")
    in
        NavTable;

shared FunctionCallThatReturnsATable = () =>
    #table({"DynamicColumn"}, {{"Dynamic Value"}});

Esse código resultará na seguinte exibição do Navegador Power BI Desktop:

Um exemplo de uma tabela de navegação simples.

Tabela de navegação de vários níveis

É possível usar tabelas de navegação aninhadas para criar uma exibição hierárquica sobre seu conjunto de dados. Você faz isso definindo o valor dessa linha como (que a marca como um nó que pode ser expandido) e formatar a coluna para também ser IsLeaf false outra tabela de Data nav.

shared NavigationTable.Nested = () as table =>
    let
        objects = #table(
            {"Name",       "Key",  "Data",                "ItemKind", "ItemName", "IsLeaf"},{
            {"Nested A",   "n1",   CreateNavTable("AAA"), "Table",    "Table",    false},
            {"Nested B",   "n2",   CreateNavTable("BBB"), "Table",    "Table",    false},
            {"Nested C",   "n3",   CreateNavTable("CCC"), "Table",    "Table",    false}
        }),
        NavTable = Table.ToNavigationTable(objects, {"Key"}, "Name", "Data", "ItemKind", "ItemName", "IsLeaf")
    in
        NavTable;

CreateNavTable = (message as text) as table => 
    let
        objects = #table(
            {"Name",  "Key",   "Data",                           "ItemKind", "ItemName", "IsLeaf"},{
            {"Item1", "item1", #table({"Column1"}, {{message}}), "Table",    "Table",    true},
            {"Item2", "item2", #table({"Column1"}, {{message}}), "Table",    "Table",    true}
        }),
        NavTable = Table.ToNavigationTable(objects, {"Key"}, "Name", "Data", "ItemKind", "ItemName", "IsLeaf")
    in
        NavTable;

Esse código resultaria na seguinte exibição do Navegador Power BI Desktop:

Um exemplo de uma tabela de navegação hierárquica.

Tabelas de navegação dinâmica

Funcionalidades mais complexas podem ser criadas com base nesses conceitos básicos. Embora todos os exemplos acima mostrem entidades em código na tabela de nav, é fácil ver como uma tabela de nav pode ser gerada dinamicamente com base em entidades que estão disponíveis para um determinado usuário. Algumas considerações importantes para tabelas de navegação dinâmica incluem:

  • Tratamento de erros para garantir uma boa experiência para usuários que não têm acesso a determinados pontos de extremidade.
  • A avaliação do nó é lento por padrão; nós folha não são avaliados até que o nó pai seja expandido. Determinadas implementações de tabelas de nav dinâmicas de vários níveis podem resultar em uma avaliação rápida de toda a árvore. Monitore o número de chamadas que Power Query está fazendo, pois ela renderiza inicialmente a tabela de navegação. Por exemplo, Table.InsertRows é 'lazier' do que Table.FromRecords , pois não precisa avaliar seus argumentos.