npm package: @mxmweb/xviewer
Description: > 动态生成组件数据传参系统，支持多种视图类型（table、form、card、markdown、customized），通过统一的配置接口实现灵活的数据展示和交互
Author: hanfeng_Zhang
Latest version: 1.4.15

# @mxmweb/xviewer

> 动态生成组件数据传参系统，支持多种视图类型（table、form、card、markdown、customized），通过统一的配置接口实现灵活的数据展示和交互

[![npm version](https://img.shields.io/npm/v/@mxmweb/xviewer.svg)](https://www.npmjs.com/package/@mxmweb/xviewer)
[![npm downloads](https://img.shields.io/npm/dm/@mxmweb/xviewer.svg)](https://www.npmjs.com/package/@mxmweb/xviewer)
[![License](https://img.shields.io/npm/l/@mxmweb/xviewer.svg)](https://github.com/your-org/xviewer/blob/main/LICENSE)

## ✨ 核心特性

- ✅ **多种视图类型**：支持 table、form、card、markdown、customized 等多种视图
- ✅ **灵活的布局模式**：支持 tabs（标签页）、files（文件树）、自动模式
- ✅ **动态数据绑定**：根据激活视图动态切换数据源
- ✅ **丰富的交互功能**：支持搜索、过滤、操作等
- ✅ **主题定制**：支持完整的主题配置和样式定制
- ✅ **TypeScript 支持**：完整的类型定义

## 📦 安装

```bash
# 使用 pnpm（推荐）
pnpm add @mxmweb/xviewer react react-dom styled-components @mxmweb/zui @mxmweb/rtext

# 使用 npm
npm install @mxmweb/xviewer react react-dom styled-components @mxmweb/zui @mxmweb/rtext

# 使用 yarn
yarn add @mxmweb/xviewer react react-dom styled-components @mxmweb/zui @mxmweb/rtext
```

### 必需依赖

本库需要以下 peerDependencies：

```bash
pnpm add react@>=18 react-dom@>=18 styled-components@^6.1.19 @mxmweb/zui@^1.3.x @mxmweb/rtext@^1.1.x
```

### 样式引入

在项目入口文件中引入样式：

```typescript
import '@mxmweb/xviewer/style.css';
```

## 🚀 快速开始

### 基础用法

```tsx
import { Xviwer } from '@mxmweb/xviewer';
import '@mxmweb/xviewer/style.css';

function App() {
  const views = [
    {
      label: '用户列表',
      id: 'user-list',
      type: 'table',
      columns: [
        { id: 'name', title: '姓名', type: 'text' },
        { id: 'email', title: '邮箱', type: 'text' },
        { id: 'status', title: '状态', type: 'status' }
      ]
    }
  ];

  const dataSource = [
    {
      id: 'user1',
      cells: [
        { columnId: 'name', type: 'text', value: '张三' },
        { columnId: 'email', type: 'text', value: 'zhangsan@example.com' },
        { columnId: 'status', type: 'status', value: 'active' }
      ]
    }
  ];

  return (
    <Xviwer
      model="tabs"
      defaultActiveId="user-list"
      views={views}
      dataSource={dataSource}
      eventsEmit={(name, data) => {
        console.log('Event:', name, data);
      }}
    />
  );
}
```

## 🔗 链接

- **NPM**: <https://www.npmjs.com/package/@mxmweb/xviewer>
- **GitHub**: <https://github.com/your-org/xviewer>

## 📚 API 文档

> 📖 完整 API 文档请查看：[doc_assets/接口/](./doc_assets/接口/)

- **接口文档**: [Xviwer API](./doc_assets/接口/Xviwer.md)
- **更新说明**: [CHANGELOG](./doc_assets/更新说明/CHANGELOG.md)
- **演示说明**: [演示文档](./doc_assets/演示/index.md)

## 📋 概述

## 概述

本套动态生成组件系统支持多种视图类型（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>
  );
}
```