listpage_cli 0.0.293 → 0.0.294

package/templates/skills-template/listpage/examples.md

@@ -0,0 +1,565 @@
+# ListPage 示例
+
+## 1. 最小示例（单文件内联，listpage-components）
+
+```tsx
+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 = [
+  { title: "姓名", dataIndex: "name", key: "name", renderer: "text" },
+  { title: "地址", dataIndex: "address", key: "address", ellipsis: true },
+];
+
+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 };
+};
+
+export default function Page() {
+  return (
+    <ListPage
+      title="用户列表"
+      extra={(ctx) => (
+        <Space>
+          <Button onClick={() => ctx.refreshTable()}>刷新</Button>
+        </Space>
+      )}
+      filter={{ items: filterItems }}
+      table={{ columns, rowKey: "id" }}
+      request={request}
+      initialValues={{ currentPage: 1, pageSize: 10 }}
+    />
+  );
+}
+```
+
+## 2. 复杂用法（内置渲染器、toolbar、多浮窗）
+
+内置列渲染器：`text`、`ellipsis`、`tag`、`badge`、`date`、`datetime`、`number`、`money`、`percent`、`boolean`、`link`、`enum`、`copyable`、`avatar`、`image`。浮窗 `onClose(1)` 表示确认并刷新，`onClose()` 表示取消。
+
+```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 };
+};
+
+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. 带初始状态（initialValues）
+
+`initialValues` 用于预填筛选条件、分页等，组件首次挂载时生效。
+
+```tsx
+<ListPage
+  title="用户列表"
+  initialValues={{
+    filterValues: { name: "张三", status: "启用" },
+    pageSize: 20,
+    currentPage: 1,
+  }}
+  filter={{ items: filterItems }}
+  table={{ columns, rowKey: "id" }}
+  request={request}
+/>
+```
+
+## 4. 带行选择
+
+```tsx
+table={{
+  columns,
+  rowKey: "id",
+  rowSelection: true,
+  rowTitleKey: "name",
+}}
+```
+
+## 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 拆分目录）
+
+目录结构：
+
+```
+pages/ContractTypeManage/
+├── index.tsx
+├── config/
+│   ├── columns.tsx
+│   ├── filters.tsx
+│   ├── floats.tsx
+│   └── request.ts
+└── components/
+      ├── ContractTypeForm.tsx
+      └── ContractTypeFormFloat.tsx
+```
+
+**components/ContractTypeForm.tsx** 表单组件：
+
+```tsx
+import { Form, Input, Select, type FormProps, type FormInstance } from "antd";
+
+export const ContractTypeForm = (
+  props: FormProps & { formRef?: React.Ref<FormInstance> }
+) => {
+  const { formRef, ...rest } = props;
+  return (
+    <Form ref={formRef} layout="vertical" {...rest}>
+      <Form.Item
+        name="name"
+        label="类型名称"
+        rules={[{ required: true, message: "请输入类型名称" }]}
+      >
+        <Input placeholder="请输入类型名称" allowClear />
+      </Form.Item>
+      <Form.Item
+        name="payment_nodes"
+        label="付款节点"
+        rules={[{ required: true, message: "请配置付款节点" }]}
+        extra="输入节点名称后按回车添加"
+      >
+        <Select
+          mode="tags"
+          style={{ width: "100%" }}
+          placeholder="请输入或选择付款节点"
+          options={[
+            { value: "预付", label: "预付" },
+            { value: "发货", label: "发货" },
+            { value: "验收", label: "验收" },
+            { value: "进度", label: "进度" },
+            { value: "尾款", label: "尾款" },
+            { value: "到货", label: "到货" },
+            { value: "送电", label: "送电" },
+          ]}
+        />
+      </Form.Item>
+    </Form>
+  );
+};
+```
+
+**components/ContractTypeFormFloat.tsx** 浮窗组件：
+
+```tsx
+import { useRef } from "react";
+import { Button, Space, type FormInstance } from "antd";
+import { ProDrawer, type FloatComponentProps } from "listpage-components";
+import api from "@/api";
+import type { ContractType } from "@/api/contract-type";
+import { ContractTypeForm } from "./ContractTypeForm";
+
+export const ContractTypeFormFloat = (
+  props: FloatComponentProps<ContractType>
+) => {
+  const { record, visible, onClose } = props;
+  const formRef = useRef<FormInstance>(null);
+  const isEdit = !!record;
+
+  const handleSubmit = async (values: any) => {
+    if (isEdit) {
+      await api.contractType.update({ id: record.id, ...values });
+    } else {
+      await api.contractType.create(values);
+    }
+    onClose(1); // 1 表示刷新列表
+  };
+
+  return (
+    <ProDrawer
+      title={isEdit ? "编辑合同类型" : "新增合同类型"}
+      open={visible}
+      onClose={() => onClose()}
+      footer={
+        <Space>
+          <Button onClick={() => onClose()}>取消</Button>
+          <Button type="primary" onClick={() => formRef.current?.submit()}>
+            确定
+          </Button>
+        </Space>
+      }
+    >
+      <div className="p-6">
+        <ContractTypeForm
+          formRef={formRef}
+          initialValues={record}
+          onFinish={handleSubmit}
+          // 关键：通过 key 强制重新渲染，确保 initialValues 生效，代替 useEffect 重置表单
+          key={visible ? record?.id || "new" : "hidden"}
+        />
+      </div>
+    </ProDrawer>
+  );
+};
+```
+
+**config/floats.tsx** 浮窗配置：
+
+```tsx
+import type { FloatItem } from "listpage-components";
+import { ContractTypeFormFloat } from "../components/ContractTypeFormFloat";
+
+export const floats: FloatItem[] = [
+  {
+    key: "create",
+    render: ContractTypeFormFloat,
+  },
+  {
+    key: "update",
+    render: ContractTypeFormFloat,
+  },
+];
+```
+
+**config/columns.tsx** 表格列配置：
+
+```tsx
+import { Tag, Space, Button, Popconfirm, message } from "antd";
+import type { ListPageColumn } from "listpage-components";
+import api from "@/api";
+
+export const columns: ListPageColumn[] = [
+  {
+    title: "类型名称",
+    dataIndex: "name",
+    key: "name",
+  },
+  {
+    title: "付款节点",
+    dataIndex: "payment_nodes",
+    key: "payment_nodes",
+    render: (nodes: string[]) => (
+      <Space wrap>
+        {nodes.map((node) => (
+          <Tag key={node} color="blue">
+            {node}
+          </Tag>
+        ))}
+      </Space>
+    ),
+  },
+  {
+    title: "操作",
+    key: "action",
+    width: 150,
+    render: (_, record, __, ctx) => (
+      <Space>
+        <Button
+          type="link"
+          size="small"
+          onClick={() => ctx.showFloat("update", record)}
+        >
+          编辑
+        </Button>
+        <Popconfirm
+          title="确定删除吗？"
+          onConfirm={async () => {
+            await api.contractType.remove(record.id);
+            message.success("删除成功");
+            ctx.refreshTable();
+          }}
+        >
+          <Button type="link" size="small" danger>
+            删除
+          </Button>
+        </Popconfirm>
+      </Space>
+    ),
+  },
+];
+```
+
+**config/filters.tsx** 筛选配置：
+
+```tsx
+import type { FilterConfig } from "listpage-components";
+
+export const filters: FilterConfig["items"] = [
+  {
+    name: "name",
+    label: "类型名称",
+    type: "input",
+  },
+];
+```
+
+**config/request.ts** 请求配置：
+
+```ts
+import type { ListPageRequest } from "listpage-components";
+import api from "@/api";
+
+export const request: ListPageRequest = async (params) => {
+  const { currentPage, pageSize, ...rest } = params;
+  const data = await api.contractType.list({
+    current: currentPage,
+    pageSize,
+    ...rest,
+  });
+
+  return {
+    list: data.list,
+    total: data.total,
+  };
+};
+```
+
+**index.tsx** 页面组装：
+
+```tsx
+import { Button } from "antd";
+import { ListPage, type ListPageContextValue } from "listpage-components";
+import { filters, columns, request, floats } from "./config";
+
+export const ContractTypeManage = () => {
+  return (
+    <ListPage
+      title="合同类型管理"
+      initialValues={{ currentPage: 1, pageSize: 10 }}
+      request={request}
+      extra={(ctx: ListPageContextValue) => (
+        <Button
+          type="primary"
+          onClick={() => ctx.showFloat("create", undefined, true)}
+        >
+          新建
+        </Button>
+      )}
+      table={{
+        columns,
+        rowKey: "id",
+      }}
+      filter={{ items: filters }}
+      floats={floats}
+    />
+  );
+};
+
+export default ContractTypeManage;
+```