listpage_cli 0.0.291 → 0.0.292

package/bin/cli.js

@@ -5,7 +5,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const fs_1 = require("fs");
-const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const prompts_1 = require("./prompts");
 const copy_1 = require("./copy");
@@ -71,16 +70,13 @@ async function syncDocsCmd() {
 }
 async function installSkillCmd() {
     const args = process.argv.slice(2);
-    const projectMode = args.includes("--project");
-    const skillName = args.find((a) => a !== "install-skill" && a !== "--project") || "listpage";
+    const skillName = args.find((a) => a !== "install-skill") || "test";
     const sourceDir = path_1.default.join(__dirname, "..", "skills", skillName);
     if (!(0, fs_1.existsSync)(sourceDir)) {
         console.error(`技能 ${skillName} 不存在`);
         process.exit(1);
     }
-    const targetDir = projectMode
-        ? path_1.default.join(process.cwd(), ".cursor", "skills", skillName)
-        : path_1.default.join(os_1.default.homedir(), ".cursor", "skills", skillName);
+    const targetDir = path_1.default.join(process.cwd(), ".cursor", "skills", skillName || "");
     (0, copy_1.copySkillDir)(sourceDir, targetDir);
     console.log(`已安装 ${skillName} 技能到 ${targetDir}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "listpage_cli",
-  "version": "0.0.291",
+  "version": "0.0.292",
   "private": false,
   "bin": {
     "listpage_cli": "bin/cli.js"

package/skills/listpage/SKILL.md

@@ -5,15 +5,22 @@ description: 使用 listpage-next 实现页面级列表/表格。Use ONLY when u
 
 # ListPage 使用技能
 
-使用 `listpage-next`。示例与 API 见 [examples.md](examples.md)、[api.md](api.md)。
+示例与 API 见 [examples.md](examples.md)、[api.md](api.md)。
 
-## 核心要点
+## 生成流程（7 步）
 
-- **request**：`(pageParams, filterValues) => Promise<{ list, total, current, pageSize }>`
-- **必配**：`request`、`table.columns`、`table.tableProps.rowKey`
-- **浮窗**：`floats=[{ key, render }]`，`ctx.showFloat(key, record, true)` 关闭后刷新
+```
+Task Progress:
+- [ ] 步骤 1：创建目录结构（简单页面单文件；复杂页面 config/ + components/）
+- [ ] 步骤 2：定义 filters（FilterFormOption[]，AntD 组件 + allowClear）
+- [ ] 步骤 3：定义 columns （ListPageTableColumn[]，优先 component: 'text'|'link'|'switch'）
+- [ ] 步骤 4：实现 request（(params, filters) => Promise<PaginationData<T>>）
+- [ ] 步骤 5：组装 index.tsx（initialValues、注入 request/filter/table/floats ）
+- [ ] 步骤 6：注册 floats（若有浮窗：floats=[{ key, render }]，ctx.showFloat(key, record, true)）
+- [ ] 步骤 7：自检（rowKey、storageKey 唯一、浮窗 key 短横线小写）
+```
 
-## 目录结构
+## 命名约定
 
-- **简单页面**：单文件内联 columns、filters、request
-- **复杂页面**（筛选项 > 3、列 > 5、浮窗 > 1）：`pages/<Feature>/config/{columns,filters,floats,request}.tsx` + `components/`
+- 浮窗 key：短横线小写（如 `create`、`edit-detail`）
+- 文件：小驼峰（`columns.tsx`、`filters.tsx`）

package/skills/listpage/api.md

@@ -1,92 +1,163 @@
-# API
+# API（listpage-components）
+
+基于 `listpage-components` 的 ListPage Props 及使用中涉及的类型。
 
 ## ListPageProps
 
-| 属性 | 说明 | 类型 | 默认值 | 必填 |
-| --- | --- | --- | --- | --- |
-| `styles` | 页面容器样式覆盖 | `{ page?: React.CSSProperties }` | - | 否 |
-| `storageKey` | 本地存储键名（分页/筛选持久化） | `string` | - | 否 |
-| `initialValues` | 初始值（在无 `state` 与缓存时生效） | `{ filterValues?: any; pageSize?: number; currentPage?: number }` | - | 否 |
-| `state` | 外部初始化值（优先级最高，非受控） | `{ filterValues?: any; pageSize?: number; currentPage?: number }` | - | 否 |
-| `request` | 数据请求函数，返回分页数据 | `(pageParams: { current?: number; pageSize?: number; sort?: string }, filterValues: any) => Promise<{ total: number; pageSize: number; current: number; list: any[] }>` | - | 是 |
-| `header` | 页面标题与右侧操作 | `{ title?: React.ReactNode; extra?: React.ReactNode | ((ctx) => React.ReactNode) }` | - | 否 |
-| `filter` | 筛选配置 | `{ labelInline?: boolean; options: FilterFormOption[]; onReset?: () => void; onChange?: (value) => void }` | - | 否 |
-| `toolbar` | 页面级工具栏 | `{ render: (ctx) => React.ReactNode }` | - | 否 |
-| `table` | 表格配置 | `DataTableProps` | - | 是 |
-| `floats` | 浮窗定义 | `Array<{ key: string; render: (props: FloatComponentProps) => JSX.Element }>` | - | 否 |
-
-## FilterFormOption
-
-| 属性 | 说明 | 类型 | 默认值 | 必填 |
-| --- | --- | --- | --- | --- |
-| `name` | 字段名 | `string` | - | 是 |
-| `label` | 标签 | `React.ReactNode` | - | 否 |
-| `component` | 组件类型或自定义节点 | `'input' | 'select' | 'async-select' | 'daterange' | ReactElement` | `'input'` | 否 |
-| `colSpan` | 栅格占比（6 表示半行） | `number` | `2` | 否 |
-| `props` | 组件 props（随类型变化） | `ComponentProps<Type>` | - | 否 |
-| `formItemProps` | antd `Form.Item` 属性（去除 children） | `Omit<FormItemProps, 'children'>` | - | 否 |
-
-组件映射与值约定：
-- `'input'` → antd `Input`
-- `'select'` → antd `Select`
-- `'async-select'` → 组件库 `AsyncSelect`，`request` 返回 `{ list, total, current, pageSize }`
-- `'daterange'` → 增强版 `RangePicker`，提交值为 `[start: string, end: string]`
-
-## DataTableProps（`ListPage.table`）
-
-| 属性 | 说明 | 类型 | 默认值 | 必填 |
-| --- | --- | --- | --- | --- |
-| `columns` | 列配置 | `ListPageTableColumn[]` | `[]` | 否 |
-| `title` | 表格卡片标题 | `React.ReactNode` | - | 否 |
-| `extra` | 标题右侧操作（函数可访问 ctx） | `React.ReactNode | ((ctx) => React.ReactNode)` | - | 否 |
-| `tableProps` | antd `Table` 其他属性（除 `dataSource/title/columns`） | `Omit<TableProps, 'dataSource' | 'title' | 'columns'>` | - | 否 |
-| `rowSelectionType` | 选择类型 | `'checkbox' | 'radio'` | - | 否 |
-| `rowTitleKey` | 标题展示所选关键字段 | `string` | - | 否 |
-
-分页说明：底部中文本地化；`pageSizeOptions=[10,20,50,100]`；`showTotal="start-end 共 total 条"`；`tableProps.pagination===false` 隐藏分页。
-
-## ListPageTableColumn
-
-| 属性 | 说明 | 类型 | 默认值 | 必填 |
-| --- | --- | --- | --- | --- |
-| `title` | 列头 | `React.ReactNode` | - | 否 |
-| `dataIndex` | 数据字段 | `string` | - | 否 |
-| `key` | 唯一键 | `string` | - | 否 |
-| `width` | 列宽 | `number` | - | 否 |
-| `fixed` | 固定列 | `'left' | 'right'` | - | 否 |
-| `ellipsis` | 省略展示 | `boolean` | - | 否 |
-| `component` | 内置或自定义渲染 | `'text' | 'time' | 'tag' | 'link' | 'switch' | ((value, record, index, ctx) => React.ReactNode)` | - | 否 |
-| `props` | 随 `component` 类型变化的 props | `any` | - | 否 |
-
-内置渲染 props 说明：
-- `text`：透传 `Typography.Text`，默认 `ellipsis={{ tooltip: true }}`
-- `time`：`{ format?: string }`，无值显示 `'-'`
-- `tag`：透传 `TagProps`
-- `link`：`{ titlePropName?: string | (record)=>string; hrefPropName?: string | (record)=>string; target?: HTMLAttributeAnchorTarget }`
-- `switch`：`{ syncChange?: (value: boolean, record) => Promise<void> }`
-
-## Floats（浮窗）
+| 属性 | 说明 | 类型 | 必填 |
+| --- | --- | --- | --- |
+| `title` | 页面标题 | `ReactNode` | 否 |
+| `extra` | 标题右侧操作区 | `ReactNode \| (ctx: ListPageContextValue) => ReactNode` | 否 |
+| `filter` | 筛选配置 | `FilterConfig \| FilterRenderConfig` | 否 |
+| `toolbar` | 工具栏 | `ToolbarRenderConfig` | 否 |
+| `table` | 表格配置 | `TableConfig \| TableRenderConfig` | 是 |
+| `request` | 数据请求 | `ListPageRequest` | 是 |
+| `floats` | 浮窗列表 | `FloatItem[]` | 否 |
+| `initialValues` | 初始值 | `InitialValues` | 否 |
 
-| 属性 | 说明 | 类型 |
-| --- | --- | --- |
-| `key` | 浮窗标识，短横线小写 | `string` |
-| `render` | 浮窗组件渲染函数 | `(props: { record: any; visible: boolean; onClose: () => void }) => JSX.Element` |
+---
+
+## InitialValues
+
+```ts
+type InitialValues = {
+  filterValues?: any;   // 预填筛选
+  pageSize?: number;   // 默认每页条数
+  currentPage?: number; // 默认当前页
+};
+```
+
+---
+
+## filter（FilterConfig）
+
+```ts
+type FilterConfig = { items: FilterItem[] };
+
+type FilterItem = {
+  name: string;
+  label?: ReactNode;
+  component?: ReactElement;   // antd Input、Select 等
+  colSpan?: number;
+  formItemProps?: Omit<FormItemProps, 'children'>;
+};
+```
+
+也可使用 `FilterRenderConfig`：`{ render: (props: FilterRenderProps) => ReactNode }` 自定义渲染。
 
-调用方式：在列或工具栏中使用 `ctx.showFloat(key, record, onCloseCallback)`；传 `true` 关闭后自动刷新列表，传函数自定义回调。
+---
 
-## ListPageStore（上下文）
+## toolbar（ToolbarRenderConfig）
 
-| 名称 | 说明 | 类型/签名 |
+```ts
+type ToolbarRenderConfig = {
+  render: (props: ToolbarRenderProps) => ReactNode;
+};
+
+type ToolbarRenderProps = {
+  ctx: ListPageContextValue;
+  selection?: SelectionState;   // { selectedRowKeys; selectedRows }
+};
+```
+
+---
+
+## table（TableConfig）
+
+```ts
+type TableConfig = {
+  columns: ListPageColumnType[];
+  rowKey?: string;
+  rowSelection?: boolean | object;
+  title?: ReactNode;            // 表格标题
+  extra?: ReactNode | (ctx: ListPageContextValue) => ReactNode;
+  rowTitleKey?: string;         // 选中项 Tooltip 展示的字段
+  pagination?: PaginationProps; // antd 分页配置
+  [key: string]: any;           // 透传至 antd Table
+};
+```
+
+---
+
+## ListPageColumnType
+
+继承 antd `ColumnType`，额外支持：
+
+| 属性 | 说明 | 类型 |
 | --- | --- | --- |
-| `filters` | 当前筛选条件 | `any` |
-| `dataSource` | 表格数据源 | `any[]` |
-| `pagination` | 分页信息 | `{ current: number; pageSize: number; total: number }` |
-| `loadingData` | 加载状态 | `boolean` |
-| `selection` | 选择集 | `{ selectedRowKeys: Key[]; selectedRows: any[] }` |
-| `submitFilters` | 提交筛选并重置页码 | `(value) => void` |
-| `showFloat` | 打开浮窗 | `(key: string, record: any, onCloseCallback?: true | (() => void)) => void` |
-| `hideFloat` | 关闭浮窗 | `() => void` |
-| `updatePage` | 更新页码与页大小 | `(page: number, pageSize: number) => void` |
-| `fetchTableData` | 拉取数据 | `() => Promise<void>` |
-| `refreshTable` | 刷新数据 | `() => void` |
-| `listen/emit` | 事件机制 | `(name: string, cb: (data:any)=>void) / (name: string, data:any) => void` |
+| `renderer` | 内置渲染器 | `ColumnRendererType` |
+| `rendererOptions` | 渲染器配置 | `ColumnRendererOptions[renderer]` |
+| `component` | 自定义渲染（优先于 renderer） | `(props: ColumnComponentProps) => ReactNode` |
+
+**ColumnComponentProps**：`{ ctx: ListPageContextValue; record; index; value }`
+
+**ColumnRendererType**：`'text' | 'ellipsis' | 'tag' | 'badge' | 'date' | 'datetime' | 'number' | 'money' | 'percent' | 'boolean' | 'link' | 'enum' | 'copyable' | 'avatar' | 'image'`
+
+**ColumnRendererOptions**（按 renderer 选配）：
+- `ellipsis`: `{ maxLength?: number }`
+- `tag`: `{ colorMap?: Record<string, string>; options?: Array<{ value; label; color? }> }`
+- `badge`: `{ colorMap }`
+- `date` / `datetime`: `{ format?: string }`
+- `number` / `money` / `percent`: `{ precision?: number }`，`money` 额外 `{ prefix?: string }`
+- `boolean`: `{ labels?: [string, string] }`
+- `link`: `{ onClick?: (record, ctx?) => void; href?: (record) => string }`
+- `enum`: `{ options: Array<{ value; label }> }`
+- `avatar`: `{ fallback?: string }`
+- `image`: `{ width?: number; height?: number }`
+
+---
+
+## request（ListPageRequest）
+
+```ts
+type ListPageRequest = (
+  pageParams: RequestParams,
+  filterValues: any,
+  sortParams: SortParams
+) => Promise<{ list: any[]; total: number }>;
+
+type RequestParams = { current: number; pageSize: number };
+type SortParams = { field?: string; order?: 'ascend' | 'descend' | null };
+```
+
+---
+
+## floats（FloatItem）
+
+```ts
+type FloatItem = {
+  key: string;
+  render: (props: FloatComponentProps) => ReactNode;
+};
+
+type FloatComponentProps<T = any> = {
+  record: T;
+  visible: boolean;
+  onClose: (code?: number) => void | (() => void);
+  // (code?: number) => void：onClose() 取消不刷新，onClose(1) 确认并刷新
+};
+```
+
+---
+
+## ListPageContextValue
+
+`extra`、`toolbar.render`、`table.extra`、列 `component` 中通过 `useListPageContext()` 获取。
+
+| 属性 | 说明 |
+| --- | --- |
+| `filters` | 当前筛选值 |
+| `initialFilterValues` | 初始筛选值 |
+| `pagination` | `{ current; pageSize; total }` |
+| `dataSource` | 表格数据 |
+| `loading` | 加载中 |
+| `selection` | `{ selectedRowKeys; selectedRows }` |
+| `sort` | `{ field?; order? }` |
+| `refreshTable` | 刷新表格 |
+| `submitFilters` | 提交筛选并刷新 |
+| `resetFilters` | 重置筛选 |
+| `updatePagination` | 更新分页 `(page, pageSize)` |
+| `updateSort` | 更新排序 `(field?, order?)` |
+| `showFloat` | 打开浮窗 `(key, record, onCloseCallback?: true \| (() => void))` |
+| `hideFloat` | 关闭浮窗 |
+| `onSelectionChange` | 选中变更 `(keys, rows)` |

package/skills/listpage/examples.md

@@ -1,108 +1,202 @@
 # ListPage 示例
 
-## 1. 最小示例（单文件内联）
+## 1. 最小示例（单文件内联，listpage-components）
 
 ```tsx
-import { ListPage, type FilterFormOption, type ListPageTableColumn } from 'listpage-next';
-import { Button, Input, Select, Space } from 'antd';
-
-const filters: FilterFormOption[] = [
-  { name: 'name', label: '姓名', component: <Input placeholder="请输入" /> },
-  { name: 'status', label: '状态', component: <Select allowClear options={[{ value: 'enabled', label: '启用' }, { value: 'disabled', label: '停用' }]} /> },
+import { ListPage } from "listpage-components";
+import { Button, Input, Select, Space } from "antd";
+
+const filterItems = [
+  { name: "name", label: "姓名", component: <Input placeholder="请输入" /> },
+  {
+    name: "status",
+    label: "状态",
+    component: (
+      <Select
+        allowClear
+        options={[
+          { value: "enabled", label: "启用" },
+          { value: "disabled", label: "停用" },
+        ]}
+      />
+    ),
+  },
 ];
 
-const columns: ListPageTableColumn[] = [
-  { title: '姓名', dataIndex: 'name', key: 'name', component: 'text' },
-  { title: '地址', dataIndex: 'address', key: 'address', ellipsis: true },
+const columns = [
+  { title: "姓名", dataIndex: "name", key: "name", renderer: "text" },
+  { title: "地址", dataIndex: "address", key: "address", ellipsis: true },
 ];
 
-const request = async ({ current = 1, pageSize = 10 }, filterValues: any) => {
-  const all = Array.from({ length: 100 }).map((_, i) => ({ id: i + 1, name: `Edward ${i + 1}`, address: `Address ${i + 1}` }));
-  let list = all.filter((r) => !filterValues?.name || r.name.includes(filterValues.name));
+const request = async (
+  { current, pageSize }: { current: number; pageSize: number },
+  filterValues: any,
+  _sortParams: { field?: string; order?: "ascend" | "descend" | null }
+) => {
+  const all = Array.from({ length: 100 }).map((_, i) => ({
+    id: i + 1,
+    name: `Edward ${i + 1}`,
+    address: `Address ${i + 1}`,
+  }));
+  let list = all.filter(
+    (r) => !filterValues?.name || r.name.includes(filterValues.name)
+  );
   const skip = (current - 1) * pageSize;
-  return { list: list.slice(skip, skip + pageSize), total: list.length, current, pageSize };
+  return { list: list.slice(skip, skip + pageSize), total: list.length };
 };
 
 export default function Page() {
   return (
     <ListPage
-      storageKey="demo-listpage"
-      initialValues={{ currentPage: 1, pageSize: 10 }}
+      title="用户列表"
+      extra={(ctx) => (
+        <Space>
+          <Button onClick={() => ctx.refreshTable()}>刷新</Button>
+        </Space>
+      )}
+      filter={{ items: filterItems }}
+      table={{ columns, rowKey: "id" }}
       request={request}
-      header={{ title: '用户列表', extra: (ctx) => <Space><Button onClick={() => ctx.refreshTable()}>刷新</Button></Space> }}
-      filter={{ options: filters }}
-      table={{ columns, tableProps: { rowKey: 'id' } }}
+      initialValues={{ currentPage: 1, pageSize: 10 }}
     />
   );
 }
 ```
 
-## 2. 带浮窗（新增 Drawer）
+## 2. 复杂用法（内置渲染器、toolbar、多浮窗）
 
-```tsx
-import { ListPage, type FilterFormOption, type ListPageTableColumn } from 'listpage-next';
-import { Button, Input, Drawer, Space } from 'antd';
-import { useState } from 'react';
-
-const filters: FilterFormOption[] = [{ name: 'name', label: '姓名', component: <Input placeholder="请输入" /> }];
-const columns: ListPageTableColumn[] = [
-  { title: '姓名', dataIndex: 'name', key: 'name', component: 'text' },
-];
+内置列渲染器：`text`、`ellipsis`、`tag`、`badge`、`date`、`datetime`、`number`、`money`、`percent`、`boolean`、`link`、`enum`、`copyable`、`avatar`、`image`。浮窗 `onClose(1)` 表示确认并刷新，`onClose()` 表示取消。
 
-const request = async ({ current = 1, pageSize = 10 }, f: any) => {
-  const list = [{ id: 1, name: 'Test' }];
-  return { list, total: 1, current, pageSize };
-};
-
-const CreateDrawer = (props: { record: any; visible: boolean; onClose: () => void }) => {
-  const { visible, onClose } = props;
-  return (
-    <Drawer open={visible} title="新增" onClose={onClose}>
-      <Input placeholder="姓名" />
-      <Button type="primary" onClick={onClose}>保存</Button>
-    </Drawer>
-  );
+```tsx
+import { ListPage } from "listpage-components";
+import { Button, Input, Select, Space, Drawer, Modal, message } from "antd";
+
+const request = async (pageParams, filterValues) => {
+  const { current, pageSize } = pageParams;
+  // 模拟数据与筛选...
+  const list = [{ id: "1", name: "张三", dept: "研发", status: "启用", price: "100.00", createTime: "2025-01-01" }];
+  return { list, total: list.length };
 };
 
-export default function Page() {
-  return (
-    <ListPage
-      storageKey="LISTPAGE_USER"
-      request={request}
-      header={{ title: '用户', extra: (ctx) => <Button type="primary" onClick={() => ctx.showFloat('create', {}, true)}>新增</Button> }}
-      filter={{ options: filters }}
-      table={{ columns, tableProps: { rowKey: 'id' } }}
-      floats={[{ key: 'create', render: CreateDrawer }]}
-    />
-  );
-}
+const DetailModal = ({ record, visible, onClose }) => (
+  <Modal open={visible} title="详情" onCancel={onClose} footer={null}>
+    <p>姓名：{record?.name}</p>
+  </Modal>
+);
+
+const EditModal = ({ record, visible, onClose }) => (
+  <Modal open={visible} title="编辑" onCancel={onClose} onOk={() => { message.success("保存成功"); onClose(1); }}>
+    <Input defaultValue={record?.name} />
+  </Modal>
+);
+
+const CreateDrawer = ({ record, visible, onClose }) => (
+  <Drawer open={visible} title="新建" onClose={() => onClose()}>
+    <Input placeholder="姓名" />
+    <Button type="primary" onClick={() => { message.success("新建成功"); onClose(1); }}>保存</Button>
+  </Drawer>
+);
+
+export default () => (
+  <ListPage
+    title="用户列表"
+    initialValues={{ filterValues: {}, pageSize: 10, currentPage: 1 }}
+    extra={(ctx) => <Button type="primary" onClick={() => ctx.showFloat("create", {}, true)}>新建</Button>}
+    filter={{
+      items: [
+        { name: "name", label: "姓名", component: <Input allowClear placeholder="姓名" /> },
+        { name: "dept", label: "部门", component: <Select allowClear options={[{ label: "研发", value: "研发" }]} /> },
+        { name: "status", label: "状态", component: <Select allowClear options={[{ label: "启用", value: "启用" }]} /> },
+      ],
+    }}
+    toolbar={{ render: ({ ctx }) => <Button onClick={() => ctx.refreshTable()}>刷新</Button> }}
+    table={{
+      title: "数据列表",
+      rowSelection: true,
+      rowTitleKey: "name",
+      extra: (ctx) => <Button size="small" onClick={() => ctx.refreshTable()}>刷新</Button>,
+      rowKey: "id",
+      columns: [
+        { title: "ID", dataIndex: "id", key: "id", width: 100, renderer: "copyable" },
+        { title: "姓名", dataIndex: "name", key: "name", width: 100, renderer: "link", rendererOptions: { onClick: (record, ctx) => ctx?.showFloat("detail", record) } },
+        { title: "部门", dataIndex: "dept", key: "dept", width: 90, renderer: "tag", rendererOptions: { colorMap: { 研发: "blue" } } },
+        { title: "状态", dataIndex: "status", key: "status", width: 90, renderer: "tag", rendererOptions: { colorMap: { 启用: "success" } } },
+        { title: "价格", dataIndex: "price", key: "price", width: 110, renderer: "money", rendererOptions: { precision: 2, prefix: "¥" } },
+        { title: "创建时间", dataIndex: "createTime", key: "createTime", width: 110, renderer: "date", rendererOptions: { format: "YYYY-MM-DD" } },
+        {
+          title: "操作",
+          key: "action",
+          width: 140,
+          fixed: "right",
+          component: ({ ctx, record }) => (
+            <Space size="small">
+              <Button type="link" size="small" onClick={() => ctx.showFloat("detail", record)}>详情</Button>
+              <Button type="link" size="small" onClick={() => ctx.showFloat("edit", record, true)}>编辑</Button>
+            </Space>
+          ),
+        },
+      ],
+    }}
+    request={request}
+    floats={[
+      { key: "detail", render: DetailModal },
+      { key: "edit", render: EditModal },
+      { key: "create", render: CreateDrawer },
+    ]}
+  />
+);
 ```
 
-## 3. 带行选择
+## 3. 带初始状态（initialValues）
+
+`initialValues` 用于预填筛选条件、分页等，组件首次挂载时生效。
 
 ```tsx
-table={{
-  columns,
-  rowSelectionType: 'checkbox',
-  rowTitleKey: 'name',
-  tableProps: { rowKey: 'id' },
-}}
+<ListPage
+  title="用户列表"
+  initialValues={{
+    filterValues: { name: "张三", status: "启用" },
+    pageSize: 20,
+    currentPage: 1,
+  }}
+  filter={{ items: filterItems }}
+  table={{ columns, rowKey: "id" }}
+  request={request}
+/>
 ```
 
-## 4. 带 toolbar
+## 4. 带行选择
 
 ```tsx
-toolbar={{
-  render: (ctx) => (
-    <Space>
-      <Button onClick={() => ctx.refreshTable()}>刷新</Button>
-      <Button>导出</Button>
-    </Space>
-  ),
+table={{
+  columns,
+  rowKey: "id",
+  rowSelection: true,
+  rowTitleKey: "name",
 }}
 ```
 
-## 5. 复杂结构（config 拆分目录）
+## 5. 内置渲染器速查（listpage-components）
+
+| renderer | 说明 | rendererOptions 示例 |
+| --- | --- | --- |
+| text | 文本 | - |
+| ellipsis | 省略 | `{ maxLength: 10 }` |
+| tag | 标签 | `{ colorMap: { 启用: "success" } }` |
+| badge | 徽标 | `{ colorMap: { 0: "default" } }` |
+| date | 日期 | `{ format: "YYYY-MM-DD" }` |
+| datetime | 日期时间 | `{ format: "YYYY-MM-DD HH:mm:ss" }` |
+| number | 数字 | `{ precision: 2 }` |
+| money | 金额 | `{ precision: 2, prefix: "¥" }` |
+| percent | 百分比 | `{ precision: 1 }` |
+| boolean | 布尔 | `{ labels: ["否", "是"] }` |
+| link | 链接 | `{ onClick: (record, ctx) => ctx?.showFloat("detail", record) }` |
+| enum | 枚举 | `{ options: [{ value: 0, label: "男" }] }` |
+| copyable | 可复制 | - |
+| avatar | 头像 | `{ fallback: "?" }` |
+| image | 图片 | `{ width: 40, height: 40 }` |
+
+## 6. 复杂结构（config 拆分目录）
 
 目录结构：
 
@@ -122,27 +216,27 @@ pages/MemberList/
 **config/index.tsx** 汇总导出：
 
 ```tsx
-export { columns } from './columns';
-export { filters } from './filters';
-export { floats } from './floats';
-export { request } from './request';
+export { columns } from "./columns";
+export { filters } from "./filters";
+export { floats } from "./floats";
+export { request } from "./request";
 ```
 
-**index.tsx** 组装：
+**index.tsx** 组装（listpage-components）：
 
 ```tsx
-import { ListPage } from 'listpage-next';
-import { columns, filters, floats, request } from './config';
+import { ListPage } from "listpage-components";
+import { columns, filters, floats, request } from "./config";
 
 export default function MemberListPage() {
   return (
     <ListPage
-      storageKey="LISTPAGE_MEMBER"
+      title="会员列表"
+      filter={{ items: filters }}
+      table={{ columns, rowKey: "id" }}
       request={request}
-      header={{ title: '会员列表' }}
-      filter={{ options: filters }}
-      table={{ columns, tableProps: { rowKey: 'id' } }}
       floats={floats}
+      initialValues={{ pageSize: 10, currentPage: 1 }}
     />
   );
 }

package/templates/backend-template/package.json.tmpl

@@ -25,7 +25,7 @@
     "class-transformer": "^0.5.1",
     "class-validator": "~0.14.2",
     "rxjs": "^7.8.1",
-    "listpage-next-nest": "~0.0.291"
+    "listpage-next-nest": "~0.0.292"
   },
   "devDependencies": {
     "@nestjs/schematics": "^11.0.0",

package/templates/frontend-template/package.json.tmpl

@@ -12,7 +12,7 @@
   "dependencies": {
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
-    "listpage-next": "~0.0.291",
+    "listpage-next": "~0.0.292",
     "react-router-dom": ">=6.0.0",
     "@ant-design/v5-patch-for-react-19": "~1.0.3",
     "ahooks": "^3.9.5",
@@ -23,7 +23,7 @@
     "styled-components": "^6.1.19",
     "mobx": "~6.15.0",
     "@ant-design/icons": "~6.0.2",
-    "listpage-components": "~0.0.291",
+    "listpage-components": "~0.0.292",
     "lucide-react": "~0.575.0"
     "mobx-react-lite": "~4.1.1"
   },

package/templates/package-app-template/package.json

@@ -9,7 +9,7 @@
     "publish": "ts-node src/publish.ts"
   },
   "dependencies": {
-    "listpage-next-deploy": "0.0.291"
+    "listpage-next-deploy": "0.0.292"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",