DetailsList 控制

项目
05/01/2023

用于显示一组数据的控件。

备注

GitHub 代码组件存储库中的完整文档和源代码。

DetailsList 控件。

说明

详细信息列表 (DetailsList) 是一种显示信息丰富的项目集合并允许人们对内容进行排序、分组和筛选的可靠方式。当信息密度至关重要时，使用 DetailsList。

DetailsList 代码组件允许从画布应用和自定义页面内使用 Fluent UI DetailsList 组件。

可以绑定到 Dataverse 数据集或本地集合。
支持与源数据集提供的列元数据分开的可配置列，以提供灵活性。
链接、图标、展开/折叠和子文本单元格的单元格类型。
支持分页。
支持使用 Dataverse 排序或可配置的 SortBy 属性进行排序。

属性

键属性

属性	说明
`Items`	包含要呈现的行的数据集。也显示为 `Records`。请参见下方的“项属性表”。
`Columns`	包含列的选项元数据的数据集。如果提供了此数据集，它将完全替换“记录”数据集中提供的列。请参见下方的“列属性表”。
`SelectionType`	选择类型（无、单选、多选）
`PageSize`	定义每页要加载的记录数。
`PageNumber`	输出显示的当前页面。
`HasNextPage`	如果有下一页，将输出 true。
`HasPreviousPage`	如果有上一页，将输出 true。
`TotalRecords`	输出可用记录的总数。
`CurrentSortColumn`	要显示为当前用于排序的列的名称
`CurrentSortDirection`	当前使用的排序列的方向

`Items` 性能

这些属性必须在数据源中可用才能启用相关功能。 Power Fx 公式 AddColumns() 可用于将这些值附加到原始数据源。

属性	说明
`RecordKey`	（可选）- 唯一的键列名称。如果您希望在更新记录时保留选择，并且希望在触发 `OnChange` 事件后 `EventRowKey` 包含 ID 而不是行索引，请提供此属性。
`RecordCanSelect`	（可选）- 包含定义是否可以选择行的 `boolean` 值的列名称。
`RecordSelected`	（可选）- 包含 `boolean` 值的列名称，定义是在否默时以及将 `InputEvent` 设置为包含 `SetSelection` 时认选择行。请参阅下面有关 `Set Selection` 的章节。

`Columns` 性能

属性	说明
`ColDisplayName`	（必需）- 提供要在标题中显示的列的名称。
`ColName`	（必需）- 提供“项目”集合中列的实际字段名称。
`ColWidth`	（必需）- 提供列的绝对固定宽度（以像素为单位）。
`ColCellType`	要呈现的单元格类型。可能的值：`expand`、`tag`、`indicatortag`、`image`、`clickableimage`、`link`。有关详细信息，请参阅后面几节。
`ColHorizontalAlign`	`ColCellType` 的类型为 `image` 或 `clickableimage` 时单元格内容的对齐方式。
`ColVerticalAlign`	`ColCellType` 的类型为 `image` 或 `clickableimage` 时单元格内容的对齐方式。
`ColMultiLine`	如果单元格文本中的文本因太长无法适应可用宽度而应换行，为 true。
`ColResizable`	当列标题宽度应可调整大小时为 true。
`ColSortable`	当列应可排序时为 true。如果数据集支持通过直接 Dataverse 连接自动排序，数据将自动排序。否则，将设置 `SortEventColumn` 和 `SortEventDirection` 输出，并且必须在记录 Power FX 绑定表达式中使用。
`ColSortBy`	对列进行排序时提供给 `OnChange` 事件的列的名称。例如，如果您在对日期列进行排序，您希望根据实际日期值而不是列中显示的带格式文本进行排序。
`ColIsBold`	当数据单元格数据应为粗体时为 true
`ColTagColorColumn`	如果单元格类型为标记，则设置为文本标记的十六进制背景颜色。可以设置为 `transparent`。如果单元格类型不是标记，则设置为十六进制颜色以用作圆圈标记单元格的指示器。如果文本值为空，标记不会显示。
`ColTagBorderColorColumn`	设置为十六进制颜色以用作文本标记的边框颜色。可以设置为 `transparent`。
`ColHeaderPaddingLeft`	向列标题文本添加填充（像素）
`ColShowAsSubTextOf`	将此属性设置为另一列的名称会将列移动为该列的子列。请参阅下方“子文本”列下的内容。
`ColPaddingLeft`	在子单元格的左侧添加填充（像素）
`ColPaddingTop`	在子单元格的顶部添加填充（像素）
`ColLabelAbove`	如果标签显示为子文本列，将标签移动到子单元格值上方。
`ColMultiValueDelimiter`	将多值数组值与此分隔符联接在一起。请参阅下方多值列下的内容。
`ColFirstMultiValueBold`	显示多值数组值时，第一项显示为粗体。
`ColInlineLabel`	如果设置为字符串值，用于在单元格值内显示可能与列名不同的标签。例如
`ColHideWhenBlank`	当为 true 时，如果单元格值为空白，任何单元格内联标签和填充都将被隐藏。
`ColSubTextRow`	在子文本单元格上显示多个单元格时，设置为行索引。零表示主单元格内容行。
`ColAriaTextColumn`	包含单元格（例如，图标单元格）的 aria 说明的列。
`ColCellActionDisabledColumn`	包含布尔标志以控制是否禁用单元格操作（例如，图标单元格）的列。
`ColImageWidth`	图标/图像大小，以像素为单位。
`ColImagePadding`	图标/图像单元格周围的填充。
`ColRowHeader`	定义呈现比其他单元格更大的单元格的列（14 像素而不是 12 像素）。通常每个列集只有一个行标题。

样式属性

属性	说明
`Theme`	使用从 Fluent UI 主题设计器生成和导出的主题的 Fluent UI 主题 JSON。有关如何配置的指导，请参阅主题化。
`Compact`	应该使用紧凑样式时为 true
`AlternateRowColor`	用于备用行的行颜色的十六进制值。
`SelectionAlwaysVisible`	选择单选按钮是否应该始终可见，而不是仅在行悬停时可见。
`AccessibilityLabel`	要添加到表 aria 说明的标签

事件属性

属性	说明
`RaiseOnRowSelectionChangeEvent`	选择/取消选择行时将引发 `OnChange` 事件。（请参阅以下内容）
`InputEvent`	一个或多个输入事件（可以使用字符串连接组合在一起）。可能的值为 `SetFocus`、`SetFocusOnRow`、`SetFocusOnHeader`、`ClearSelection`、`SetSelection`。必须后跟随机字符串元素以确保触发事件。事件可以组合，例如，`SetFocusClearSelection` 将同时清除和设置焦点。 `SetFocusOnRowSetSelection` 将焦点设置在一行上，并同时设置选择。
`EventName`	触发 `OnChange` 时的输出事件。可能的值 - `Sort`、`CellAction`、`OnRowSelectionChange`
`EventColumn`	调用 `CellAction` 时使用的输出事件列字段名称
`EventRowKey`	保留调用事件的行的索引的输出事件列，如果设置了 `RecordKey` 属性，则为行键。
`SortEventColumn`	触发排序 `OnChange` 事件的列的名称
`SortEventDirection`	触发排序 `OnChange` 事件的排序的方向

基本用法

要确定 DetailsList 中显示哪些列，请配置 DetailsList 的以下属性：

领域。通过选择右侧控件弹出项目菜单中的“编辑”选项来添加所需的字段（使用同一界面修改预定义数据卡）。
列。在 Columns 属性中提供列和字段之间的特定映射。

示例:

映射到 Dataverse 客户系统表，使用以下公式：

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

子文本列

ColShowAsSubTextOf 列属性将列定义为显示在另一列中的值下方。这可用于显示辅助信息和可扩展内容（见下文）。

如果您有一个集合定义为：

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

您可以将列定义为：

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

结果将是一个如下所示的表：

单元格类型

ColCellType 列属性接受以下值：expand、tag、image、indicatortag、clickableimage、link

展开/折叠

如果“子文本”行需要具有展开/折叠图标，可以将其他列添加到列数据集中，并且列定义 ColCellType 同时也设置 expand：

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

假设 RecordKey 属性设置为 index 列，OnChange 事件可以包含以下内容以展开/折叠行：

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

这将使用索引搜索已调用单元格操作的行（如果未设置 RecordKey，EventRowKey 将包含行号），然后切换展开值。

这将给出以下结果：

标记和指示标记

使用单元格类型的 tag 或 indicatortag，您可以创建内联彩色标记来显示单元格内容。

tag - 这将显示一个带有彩色背景和边框的标签框
tagindicator - 显示带有彩色圆圈指示器的标签框

颜色可以随行变化，因此列元数据数据集只提供保留标记颜色的列的名称。

考虑数据集：

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

然后，您可以添加列元数据来添加两个列，一个显示为标记，另一个显示为指示标记 - 每个列使用 TagColor 和 TagBorderColor 列来确定颜色：

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

这将给出以下结果：

图像和可点击图像

使用 image 或 clickableimage 单元格类型，您可以配置内联图像，然后可以有选择地选择这些图像来引发 OnChange 操作。

图像内容可以通过添加以下前缀来定义：

https: 指向外部图像的链接。例如，https://via.placeholder.com/100x70
icon: 例如，使用其中一个 Fluent UI 图标， icon:SkypeCircleCheck
data: 使用内联 svg 图像数据：例如， data:image/svg+xml;utf8, %3Csvg%20%20viewBox%3D%270%200%2020...

如果图像是 clickableimage 类型，选择图标时将触发 OnChange 事件，其中包含 CellAction 的 EvenName，EventColumn 提供图像列的名称，EventRowKey 是行的 RecordKey（如果未设置 RecordKey，EventRowKey 将包含行号）。

例如，考虑行数据：

{
        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"
    }

和列元数据：

 {
        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"
}

这会给出以下结果：

对于 clickableimage 列，OnChange 事件可以在用户选择（鼠标或键盘）和图标（假设未被禁用）时使用以下各项进行处理：

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

EventRowKey 将填充定义为 RecordKey 属性的列值。

链接

列可以呈现为链接，当以与上述可点击图像的工作方式类似的方式选择链接时，这将引发 OnChange 事件。

链接的列元数据配置如下：

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

这会让单元格内容呈现为：

OnChange 事件将在单击链接时被再次触发，EventColumn 是包含链接的列的名称，EventRowKey 填充定义为 RecordKey 属性的列值。

多值列

如果一个列值可以通过将其设置为表/集合来具有多个值。这会将值呈现为多个单元格值。例如：

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

列元数据可以是：

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

这会让表显示：

行为

排序事件

通过将 ColSortable 属性设置为 true，列被定义为可排序。如果列显示的文本值与所需的排序顺序不同（例如，带格式的日期或状态列），则可以使用 ColSortBy 属性指定不同的排序列。

然后将通过两种方式处理排序：

连接到 Dataverse 数据源时自动进行。
使用集合时手动进行。

自动排序

当“项目”数据集是原生 Dataverse 数据集时，如果列被标记为可排序，它将自动排序。如果使用 AddColumn 或者通过将数据存储在集合中对 Dataverse 集合的形状进行了任何更改，自动排序将不再起作用，必须实施手动排序。

手动排序

手动排序在组件外部受支持，以允许在未连接到 Dataverse 连接时支持自定义连接器和进行本地集合排序。列可以定义为可排序或不可排序。选择列排序时，将引发 OnChange 事件，以提供列和方向。然后，应用应使用这些值将绑定的集合更改为表以使用已排序的记录进行更新。

在“列”集合中，添加一个可排序的布尔列
将可排序列的名称添加到 Columns.ColSortable 属性

在表的 OnChange 事件中，添加代码：

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

将属性 Sort Column 设置为 ctxSortCol

将属性 Sort Direction 设置为：

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

使用上面设置的上下文变量设置输入项集合以进行排序：

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

当用户选择列标题更改排序后触发 OnChange 事件时，将使用提供的新排序信息更新排序上下文变量，这会导致输入数据集重新排序并相应更新表。

分页

分页由组件内部处理，但是后退/前进按钮必须由托管应用创建，事件将被发送到组件。

以下属性用于控制分页：

PageSize - 定义每页要加载的记录数。
PageNumber - 输出显示的当前页面。
HasNextPage - 如果有下一页，则输出 true。
HasPreviousPage - 如果有上一页，则输出 true。
TotalRecords - 输出可用记录的总数。

然后可以按如下方式定义分页按钮：

加载第一页
- OnSelect: UpdateContext({ctxGridEvent:"LoadFirstPage" & Text(Rand())})
- DisplayMode: If(grid.HasPreviousPage,DisplayMode.Edit,DisplayMode.Disabled)
加载上一页
- OnSelect: UpdateContext({ctxGridEvent:"LoadPreviousPage" & Text(Rand())})
- DisplayMode: If(grid.HasPreviousPage,DisplayMode.Edit,DisplayMode.Disabled)
加载下一页
- OnSelect: UpdateContext({ctxGridEvent:"LoadNextPage" & Text(Rand())})
- DisplayMode: If(grid.HasNextPage,DisplayMode.Edit,DisplayMode.Disabled)

记录标签的数量可以设置为类似于以下内容的表达式：

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

显示下一页的顶部

这使用“SetFocusOnRow”事件实现。如果您将 InputEvent 属性绑定到 ctxGridEvent，在下一页按钮的 OnSelect 属性上，您将使用：UpdateContext({ctxGridEvent:"LoadNextPageSetFocusOnRow" & Text(Rand())});

输入事件

InputEvent 属性可以设置为以下一项或多项：

SetFocus - 将焦点设置在网格的第一行上
ClearSelection - 清除任何选择，并设置回默认选择。
SetSelection - 设置由列定义的 RowSelected 选择。
LoadNextPage - 如果有下一页，则加载下一页
LoadPreviousPage - 如果有，则加载上一页
LoadFirstPage - 加载第一页

为确保输入事件被选取，必须有一个随机值。例如，SetSelection" & Text(Rand())

有关详细信息，请参阅下文。

所选项和行操作

此组件支持单选、多选或无选择模式。

选择项目时，SelectedItems 和 Selected 属性将更新。

SelectedItems - 如果表处于 Multiple selection 模式，则这将包含 Items 集合中的一条或多条记录。
Selected - 如果表处于 Single selection 模式，则这将包含所选记录。

当用户通过双击或按 Enter 或选定的行调用行操作时，将触发 OnSelect 事件。 Selected 属性将包含对已调用记录的引用。此事件可用于显示详细记录或导航到另一个屏幕。

如果启用了 RaiseOnRowSelectionChangeEvent 属性，在更改选定的行时，将引发 OnChange 事件，事件的 EventName 设置为 OnRowSelectionChange。如果应用需要响应单行选择而不是行双击，OnChange 可以使用类似于下方的代码检测到此情况：

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

清除当前选择的项目

要清除选定的记录，您必须将 InputEvent 属性设置为以以下内容开头的字符串

例如

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

上下文变量 ctxTableEvent 然后可以被绑定到 InputEvent 属性。

设置行选择

如果存在应以编程方式选择特定记录集的情况，可以将 InputEvent 属性设置为 SetSelection 或 SetFocusOnRowSetSelection，与在记录上设置 RecordSelected 属性相结合。

例如，如果您有如下数据集：

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

要选择并选择第一行，您可以将 InputEvent 设置为 "SetFocusOnRowSetSelection"&Text(Rand()) 或 "SetSelection"&Text(Rand())

配置“更改时”行为

在组件的 OnChange 属性中添加和修改以下公式，以根据组件提供的 EventName 配置特定操作：

用户更改所选行时触发事件：在组件中启用属性 Raise OnRowSelectionChange event。
配置链接行为：添加 ColCellType 值设置为 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 )
)

限制

此代码组件只能在画布应用和自定义页面中使用。

通过

DetailsList 控制

说明

属性

键属性

`Items` 性能

`Columns` 性能

样式属性

事件属性

基本用法

子文本列

单元格类型

展开/折叠

标记和指示标记

图像和可点击图像

链接

多值列

行为

排序事件

自动排序

手动排序

分页

显示下一页的顶部

输入事件

所选项和行操作

清除当前选择的项目

设置行选择

配置“更改时”行为

限制

反馈

其他资源

通过

DetailsList 控制

说明

属性

键属性

Items 性能

Columns 性能

样式属性

事件属性

基本用法

子文本列

单元格类型

展开/折叠​​

标记和指示标记

图像和可点击图像

链接

多值列

行为

排序事件

自动排序

手动排序

分页

显示下一页的顶部

输入事件

所选项和行操作

清除当前选择的项目

设置行选择

配置“更改时”行为

限制

反馈

其他资源

`Items` 性能

`Columns` 性能

展开/折叠