文档中心

一、文档总览

当前文档中心主要整理了四类内容：AI 生成列表提示词、AI 生成表单提示词、组件总览索引、常用组件详细配置。目标不是替代完整源码，而是把最常查、最常复制、最容易出错的配置项集中展示出来。

二、AI 列表提示词摘要

列表 DSL 的核心是“页面骨架 + 搜索条件 + 列渲染 + 按钮动作 + 查询表达式”。给 AI 下指令时，尽量把这五部分说清楚，生成质量会明显更高。

推荐让 AI 明确输出的顶级结构

{
  "id": "saleorder",
  "name": "订单列表",
  "dataSource": "dataSource",
  "hideSearch": false,
  "body": {
    "emptyShow": "-",
    "showIndex": true,
    "selectable": true,
    "rowActionWidth": 175,
    "limit": 30,
    "skin": "grid",
    "even": true,
    "size": "sm"
  },
  "search": [{"row": []}],
  "column": [],
  "tableButton": [],
  "rowButton": [],
  "express": {
    "main": "@import(saleorder.json.express_main.ql)",
    "orderBy": "ORDER BY t.ID DESC"
  }
}

让 AI 生成列表时要讲清的 6 件事

• 列表名称和页面用途，例如“采购单列表”“库存变动日志”。
• 查询主表和关联表，是否需要带公司、状态、删除标记等固定条件。
• 搜索项有哪些，分别是模糊查询、精确查询、范围查询还是多选查询。
• 表格列如何展示，哪些字段是日期、金额、状态映射、链接、图片。
• 工具栏和行按钮有哪些动作，要打开表单、弹窗、详情页还是 Ajax 删除。
• 是否需要树结构、隐藏搜索、appendFoot 脚本、自定义 count 或 groupBy。

常见搜索操作符

三、AI 表单提示词摘要

表单 DSL 的关键不是“字段越多越好”，而是让 AI 明确页面结构、卡片划分、字段布局和提交逻辑。复杂表单往往还会带 iframe 子区域和流程字段。

推荐让 AI 明确输出的顶级结构

{
  "id": "base-trader",
  "name": "客户表单",
  "dataSource": "dataSource",
  "successUrl": "reload",
  "cardList": [],
  "buttonList": [],
  "initExpress": "@import(base-trader_initExpress.ql)",
  "submitExpress": "@import(base-trader_submitExpress.ql)",
  "deleteExpress": "@import(base-trader_deleteExpress.ql)",
  "appendFoot": "@import(base-trader_appendFoot.html)"
}

让 AI 生成表单时要讲清的 6 件事

• 这是新增页、编辑页、详情页，还是查看型表单。
• 表单需要分成哪些卡片，每张卡片展示什么业务信息。
• 每一行字段怎么排版，例如 layui-col-md6 两列、layui-col-md12 整行。
• 哪些字段是只读展示，哪些字段是用户可编辑输入。
• 保存时是单表写入，还是主从表联动、流程联动、状态校验。
• 是否需要嵌入子列表 iframe，例如联系人、产品明细、审核记录。

successUrl 常见取值

四、组件索引

组件按使用位置可以拆成四类：表单输入组件、只读展示组件、列表列组件、动作按钮组件。理解这个分类后，配置会更清晰。

表单输入组件

只读展示组件

列表列组件

按钮组件

五、组件细项与常用片段

这一部分不是罗列所有能力，而是收录最常复制的配置片段。足够支撑大多数 DSL 页面配置。

1. input / textarea

{
  "item_name": "TRADER_NAME",
  "label": "客户名称",
  "component": "input",
  "classAppend": "layui-col-md8",
  "props": {
    "placeholder": "请输入客户名称",
    "lay-verify": "required",
    "maxlength": "100",
    "description": "字段下方说明文字"
  }
}

{
  "item_name": "COMMENT",
  "label": "备注",
  "component": "textarea",
  "classAppend": "layui-col-md12",
  "props": {
    "rows": 4,
    "maxlength": 500
  }
}

2. select / select-multiple / cascader

{
  "item_name": "STATUS",
  "label": "状态",
  "component": "select",
  "initData": {
    "dataJson": [
      {"label": "启用", "value": "1"},
      {"label": "禁用", "value": "0"}
    ]
  }
}

{
  "item_name": "ROLE_IDS",
  "label": "角色",
  "component": "select-multiple",
  "operator": "in",
  "initData": {
    "dataSource": "dataSource",
    "dataSql": "SELECT ROLE_ID value, ROLE_NAME label FROM T_SYS_ROLE WHERE DELETE_FLAG=0"
  }
}

{
  "item_name": "REGION_ID",
  "label": "地区",
  "component": "cascader",
  "initData": {
    "dataSource": "dataSource",
    "dataSql": "SELECT REGION_FULL_ID value, REGION_FULL_NAME label, PARENT_ID parent_id FROM T_BASE_REGION WHERE DELETE_FLAG=0"
  }
}

3. radio / checkbox / hidden

{
  "item_name": "STATUS",
  "label": "状态",
  "component": "radio",
  "initData": {
    "dataJson": [{"value": 1, "label": "启用"}, {"value": 0, "label": "禁用"}]
  }
}

{
  "item_name": "FEATURES",
  "label": "功能",
  "component": "checkbox",
  "initData": {
    "dataJson": [
      {"label": "邮件通知", "value": "email"},
      {"label": "短信通知", "value": "sms"}
    ]
  }
}

{
  "item_name": "TRADER_ID",
  "label": "客户ID",
  "component": "hidden"
}

4. date / date-span / uniondate

{
  "item_name": "ADD_TIME",
  "label": "添加时间",
  "component": "date",
  "operator": "BETWEEN",
  "props": {
    "range": true,
    "format": "yyyy-MM-dd HH:mm:ss"
  }
}

{
  "item_name": "CREATE_TIME",
  "label": "创建时间",
  "component": "date-span",
  "classAppend": "layui-col-md6"
}

{
  "item_name": "UNIONDATE",
  "label": "时间",
  "component": "uniondate",
  "operator": "BETWEEN",
  "props": {"range": true},
  "options": [
    {"label": "添加时间", "value": "ADD_TIME"},
    {"label": "审核时间", "value": "VALID_TIME"}
  ]
}

5. upload / file / tinymce

{
  "item_name": "CONTRACT_FILE",
  "label": "合同附件",
  "component": "upload",
  "props": {
    "accept": "file",
    "multiple": true,
    "number": 5,
    "size": 10240,
    "description": "- 支持 PDF、Word 格式"
  }
}

{
  "item_name": "CONTENT",
  "label": "内容",
  "component": "tinymce",
  "classAppend": "layui-col-md12"
}

6. td 系列与按钮

{
  "item_name": "SALEORDER_NO",
  "label": "订单号",
  "component": "tdLink",
  "props": {
    "url": "/topezadmin/form/page-saleorder/saleorder?ID={{=d.ID}}",
    "windowname": "订单详情"
  }
}

{
  "item_name": "CHECK_STATUS",
  "label": "审核状态",
  "component": "tdSelect",
  "initData": {
    "dataJson": [
      {"value": "0", "label": "待审核"},
      {"value": "3", "label": "审核通过"}
    ]
  }
}

{
  "item_name": "EDIT",
  "label": "编辑",
  "component": "button-normal",
  "props": {
    "opentype": "MODAL",
    "windowname": "编辑",
    "url": "/topezadmin/form/page-user-form?ID={{=d.ID}}"
  }
}

常见 opentype

六、使用建议

• 首页文档负责讲 DSL 全貌，这个文档中心负责查“现成片段”和“AI 提示词模板”。
• 如果一个组件被多个页面复用，优先把选项沉淀到 dsl/data/*.json，不要在每个页面重复写。
• 让 AI 生成 DSL 时，尽量指定“页面类型 + 业务场景 + 表结构 + 组件偏好 + 跳转方式”。
• 复杂 SQL 和提交逻辑不要堆在 JSON 里，优先拆到独立 .ql 文件后用 @import 引用。