資料表格 React API · Needless UI

匯入

import-grid.tsx

import { NuiGrid, type NuiGridColumn, type NuiGridHandle } from '@needless-ui/react/grid';

NuiGrid

以原生 table 元素打造的資料表格。

NuiGrid: 屬性
名稱	型別	預設值	說明
`rows`prop	`readonly T[]`		資料。編輯會替換對應的列並呼叫 `onRowsChange`；之後傳入的 `rows` 會取代這些編輯。
`onRowsChange`回呼	`(rows: readonly T[]) => void`		每次確認編輯後呼叫，參數為編輯後的列。
`columns`prop	`NuiGridColumn<T>[]`		欄，以 `NuiGridColumn` 物件的形式提供。
`rowId`prop	`(row: T) => unknown`	`row.id ?? row`	列的 key，用於選取與追蹤。
`label`prop	`string`		表格的無障礙名稱。
`selection`prop	`'none' \| 'single' \| 'multiple'`	`'none'`	列是否可選取，以及可選取幾列。
`selected` `defaultSelected` `onSelectedChange`狀態	`unknown[]`	`[]`	所選列的 key。
`sort` `defaultSort` `onSortChange`狀態	`NuiGridSort[]`	`[]`	排序，以 `{ column, direction }` 物件的形式提供；排在前面的優先。
`filters` `defaultFilters` `onFiltersChange`狀態	`Record<string, NuiGridFilter>`	`{}`	依欄 id 設定的篩選條件：一個運算子和一個值。
`search` `defaultSearch` `onSearchChange`狀態	`string`	`''`	必須全部出現在同一列中的詞。
`pageSize` `defaultPageSize` `onPageSizeChange`狀態	`number`	`0`	每頁列數；設為 0 則顯示為單一捲動清單。
`page` `defaultPage` `onPageChange`狀態	`number`	`0`	目前顯示的頁面，從 0 開始。
`pageSizes`prop	`number[]`	`[10, 25, 50, 100]`	分頁器中可選的每頁列數。
`virtual`prop	`boolean \| 'auto'`	`'auto'`	只渲染可見的列：一律、從不，或 `auto`（不分頁且超過 100 列時啟用）。
`height`prop	`string`		限制表格高度的 CSS 長度，內容會在表格內捲動。
`columnState` `defaultColumnState` `onColumnStateChange`狀態	`NuiGridColumnState[]`	`[]`	每一欄的寬度、順序、固定與可見性，用於儲存和還原。
`mode`prop	`'client' \| 'server'`	`'client'`	`server` 會照收到的樣子顯示列，並把排序、篩選和分頁交給你處理。
`total`prop	`number`		伺服器上的總列數。
`loading`prop	`boolean`	`false`	顯示進度列；沒有列時顯示預留位置列。
`locale`prop	`string`	`'en-US'`	用於格式化數字和日期，以及解析輸入的數字。
`labels`prop	`Partial<NuiGridLabels>`		表格顯示或朗讀的所有文字，供翻譯使用。
`corners`prop	`NuiCorners`		邊角的形狀：`round`、`squircle`、`bevel`、`scoop`、`notch` 或 `square`。
`radius`prop	`NuiRadius`		邊角的大小：`none`、`small`、`medium`、`large` 或 `full`。
`density`prop	`NuiDensity`		佔用的空間：`compact`、`regular` 或 `roomy`。
`groupBy`prop	`string[]`	`[]`	用來將列分組的欄，由最外層開始。
`collapsed` `defaultCollapsed` `onCollapsedChange`狀態	`string[]`	`[]`	已收合群組的 key；群組預設為展開。
`getChildren`prop	`(row: T) => T[] \| undefined`		列的子列：表格會顯示樹狀資料。
`expanded` `defaultExpanded` `onExpandedChange`狀態	`unknown[]`	`[]`	樹狀資料中已展開的列的 key；列預設為收合。
`details` `defaultDetails` `onDetailsChange`狀態	`unknown[]`	`[]`	已開啟詳細資料的列的 key。
`totals, flash`prop	`boolean`	`false`	彙總所有篩選後列的一列；以及文字變動時會閃爍的儲存格，僅適用於具有固定 `rowId` 的列。
`layout`prop	`'table' \| 'list' \| 'auto'`	`'table'`	`list` 以卡片顯示列，`auto` 則只在窄螢幕上這樣顯示。
`toolbar`prop	`boolean \| 'auto'`	`'auto'`	對列排序、篩選和全選的工具列：一律、從不，或 `auto`（顯示卡片時出現）。
`renderEmpty`渲染 prop	`(filtered: boolean) => ReactNode`		沒有列時顯示的內容；參數會說明這些列是否被篩選條件隱藏。
`renderDetail`渲染 prop	`(row: T) => ReactNode`		列的詳細資料，開啟後顯示在該列下方。表格會加上一欄切換按鈕。
`onRowActivate`回呼	`(row: T) => void`		按 Enter 鍵或雙擊開啟某列時呼叫，參數為該列。
`onCellEdit`回呼	`(edit: NuiGridEdit<T>) => void`		每次確認編輯時呼叫，參數為該編輯。
`onQueryChange`回呼	`(query: NuiGridQuery) => void`		排序、篩選、搜尋或頁碼變更時呼叫，參數為它們；一開始也會呼叫一次。
`ref`prop	`Ref<NuiGridHandle>`		表格的 `ref` 能呼叫的方法：匯出、列印和焦點。
`exportXlsx, print`方法	`(options?) => Blob, () => void`		以試算表形式匯出篩選和排序後的列；列印所有列。
`exportCsv`方法	`(options?) => string`		以 CSV 格式傳回篩選和排序後的列，只包含可見的欄。
`expandAll`方法	`(open?: boolean) => void`		展開所有群組和所有帶有子列的列，或全部收合。
`focusCell`方法	`(row: number, col: number) => void`		讓某個儲存格取得焦點；第 `-1` 列是標題列。
`clearFilters`方法	`() => void`		清除所有篩選條件和搜尋。
`fit`方法	`(id: string) => void`		把欄寬調整為已渲染儲存格中最寬的那一格。

狀態的用法和 React 內建的表單輸入相同：傳入一個值，並在它的 on…Change 回呼中更新；或是傳入 default… 值，讓元件自己保存。

用於客製化的 prop 如果未設定，會沿用最近的 data-nui-* 屬性。詳見客製化指南。

NuiGridColumn

一欄。接收 Angular 欄的所有屬性（只有 id 和 header 是必要的），以及用來繪製該欄的這兩個屬性。

NuiGridColumn: 屬性
名稱	型別	預設值	說明
`renderCell`渲染 prop	`({ row, value, text, column }) => ReactNode`		自行繪製該欄的儲存格，參數為列、它的值和文字。
`renderHeader`渲染 prop	`(column) => ReactNode`		自行繪製該欄的欄標題；欄的名稱仍由 `header` 提供。