@mxmweb/xviewer 1.0.0

package/README.md

@@ -0,0 +1,989 @@
+# 动态生成组件数据传参文档
+
+## 概述
+
+本套动态生成组件系统支持多种视图类型（table、form、card、markdown、customized），通过统一的配置接口实现灵活的数据展示和交互。
+
+## 核心组件
+
+- `DynamicDashDataCore`: 主容器组件，负责视图切换和布局
+- `DynamicCards`: 卡片展示组件，支持分页和虚拟滚动
+- `DynamicTable`: 表格展示组件，支持搜索、过滤、操作
+- `DynamicForm`: 表单组件，支持动态表单项配置
+
+## 1. DynamicDashDataCore 主容器
+
+### 基础配置
+
+```typescript
+interface DynamicDashView {
+  label?: string;                    // 标题
+  key?: string;                      // 唯一标识
+  defaultActiveId: string;           // 默认激活的视图ID
+  model?: 'files' | 'tabs' | null;   // 布局模式：files(文件树)、tabs(标签页)、null(自动)
+  views: ViewType[];                 // 视图配置数组
+  dataSource?: any;                  // 数据源
+  eventsEmit?: (name: string, data?: any) => any;  // 事件回调
+  styles?: any;                      // 样式配置
+}
+```
+
+### 布局模式详解
+
+#### 1.1 `model: 'tabs'` - 标签页模式
+
+**功能特性：**
+- 顶部显示标签页导航栏
+- 支持多级下拉菜单嵌套
+- 适合功能模块切换和分类展示
+- 支持无限层级的菜单结构
+
+**参数要求：**
+```typescript
+// 基础配置
+{
+  model: 'tabs',
+  defaultActiveId: 'view1',
+  views: [
+    {
+      label: '功能模块',
+      id: 'module1',
+      children: [
+        {
+          label: '子功能',
+          id: 'submodule1',
+          children: [
+            {
+              label: '具体功能',
+              id: 'view1',
+              type: 'table' // 叶子节点必须有type
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+
+// 事件处理
+const handleEvents = (name: string, data: any) => {
+  switch (name) {
+    case 'select':
+      // 叶子节点选择事件
+      // data: { id: string, type: string }
+      setActiveId(data.id);
+      break;
+    case 'toolbar_${key}':
+      // 工具栏操作事件
+      // data: { viewId: string }
+      break;
+  }
+};
+```
+
+**适用场景：**
+- 功能模块导航
+- 分类数据展示
+- 平级功能切换
+- 多级菜单系统
+
+#### 1.2 `model: 'files'` - 文件树模式
+
+**功能特性：**
+- 左侧显示树形导航结构
+- 支持展开/收起操作
+- 适合层级数据展示和文件管理
+- 支持目录和文件的区分处理
+
+**参数要求：**
+```typescript
+// 基础配置
+{
+  model: 'files',
+  defaultActiveId: 'file1',
+  views: [
+    {
+      label: '项目文档',
+      id: 'project-docs',
+      children: [
+        {
+          label: '需求文档',
+          id: 'requirements',
+          children: [
+            {
+              label: '用户需求',
+              id: 'user-requirements',
+              type: 'table' // 叶子节点必须有type
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+
+// 事件处理
+const handleEvents = (name: string, data: any) => {
+  switch (name) {
+    case 'select':
+      // 叶子节点选择事件
+      // data: { id: string, type: string }
+      setActiveId(data.id);
+      break;
+    case 'filesDir_clicked':
+      // 非叶子节点（目录）点击事件 - files模式特有
+      // data: { node: ViewType, allChildren: ViewType[] }
+      console.log('目录点击:', data.node.label);
+      console.log('所有子节点:', data.allChildren);
+      break;
+    case 'toolbar_${key}':
+      // 工具栏操作事件
+      // data: { viewId: string }
+      break;
+  }
+};
+```
+
+**适用场景：**
+- 文件管理器
+- 文档结构展示
+- 层级数据导航
+- 项目目录管理
+
+#### 1.3 `model: null` - 自动模式
+
+**功能特性：**
+- 无导航栏，直接显示内容
+- 适合单一功能页面
+- 简化布局，专注内容展示
+
+**参数要求：**
+```typescript
+// 基础配置
+{
+  model: null, // 或省略此字段
+  defaultActiveId: 'view1',
+  views: [
+    {
+      label: '单一视图',
+      id: 'view1',
+      type: 'table' // 必须有type
+    }
+  ]
+}
+
+// 事件处理
+const handleEvents = (name: string, data: any) => {
+  switch (name) {
+    case 'select':
+      // 视图选择事件（通常不会触发，因为只有一个视图）
+      break;
+    case 'toolbar_${key}':
+      // 工具栏操作事件
+      break;
+  }
+};
+```
+
+**适用场景：**
+- 单一功能页面
+- 弹窗内容展示
+- 嵌入式组件
+- 简化布局需求
+
+### 模式对比总结
+
+| 特性 | Tabs模式 | Files模式 | 自动模式 |
+|------|----------|-----------|----------|
+| **导航方式** | 顶部标签页/下拉菜单 | 左侧树形菜单 | 无导航 |
+| **层级支持** | 多级下拉菜单 | 无限层级树形结构 | 单层 |
+| **展开状态** | 无需管理 | 需要管理展开/收起 | 无需管理 |
+| **特有事件** | 无 | `filesDir_clicked` | 无 |
+| **数据传递** | 根据activeId动态变化 | 根据activeId动态变化 | 静态数据 |
+| **布局复杂度** | 中等 | 高 | 低 |
+| **适用场景** | 功能模块切换 | 文件管理、层级展示 | 单一功能 |
+
+## 2. ViewType 视图配置
+
+### 基础结构
+
+```typescript
+interface ViewType {
+  label: string;                     // 显示名称
+  id: string;                        // 唯一标识
+  type?: 'table' | 'form' | 'markdown' | 'card' | 'customized';  // 视图类型
+  columns?: Array<{ title: string; id: string; type: string; [key: string]: any }>;  // 表格列配置
+  children?: ViewType[];             // 子视图（用于多级导航）
+  cardType?: string;                 // 卡片类型
+  viewBehavior?: 'pagination' | 'scroll';  // 卡片展示行为
+  actions?: CardAction[];            // 卡片操作配置
+  toolbar?: ToolbarItem[];           // 工具栏配置
+}
+```
+
+### 2.1 表格视图 (`type: 'table'`)
+
+#### 列配置格式
+
+```typescript
+const columns = [
+  {
+    id: 'name',           // 列标识
+    title: '姓名',        // 列标题
+    type: 'text'          // 列类型：text|number|status|image|longText|tag|action|date
+  },
+  {
+    id: 'status',
+    title: '状态',
+    type: 'status'
+  },
+  {
+    id: 'actions',
+    title: '操作',
+    type: 'action'
+  }
+];
+```
+
+#### 数据源格式
+
+```typescript
+const dataSource = [
+  {
+    id: 'row1',           // 行唯一标识
+    cells: [              // 单元格数组
+      {
+        columnId: 'name', // 对应列ID
+        type: 'text',     // 数据类型
+        value: '张三'     // 显示值
+      },
+      {
+        columnId: 'status',
+        type: 'status',
+        value: 'active'
+      },
+      {
+        columnId: 'actions',
+        type: 'action',
+        value: 'edit',
+        label: '编辑'     // 操作按钮文本
+      }
+    ]
+  }
+];
+```
+
+#### 支持的数据类型
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| `text` | 普通文本 | `{ value: '张三' }` |
+| `number` | 数字 | `{ value: 100 }` |
+| `status` | 状态标签 | `{ value: 'active' }` |
+| `image` | 图片 | `{ value: 'https://example.com/avatar.jpg' }` |
+| `longText` | 长文本（带省略） | `{ value: '很长的文本内容...' }` |
+| `tag` | 标签组 | `{ value: ['标签1', '标签2'] }` |
+| `action` | 操作按钮 | `{ value: 'edit', label: '编辑' }` |
+| `date` | 日期 | `{ value: '2024-01-01' }` |
+
+### 2.2 卡片视图 (`type: 'card'`)
+
+#### 卡片配置
+
+```typescript
+const cardView = {
+  label: '我的数据库',
+  id: 'my-db',
+  type: 'card',
+  cardType: 'database',              // 卡片类型
+  viewBehavior: 'scroll',            // 展示行为：pagination|scroll
+  actions: [                         // 卡片操作
+    { label: '编辑', key: 'edit', allow: true },
+    { label: '删除', key: 'delete', allow: false }
+  ],
+  toolbar: [                         // 工具栏
+    { type: 'button', key: 'add', label: '添加连接' },
+    { type: 'fuzzy_search', key: 'search', label: '搜索', searchKeys: ['name', 'description'] }
+  ]
+};
+```
+
+#### 数据源格式
+
+```typescript
+// 数据库卡片
+const databaseCards = [
+  {
+    id: 'db1',
+    name: '订单数据库',
+    description: '订单相关数据',
+    status: 'connect',               // 连接状态：connect|error
+    author: 'admin',                 // 作者
+    dbType: 'mysql',                 // 数据库类型
+    url: 'https://example.com',      // 连接地址
+    port: 3306,                      // 端口
+    username: 'root',                // 用户名
+    password: '******',              // 密码
+    actions: [                       // 卡片级操作（覆盖全局）
+      { label: '查看', key: 'view', allow: true }
+    ]
+  }
+];
+
+// 设计卡片
+const designCards = [
+  {
+    id: 'design1',
+    name: '登录页面设计',
+    description: '用户登录界面的UI设计稿',
+    status: 'completed',             // 状态：completed|in_progress|pending
+    author: 'designer1',             // 设计师
+    designType: 'figma',             // 设计工具：figma|sketch|ps|ai
+    url: 'https://figma.com/file/123', // 设计稿链接
+    version: 'v1.2',                 // 版本号
+    lastModified: '2024-12-15',      // 最后修改时间
+    actions: [
+      { label: '预览', key: 'preview', allow: true },
+      { label: '编辑', key: 'edit', allow: true }
+    ]
+  }
+];
+
+// 原型卡片
+const prototypeCards = [
+  {
+    id: 'proto1',
+    name: '用户流程原型',
+    description: '用户注册到登录的完整流程',
+    status: 'completed',             // 状态：completed|in_progress|pending
+    author: 'ux1',                   // 设计师
+    prototypeType: 'axure',          // 原型工具：axure|sketch|figma
+    url: 'https://axure.com/proto/123', // 原型链接
+    pages: 15,                       // 页面数量
+    lastModified: '2024-12-12',      // 最后修改时间
+    actions: [
+      { label: '查看', key: 'view', allow: true },
+      { label: '导出', key: 'export', allow: true }
+    ]
+  }
+];
+
+// 代码仓库卡片
+const repositoryCards = [
+  {
+    id: 'repo1',
+    name: 'React管理后台',
+    description: '基于React的管理系统前端项目',
+    status: 'active',                // 状态：active|archived|deprecated
+    author: 'dev1',                  // 开发者
+    repoType: 'git',                 // 仓库类型：git|svn
+    url: 'https://github.com/company/react-admin', // 仓库地址
+    language: 'TypeScript',          // 主要语言
+    stars: 156,                      // Star数量
+    lastCommit: '2024-12-18',        // 最后提交时间
+    deployment: 'production',        // 部署环境：production|staging|development
+    lastDeploy: '2024-12-18',        // 最后部署时间
+    actions: [
+      { label: '克隆', key: 'clone', allow: true },
+      { label: '部署', key: 'deploy', allow: true }
+    ]
+  }
+];
+```
+
+#### 支持的卡片类型
+| 类型 | 说明 | 特殊字段 |
+|------|------|----------|
+| `design` | 设计卡片 | `designType`, `version`, `lastModified`, `status` |
+| `prototype` | 原型卡片 | `prototypeType`, `pages`, `lastModified`, `status` |
+| `repository` | 代码仓库卡片 | `language`, `stars`, `deployment`, `lastCommit`, `lastDeploy` |
+| `database` | 数据库卡片 | `dbType`, `status`, `url`, `port`, `username` |
+| `default` | 默认卡片 | `title`, `content` |
+| `customized` | 自定义卡片 | 支持自定义 `render` 函数 |
+
+#### 工具栏类型
+
+| 类型 | 说明 | 配置项 |
+|------|------|--------|
+| `button` | 普通按钮 | `label`, `key` |
+| `fuzzy_search` | 模糊搜索 | `label`, `key`, `searchKeys` |
+| `customized` | 自定义组件 | `render` 函数 |
+
+### 2.3 表单视图 (`type: 'form'`)
+
+#### 表单项配置
+
+```typescript
+const formItems = [
+  {
+    type: 'input',                   // 表单项类型
+    label: '姓名',                   // 标签
+    name: 'name',                    // 字段名
+    required: true,                  // 是否必填
+    placeholder: '请输入姓名',       // 占位符
+    description: '用户真实姓名'      // 描述信息
+  },
+  {
+    type: 'select',
+    label: '性别',
+    name: 'gender',
+    options: [
+      { label: '男', value: 'male' },
+      { label: '女', value: 'female' }
+    ]
+  },
+  {
+    type: 'switch',
+    label: '启用通知',
+    name: 'notifications',
+    controlledItems: ['email', 'sms']  // 受控项
+  }
+];
+```
+
+#### 支持的表单项类型
+
+| 类型 | 说明 | 特殊配置 |
+|------|------|----------|
+| `input` | 文本输入 | `placeholder` |
+| `select` | 下拉选择 | `options` |
+| `number` | 数字输入 | `range`, `step`, `unit` |
+| `slider` | 滑块 | `range`, `step`, `unit` |
+| `switch` | 开关 | `controlledItems` |
+| `textarea` | 多行文本 | `autoSize` |
+| `date` | 日期选择 | - |
+| `radio` | 单选 | `options` |
+| `divider` | 分割线 | - |
+
+### 2.4 Markdown视图 (`type: 'markdown'`)
+
+#### 数据源格式
+
+```typescript
+const dataSource = {
+  content: '# 标题\n\n这是 **Markdown** 内容。'
+};
+```
+
+### 2.5 自定义视图 (`type: 'customized'`)
+
+#### 数据源格式
+
+```typescript
+const dataSource = {
+  component: <CustomComponent />  // React组件
+};
+```
+
+## 3. 事件系统
+
+### 事件类型
+
+| 事件名 | 说明 | 数据格式 |
+|--------|------|----------|
+| `select` | 视图切换 | `{ id: string, type: string }` |
+| `filesDir_clicked` | 文件树点击 | `{ node: ViewType, allChildren: ViewType[] }` |
+| `toolbar_${key}` | 工具栏操作 | `{ viewId: string }` |
+| `card_${action}` | 卡片操作 | `{ action: string, data: any }` |
+| `table_action_${action}` | 表格操作 | `{ action: string, row: any }` |
+| `form:submit` | 表单提交 | `{ formName: string, values: any }` |
+
+### 卡片事件详解
+
+#### 设计卡片事件 (`cardType: 'design'`)
+```typescript
+// 事件处理
+const handleDesignEvents = (name: string, data: any) => {
+  switch (name) {
+    case 'card_preview':
+      // 预览设计稿
+      // data: { id, name, description, designType, url, version, ... }
+      openDesignPreview(data.url);
+      break;
+    case 'card_edit':
+      // 编辑设计稿
+      openDesignEditor(data.id);
+      break;
+    case 'card_delete':
+      // 删除设计稿
+      confirmDeleteDesign(data.id);
+      break;
+  }
+};
+```
+
+#### 原型卡片事件 (`cardType: 'prototype'`)
+```typescript
+// 事件处理
+const handlePrototypeEvents = (name: string, data: any) => {
+  switch (name) {
+    case 'card_view':
+      // 查看原型
+      // data: { id, name, description, prototypeType, url, pages, ... }
+      openPrototypeViewer(data.url);
+      break;
+    case 'card_export':
+      // 导出原型
+      exportPrototype(data.id, data.prototypeType);
+      break;
+  }
+};
+```
+
+#### 代码仓库事件 (`cardType: 'repository'`)
+```typescript
+// 事件处理
+const handleRepositoryEvents = (name: string, data: any) => {
+  switch (name) {
+    case 'card_clone':
+      // 克隆项目
+      // data: { id, name, url, language, ... }
+      gitClone(data.url, data.name);
+      break;
+    case 'card_view':
+      // 查看项目
+      openRepository(data.url);
+      break;
+    case 'card_deploy':
+      // 部署项目
+      deployProject(data.id, data.deployment);
+      break;
+    case 'card_monitor':
+      // 监控项目
+      openMonitoring(data.id);
+      break;
+  }
+};
+```
+
+### 事件处理示例
+
+```typescript
+const handleEvents = (name: string, data: any) => {
+  switch (name) {
+    case 'select':
+      console.log('切换到视图:', data.id);
+      break;
+    case 'card_edit':
+      console.log('编辑卡片:', data);
+      break;
+    case 'form:submit':
+      console.log('表单提交:', data.values);
+      break;
+  }
+};
+```
+
+## 4. 样式配置
+
+### 主题配置
+
+```typescript
+const theme = {
+  colors: {
+    primary: '#007bff',
+    secondary: '#6c757d',
+    success: '#008000',
+    warning: '#FFA500',
+    error: '#FF0000',
+    background: '#f8f9fa',
+    text: '#343a40',
+    border: '#dee2e6'
+  },
+  space: {
+    sidebar: 'md',      // sm|md|lg
+    size: 'md',         // sm|md|lg
+    radius: 'md',       // sm|md|lg
+    padding: 'md',      // sm|md|lg
+    margin: 'md',       // sm|md|lg
+    shadow: 'md',       // sm|md|lg
+    lineHeight: 'md'    // sm|md|lg
+  }
+};
+```
+
+### 样式优先级
+
+1. `props.styles?.theme` - 最高优先级
+2. `contextTheme` - 上下文主题
+3. `defaultTheme` - 默认主题
+
+## 5. 完整示例
+
+### 数据库管理页面
+
+```typescript
+const DatabaseView = () => {
+  const views = [
+    {
+      label: '我的数据库',
+      id: 'my-db',
+      type: 'card',
+      cardType: 'database',
+      viewBehavior: 'scroll',
+      actions: [
+        { label: '编辑', key: 'edit', allow: true },
+        { label: '删除', key: 'delete', allow: false }
+      ],
+      toolbar: [
+        { type: 'button', key: 'add', label: '添加连接' },
+        { type: 'fuzzy_search', key: 'search', label: '搜索', searchKeys: ['name', 'description'] }
+      ]
+    },
+    {
+      label: '共享数据库',
+      id: 'shared-db',
+      type: 'card',
+      cardType: 'database',
+      actions: [
+        { label: '查看', key: 'view', allow: true }
+      ],
+      toolbar: [
+        { type: 'fuzzy_search', key: 'search', label: '搜索' }
+      ]
+    }
+  ];
+
+  const dataSource = [
+    {
+      id: 'db1',
+      name: '订单数据库',
+      description: '订单相关数据',
+      status: 'connect',
+      author: 'admin',
+      dbType: 'mysql',
+      url: 'https://example.com',
+      port: 3306,
+      username: 'root'
+    }
+  ];
+
+  return (
+    <DynamicDashDataCore
+      label="数据库管理"
+      model="tabs"
+      defaultActiveId="my-db"
+      views={views}
+      dataSource={dataSource}
+      eventsEmit={handleEvents}
+    />
+  );
+};
+```
+
+### 用户管理表格
+
+```typescript
+const UserTable = () => {
+  const views = [
+    {
+      label: '用户列表',
+      id: 'user-list',
+      type: 'table',
+      columns: [
+        { id: 'name', title: '姓名', type: 'text' },
+        { id: 'email', title: '邮箱', type: 'text' },
+        { id: 'status', title: '状态', type: 'status' },
+        { id: 'actions', title: '操作', type: 'action' }
+      ]
+    }
+  ];
+
+  const dataSource = [
+    {
+      id: 'user1',
+      cells: [
+        { columnId: 'name', type: 'text', value: '张三' },
+        { columnId: 'email', type: 'text', value: 'zhangsan@example.com' },
+        { columnId: 'status', type: 'status', value: 'active' },
+        { columnId: 'actions', type: 'action', value: 'edit', label: '编辑' }
+      ]
+    }
+  ];
+
+  return (
+    <DynamicDashDataCore
+      model="tabs"
+      defaultActiveId="user-list"
+      views={views}
+      dataSource={dataSource}
+      eventsEmit={handleEvents}
+    />
+  );
+};
+```
+
+### 项目资源管理（混合卡片类型）
+
+```typescript
+const ProjectResourceManager = () => {
+  const views = [
+    {
+      label: '设计资源',
+      id: 'design-resources',
+      type: 'card',
+      cardType: 'design',
+      viewBehavior: 'scroll',
+      actions: [
+        { label: '预览', key: 'preview', allow: true },
+        { label: '编辑', key: 'edit', allow: true },
+        { label: '删除', key: 'delete', allow: false }
+      ],
+      toolbar: [
+        { type: 'button', key: 'upload', label: '上传设计稿' },
+        { type: 'fuzzy_search', key: 'search', label: '搜索', searchKeys: ['name', 'description'] }
+      ]
+    },
+    {
+      label: '原型资源',
+      id: 'prototype-resources',
+      type: 'card',
+      cardType: 'prototype',
+      viewBehavior: 'pagination',
+      actions: [
+        { label: '查看', key: 'view', allow: true },
+        { label: '导出', key: 'export', allow: true }
+      ],
+      toolbar: [
+        { type: 'fuzzy_search', key: 'search', label: '搜索' }
+      ]
+    },
+    {
+      label: '代码仓库',
+      id: 'code-repositories',
+      type: 'card',
+      cardType: 'repository',
+      viewBehavior: 'scroll',
+      actions: [
+        { label: '克隆', key: 'clone', allow: true },
+        { label: '部署', key: 'deploy', allow: true },
+        { label: '监控', key: 'monitor', allow: true }
+      ],
+      toolbar: [
+        { type: 'button', key: 'create', label: '创建仓库' },
+        { type: 'fuzzy_search', key: 'search', label: '搜索', searchKeys: ['name', 'language'] }
+      ]
+    }
+  ];
+
+  // 根据当前激活的视图提供不同的数据
+  const getDataSource = (activeId: string) => {
+    switch (activeId) {
+      case 'design-resources':
+        return [
+          {
+            id: 'design1',
+            name: '登录页面设计',
+            description: '用户登录界面的UI设计稿',
+            status: 'completed',
+            author: 'designer1',
+            designType: 'figma',
+            url: 'https://figma.com/file/123',
+            version: 'v1.2',
+            lastModified: '2024-12-15'
+          },
+          {
+            id: 'design2',
+            name: '仪表板设计',
+            description: '数据仪表板界面设计',
+            status: 'in_progress',
+            author: 'designer2',
+            designType: 'sketch',
+            url: 'https://sketch.com/file/456',
+            version: 'v2.0',
+            lastModified: '2024-12-18'
+          }
+        ];
+      
+      case 'prototype-resources':
+        return [
+          {
+            id: 'proto1',
+            name: '用户流程原型',
+            description: '用户注册到登录的完整流程',
+            status: 'completed',
+            author: 'ux1',
+            prototypeType: 'axure',
+            url: 'https://axure.com/proto/123',
+            pages: 15,
+            lastModified: '2024-12-12'
+          }
+        ];
+      
+      case 'code-repositories':
+        return [
+          {
+            id: 'repo1',
+            name: 'React管理后台',
+            description: '基于React的管理系统前端项目',
+            status: 'active',
+            author: 'dev1',
+            repoType: 'git',
+            url: 'https://github.com/company/react-admin',
+            language: 'TypeScript',
+            stars: 156,
+            lastCommit: '2024-12-18',
+            deployment: 'production',
+            lastDeploy: '2024-12-18'
+          }
+        ];
+      
+      default:
+        return [];
+    }
+  };
+
+  const [activeId, setActiveId] = useState('design-resources');
+  const dataSource = getDataSource(activeId);
+
+  const handleEvents = (name: string, data: any) => {
+    switch (name) {
+      case 'select':
+        setActiveId(data.id);
+        break;
+      case 'card_preview':
+        console.log('预览设计稿:', data);
+        break;
+      case 'card_edit':
+        console.log('编辑设计稿:', data);
+        break;
+      case 'card_view':
+        console.log('查看原型:', data);
+        break;
+      case 'card_export':
+        console.log('导出原型:', data);
+        break;
+      case 'card_clone':
+        console.log('克隆项目:', data);
+        break;
+      case 'card_deploy':
+        console.log('部署项目:', data);
+        break;
+      case 'card_monitor':
+        console.log('监控项目:', data);
+        break;
+    }
+  };
+
+  return (
+    <DynamicDashDataCore
+      label="项目资源管理"
+      model="tabs"
+      defaultActiveId={activeId}
+      views={views}
+      dataSource={dataSource}
+      eventsEmit={handleEvents}
+    />
+  );
+};
+```
+
+## 6. 注意事项
+
+1. **数据一致性**: 确保 `columns` 配置与 `dataSource` 中的 `cells` 字段对应
+2. **ID唯一性**: 所有 `id` 字段必须唯一，避免冲突
+3. **类型匹配**: 确保数据类型与配置的 `type` 字段匹配
+4. **事件处理**: 根据业务需求实现相应的事件处理逻辑
+5. **性能优化**: 大量数据时建议使用 `viewBehavior: 'scroll'` 启用虚拟滚动
+
+## 7. 扩展开发
+
+### 自定义卡片类型
+
+```typescript
+// 1. 扩展 CardType 类型定义
+export type CardType = 'database' | 'default' | 'customized' | 'design' | 'prototype' | 'repository' | 'custom';
+
+// 2. 在 useDynamicCards 中添加新的 case
+case 'custom':
+  return {
+    ...card,
+    render: (data: any) => {
+      const actionsRaw: CardAction[] = data.actions || card.actions || globalActions || [];
+      const actions: DropdownMenuAction[] = actionsRaw.filter((a) => a.allow !== false).map((a) => ({
+        key: a.key,
+        label: a.label,
+        icon: a.icon,
+        onClick: a.onClick ? () => a.onClick!(data) : undefined,
+      }));
+      const handleAction = (key: string) => {
+        const action = actions.find(a => a.key === key);
+        if (action?.onClick) action.onClick();
+        else options?.onAction?.(key, data);
+      };
+      
+      return (
+        <CardWrapper theme={theme} className="group">
+          <CardContent>
+            <CardHeader>
+              <CustomIcon size={20} className="text-blue-500" />
+              <CardTitle>{data.name || '自定义卡片'}</CardTitle>
+              {data.status && (
+                <span style={{ position: 'absolute', right: -5, top: -10, margin: 12 }}>
+                  <StatusDotWrapper>
+                    <StatusDot status={data.status} />
+                  </StatusDotWrapper>
+                </span>
+              )}
+            </CardHeader>
+            <CardDesc>{data.description || '暂无描述'}</CardDesc>
+            {/* 自定义字段显示 */}
+            {data.customField && <CardMeta>自定义字段: <b>{data.customField}</b></CardMeta>}
+            {data.url && (
+              <span className="text-blue-500 font-normal">
+                <span className="underline cursor-pointer">{data.url}</span>
+              </span>
+            )}
+            <div style={{ flex: 1 }} />
+          </CardContent>
+          {actions.length > 0 && (
+            <CardActions>
+              <DropdownMenu actions={actions} onAction={handleAction} />
+            </CardActions>
+          )}
+        </CardWrapper>
+      );
+    },
+  };
+```
+
+// 3. 使用自定义卡片类型
+const customCardView = {
+  label: '自定义资源',
+  id: 'custom-resources',
+  type: 'card',
+  cardType: 'custom',
+  viewBehavior: 'scroll',
+  actions: [
+    { label: '查看', key: 'view', allow: true },
+    { label: '编辑', key: 'edit', allow: true }
+  ]
+};
+
+const customDataSource = [
+  {
+    id: 'custom1',
+    name: '自定义项目',
+    description: '这是一个自定义卡片示例',
+    status: 'active',
+    customField: '自定义值',
+    url: 'https://example.com',
+    actions: [
+      { label: '查看', key: 'view', allow: true }
+    ]
+  }
+];
+```
+
+### 自定义表单项类型
+
+```typescript
+// 在 useDynamicFormItems 中添加新的 case
+if (item.type === 'custom') {
+  return (
+    <Form.Item key={item.name} label={renderLabel(item)} name={item.name}>
+      <CustomInput {...item} />
+    </Form.Item>
+  );
+}
+```