卡片选择插件功能设计文档

一、功能概述

1.1 背景与目标

在 NocoBase 2.0 表单中，关系字段（多对多、多对一、一对多、一对一）默认提供下拉选择、弹窗选择、子表单等交互模式。这些模式在数据量大或需要直观浏览时体验不够理想。

本插件新增”卡片选择”字段组件模式，将关联数据以卡片网格形式展示，用户通过点击卡片完成选择，提供更直观、更丰富的选择体验。

1.2 核心特性

特性	说明
卡片选择模式	关系字段新增”卡片选择”字段组件选项
自动单选/多选	根据字段关系类型自动切换：对一 = 单选，对多 = 多选
字段配置	卡片内容和筛选区域均支持管理员添加/拖拽排列字段（与 NocoBase 2.0 统一）
丰富样式自定义	每个字段支持字体大小、颜色、加粗、背景色、边距、边框、图标前缀、对齐方式等样式配置
响应式布局	卡片网格支持不同屏幕尺寸下的列数自适应
数据筛选与排序	支持管理员配置数据范围和默认排序，支持用户筛选
分页加载	支持分页浏览，页大小由行数 × 列数计算
主题统一	卡片风格使用 Ant Design 主题 Token，与项目整体风格保持一致

1.3 适用场景

仅在表单区块中使用（不支持表格行内编辑）
仅在编辑模式下可用（ReadPretty 模式回退为默认展示）
插件卸载后，已配置为卡片选择的字段自动回退为默认 Select 模式

二、交互设计

2.1 配置流程

表单区块 → 配置关系字段 → 字段组件下拉
                              ├── 下拉选择 (Select)
                              ├── 弹窗选择 (Picker)
                              ├── 子表单 (Nester)
                              ├── ...
                              └── 卡片选择 (CardSelect)  ← 新增

选择”卡片选择”后，字段设置菜单中出现：

字段设置菜单
  ├── 字段组件: 卡片选择
  ├── 卡片设置              ← 新增，打开配置弹窗
  ├── 数据范围              ← 复用现有组件
  ├── 默认排序              ← 复用现有组件
  └── 数据加载方式           ← 复用现有组件

2.2 卡片设置弹窗

点击”卡片设置”打开弹窗，包含以下配置项：

配置项	交互方式	说明
高度	参考”区块高度”的交互：Radio（默认 / 指定高度 / 全屏高度）+ 条件 InputNumber	与 NocoBase 2.0 区块高度设置保持一致
一行展示的列数	响应式 Slider × 4 个断点	xs/md/lg/xxl，默认 1/2/3/4 ，参考”网格卡片”的交互
一页展示的行数	InputNumber	默认 3，pageSize = 行数 × 当前断点列数
显示筛选	Switch	开启后在卡片区域上方显示筛选区域

数据范围、默认排序、数据加载方式作为独立的设置菜单项，不放在弹窗内，与”网格卡片”保持一致的交互模式。

2.3 卡片内容配置（设计模式）

在 NocoBase 2.0 的设计模式下，管理员可以在卡片中配置字段：

┌──────────────────────────────────────────────────┐
│ [筛选区域 - 可配置字段]  (仅开启"显示筛选"时显示)    │
│  ┌─────────────┐ ┌─────────────┐ ┌──────────┐    │
│  │ 字段1 ✕     │ │ 字段2 ✕     │ │ + 添加   │    │
│  └─────────────┘ └─────────────┘ └──────────┘    │
├──────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 模板卡片     │ │ 模板卡片     │ │ 模板卡片     │ │
│ │ ┌─────────┐ │ │ ┌─────────┐ │ │ ┌─────────┐ │ │
│ │ │字段A  ⚙│ │ │ │字段A  ⚙│ │ │ │字段A  ⚙│ │ │
│ │ │字段B  ⚙│ │ │ │字段B  ⚙│ │ │ │字段B  ⚙│ │ │
│ │ │+ 添加   │ │ │ │+ 添加   │ │ │ │+ 添加   │ │ │
│ │ └─────────┘ │ │ └─────────┘ │ │ └─────────┘ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│              < 1 / 3 >                           │
└──────────────────────────────────────────────────┘

字段配置方式与 NocoBase 2.0 保持统一（添加/移除/排列字段）
每个字段保留 NocoBase 2.0 自带的字段配置项
在自带配置基础上，额外增加”样式设置”配置项

2.4 运行模式

普通用户看到的界面：

┌──────────────────────────────────────────────────┐
│ [筛选区域]                                         │
│  姓名: [________]  部门: [▼ 全部]  [查询] [重置]    │
├──────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ ✓ 张三      │ │   李四       │ │   王五       │ │
│ │   开发部     │ │   产品部     │ │   设计部      │ │
│ │   高级工程师  │ │   产品经理   │ │   UI设计师    │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │   赵六       │ │   孙七       │ │   周八       │ │
│ │   运维部     │ │   测试部     │ │   市场部      │ │
│ │   运维工程师  │ │   测试主管   │ │   市场专员    │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│              < 1 / 5 >                           │
└──────────────────────────────────────────────────┘

选中的卡片有主题色边框 + 勾选图标
单选模式：点击即选中，再次点击取消，点击其他卡片切换
多选模式：点击切换选中/取消状态
支持分页切换，选中状态跨页保持

2.5 字段样式配置

每个卡片内字段保留 NocoBase 2.0 原有的字段配置，在此基础上额外增加”样式设置”项，点击打开弹窗：

样式项	组件	说明
字体大小	InputNumber	单位 px
字体颜色	ColorPicker
是否加粗	Switch
背景色	ColorPicker	字段行背景色
内边距	InputNumber × 4	上右下左
边框	Select + ColorPicker	边框样式 + 颜色
图标前缀	IconPicker	字段前显示图标
对齐方式	Radio.Group	左/居中/右

三、开发分期

阶段	里程碑	交付物
一	MVP	基本功能实现，如卡片渲染、单选/多选交互、卡片设置弹窗（高度/列数/行数）、字段配置
二	迭代优化	字段丰富样式配置（字体/颜色/背景/边距/边框/图标/对齐）、筛选区域字段配置、筛选交互
三	优化完善	用户体验优化

四、注意事项

性能：大数据量时确保分页工作正常，避免一次渲染过多卡片 DOM
表单验证兼容：确保卡片选择的值绑定与表单验证规则（required 等）正常配合