crud-page-react 0.0.1

package/README.md

@@ -0,0 +1,200 @@
+# CRUD Page React
+
+一个基于 React + Ant Design 的动态 CRUD 组件库，支持通过 JSON Schema 配置生成完整的增删改查界面。
+
+## 特性
+
+- 🚀 **零代码配置** - 通过 JSON Schema 配置即可生成完整 CRUD 界面
+- 📝 **丰富的表单组件** - 支持 15+ 种表单控件类型
+- 🔍 **智能筛选** - 自动生成筛选器，支持范围查询
+- 📊 **灵活表格** - 可配置列宽、排序、固定列等
+- 🎨 **Raw JSON 模式** - 支持原始 JSON 编辑和查看
+- 🔌 **自定义 API** - 支持自定义 API 请求函数
+- 📱 **响应式设计** - 适配移动端和桌面端
+- 🎯 **TypeScript 支持** - 完整的类型定义
+
+## 安装
+
+```bash
+npm install crud-page-react
+# 或
+yarn add crud-page-react
+```
+
+### 依赖要求
+
+```json
+{
+  "react": ">=16.8.0",
+  "react-dom": ">=16.8.0",
+  "antd": ">=5.0.0",
+  "dayjs": ">=1.11.0"
+}
+```
+
+## 快速开始
+
+```tsx
+import React from 'react';
+import { CrudPage } from 'crud-page-react';
+import type { CrudPageSchema } from 'crud-page-react';
+
+const schema: CrudPageSchema = {
+  id: 'users',
+  title: '用户管理',
+  api: {
+    list: '/api/users',
+    create: '/api/users',
+    update: '/api/users/:id',
+    delete: '/api/users/:id',
+  },
+  fields: [
+    {
+      key: 'id',
+      label: 'ID',
+      type: 'number',
+      table: { width: 80 },
+      form: false,
+    },
+    {
+      key: 'name',
+      label: '姓名',
+      type: 'string',
+      filter: true,
+      table: true,
+      form: { required: true },
+    },
+    {
+      key: 'email',
+      label: '邮箱',
+      type: 'string',
+      filter: true,
+      table: true,
+      form: { required: true },
+      rules: ['email'],
+    },
+    {
+      key: 'status',
+      label: '状态',
+      type: 'string',
+      widget: 'select',
+      config: {
+        options: [
+          { label: '启用', value: 'active' },
+          { label: '禁用', value: 'inactive' },
+        ],
+      },
+      filter: true,
+      table: true,
+      form: true,
+    },
+  ],
+  rowKey: 'id',
+};
+
+function App() {
+  return (
+    <div>
+      <CrudPage schema={schema} />
+    </div>
+  );
+}
+
+export default App;
+```
+
+## 自定义 API 请求
+
+```tsx
+import { CrudPage, ApiRequest } from 'crud-page-react';
+
+// 自定义 API 请求函数
+const customApiRequest: ApiRequest = async (url, options) => {
+  const token = localStorage.getItem('token');
+  const response = await fetch(url, {
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': token ? `Bearer ${token}` : '',
+      ...options?.headers,
+    },
+    ...options,
+  });
+  
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+  }
+  
+  return response.json();
+};
+
+// 使用自定义 API 请求
+<CrudPage
+  schema={schema}
+  apiRequest={customApiRequest}
+/>
+```
+
+## API 文档
+
+### CrudPageProps
+
+| 属性 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| schema | CrudPageSchema | ✓ | - | 页面配置 schema |
+| initialData | Record<string, unknown>[] | ✗ | [] | 初始数据，API 失败时作为降级数据 |
+| apiRequest | ApiRequest | ✗ | 内置 fetch | 自定义 API 请求函数 |
+
+### ApiRequest
+
+```typescript
+interface ApiRequest {
+  <T = unknown>(url: string, options?: RequestInit): Promise<T>;
+}
+```
+
+### CrudPageSchema
+
+完整的 schema 配置请参考类型定义文件。
+
+## 字段类型支持
+
+- `string` - 字符串
+- `number` - 数字  
+- `boolean` - 布尔值
+- `date` - 日期
+- `datetime` - 日期时间
+- `array` - 数组
+- `objectArray` - 对象数组
+
+## 组件类型支持
+
+- `input` - 输入框
+- `textarea` - 文本域
+- `inputNumber` - 数字输入
+- `select` - 下拉选择
+- `multiselect` - 多选下拉
+- `radio` - 单选按钮
+- `checkbox` - 复选框
+- `switch` - 开关
+- `datePicker` - 日期选择
+- `rangePicker` - 日期范围
+- `timePicker` - 时间选择
+- `editableTable` - 可编辑表格
+- `jsonInput` - JSON 编辑器
+
+## 开发
+
+```bash
+# 安装依赖
+npm install
+
+# 开发模式
+npm run dev
+
+# 构建
+npm run build
+```
+
+## 许可证
+
+MIT

package/dist/components/CrudPage.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import type { CrudPageSchema, ApiRequest } from '../types/schema';
+interface CrudPageProps {
+    schema: CrudPageSchema;
+    initialData?: Record<string, unknown>[];
+    apiRequest?: ApiRequest;
+}
+declare const CrudPage: React.FC<CrudPageProps>;
+export default CrudPage;

package/dist/components/DynamicFilter.d.ts

@@ -0,0 +1,8 @@
+import type { CrudPageSchema } from '../types/schema';
+interface DynamicFilterProps {
+    schema: CrudPageSchema;
+    onSearch: (values: Record<string, unknown>) => void;
+    onReset: () => void;
+}
+export default function DynamicFilter({ schema, onSearch, onReset }: DynamicFilterProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/DynamicForm.d.ts

@@ -0,0 +1,12 @@
+import type { CrudPageSchema } from '../types/schema';
+type FormMode = 'create' | 'edit' | 'view';
+interface DynamicFormProps {
+    schema: CrudPageSchema;
+    mode: FormMode;
+    visible: boolean;
+    initialValues?: Record<string, unknown>;
+    onSubmit: (values: Record<string, unknown>) => void;
+    onCancel: () => void;
+}
+export default function DynamicForm({ schema, mode, visible, initialValues, onSubmit, onCancel, }: DynamicFormProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/DynamicTable.d.ts

@@ -0,0 +1,18 @@
+import type { CrudPageSchema } from '../types/schema';
+interface DynamicTableProps {
+    schema: CrudPageSchema;
+    data: Record<string, unknown>[];
+    loading: boolean;
+    pagination: {
+        current: number;
+        pageSize: number;
+        total: number;
+        onChange: (page: number, pageSize: number) => void;
+    };
+    onView: (record: Record<string, unknown>) => void;
+    onEdit: (record: Record<string, unknown>) => void;
+    onDelete: (record: Record<string, unknown>) => void;
+    onCustomAction?: (actionKey: string, record: Record<string, unknown>) => void;
+}
+export default function DynamicTable({ schema, data, loading, pagination, onView, onEdit, onDelete, onCustomAction, }: DynamicTableProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,270 @@
+import React from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Rule } from 'antd/es/form';
+
+/** API 请求函数类型 */
+interface ApiRequest {
+    <T = unknown>(url: string, options?: RequestInit): Promise<T>;
+}
+/**
+ * 数据类型：描述字段存储的值类型。
+ *
+ * 嵌套对象不再作为独立类型，而是通过 key 的点分路径（dot-path）表达，
+ * 例如 `emergencyContact.name`、`emergencyContact.phone`。
+ * 框架会自动将 Form 数据写入/读出对应的嵌套路径。
+ */
+type DataType = 'string' | 'number' | 'boolean' | 'datetime' | 'date' | 'array' | 'objectArray';
+/** UI 组件类型：描述字段渲染使用的组件 */
+type WidgetType = 'input' | 'textarea' | 'inputNumber' | 'select' | 'multiselect' | 'radio' | 'checkbox' | 'switch' | 'datePicker' | 'rangePicker' | 'timePicker' | 'editableTable' | 'jsonInput';
+interface SelectOption {
+    label: string;
+    value: string | number | boolean;
+    color?: string;
+}
+/**
+ * 筛选项配置 —— 仅放筛选独有配置。
+ * options / placeholder / dateFormat 统一在 FieldSchema.config 里配置。
+ */
+interface FilterConfig {
+    /** 覆盖字段级 widget，指定筛选组件类型 */
+    widget?: WidgetType;
+    /** inputNumber 时可开启数字范围（min/max 两个输入框） */
+    range?: boolean;
+    defaultValue?: unknown;
+}
+/** 表格列配置 */
+interface TableColumnConfig {
+    width?: number;
+    fixed?: 'left' | 'right';
+    sortable?: boolean;
+    ellipsis?: boolean;
+}
+/**
+ * 表单字段配置 —— 仅放表单独有配置。
+ * options / placeholder / dateFormat / rows 统一在 FieldSchema.config 里配置。
+ */
+interface FormFieldConfig {
+    /** 覆盖字段级 widget，指定表单组件类型 */
+    widget?: WidgetType;
+    required?: boolean;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+/**
+ * 字段级共用组件配置。
+ * filter 和 form 均可读取，无需在两处重复填写。
+ */
+interface FieldConfig {
+    /** 下拉/多选/单选等组件的选项列表 */
+    options?: SelectOption[];
+    /** 输入框、选择框等的占位提示文字 */
+    placeholder?: string;
+    /** 日期/时间组件的显示格式，如 'YYYY-MM-DD' */
+    dateFormat?: string;
+    /** textarea / jsonInput 的行数 */
+    rows?: number;
+}
+/**
+ * 对象数组（objectArray）中每个 item 的字段定义。
+ * 故意保持简单：不支持嵌套 objectArray，不支持 dot-path key。
+ */
+interface ArrayItemField {
+    /** item 对象的属性名，不使用点分路径 */
+    key: string;
+    label: string;
+    /** 不允许嵌套数组 */
+    type: Exclude<DataType, 'array' | 'objectArray'>;
+    /** 不允许嵌套 editableTable */
+    widget?: Exclude<WidgetType, 'editableTable'>;
+    config?: Pick<FieldConfig, 'options' | 'placeholder' | 'dateFormat'>;
+    required?: boolean;
+    /** 列宽（px） */
+    width?: number;
+}
+/**
+ * 字段定义。
+ *
+ * ### 点分路径（dot-path）规则
+ * `key` 支持点分路径表达嵌套结构，例如：
+ * - `emergencyContact.name`
+ * - `emergencyContact.phone`
+ *
+ * Form 层会自动将值写入 / 读取对应的嵌套对象属性；
+ * 具有相同前缀的字段在表单中会被归为同一视觉分组，并显示分组标题。
+ */
+interface FieldSchema {
+    key: string;
+    label: string;
+    /** 数据类型（值的类型） */
+    type: DataType;
+    /**
+     * 默认 UI 组件类型；可被 filter / form 级别的 widget 覆盖。
+     * 不填时由 defaultWidgetForType 推导。
+     */
+    widget?: WidgetType;
+    filter?: boolean | FilterConfig;
+    table?: boolean | TableColumnConfig;
+    form?: boolean | FormFieldConfig;
+    /**
+     * 字段级共用组件配置（options、placeholder、dateFormat 等）。
+     * filter 和 form 均从这里读取，不再重复配置。
+     */
+    config?: FieldConfig;
+    render?: string;
+    /**
+     * 对象数组子字段定义，仅 type='objectArray' 时生效。
+     * 配置后 widget 默认推导为 'editableTable'。
+     */
+    itemFields?: ArrayItemField[];
+    /**
+     * 校验规则 key 数组，引用 validationRules.ts 中内置或自定义规则的 key。
+     * 例如 `rules: ['phone_cn', 'max_len_50']`
+     * 注意：required 规则通过 form.required 单独控制，无需在此重复。
+     */
+    rules?: string[];
+}
+type ActionType = 'edit' | 'delete' | 'view' | 'custom';
+interface ActionPermission {
+    role?: string[];
+    condition?: string;
+}
+interface ActionSchema {
+    key: string;
+    label: string;
+    type: ActionType;
+    icon?: string;
+    danger?: boolean;
+    permission?: ActionPermission;
+    confirm?: {
+        title: string;
+        content?: string;
+    };
+}
+interface PaginationConfig {
+    pageSize?: number;
+    pageSizeOptions?: number[];
+    showTotal?: boolean;
+}
+interface CrudPageSchema {
+    id: string;
+    title: string;
+    api: {
+        list: string;
+        create?: string;
+        update?: string;
+        delete?: string;
+        detail?: string;
+    };
+    fields: FieldSchema[];
+    actions?: ActionSchema[];
+    pagination?: PaginationConfig;
+    rowKey?: string;
+    createButtonLabel?: string;
+}
+/**
+ * 根据数据类型推导默认 UI 组件
+ *
+ * string      → input
+ * number      → inputNumber
+ * boolean     → switch
+ * date        → datePicker
+ * datetime    → datePicker
+ * array       → multiselect
+ * objectArray → editableTable
+ */
+declare function defaultWidgetForType(type: DataType): WidgetType;
+/** 获取实际生效的组件类型（context.widget > field.widget > type 推导） */
+declare function getEffectiveWidget(field: FieldSchema, config?: FilterConfig | FormFieldConfig): WidgetType;
+/**
+ * 从嵌套对象按点分路径取值
+ *
+ * getNestedValue({ a: { b: 1 } }, 'a.b') → 1
+ * getNestedValue({ x: [1, 2] }, 'x')      → [1, 2]
+ */
+declare function getNestedValue(obj: Record<string, unknown>, path: string): unknown;
+/**
+ * 从点分路径 key 中提取分组前缀（第一个 segment）。
+ * 无前缀的顶层字段返回 null。
+ *
+ * 'emergencyContact.name' → 'emergencyContact'
+ * 'name'                  → null
+ */
+declare function getFieldGroupPrefix(key: string): string | null;
+
+interface CrudPageProps {
+    schema: CrudPageSchema;
+    initialData?: Record<string, unknown>[];
+    apiRequest?: ApiRequest;
+}
+declare const CrudPage: React.FC<CrudPageProps>;
+
+interface DynamicFilterProps {
+    schema: CrudPageSchema;
+    onSearch: (values: Record<string, unknown>) => void;
+    onReset: () => void;
+}
+declare function DynamicFilter({ schema, onSearch, onReset }: DynamicFilterProps): react_jsx_runtime.JSX.Element;
+
+interface DynamicTableProps {
+    schema: CrudPageSchema;
+    data: Record<string, unknown>[];
+    loading: boolean;
+    pagination: {
+        current: number;
+        pageSize: number;
+        total: number;
+        onChange: (page: number, pageSize: number) => void;
+    };
+    onView: (record: Record<string, unknown>) => void;
+    onEdit: (record: Record<string, unknown>) => void;
+    onDelete: (record: Record<string, unknown>) => void;
+    onCustomAction?: (actionKey: string, record: Record<string, unknown>) => void;
+}
+declare function DynamicTable({ schema, data, loading, pagination, onView, onEdit, onDelete, onCustomAction, }: DynamicTableProps): react_jsx_runtime.JSX.Element;
+
+type FormMode = 'create' | 'edit' | 'view';
+interface DynamicFormProps {
+    schema: CrudPageSchema;
+    mode: FormMode;
+    visible: boolean;
+    initialValues?: Record<string, unknown>;
+    onSubmit: (values: Record<string, unknown>) => void;
+    onCancel: () => void;
+}
+declare function DynamicForm({ schema, mode, visible, initialValues, onSubmit, onCancel, }: DynamicFormProps): react_jsx_runtime.JSX.Element;
+
+/** 校验规则配置（内置 + 自定义均使用此结构） */
+interface ValidationRuleConfig {
+    key: string;
+    label: string;
+    description?: string;
+    message: string;
+    /** 正则字符串（将转为 RegExp） */
+    pattern?: string;
+    /** 最小值（number）或最小长度（string） */
+    min?: number;
+    /** 最大值（number）或最大长度（string） */
+    max?: number;
+    /** antd 内置类型校验 */
+    type?: 'string' | 'number' | 'email' | 'url' | 'integer';
+    /** 是否不允许纯空白字符 */
+    whitespace?: boolean;
+    /** 是否内置（内置规则不可删除） */
+    builtin?: boolean;
+}
+/** 内置规则集 */
+declare const BUILTIN_RULES: ValidationRuleConfig[];
+declare function loadCustomRules(): ValidationRuleConfig[];
+declare function saveCustomRules(rules: ValidationRuleConfig[]): void;
+/** 获取所有规则（内置 + 自定义） */
+declare function getAllRules(): ValidationRuleConfig[];
+/** 根据 key 查找规则 */
+declare function getRuleByKey(key: string): ValidationRuleConfig | undefined;
+/** 将规则配置转为 Ant Design Form Rule */
+declare function ruleConfigToAntdRule(config: ValidationRuleConfig): Rule;
+/** 将一组规则 key 转为 Ant Design Form Rules 数组 */
+declare function keysToAntdRules(keys: string[]): Rule[];
+
+export { BUILTIN_RULES, CrudPage, DynamicFilter, DynamicForm, DynamicTable, defaultWidgetForType, getAllRules, getEffectiveWidget, getFieldGroupPrefix, getNestedValue, getRuleByKey, keysToAntdRules, loadCustomRules, ruleConfigToAntdRule, saveCustomRules };
+export type { ActionPermission, ActionSchema, ActionType, ApiRequest, ArrayItemField, CrudPageSchema, DataType, FieldConfig, FieldSchema, FilterConfig, FormFieldConfig, PaginationConfig, SelectOption, TableColumnConfig, ValidationRuleConfig, WidgetType };