DetailsList 控制

發行項
10/16/2024

用來顯示資料集的控制項。

Note

完整文件和原始程式碼可在 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`	(選用) - 唯一索引鍵資料行名稱。當更新記錄時，如果您希望保留選取項目，以及當您想要 `EventRowKey` 在觸發 `OnChange` 事件後包含識別碼而不是資料列索引時，請提供此項。
`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 設定特定動作：

當使用者變更所選取的資料列時觸發事件：在元件中啟用屬性引發 OnRowSelectionChange 事件。
設定連結行為：新增 ColCellType 值設定為連結的資料行。

/* 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` 性能

展開/摺疊