@mxmweb/xviewer

v1.4.10

Published

20 days ago

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

0High
0Medium
0Low

mxmweb

@mxmweb/xviewer

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

✨ 核心特性

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

📦 安装

# 使用 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：

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

样式引入

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

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

🚀 快速开始

基础用法

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: '[email protected]' },
        { 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/接口/

接口文档: Xviwer API
更新说明: CHANGELOG
演示说明: 演示文档

📋 概述

概述

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

核心组件

DynamicDashDataCore: 主容器组件，负责视图切换和布局
DynamicCards: 卡片展示组件，支持分页和虚拟滚动
DynamicTable: 表格展示组件，支持搜索、过滤、操作
DynamicForm: 表单组件，支持动态表单项配置

1. DynamicDashDataCore 主容器

基础配置

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'` - 标签页模式

功能特性：

顶部显示标签页导航栏
支持多级下拉菜单嵌套
适合功能模块切换和分类展示
支持无限层级的菜单结构

参数要求：

// 基础配置
{
  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'` - 文件树模式

功能特性：

左侧显示树形导航结构
支持展开/收起操作
适合层级数据展示和文件管理
支持目录和文件的区分处理

参数要求：

// 基础配置
{
  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` - 自动模式

功能特性：

无导航栏，直接显示内容
适合单一功能页面
简化布局，专注内容展示

参数要求：

// 基础配置
{
  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 视图配置

基础结构

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'`)

列配置格式

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'
  }
];

数据源格式

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'`)

卡片配置

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'] }
  ]
};

数据源格式

// 数据库卡片
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'`)

表单项配置

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'`)

数据源格式

const dataSource = {
  content: '# 标题\n\n这是 **Markdown** 内容。'
};

2.5 自定义视图 (`type: 'customized'`)

数据源格式

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'`)

// 事件处理
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'`)

// 事件处理
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'`)

// 事件处理
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;
  }
};

事件处理示例

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. 样式配置

主题配置

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
  }
};

样式优先级

props.styles?.theme - 最高优先级
contextTheme - 上下文主题
defaultTheme - 默认主题

5. 完整示例

数据库管理页面

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}
    />
  );
};

用户管理表格

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: '[email protected]' },
        { 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}
    />
  );
};

项目资源管理（混合卡片类型）

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. 注意事项

数据一致性: 确保 columns 配置与 dataSource 中的 cells 字段对应
ID唯一性: 所有 id 字段必须唯一，避免冲突
类型匹配: 确保数据类型与配置的 type 字段匹配
事件处理: 根据业务需求实现相应的事件处理逻辑
性能优化: 大量数据时建议使用 viewBehavior: 'scroll' 启用虚拟滚动

7. 扩展开发

自定义卡片类型

// 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>
  );
}

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@mxmweb/xviewer

✨ 核心特性

📦 安装

必需依赖

样式引入

🚀 快速开始

基础用法

🔗 链接

📚 API 文档

📋 概述

概述

核心组件

1. DynamicDashDataCore 主容器

基础配置

布局模式详解

1.1 model: 'tabs' - 标签页模式

1.2 model: 'files' - 文件树模式

1.3 model: null - 自动模式

模式对比总结

2. ViewType 视图配置

基础结构

2.1 表格视图 (type: 'table')

列配置格式

数据源格式

支持的数据类型

2.2 卡片视图 (type: 'card')

卡片配置

数据源格式

支持的卡片类型

工具栏类型

2.3 表单视图 (type: 'form')

表单项配置

支持的表单项类型

2.4 Markdown视图 (type: 'markdown')

数据源格式

2.5 自定义视图 (type: 'customized')

数据源格式

3. 事件系统

事件类型

卡片事件详解

设计卡片事件 (cardType: 'design')

原型卡片事件 (cardType: 'prototype')

代码仓库事件 (cardType: 'repository')

事件处理示例

4. 样式配置

主题配置

样式优先级

5. 完整示例

数据库管理页面

用户管理表格

项目资源管理（混合卡片类型）

6. 注意事项

7. 扩展开发

自定义卡片类型

1.1 `model: 'tabs'` - 标签页模式

1.2 `model: 'files'` - 文件树模式

1.3 `model: null` - 自动模式

2.1 表格视图 (`type: 'table'`)

2.2 卡片视图 (`type: 'card'`)

2.3 表单视图 (`type: 'form'`)

2.4 Markdown视图 (`type: 'markdown'`)

2.5 自定义视图 (`type: 'customized'`)

设计卡片事件 (`cardType: 'design'`)

原型卡片事件 (`cardType: 'prototype'`)

代码仓库事件 (`cardType: 'repository'`)