SmartCRUD 使用说明 #

基于 SmartChart 平台的低代码 CRUD 框架，通过可视化配置面板快速构建数据管理界面。

目录 #

1. 快速开始
2. 整体架构
3. 数据集绑定（⚙️ 数据管理）
4. 表格显示配置（📋 表格显示）
5. 查询与过滤（🔍 筛选过滤）
6. 新增与修改（✏️ 新增修改）
7. 字段类型参考
8. 模型管理（🔧 模型管理）
9. 高级功能
10. 常见问题

1. 快速开始 #

1.1 打开配置面板 #

页面右下角点击 「CRUD配置」 按钮，弹出底部配置抽屉，共有 5 个 Tab：

1.2 基本配置流程 #

① ⚙️ 数据管理 → 填写 table_id（查询数据集）
② ⚙️ 数据管理 → 填写 add_id / update_id / delete_id
③ 📋 表格显示 → 设置 tableFields（表格显示字段）和 nameDict（字段中文名）
④ ✏️ 新增修改 → 设置 aform（新增字段）和 constFields（只读/主键字段）
⑤ 点击「预览」查看效果 → 确认后点击「发布」

1.3 三个操作按钮 #

每个 Tab 底部均有三个按钮：

2. 整体架构 #

2.1 渲染流程 #

页面加载
  → JS 向各 DOM 节点注入 Vue 模板字符串
  → vapp.rend() 被调用
      → refreshTable()：加载主表数据
      → transfer_config()：配置格式转换
      → startRender = true：全屏 loading 消失，界面呈现

2.2 配置的保存位置 #

所有配置以 vapp.xxx = yyy 格式写入看板 JS 文件的注释标记之间：

//=start_crud=//
vapp.table_id=5
vapp.aform=`code,name,status`
vapp.nameDict=`code:编码,name:名称`
//=end_crud=//

2.3 配置值格式说明 #

3. 数据集绑定 #

⚙️ 数据管理 Tab

3.1 核心数据集 #

3.2 扩展数据集 #

3.3 联动数据集 #

3.4 后端分页 #

开启 isBackPage = true 后，每次翻页都请求后端。数据集需返回两个数据帧：

df0: [[总条数]]
df1: [[字段名列表], [数据行1], [数据行2], ...]

框架自动传递参数：limit（每页条数）和 offset（偏移量）。

4. 表格显示配置 #

📋 表格显示 Tab

4.1 字段显示 #

4.2 外观配置 #

4.3 特殊列展示 #

Tag 标签：

tagFields = status,category
statusColor = 启用:green,禁用:red,待审:#ff9900

字段值会渲染为彩色 Tag，多个值（逗号分隔）会展示多个 Tag。

表头高亮（spotFields）：

spotFields = status:red,amount:green

表头说明（tooltipDict）：

tooltipDict = code:这是物料的唯一编码,amount:金额单位为元

行合并（mergeFields）：

mergeFields = department,category

相邻行中该字段值相同时自动合并单元格。启用后该字段排序禁用。

4.4 分页配置 #

提示： 设置 pageSize=9999 可隐藏分页控件（适合数据量少的场景）。

5. 查询与过滤 #

🔍 筛选过滤 Tab

5.1 后端查询（searchDict） #

点击「查询」按钮后，将字段值提交给后端数据集作为查询参数。

searchDict = status,department,order_date
typeDict = order_date:date,status:select

特殊处理：

• date/month 类型 → 自动拆分为 字段名_s（开始）和 字段名_e（结束）
• 多选（selects）→ 自动转为 'val1','val2' 的 SQL IN 格式
• 设置 defaultDict = {"status":1} 可配置查询初始默认值

5.2 前端实时过滤（filterDict） #

在已加载的数据中实时过滤，不请求后端，适合快速筛选。

filterDict = status,amount,name

支持运算符：

5.3 全局关键词搜索（isfilter） #

开启 isfilter = true 后显示全局搜索框，对所有字段进行模糊匹配：

• 空格分隔多个关键词（AND 逻辑）
• 匹配内容黄色高亮显示
• 200ms 防抖优化

5.4 查询区其他配置 #

6. 新增与修改 #

✏️ 新增修改 Tab

6.1 表单字段配置 #

⚠️ 重要： constFields 的第一位必须是主键字段名，框架依赖它来区分新增和修改。

6.2 按钮权限控制 #

行级权限（数据驱动）： 数据集返回的数据中若包含 操作 字段，可控制单行按钮显示：

• 包含 E → 显示编辑按钮
• 包含 D → 显示删除按钮
• 包含自定义图标名 → 显示对应的 viewDsDict 按钮

6.3 表单外观配置 #

6.4 高级表单行为 #

6.5 子表（明细录入） #

在新增/修改弹窗中内嵌明细数据录入，适用于主从表场景：

ztable_id = 8      // 查询子表数据，传参 fid=主键值
aform1 = product_code,qty,unit_price   // 子表新增字段
mform1 = product_code,qty,unit_price   // 子表修改字段

提交数据格式：

{
  "main_field": "xxx",
  "_child": {
    "fid": "主键值",
    "add": [{"product_code":"A001","qty":10}],
    "mod": [{"id":5,"qty":20}],
    "del": [3, 7]
  }
}

7. 字段类型参考 #

通过 typeDict 配置字段类型，格式：字段名:类型。

typeDict = status:select,birthday:date,amount:number,remark:text

选项数据配置（optionDict）：

{
  "status": [[1, "启用"], [0, "禁用"]],
  "category": [["A", "类别A"], ["B", "类别B"]]
}

格式：二维数组，每项 [值, 显示文本]。也可通过 option_id 从数据集动态加载。

8. 模型管理 #

🔧 模型管理 Tab（仅 Dev 模式可见）

提供可视化的数据库表结构管理，支持建表和字段变更。

8.1 操作流程 #

① 输入表名（可选）→ 点「查询」
   ├─ 有表名：从数据库读取真实表结构
   └─ 无表名：从当前 CRUD 配置中收集字段
② 在列表中修改字段属性
③ 点「预览」→ 将字段配置应用到 CRUD 设置面板
④ 点「保存」→ 保存 CRUD 配置
⑤ 点「执行」→ 生成并执行 SQL（⚠️ 不可恢复）

8.2 字段属性说明 #

8.3 特殊字段自动处理 #

8.4 数据库兼容说明 #

9. 高级功能 #

9.1 选择联动（selectDsDict） #

当某字段值变化时，调用数据集自动带出其他字段：

selectDsDict = supplier_code:5

字段 supplier_code 变化时，调用数据集 5（传参 {supplier_code: 值}），返回数据自动填充到表单同名字段。

如需额外传参：

selectParamDict = {"supplier_code": ["warehouse", "category"]}

9.2 远程搜索（remoteDsDict） #

让下拉框支持输入搜索：

remoteDsDict = product_code:8
typeDict = product_code:select

输入时实时调用数据集 8（传参 {product_code: 输入值}），返回结果作为选项列表。

9.3 自定义操作按钮（viewDsDict） #

在操作列添加自定义按钮：

viewDsDict = el-icon-printer:9,详情:10!,el-icon-goods:11!!

按钮名用 Element Icon 类名（如 el-icon-printer）显示为图标，中文则显示为文字按钮。

9.4 工具栏功能按钮（funDsDict） #

在工具栏添加批量操作按钮：

funDsDict = el-icon-check:12!,批量审批:13

传参：action（按钮 key）、updatelist（选中行主键列表，逗号分隔）。

9.5 批量动作（actionDict） #

开启多选后，针对选中行执行批量操作：

actionDict = {"approve": ["批量审批", "green"], "reject": ["批量驳回", "red"]}

显示为按钮，点击后带二次确认，执行时传参 action 和 updatelist。

9.6 左侧树形菜单（tree_ds） #

tree_ds = 15       // 树形菜单数据集 ID
treeWidth = 180px  // 树宽度

数据集返回树形结构数据，点击叶子节点自动向后端传 _label 参数并刷新表格。

9.7 新增前后钩子（addb_id / adda_id） #

新增前校验（addb_id）：

# 数据集返回格式
{"status": 200, "msg": "提示信息", "data": {...}}  # data 可替换提交数据
{"status": 400, "msg": "校验失败原因"}  # 阻止提交

新增后触发（adda_id）： 提交成功后自动调用，可用于发送通知、触发工作流等。

9.8 扫码输入 #

typeDict = barcode:qr
qrFormats = code_128,qr_code   // 支持的码格式（空则全支持）
qrCheckStr = SC                // 扫码内容必须以 SC 开头
scanSubmit = true              // 扫码后自动提交表单

9.9 文件/图片上传 #

typeDict = avatar:img,attachment:file
uploadpath = my_files   // 文件存储路径

上传地址：/echart/upload_file/，存储路径：/static/custom/{uploadpath}/{filename}。

9.10 自定义计算（calcChange） #

在看板 JS 中重写 calcChange 方法实现联动计算：

vapp.calcChange = function(key) {
    if (key === 'qty') {
        vapp.form.amount = vapp.form.qty * vapp.form.price;
    }
}

10. 常见问题 #

Q: 配置保存后没有生效？

「保存」写入测试配置，「发布」才会覆盖线上。确认点击的是正确按钮。

Q: 新增提交提示「没有任何修改项」？

所有字段值为 null 时会触发此提示。检查 aform 配置是否正确，字段名是否与数据一致。

Q: 修改时找不到主键？

constFields 第一位必须是主键字段名，且该字段必须存在于表格数据中（加入 tableFields 或不设置 tableFields）。

Q: 下拉框没有选项？

设置 optionDict 配置固定选项，或设置 option_id 从数据集动态加载，数据集第一行第一列为字段名。

Q: 子表数据没有加载？

确认设置了 ztable_id，且该数据集支持接收 fid 参数（主键值）。子表必须包含 id 字段作为主键。

Q: 表格列太多横向滚动？

设置 shortTableFields 显示少量关键列，其余字段在展开行中显示。或使用 widthDict 控制列宽。

Q: 导出按钮导出的是什么？

默认导出 shortTableFields 或 tableFields 中的字段，使用 fullData（全量数据，非当前页）。设置 daochu_id 可自定义导出数据集。

Q: 移动端显示效果不好？

开启 isMobileCard = true 在移动端切换为卡片列表模式，通过 tableFields 控制显示字段，shortCol 控制列数。

版权说明： SmartChart / SmartCRUD 由 JohnYan 设计