@lensui/lens-table 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +46 -61
  2. package/dist/index.cjs +764 -170
  3. package/dist/index.css +362 -31
  4. package/dist/index.d.cts +39 -33
  5. package/dist/index.d.ts +39 -33
  6. package/dist/index.js +764 -170
  7. package/package.json +1 -1
package/README.md CHANGED
@@ -105,30 +105,28 @@ export function Example() {
105
105
  | `tooltip` | `boolean \| { header?: boolean; cell?: boolean }` | `true` | 文本 tooltip 总配置。传`true` 时表头和单元格 hover 都显示完整文本；传 `false` 可关闭；传对象可分别控制表头和单元格。 |
106
106
  | `summary` | `boolean \| { position?: 'top' \| 'bottom'; verticalBordered?: boolean; emptyValue?: ReactNode }` | `false` | 表格级合计行配置。默认不显示；传 `true` 或对象即开启合计行，对象可控制显示在表头下方或底部、是否显示内部竖线，以及无合计值单元格的填充内容。 |
107
107
  | `rowNumber` | `boolean` | `true` | 是否显示序号列。默认开启并自动生成左侧序号列，不需要在`columns` 中配置；传 `false` 可关闭。 |
108
- | `selectedCell` | `GridSelection \| null` | 非受控 | 受控单元格选中状态。 |
109
- | `defaultSelectedCell` | `GridSelection \| null` | `null` | 非受控模式下的默认选中单元格。 |
110
- | `onSelectedCellChange` | `(selection) => void` | - | 单元格选中变化回调。 |
108
+ | `selectedCell` | `GridSelectionTarget \| null` | 非受控 | 受控单元格选中状态。传 `columnKey`，行可使用 `rowKey` 或 `rowIndex` 定位。 |
109
+ | `defaultSelectedCell` | `GridSelectionTarget \| null` | `null` | 默认选中单元格。传 `columnKey`，行可使用 `rowKey` 或 `rowIndex` 定位。 |
110
+ | `onSelectedCellChange` | `(selection) => void` | - | 单元格选中变化回调，`selection.value` 为当前单元格的原始值。 |
111
111
  | `rangeSelection` | `boolean` | `false` | 是否允许鼠标拖动选择多个单元格。开启后支持范围复制、范围右键菜单和右下角拖拽扩展范围。 |
112
112
  | `rowSelection` | `boolean \| AxisSelectionConfig` | `false` | 开启行选择。可传`{ mode: 'single' \| 'multiple' }`；开启后组件自动生成左侧选择列，不需要在 `columns` 中配置。 |
113
113
  | `selectedRowKeys` | `GridKey[]` | 非受控 | 受控行选择 key 列表。 |
114
114
  | `defaultSelectedRowKeys` | `GridKey[]` | `[]` | 非受控模式下默认选中的行 key。 |
115
- | `onSelectedRowKeysChange` | `(keys, rows, indices) => void` | - | 行选择变化回调。 |
115
+ | `onSelectedRowChange` | `(keys, rows, indices) => void` | - | 行选择变化回调。 |
116
116
  | `columnSelection` | `boolean \| AxisSelectionConfig` | `false` | 开启列选择。可传`{ mode: 'single' \| 'multiple' }`。 |
117
117
  | `selectedColumnKeys` | `string[]` | 非受控 | 受控列选择 key 列表。 |
118
118
  | `defaultSelectedColumnKeys` | `string[]` | `[]` | 非受控模式下默认选中的列 key。 |
119
- | `onSelectedColumnKeysChange` | `(keys) => void` | - | 列选择变化回调。 |
119
+ | `onSelectedColumnChange` | `(keys) => void` | - | 列选择变化回调。 |
120
120
  | `columnDraggable` | `boolean` | `true` | 是否允许拖拽调整列顺序。默认开启，普通列默认显示表头拖拽入口，传`false` 可关闭。 |
121
- | `columnResizable` | `boolean` | `false` | 是否允许拖拽调整列宽。 |
122
- | `onColumnOrderChange` | `(sourceIndex, targetIndex) => void` | - | 列拖拽排序回调。需要在外部更新`columns`。 |
123
- | `onColumnResize` | `(columnKey, width) => void` | - | 列宽变化回调。未传时组件会在内部维护列宽；传入后可用于持久化或受控同步。 |
121
+ | `onColumnsReorder` | `(columns, detail) => void` | - | 列拖拽重排完成回调，返回重排后的完整列配置和索引详情。 |
124
122
  | `rowDraggable` | `boolean` | `false` | 是否允许拖拽调整行顺序。开启后组件自动生成左侧拖拽手柄列，不需要在`columns` 中配置。 |
125
- | `onRowOrderChange` | `(sourceIndex, targetIndex) => void` | - | 行拖拽排序回调。需要在外部更新`rows`。 |
126
- | `onInsertRows` | `(event) => void` | - | 右键菜单插入行回调。 |
127
- | `onDeleteRows` | `(event) => void` | - | 右键菜单删除行回调。 |
128
- | `sortState` | `GridSortState \| null` | 非受控 | 受控排序状态。组件只管理 UI 状态，数据排序由外部完成。 |
129
- | `onSortStateChange` | `(state) => void` | - | 点击表头排序时触发。 |
130
- | `filterValues` | `Record<string, string>` | 非受控 | 受控筛选值。组件只管理输入值，数据过滤由外部完成。 |
131
- | `onFilterValuesChange` | `(values) => void` | - | 表头筛选值变化回调。 |
123
+ | `onRowsReorder` | `(rows, detail) => void` | - | 行拖拽重排完成回调，返回重排后的完整行数据和索引详情。 |
124
+ | `columnResizable` | `boolean` | `true` | 是否允许拖拽调整列宽。默认开启，传 `false` 可关闭。 |
125
+ | `onColumnResize` | `(columnKey, width) => void` | - | 列宽变化回调。未传时组件会在内部维护列宽；传入后可用于持久化或受控同步。 |
126
+ | `onInsertRows` | `(rows, insertedRows) => void` | - | 插入完成后返回新的完整行数组和本次插入的行。 |
127
+ | `onDeleteRows` | `(rows, deletedRows) => void` | - | 删除完成后返回新的完整行数组和本次删除的行。 |
128
+ | `onSortChange` | `(rows, state) => Row[]` | - | 自定义排序方法。排序状态由组件内部管理；返回排序后的行。 |
129
+ | `onFilterChange` | `(rows, values) => Row[]` | - | 自定义筛选方法。筛选值由组件内部管理；返回符合条件的行。 |
132
130
  | `onCellChange` | `(change) => void` | - | 单元格编辑提交回调。 |
133
131
  | `onCellContextMenu` | `(event) => void` | - | 单元格右键回调，可用于扩展自定义菜单逻辑。 |
134
132
  | `contextMenu` | `boolean \| { header?, cell?, range? }` | `true` | `true` 开启默认右键菜单，`false` 关闭右键菜单，传对象可自定义菜单项、顺序和分割线。 |
@@ -137,6 +135,17 @@ export function Example() {
137
135
  | `style` | `CSSProperties` | - | 根节点内联样式，可用于传入主题 CSS 变量。 |
138
136
  | `ariaLabel` | `string` | `Table` | 表格区域无障碍名称。 |
139
137
 
138
+ 插入和删除的位置计算、空行生成、乐观显示及目标行过滤均由组件处理，外部只需更新最终数组：
139
+
140
+ ```tsx
141
+ <Table
142
+ rows={rows}
143
+ columns={columns}
144
+ onInsertRows={setRows}
145
+ onDeleteRows={setRows}
146
+ />
147
+ ```
148
+
140
149
  ## 高亮和范围选择
141
150
 
142
151
  编辑高亮、插入行高亮和鼠标拖动多单元格选择默认都不开启。需要这些视觉反馈或批量选择能力时，通过表格级配置显式开启：
@@ -199,8 +208,8 @@ export function Example() {
199
208
  | `align` | `'left' \| 'center' \| 'right'` | `'left'` | 单元格文本和拖拽预览文本对齐方式。 |
200
209
  | `editable` | `boolean` | `false` | 是否允许双击或按 Enter 进入编辑。 |
201
210
  | `editor` | `EditorConfig` | `{ type: 'text' }` | 内置编辑器配置。详见下方编辑器表。未配置时默认使用文本编辑器。 |
202
- | `sortable` | `boolean` | `true` | 表头显示排序按钮，并触发`onSortStateChange`。普通数据列默认开启，传 `false` 可关闭。 |
203
- | `filterable` | `boolean` | `true` | 表头显示筛选按钮，并触发`onFilterValuesChange`。普通数据列默认开启，传 `false` 可关闭。 |
211
+ | `sortable` | `boolean` | `true` | 表头显示排序按钮。普通数据列默认开启，传 `false` 可关闭。 |
212
+ | `filterable` | `boolean` | `true` | 表头显示筛选按钮。普通数据列默认开启，传 `false` 可关闭。 |
204
213
  | `formatter` | `(value, row, rowIndex) => string` | - | 自定义展示文本。异常会被隔离并显示渲染错误文案。 |
205
214
  | `renderCell` | `(value, row, rowIndex) => ReactNode` | - | 自定义单元格 React 内容。适合标签、徽标、图标组合等内置编辑器无法表达的展示。 |
206
215
  | `summary` | `boolean \| ((rows, column) => ReactNode)` | `false` | 是否在合计行显示该列合计。传`true` 自动累加数字值；传函数可自定义合计内容。 |
@@ -457,42 +466,33 @@ const columns: GridColumn<Row>[] = [
457
466
 
458
467
  ## 排序和筛选
459
468
 
460
- 组件只负责展示排序/筛选交互，不会直接改变 `rows`。业务侧需要根据回调结果自行排序、过滤。
469
+ 排序和筛选状态均由组件内部管理。默认排序会比较数值或单元格显示文本；默认筛选按照显示文本执行不区分大小写的包含匹配。需要其他规则时，分别通过 `onSortChange` 和 `onFilterChange` 返回处理后的行。
461
470
 
462
471
  ```tsx
463
- const [sortState, setSortState] = useState<GridSortState | null>(null);
464
- const [filterValues, setFilterValues] = useState<Record<string, string>>({});
465
-
466
- const visibleRows = useMemo(() => {
467
- const filtered = rows.filter((row) =>
468
- Object.entries(filterValues).every(([key, value]) =>
469
- String(row[key as keyof Row] ?? '').includes(value),
470
- ),
471
- );
472
-
473
- if (!sortState) return filtered;
474
-
475
- return filtered.slice().sort((a, b) => {
476
- const left = a[sortState.columnKey as keyof Row];
477
- const right = b[sortState.columnKey as keyof Row];
478
- const result = String(left).localeCompare(String(right));
479
- return sortState.direction === 'asc' ? result : -result;
480
- });
481
- }, [rows, sortState, filterValues]);
482
-
483
472
  <Table
484
473
  columns={columns}
485
- rows={visibleRows}
486
- sortState={sortState}
487
- filterValues={filterValues}
488
- onSortStateChange={setSortState}
489
- onFilterValuesChange={setFilterValues}
474
+ rows={rows}
475
+ onSortChange={(currentRows, state) => {
476
+ const direction = state.direction === 'asc' ? 1 : -1;
477
+ return currentRows.slice().sort((left, right) =>
478
+ String(left[state.columnKey as keyof Row]).localeCompare(
479
+ String(right[state.columnKey as keyof Row]),
480
+ ) * direction,
481
+ );
482
+ }}
483
+ onFilterChange={(currentRows, values) =>
484
+ currentRows.filter((row) =>
485
+ Object.entries(values).every(([key, value]) =>
486
+ String(row[key as keyof Row] ?? '').startsWith(value),
487
+ ),
488
+ )
489
+ }
490
490
  />;
491
491
  ```
492
492
 
493
493
  ## 拖拽和列宽
494
494
 
495
- 拖拽排序采用外部受控数据模式：组件告诉你发生了什么，真正的 `rows` 或 `columns` 更新由你完成。列宽调整支持非受控使用，只传 `columnResizable` 即可拖动；如果需要持久化宽度，可以监听 `onColumnResize` 并同步到你的列配置。
495
+ 拖拽后组件会在内部维护新的行列顺序，因此排序回调不是必需的。需要持久化或同步结果时，可以通过回调直接取得排序后的 `rows` 或 `columns`。列宽调整默认开启并支持非受控使用，传 `columnResizable={false}` 可关闭。
496
496
 
497
497
  `columnDraggable` 默认开启，普通列会自动显示表头拖拽入口。行选择和行拖拽是表格级配置：开启 `rowSelection` 后自动生成左侧选择列，开启 `rowDraggable` 后自动生成左侧拖拽手柄列，不需要在 `columns` 里配置 `rowSelection` 或 `rowDragHandle`。
498
498
 
@@ -501,16 +501,9 @@ const visibleRows = useMemo(() => {
501
501
  columns={columns}
502
502
  rows={rows}
503
503
  rowSelection={{ mode: 'multiple' }}
504
- columnResizable
505
504
  rowDraggable
506
- onColumnOrderChange={(sourceIndex, targetIndex) => {
507
- setColumns((current) => {
508
- const next = current.slice();
509
- const [column] = next.splice(sourceIndex, 1);
510
- next.splice(targetIndex, 0, column);
511
- return next;
512
- });
513
- }}
505
+ onColumnsReorder={(nextColumns) => saveColumns(nextColumns)}
506
+ onRowsReorder={(nextRows) => saveRows(nextRows)}
514
507
  onColumnResize={(columnKey, width) => {
515
508
  setColumns((current) =>
516
509
  current.map((column) =>
@@ -518,14 +511,6 @@ const visibleRows = useMemo(() => {
518
511
  ),
519
512
  );
520
513
  }}
521
- onRowOrderChange={(sourceIndex, targetIndex) => {
522
- setRows((current) => {
523
- const next = current.slice();
524
- const [row] = next.splice(sourceIndex, 1);
525
- next.splice(targetIndex, 0, row);
526
- return next;
527
- });
528
- }}
529
514
  />;
530
515
  ```
531
516