DetailsList controle

Um controle usado para exibir um conjunto de dados.

Descrição

Uma lista de detalhes (DetailsList) é uma maneira robusta de exibir uma coleção de itens rica em informações e permitir que as pessoas classifiquem, agrupem e filtrem o conteúdo. Use um DetailsList quando a densidade das informações for crítica.

O componente de código DetailsList permite usar o componente DetailsList do Fluent UI em aplicativos de tela e páginas personalizadas.

• Pode ser vinculado a um conjunto de dados ou coleção local do Dataverse.
• Oferece suporte a colunas configuráveis separadas dos metadados de coluna fornecidos pelo conjunto de dados de origem para flexibilidade.
• Tipos de células para links, ícones, expansão/recolhimento e células com texto secundário.
• Suporte para paginação.
• Suporte para classificação usando a classificação do Dataverse ou propriedades SortBy configuráveis.

Propriedades

Principais Propriedades

Propriedades do Items

Esses atributos devem estar disponíveis na fonte de dados para habilitar a funcionalidade relacionada. A fórmula Power Fx AddColumns() pode ser usada para anexar esses valores à fonte de dados original.

Propriedades do Columns

Propriedade	Descrição
ColDisplayName	(Obrigatório) - Fornece o nome da coluna a ser exibida no cabeçalho.
ColName	(Obrigatório) - Fornece o nome real do campo da coluna na coleção Items.
ColWidth	(Obrigatório) - Fornece a largura fixa absoluta da coluna em pixels.
ColCellType	O tipo de célula a ser renderizada. Valores possíveis: expand, tag, indicatortag, image, clickableimage, link. Para obter mais informações, consulte as próximas seções.
ColHorizontalAlign	O alinhamento do conteúdo da célula se o ColCellType for do tipo image ou clickableimage.
ColVerticalAlign	O alinhamento do conteúdo da célula se o ColCellType for do tipo image ou clickableimage.
ColMultiLine	Verdadeiro quando o texto nas células deve ser quebrado em várias linhas, caso seja longo demais para caber na largura disponível.
ColResizable	Verdadeiro quando a largura do cabeçalho da coluna puder ser redimensionada.
ColSortable	Verdadeiro quando a coluna deve ser ordenável. Se o conjunto de dados oferecer suporte à classificação automática por meio de uma conexão direta com o Dataverse, os dados serão classificados automaticamente. Caso contrário, as saídas SortEventColumn e SortEventDirection serão configuradas e deverão ser usadas na expressão de associação de registros no Power FX.
ColSortBy	O nome da coluna a ser fornecida para o evento OnChange quando a coluna for classificada. Por exemplo, se você estiver classificando colunas de data, você quer classificar pelo valor de data real, em vez de texto formatado mostrado na coluna.
ColIsBold	Verdadeiro quando os dados da célula de dados devem estar em negrito
ColTagColorColumn	Se o tipo de célula for marca, defina a cor de fundo hexadecimal da marca de texto. Pode ser definido como transparent. Se o tipo de célula não for uma tag, defina como uma cor hexadecimal para usar como uma célula de tag com círculo indicador. Se o valor do texto estiver vazio, a tag não será exibida.
ColTagBorderColorColumn	Defina uma cor hexadecimal para usar como cor da borda de uma tag de texto. Pode ser definido como transparent.
ColHeaderPaddingLeft	Adiciona espaçamento interno ao texto do cabeçalho da coluna (em pixels)
ColShowAsSubTextOf	Definir este valor como o nome de outra coluna fará com que a coluna se torne filha dessa coluna. Veja abaixo, nas colunas de Subtexto.
ColPaddingLeft	Adiciona espaçamento interno à esquerda da célula filha (pixels)
ColPaddingTop	Adiciona espaçamento interno à parte superior da célula filha (pixels)
ColLabelAbove	Move o rótulo para cima do valor da célula filha, se ele for exibido como uma coluna de subtexto.
ColMultiValueDelimiter	Une os valores de um array multivalorado usando este delimitador. Veja abaixo, em colunas multivaloradas.
ColFirstMultiValueBold	Ao mostrar um valor de matriz com vários valores, o primeiro item é mostrado em negrito.
ColInlineLabel	Se definido como um valor de string, isso é usado para mostrar um rótulo dentro do valor da célula que pode ser diferente do nome da coluna. por exemplo
ColHideWhenBlank	Quando verdadeiro, qualquer rótulo embutido e padding da célula serão ocultados se o valor da célula estiver em branco.
ColSubTextRow	Ao mostrar várias células em uma célula de texto secundário, defina-o como o índice da linha. Zero indica a linha de conteúdo da célula principal.
ColAriaTextColumn	A coluna que contém a descrição ária das células (por exemplo, células de ícone).
ColCellActionDisabledColumn	A coluna que contém um sinalizador booleano para controlar se uma ação em uma célula (por exemplo, células com ícone) está desabilitada.
ColImageWidth	O tamanho do ícone/imagem em pixels.
ColImagePadding	O preenchimento em torno de uma célula de ícone ou imagem.
ColRowHeader	Define uma coluna para ser renderizada maior do que as outras células (14 px em vez de 12 px). Normalmente, haveria apenas um Cabeçalho de Linha por conjunto de colunas.

Propriedades de Estilo

Propriedades do evento

Uso Básico

Para determinar quais colunas são exibidas no DetailsList, configure as seguintes propriedades do DetailsList:

1. Campos. Adicione os campos desejados, selecionando a opção Editar no submenu de controles à direita (usa a mesma interface para modificar cartões de dados predefinidos).

2. Colunas. Forneça mapeamento específico entre colunas e campos na propriedade Columns.

Exemplo:

Mapeamento para a tabela do sistema do Dataverse Contas, com a seguinte fórmula:

Table(
    {
        ColName: "name",
        ColDisplayName: "Name",
        ColWidth: 200,
        ColSortable: true,
        ColIsBold: true,
        ColResizable: true
    },{
        ColName: "address1_city",
        ColDisplayName: "City:",
        ColShowAsSubTextOf: "name"
    },{
        ColName: "address1_country",
        ColDisplayName: "Country:",
        ColShowAsSubTextOf: "name"
    },{
        ColName: "telephone1",
        ColDisplayName: "Telephone",
        ColWidth: 100,
        ColSortable: true,
        ColResizable: true
    },{
        ColName: "primarycontactid",
        ColDisplayName: "Primary Contact",
        ColWidth: 200,
        ColSortable: true,
        ColSortBy: "_primarycontactid_value",
        ColResizable: true,
        ColCellType: "link"
    }
)

Colunas de Subtexto

A propriedade da coluna ColShowAsSubTextOf define uma coluna como sendo mostrada abaixo do valor em outra coluna. Isso pode ser usado para mostrar informações secundárias e conteúdo expansível (veja abaixo).

Se você tivesse uma coleção definida como:

ClearCollect(colAccounts,
{id:"1",name:"Contoso",city:"Redmond",country:"U.S.",description:"Lorem ipsum dolor sit amet, consectetur adipiscing elit.",expand:false},
{id:"2",name:"Litware, Inc",city:"Dallas",country:"U.S.",description:"Donec vel pellentesque turpis.",expand:false});

Você poderia definir as colunas como:

Table(
    {
        ColName: "name",
        ColDisplayName: "Account Name",
        ColWidth: Self.Width-100,
        ColIsBold:true
    },
    {
        ColName: "city",
        ColDisplayName: "City:",
        ColShowAsSubTextOf:"name",
        ColLabelAbove:false,
        ColIsBold:true,
        ColSubTextRow: 1
    },
    {
        ColName: "country",
        ColDisplayName: "Country:",
        ColShowAsSubTextOf:"name",
        ColLabelAbove:false,
        ColIsBold:true,
        ColSubTextRow: 1
    },
    {
        ColName: "description",
        ColDisplayName: "",
        ColShowAsSubTextOf:"name",
        ColLabelAbove:false,
        ColIsBold:false,
        ColSubTextRow: 2
    }
)

O resultado seria uma tabela semelhante à seguinte:

Tipos de Célula

A propriedade da coluna ColCellType aceita os seguintes valores: expand, tag, image, indicatortag, clickableimage, link

Expandir/Recolher

Se as linhas de 'Sub Text' precisarem ter um ícone de expandir/recolher, uma coluna adicional poderá ser adicionada ao conjunto de dados de colunas, e o conjunto de definição de colunas ColCellTypeexpand também poderá ser definido:

{ColName:"expand",ColDisplayName:"",ColWidth:32,ColResponsive:false, ColRightAligned:true, ColCellType:"expand"}

Supondo que a propriedade RecordKey esteja definida para a coluna index, o evento OnChange poderá então conter o seguinte para expandir/recolher as linhas:

If(Self.EventName="CellAction" && Self.EventColumn="expand",
    With(LookUp(colExpand,index=Self.EventRowKey) As Row,
        Patch(colExpand,Row,{expand:!Row.expand})
        )
);

Isso procura a linha na qual a Ação da Célula foi invocada usando o índice (se nenhum RecordKey tiver sido definido, então o EventRowKey conterá o número da linha) e, em seguida, alterna o valor de expansão.

Isso dará o seguinte resultado:

Tag & Tag indicadora

Usando um tipo de célula de tag ou indicatortag, você pode criar marcas coloridas em linha para exibir o conteúdo da célula.

• tag - Isso exibirá uma caixa de tag com fundo e borda coloridos
• tagindicator- mostra uma caixa de etiquetas com um indicador de círculo colorido

As cores podem variar de acordo com a linha e, portanto, o conjunto de dados de metadados das colunas simplesmente fornece o nome das colunas que armazenam as cores das tags.

Considere o conjunto de dados:

ClearCollect(
    colAccounts,
    {
        name: "Contoso",
        city: "Redmond",
        country: "U.S.",
        TagColor: "rgb(0, 183, 195)",
        TagBorderColor: "rgb(0,137,147)"
    },
    {
        name: "Litware, Inc",
        city: "Dallas",
        country: "U.S.",
        TagColor: "rgb(255, 140, 0)",
        TagBorderColor: "rgb(194,107,0)"
    }
);

Você pode então adicionar os metadados das colunas para incluir duas colunas: uma exibida como uma tag e a outra como um tagindicator, cada uma usando as colunas TagColor e TagBorderColor para definir as cores:

{
        ColName: "country",
        ColDisplayName: "Country",
        ColCellType:"tag",
        ColWidth: 60,
        ColTagColorColumn: "TagColor",
        ColTagBorderColorColumn: "TagBorderColor"
},
{
        ColName: "country",
        ColDisplayName: "Country",
        ColCellType:"indicatortag",
        ColWidth: 60,
        ColTagColorColumn: "TagColor",
        ColTagBorderColorColumn: "TagBorderColor"
}

Isso dará o seguinte resultado:

Imagem e imagem clicável

Usando um tipo de célula image ou clickableimage, você pode configurar imagens em linha que podem, opcionalmente, ser selecionadas para acionar a ação OnChange.

O conteúdo da imagem pode ser definido prefixando com:

• https: Um link para uma imagem externa. Por exemplo, https://via.placeholder.com/100x70
• icon: Usando um dos ícones do Fluent UI, por exemplo, icon:SkypeCircleCheck
• data: Usando dados de imagem svg em linha: por exemplo, data:image/svg+xml;utf8, %3Csvg%20%20viewBox%3D%270%200%2020...

Se a imagem for do tipo clickableimage, o evento OnChange será acionado quando o ícone for selecionado, com um EvenName de CellAction, EventColumn fornecendo o nome da coluna de imagem e EventRowKey sendo o RecordKey da linha (se nenhum RecordKey estiver definido, então o EventRowKey conterá o número da linha).

Por exemplo, considere os dados da linha:

{
        id: "1",
        name: "Contoso",
        city: "Redmond",
        country: "U.S.",
        ImageColor: "rgb(0, 183, 195)",
        externalimage: "https://via.placeholder.com/100x70",
        iconimage: "icon:SkypeCircleCheck"
    },
    {
        id: "2",
        name: "Litware, Inc",
        city: "Dallas",
        country: "U.S.",
        ImageColor: "rgb(255, 140, 0)",
        externalimage: "https://via.placeholder.com/100x70",
        iconimage: "icon:SkypeCircleCheck"
    }

e os metadados da coluna:

 {
        ColName: "externalimage",
        ColDisplayName: "Image",
        ColCellType:"image",
        ColWidth: 60,
        ColImageWidth: 60,
        ColImagePadding: 8,
        ColVerticalAlign: "Top"
},
{
        ColName: "iconimage",
        ColDisplayName: "Clickable Image",
        ColCellType:"clickableimage",
        ColWidth: 60,
        ColImageWidth: 60,
        ColImagePadding: 8,
        ColVerticalAlign: "Top"
}

Isso daria o resultado:

Para a coluna clickableimage, o evento OnChange pode então tratar quando um usuário seleciona (com o mouse ou o teclado) um ícone (supondo que ele não esteja desativado) usando:

If(Self.EventName="CellAction",
	Notify("CellAction " & Self.EventColumn & " " & Self.EventRowKey)
)

O EventRowKey será preenchido com o valor da coluna definido como a propriedade RecordKey.

Links

As colunas podem ser renderizadas como links, que acionarão o evento OnChange quando o link for selecionado de maneira semelhante à forma como as imagens clicáveis descritas acima funcionam.

Os metadados da coluna para um link são configurados da seguinte forma:

  {
        ColName: "name",
        ColDisplayName: "Account Name",
        ColWidth: 150,
        ColIsBold:true,
        ColCellType: "link"
    }

Isso resultará no conteúdo da célula sendo renderizado como:

O evento OnChange é acionado novamente quando o link é clicado, com o EventColumn sendo o nome da coluna que contém o link, e o EventRowKey preenchido com o valor da coluna definido como a propriedade RecordKey.

Colunas de vários valores

Se um valor de coluna puder ter vários valores, definindo-o como uma Tabela/Coleção. Isso renderizará os valores como valores de várias células. por exemplo:

 {
        id: "1",
        name: "Contoso",
        tags:["#PowerApps","#PowerPlatform"]
    },

Os metadados da coluna podem ser:

 {
        ColName: "tags",
        ColDisplayName: "Tags",
        ColWidth: 250,
        ColFirstMultiValueBold :true,
        ColMultiValueDelimiter:" "
    }

Isso resultaria na tabela mostrando:

Comportamento

Classificar Eventos

Uma coluna é definida como classificável definindo a propriedade ColSortable como verdadeira. Se a coluna mostrar um valor de texto diferente da ordem de classificação exigida (por exemplo, uma coluna de data ou status formatada), uma coluna de classificação diferente poderá ser especificada usando a propriedade ColSortBy.

A classificação é então tratada de duas maneiras:

1. Automaticamente, quando conectado a uma fonte de dados do Dataverse.
2. Manualmente ao usar coleções.

Classificação Automática

Quando o conjunto de dados de Itens for um conjunto de dados nativo do Dataverse, ele será classificado automaticamente, se uma coluna for marcada como classificável. Se houver alguma alteração feita na forma de uma coleção do Dataverse usando AddColumn, ou armazenando os dados em uma coleção, a classificação automática não funcionará mais e a classificação manual deverá ser implementada.

Classificação Manual

A classificação manual tem suporte fora do componente para permitir suporte a conectores personalizados e a classificação de coleções locais quando não houver conexão com o Dataverse. As colunas podem ser definidas como classificáveis ou não. Quando a ordenação da coluna é selecionada, um evento OnChange é disparado, fornecendo a coluna e a direção. O aplicativo deve usar esses valores para alterar a coleção vinculada à tabela para atualizar com os registros classificados.

1. Na coleção Colunas, adicione uma coluna booliana classificável

2. Adicione o nome da coluna classificável à propriedade Columns.ColSortable

3. Dentro do evento OnChange da Tabela, adicione o código:

   If(Self.EventName="Sort", 
   UpdateContext({
                   ctxSortCol:Self.SortEventColumn,
                   ctxSortAsc:If(Self.SortEventDirection='PowerCAT.FluentDetailsList.SortEventDirection'.Ascending,true,false)
    })
   );
   

4. Defina a propriedade Sort Column como ctxSortCol

5. Defina a propriedade Sort Direction para:

   If(ctxSortAsc,
       'PowerCAT.FluentDetailsList.CurrentSortDirection'.Ascending,
       'PowerCAT.FluentDetailsList.CurrentSortDirection'.Descending) 
   

6. Defina a coleção de itens de entrada para classificar usando as variáveis de contexto definidas acima:

   SortByColumns(colData,ctxSortCol,If(ctxSortAsc,SortOrder.Ascending,SortOrder.Descending))
   

Quando o evento OnChange é acionado depois que o usuário seleciona no cabeçalho da coluna para alterar a classificação, as variáveis de contexto de classificação são atualizadas, usando as novas informações de classificação fornecidas, o que faz com que o conjunto de dados de entrada seja reclassificado e a tabela seja atualizada adequadamente.

Paginação

A paginação é tratada internamente pelo componente, porém os botões para retroceder/avançar devem ser criados pelo aplicativo de hospedagem e os eventos enviados para o componente.

As seguintes propriedades são usadas para controlar a paginação:

• PageSize - Define quantos registros devem ser carregados por página.
• PageNumber - Exibe a página atual mostrada.
• HasNextPage - Retorna verdadeiro se houver uma próxima página.
• HasPreviousPage - Retorna verdadeiro se houver uma página anterior.
• TotalRecords - Exibe o número total de registros disponíveis.

Os botões de paginação podem ser definidos da seguinte forma:

• Carregar Primeira Página
  • OnSelect: UpdateContext({ctxGridEvent:"LoadFirstPage" & Text(Rand())})
  • DisplayMode: If(grid.HasPreviousPage,DisplayMode.Edit,DisplayMode.Disabled)
• Carregar Página Anterior
  • OnSelect: UpdateContext({ctxGridEvent:"LoadPreviousPage" & Text(Rand())})
  • DisplayMode: If(grid.HasPreviousPage,DisplayMode.Edit,DisplayMode.Disabled)
• Carregar Próxima Página
  • OnSelect: UpdateContext({ctxGridEvent:"LoadNextPage" & Text(Rand())})
  • DisplayMode: If(grid.HasNextPage,DisplayMode.Edit,DisplayMode.Disabled)

O rótulo do número de registros pode ser definido como uma expressão semelhante a:

grid.TotalRecords & " record(s)  " & Text(CountRows(grid.SelectedItems)+0) & " selected" 

Mostrar o topo da próxima página

Isso é implementado usando o evento 'SetFocusOnRow'. Se você tivesse a propriedade InputEvent vinculada a ctxGridEvent, na propriedade OnSelect do botão da próxima página, você usaria: UpdateContext({ctxGridEvent:"LoadNextPageSetFocusOnRow" & Text(Rand())});

Eventos de entrada

A propriedade InputEvent pode ser definida com um ou mais dos seguintes valores:

• SetFocus - Define o foco na primeira linha da grade
• ClearSelection - Limpa qualquer seleção e retorna à seleção padrão.
• SetSelection - Define a seleção, conforme definido pela coluna RowSelected.
• LoadNextPage - Carrega a próxima página, se houver
• LoadPreviousPage - Carrega a página anterior, se houver uma
• LoadFirstPage - Carrega a primeira página

Para garantir que o evento de entrada seja capturado, ele deve ser complementado com um valor aleatório. Por exemplo, SetSelection" & Text(Rand())

Consulte abaixo para obter detalhes.

Itens Selecionados e Ações de Linha

O componente suporta os modos de seleção Único, Múltiplo ou Nenhum.

Ao selecionar os itens, as propriedades SelectedItems e Selected são atualizadas.

• SelectedItems - Se a tabela estiver no modo Seleção múltipla, conterá um ou mais registros da coleção Itens.
• Selected - Se a tabela estiver no modo de seleção Única, conterá os registros selecionados.

Quando um usuário chama a ação de linha, clicando duas vezes ou pressionando Enter ou uma linha selecionada, o evento OnSelect é acionado. A propriedade Selected conterá uma referência ao registro que foi chamado. Este evento pode ser usado para mostrar um registro detalhado ou navegar para outra tela.

Se a propriedade RaiseOnRowSelectionChangeEvent estiver habilitada, quando as linhas selecionadas forem alteradas, o evento OnChange será gerado com o EventName definido como OnRowSelectionChange. Se o aplicativo precisar responder a uma seleção de linha única em vez de um clique duplo de linha, o OnChange pode detectar isso usando um código semelhante a:

If(
    Self.EventName = "OnRowSelectionChange",
        If(!IsBlank(Self.EventRowKey),
        	// Row Selected
        )
);

Limpar os itens atualmente selecionados

Para limpar os registros selecionados, você deve definir a propriedade InputEvent como uma string que começa com

por exemplo

UpdateContext({ctxTableEvent:"ClearSelection"&Text(Rand())})

A variável de contexto ctxTableEvent pode então ser vinculada à propriedade InputEvent.

Configurar seleção de linha

Se houver um cenário em que um conjunto específico de registros deva ser selecionado de forma programada, a propriedade InputEvent poderá ser definida como SetSelection ou SetFocusOnRowSetSelection, em combinação com a configuração da propriedade RecordSelected no registro.

por exemplo, se você tivesse um conjunto de dados da seguinte forma:

{RecordKey:1, RecordSelected:true, name:"Row1"}

Para selecionar e selecionar a primeira linha, você pode definir o InputEvent para ser "SetFocusOnRowSetSelection"&Text(Rand()) ou "SetSelection"&Text(Rand())

Configurar o comportamento "On Change"

Adicione e modifique a seguinte fórmula na propriedade OnChange do componente para configurar ações específicas com base no EventName fornecido pelo componente:

• Acione eventos quando um usuário alterar a linha selecionada: habilite a propriedade Gerar evento OnRowSelectionChange no componente.
• Configure o comportamento do link: adicione colunas com o valor ColCellType definido como link.

/* Runs when selected row changes and control property 'Raise OnRowSelection event' is true */
If( Self.EventName = "OnRowSelectionChange",
    Notify( "Row Select " & Self.EventRowKey )
);

/* Runs when a user selects a column with ColCellType set to 'link' */
If( Self.EventName = "CellAction",
    Notify( "Open Link " &  Self.EventColumn & " " & Self.EventRowKey )
)

Limitações

Esse componente de código só pode ser usado em aplicativos de tela e páginas personalizadas.