DetailsList controlo

Um controlo utilizado para apresentar um conjunto de dados.

Descrição

Uma lista de detalhes (DetailsList) é uma forma robusta de apresentar uma coleção de itens rica em informações e permitir que as pessoas ordenem, agrupem e filtrem o conteúdo. Utilize um DetailsList quando a densidade de informações for crucial.

O componente de código DetailsList permite utilizar o componente DetailsList do Fluent UI em aplicações de tela e páginas personalizadas.

• Pode estar dependente de uma coleção local ou um conjunto de dados do Dataverse.
• Suporta colunas configuráveis separadas dos metadados das colunas fornecidos pelo conjunto de dados de origem, para maior flexibilidade.
• Tipos de célula para ligações, ícones, expandir/fechar e células de subtexto.
• Suporte para paginação.
• Suporte para ordenação, quer através da ordenação do Dataverse, quer através de propriedades SortBy configuráveis.

Propriedades

Propriedades-chave

Propriedades Items

Estes atributos têm de estar disponíveis na origem de dados para ativar a funcionalidade relacionada. A fórmula do Power Fx AddColumns() pode ser utilizada para anexar estes valores à origem de dados original.

Propriedades Columns

Propriedade	Descrição
ColDisplayName	(Obrigatório) – Fornece o nome da coluna a mostrar no cabeçalho.
ColName	(Obrigatório) – Fornece o nome efetivo do campo correspondente à coluna na coleção Items.
ColWidth	(Obrigatório) – Fornece a largura fixa absoluta da coluna em pixéis.
ColCellType	O tipo de célula a apresentar. Valores possíveis: expand, tag, indicatortag, image, clickableimage, link. Para obter mais informações, consulte as secções seguintes.
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	True quando o texto no texto das células deve ser encapsulado se for demasiado comprido para se adaptar à largura disponível.
ColResizable	True quando a largura do cabeçalho da coluna deve ser redimensionável.
ColSortable	True quando a coluna deve ser passível de ordenação. Se o conjunto de dados suportar a ordenação automática através de uma ligação direta do Dataverse, os dados serão ordenados automaticamente. Caso contrário, as saídas SortEventColumn e SortEventDirection ficarão definidas e têm de ser utilizadas na expressão de associação Power FX dos registos.
ColSortBy	O nome da coluna a fornecer ao evento OnChange quando essa coluna é ordenada. Por exemplo, se estiver a ordenar colunas de data, pretende ordenar pelo valor de data real, em vez de ordenar pelo texto formatado mostrado na coluna.
ColIsBold	True quando os dados da célula de dados devem estar a negrito
ColTagColorColumn	Se o tipo de célula for etiqueta, defina para a cor de fundo hexadecimal da etiqueta de texto. Pode ser definido como transparent. Se o tipo de célula não for uma tag, defina-a como uma cor hexadecimal para a utilizar como célula de tag com círculo indicador. Se o valor de texto estiver vazio, a etiqueta não é mostrada.
ColTagBorderColorColumn	Defina como uma cor hexadecimal para ser utilizada como a cor da borda de uma etiqueta de texto. Pode ser definido como transparent.
ColHeaderPaddingLeft	Adiciona preenchimento ao texto do cabeçalho da coluna (pixéis)
ColShowAsSubTextOf	Definir isto como o nome de outra coluna moverá a coluna para que passe a ser uma coluna filha dessa coluna. Consulte abaixo, nas colunas de Subtexto.
ColPaddingLeft	Adiciona preenchimento à esquerda da célula filha (pixéis)
ColPaddingTop	Adiciona espaçamento interno na parte superior da célula filha (píxeis)
ColLabelAbove	Move o rótulo acima do valor da célula secundária, se este for apresentado como uma coluna de subtexto.
ColMultiValueDelimiter	Une os valores de um array multivalor com este delimitador. Consulte abaixo, sob colunas de múltiplos valores.
ColFirstMultiValueBold	Quando mostra um valor de matriz de múltiplos valores, o primeiro item é mostrado a negrito.
ColInlineLabel	Se estiver definido como uma cadeia de caracteres, é utilizado para apresentar um rótulo no valor da célula que pode ser diferente do nome da coluna. por exemplo
ColHideWhenBlank	Quando for verdadeiro, qualquer rótulo em linha e padding da célula serão ocultados se o valor da célula estiver vazio.
ColSubTextRow	Ao mostrar várias células numa célula de texto secundário, defina esse valor para o índice da linha. Zero indica a linha de conteúdo da célula principal.
ColAriaTextColumn	A coluna que contém a descrição ARIA das células (por exemplo, células com ícone).
ColCellActionDisabledColumn	A coluna que contém um sinalizador booleano que controla se uma ação numa célula (por exemplo, células com ícone) está desativada.
ColImageWidth	O tamanho do ícone/imagem, em pixéis.
ColImagePadding	O preenchimento em torno de uma célula de ícone/imagem.
ColRowHeader	Define uma coluna para ser apresentada com um tamanho maior do que as restantes células (14 px em vez de 12 px). Normalmente, existiria apenas um cabeçalho de linha em cada conjunto de colunas.

Propriedades de Estilo

Propriedades do evento

Utilização Básica

Para determinar que colunas são apresentadas no DetailsList, configure as seguintes propriedades do DetailsList:

1. Campos. Adicione os campos que pretende selecionando a opção Editar no menu da lista de opções dos controlos à direita (isto utiliza 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 Contas do Dataverse, com a fórmula seguinte:

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 de coluna ColShowAsSubTextOf define uma coluna como sendo mostrada abaixo do valor noutra coluna. Este valor pode ser utilizado para mostrar informações secundárias e conteúdo expansível (consulte abaixo).

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

Pode 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 será uma tabela com o seguinte aspeto:

Tipos de Célula

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

Expandir/Fechar

Se as linhas de "Sub Text" precisarem de ter um ícone de expandir/recolher, pode ser adicionada uma coluna adicional ao conjunto de dados das colunas, e também definir ColCellTypeexpand na definição da coluna:

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

Partindo do princípio que uma propriedade RecordKey está definida para a coluna index, o evento OnChange poderá conter o seguinte para expandir/fechar as linhas:

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

Procura a linha em que a ação da célula foi invocada, utilizando o índice (se não estiver definido nenhum RecordKey, o EventRowKey conterá o número da linha) e, em seguida, alterna o valor de expansão.

Isto apresentará o seguinte resultado:

Etiqueta & Etiqueta indicadora

Ao utilizar um tipo de célula de tag ou indicatortag, pode criar etiquetas coloridas inline para apresentar o conteúdo da célula.

• tag — Isto irá mostrar uma caixa de etiqueta com um fundo e limite coloridos
• tagindicator – Mostra uma caixa de etiqueta com um indicador de círculo colorido

As cores podem variar por linha, pelo que o conjunto de dados de metadados da coluna fornece simplesmente o nome das colunas que contém as cores para as etiquetas.

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

Em seguida, pode adicionar os metadados de coluna para adicionar duas colunas, uma apresentada como tag e a outra como tagindicator – cada uma utilizando as colunas TagColor e TagBorderColor para determinar 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"
}

Isto apresentará o seguinte resultado:

Imagem e Imagem Clicável

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

O conteúdo da imagem pode ser definido acrescentando o prefixo:

• https: Uma ligação para uma imagem externa. por exemplo, https://via.placeholder.com/100x70
• icon: Utilizar um dos ícones da Fluent UI, por exemplo, icon:SkypeCircleCheck
• data: Utilizar dados de imagem svg inline: 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 é selecionado, com um EvenName de CellAction, EventColumn a fornecer o nome da coluna de imagem e EventRowKey a ser o RecordKey da linha (se não estiver definido qualquer RecordKey, o EventRowKey irá 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"
}

Isto apresentaria o resultado:

Para a coluna clickableimage, o evento OnChange pode então tratar a ação quando um utilizador seleciona, com o rato ou o teclado, um ícone (desde que este não esteja desativado) utilizando:

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

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

Ligações

As colunas podem ser apresentadas como ligações, o que desencadeará o evento OnChange quando a ligação for selecionada, de forma semelhante à descrita acima para as imagens clicáveis.

Os metadados de coluna para uma ligação são configurados da seguinte forma:

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

Isto fará com que o conteúdo da célula seja apresentado da seguinte forma:

O evento OnChange é novamente acionado quando a ligação é clicada, com o EventColumn a ser o nome da coluna que contém a ligação e EventRowKey preenchido com o valor de coluna definido como a propriedade RecordKey.

Colunas de múltiplos valores

Se uma coluna puder ter vários valores, defina-a como Tabela/Coleção. Isto irá apresentar os valores como múltiplos valores de célula. por exemplo:

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

Os metadados da coluna poderiam então ser:

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

Isto faria com que a tabela mostrasse:

Comportamento

Ordenar Eventos

Uma coluna é definida como sendo ordenável definindo a propriedade ColSortable como true. Se a coluna mostrar um valor de texto diferente da sequência de ordenação necessária (por exemplo, uma coluna de data ou de estado formatada), poderá ser especificada uma coluna de ordenação diferente utilizando a propriedade ColSortBy.

A ordenação é então processada de duas maneiras:

1. Automaticamente, quando ligada a uma origem de dados do Dataverse.
2. Manualmente, quando utilizar coleções.

Ordenação Automática

Quando o conjunto de dados Itens é um conjunto de dados do Dataverse nativo, será ordenado automaticamente se uma coluna estiver marcada como ordenável. Se forem efetuadas alterações à forma de uma coleção do Dataverse utilizando AddColumn ou armazenando os dados numa coleção, a ordenação automática deixa de funcionar e a ordenação manual tem de ser implementada.

Ordenação Manual

A Ordenação Manual é suportada fora do componente para permitir o suporte de conectores personalizados e a ordenação de coleções locais quando não estiver ligada a uma ligação do Dataverse. As colunas podem ser definidas como sendo ou não ordenáveis. Quando a ordenação de uma coluna é selecionada, é acionado um evento OnChange, fornecendo a coluna e a direção. Em seguida, a aplicação deverá utilizar estes valores para alterar a coleção associada à tabela, para que esta seja atualizada com os registos ordenados.

1. Na coleção Colunas, adicione uma coluna booleana ordenável

2. Adicionar o nome da coluna ordená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 como:

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

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

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

Quando o evento OnChange é acionado depois de o utilizador selecionar o cabeçalho da coluna para alterar a ordenação, as variáveis de contexto da ordenação são atualizadas utilizando as novas informações de ordenação fornecidas, o que faz com que o conjunto de dados de entrada seja ordenado novamente e que a tabela seja atualizada em conformidade.

Paginação

A paginação é gerida internamente pelo componente; no entanto, os botões para recuar/avançar têm de ser criados pela aplicação anfitriã, e os eventos têm de ser enviados para o componente.

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

• PageSize – Define a quantidade de registos a carregar por página.
• PageNumber – Apresenta a página atual mostrada.
• HasNextPage — Apresenta true se houver uma página seguinte.
• HasPreviousPage — Devolve verdadeiro se houver uma página anterior.
• TotalRecords – Apresenta o número total de registos disponíveis.

Em seguida, é possível definir os botões de paginação 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 Página Seguinte
  • OnSelect: UpdateContext({ctxGridEvent:"LoadNextPage" & Text(Rand())})
  • DisplayMode: If(grid.HasNextPage,DisplayMode.Edit,DisplayMode.Disabled)

O número de etiquetas de registos pode ser definido como uma expressão semelhante a:

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

Mostrar o topo da página seguinte

Isto é implementado utilizando o evento "SetFocusOnRow". Se tivesse a propriedade InputEvent vinculada a ctxGridEvent, na propriedade OnSelect do botão da página seguinte, utilizaria: UpdateContext({ctxGridEvent:"LoadNextPageSetFocusOnRow" & Text(Rand())});

Eventos de entrada

A propriedade InputEvent pode ser definida como uma ou mais das seguintes:

• SetFocus — Define o foco na primeira linha da grelha
• ClearSelection — Limpa qualquer seleção e redefine para a seleção predefinida.
• SetSelection — Define a seleção conforme definido pela coluna RowSelected.
• LoadNextPage — Carrega a página seguinte, se houver uma
• LoadPreviousPage — Carrega a página anterior, se houver uma
• LoadFirstPage — Carrega a primeira página

Para garantir que o evento de entrada é detetado, deve ser complementado com um valor aleatório. por exemplo, SetSelection" & Text(Rand())

Consulte abaixo para mais detalhes

Itens Selecionados e Ações de Linha

O componente suporta os modos de seleção Single, Multiple ou None.

Quando seleciona itens, as propriedades SelectedItems e Selected são atualizadas.

• SelectedItems – Se a tabela estiver no modo de seleção múltipla, conterá um ou mais registos da coleção Items.
• Selected – Se a tabela estiver no modo de seleção Único, irá conter os registos selecionados.

Quando um utilizador invoca a ação de linha, seja através de clique duplo, premindo Enter ou uma linha selecionada, o evento OnSelect é acionado. A propriedade Selected irá conter uma referência para o registo que foi invocado. Este evento pode ser utilizado para mostrar um registo detalhado ou navegar para outro ecrã.

Se a propriedade RaiseOnRowSelectionChangeEvent estiver ativada, quando as linhas selecionadas forem alteradas, o evento OnChange é criado com o EventName definido como OnRowSelectionChange. Se a aplicação precisar de responder à seleção de uma única linha em vez de a um duplo clique numa linha, o OnChange pode detetar isso com código semelhante ao seguinte:

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

Limpar os itens atualmente selecionados

Para limpar os registos selecionados, tem de definir a propriedade InputEvent para uma cadeia que comece por

por exemplo

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

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

Definir seleção de linhas

Se houver um cenário no qual um conjunto de registos específico deve ser selecionado programaticamente, a propriedade InputEvent pode ser definida como SetSelection ou SetFocusOnRowSetSelection em combinação com a definição da propriedade RecordSelected no registo.

Por exemplo, se tivesse um conjunto de dados da seguinte forma:

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

Para selecionar a primeira linha, pode definir o InputEvent como "SetFocusOnRowSetSelection"&Text(Rand()) ou "SetSelection"&Text(Rand())

Configurar o comportamento "Ao Alterar"

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

• Acione eventos quando um utilizador altera a linha selecionada: ative a propriedade Raise OnRowSelectionChange event no componente.
• Configurar o comportamento da ligação: adicione colunas com o valor ColCellType definido como ligação.

/* 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

Este componente de código só pode ser utilizado em aplicações de tela e páginas personalizadas.