@canvas-components/list-table 0.3.14 → 0.3.16

package/README.md

@@ -13,6 +13,82 @@
 - 列宽调整、列拖拽、行拖拽、轮播滚动
 - 内建二维码、条形码、进度、图表、评分、按钮等单元格内容
 
+### 展开详情自动高度
+
+`expandable.expandedRowRender` 返回标签、文本等富内容时，不传 `expandedRowHeight` 即按实际内容宽度自动换行、测高。容器宽度、列宽、字体或密度变化后会重新计算，并同步更新行位置和滚动范围。测量与绘制共用布局规则，业务侧无需自行测量标签或监听容器宽度。
+
+显式设置 `expandedRowHeight` 数字或回调时仍优先使用该配置；嵌套子表继续使用其独立的内容高度计算。
+
+### 分页尺寸缓存
+
+设置表格 `storageKey` 后，用户切换每页条数会自动保存到 localStorage，下次创建表格时恢复。不同表格应使用不同的键；不缓存页码，不影响滚动加载。无键、缓存无效或浏览器禁用存储时，继续使用默认配置。
+
+显式传入 `pagination.pageSize` 时以受控值为准。外部负责请求的封装（如 WWISuperTable）应在首次请求前读取缓存，初始化自己的分页状态，避免只改变显示值而请求条数不一致：
+
+```ts
+import { getListTableStoredPageSize } from "@canvas-components/list-table";
+
+const initialPageSize =
+  explicitPageSize ?? getListTableStoredPageSize(storageKey) ?? 10;
+// 将 initialPageSize 用于首次请求和受控 pagination.pageSize。
+```
+
+该读取方法也由 `@canvas-components/react-list-table` 导出。
+
+## 分区 CSS 样式
+
+原生 `ListTable` 和 `ReactListTable` 均支持 `styles`。Canvas 区域通过 CSS 属性映射到绘制参数，不创建单元格 DOM，不注入全局样式。
+
+```ts
+styles: {
+  cell: { fontSize: '14px', padding: '2px 12px', borderColor: '#d9e1ec' },
+  header: { backgroundColor: '#f0f9ff', color: '#075985', fontWeight: 700, textAlign: 'center' },
+  body: { color: '#334155' },
+  summary: { backgroundColor: '#f0fdf4', color: '#166534', textAlign: 'right' },
+  activeCell: { backgroundColor: '#fef3c7', borderColor: '#d97706', borderWidth: '2px' },
+  activeRow: { backgroundColor: '#e0e7ff', color: '#3730a3' },
+  scrollVertical: { width: '14px', color: '#94a3b8', backgroundColor: '#f1f5f9', borderRadius: 4 },
+  scrollHorizontal: { height: '12px', color: '#64748b', backgroundColor: '#f8fafc' },
+  pagination: {
+    root: { backgroundColor: '#f8fafc', color: '#334155', fontSize: '14px' },
+    total: { color: '#64748b' },
+    pageItem: { borderRadius: 4 },
+    activePageItem: { backgroundColor: '#1677ff', color: '#fff' },
+    sizeChanger: { width: 140 },
+    quickJumperInput: { width: 64 },
+  },
+}
+```
+
+- `cell` 是表头、表体和汇总单元格的通用默认值；分区覆盖通用值，列级 `headerStyle` / `cellStyle` / `summaryStyle` 优先。
+- Canvas 分区支持 `backgroundColor`、`color`、`fontSize`、`fontWeight`、`fontFamily`、`textAlign`、`verticalAlign`、`padding`、`paddingInline`、`paddingBlock`、`borderColor`、`borderWidth`。长度只支持非负数字或 `px`，`padding` 支持一值或“上下 左右”两值；不支持百分比、`em` 或 DOM 布局属性。
+- `activeCell` 支持背景、文字和边框，`activeRow` 支持背景与文字；仅改变已有选中状态的绘制，不改变选择模式。校验错误提示仍优先。
+- 滚动条 `color` 对应滑块、`backgroundColor` 对应槽色；纵轴 `width`、横轴 `height` 对应厚度。显式 `scrollbar.vertical/horizontal: false` 仍禁止对应轴显示。
+- `pagination` 按节点直接应用 DOM CSS，使用 camelCase 属性名，数字长度按 React DOM 规则处理；仅影响当前实例。通过原生 UI 回调自行渲染分页器时，从 `PaginationConfig.styles` 读取并应用样式。当前分页占位高度仍由表格密度决定，避免设置超出该高度的高度或纵向间距。
+
+分页器支持以下节点：
+
+| 节点                        | 作用                                                 |
+| --------------------------- | ---------------------------------------------------- |
+| `root`                      | 分页器根容器，颜色、字体等可向内部继承               |
+| `total`                     | 总条数文本                                           |
+| `pages`                     | 页码列表容器                                         |
+| `pageItem`                  | 普通页码按钮；简易模式下为页码文本                   |
+| `activePageItem`            | 当前页按钮，叠加并覆盖 `pageItem`                    |
+| `prevButton` / `nextButton` | 上一页 / 下一页按钮                                  |
+| `prevIcon` / `nextIcon`     | 上一页 / 下一页箭头，通过 `borderColor` 设置箭头颜色 |
+| `ellipsis`                  | 页码省略号                                           |
+| `sizeChanger`               | 分页尺寸选择控件，不包含弹出选项面板                 |
+| `quickJumper`               | 快速跳转区域容器                                     |
+| `quickJumperText`           | “跳至”和“页”文本                                     |
+| `quickJumperInput`          | 跳转输入控件外框，可设置宽度、背景与边框             |
+
+节点样式优先于默认样式；未配置节点保持原样。独立使用 `ReactPagination` 时也支持同名 `styles`，其中 `styles.root` 优先于 `style`。
+
+- 更新或移除 `styles` 后即时生效；不额外持久化 `styles` 对象，已有列配置缓存中的对齐设置仍优先。嵌套子表格的独立内容样式仍通过其列/内容配置指定。
+
+文档站“主题”示例增加了“启用分区 CSS 样式”开关，可切换验证。
+
 ## 安装方法
 
 ```bash