Form Widget 用于详情界面制作。 Form DSL 文件放在 forms 目录中, 文件扩展名为 .form.yao。

约定

1. 示例中约定应用根目录为 /data/app, 实际编写时需替换为应用根目录。
2. 使用 <> 标识自行替换的内容。 例如: icon-<图标名称>, 实际编写时应替换为: icon-foo, icon-bar ...

命名

DSL 文件命名:

1. 由 小写字母, 下划线 “_”, 横杠 "-" 组成,
2. 必须由 小写字母 开头,
3. Widget ID 为文件名称(不含扩展名), 如包含多级目录用 "." 替代 "\/"

路由

阅读模式:

http://<IP|域名>:<YAO_PORT>/<管理后台路由前缀>/x/Form/<Widget ID>/view

编辑模式:

http://<IP|域名>:<YAO_PORT>/<管理后台路由前缀>/x/Form/<Widget ID>/edit

表单数据交互。用于指定列表检索、保存等操作的处理器，设置数据 Hook，绑定模型等

绑定 model 或 form。 根据关联 Widget ID 设定表单关联处理器和界面呈现默认值

{
  "name": "::Bind Model",
  "action": {
    "bind": { "model": "pet" },

    // 自定义关联处理器
    "find": {
      "guard": "-", // 鉴权方式
      "process": "scripts.pet.Find", // 调用处理器
      "default": [null, { "select": ["id", "name", "status"] }] // 默认参数表
    }
  }
}

关联处理器默认值:

数据表字段类型与表单字段定义 fields 映射表:

https://github.com/YaoApp/yao/blob/main/yao/fields/model.trans.json

{
  "name": "::Pet Admin Bind Table",
  "action": {
    "bind": { "table": "pet" },
    "find": {
      "guard": "-",
      "process": "scripts.pet.Find",
      "default": [null, { "select": ["id", "name", "status"] }] // 默认参数表
    }
  }
}

复制指定 Table Widget ID 的 action 和 fields, 并自动生成表单布局 layout, 在次表单基础上微调，创建一张新的表单。

{
  "name": "::Pet Admin Bind Form",
  "action": {
    "bind": { "form": "bind.pet" },
    "find": {
      "guard": "-",
      "process": "scripts.pet.Find",
      "default": [null, { "select": ["id", "name", "status"] }] // 默认参数表
    }
  }
}

复制指定 Form Widget ID 的表单, 在次表单基础上微调，创建一张新的表单。

使用关联处理器指定表单数据读取、写入逻辑。

在关联处理器之前运行，一般用于处理参数表数据。

{
  "name": "::Pet Admin Bind Form",
  "action": {
    "bind": { "model": "pet" },
    "before:find": "scripts.pet.BeforeFind" // 设定 Hook 处理器
  }
}

/data/app/scripts/pet.js Hook 脚本

/**
 * 在关联处理器 find 之前运行
 * @param id 数据记录主键数值
 * @param query 查询参数
 */
function BeforeFind(id, query) {
  return [id, query];
}

/**
 * 在关联处理器 save 之前运行
 * @param payload 用户提交数据记录
 */
function BeforeSave(payload) {
  return [payload];
}

/**
 * 在关联处理器 create 之前运行
 * @param payload 用户提交数据记录
 */
function BeforeCreate(payload) {
  return [payload];
}

/**
 * 在关联处理器 update 之前运行
 * @param id 数据记录主键数值
 * @param payload 用户提交数据记录
 */
function BeforeUpdate(id, payload) {
  return [payload];
}

/**
 * 在关联处理器 delete 之前运行
 * @param id 数据记录主键数值
 * @param query 查询参数
 */
function BeforeDelete(id) {
  return [id];
}

在关联处理器之后运行，一般用于处理结果集数据。

{
  "name": "::Pet Admin Bind Form",
  "action": {
    "bind": { "model": "pet" },
    "after:find": "scripts.pet.AfterFind" // 设定 Hook 处理器
  }
}

/data/app/scripts/pet.js Hook 脚本

/**
 * 在关联处理器 find 之后运行
 * @param result 处理器运行结果
 */
function AfterFind(result) {
  return result;
}

/**
 * 在关联处理器 save 之后运行
 * @param result 处理器运行结果
 */
function AfterSave(result) {
  return result;
}

/**
 * 在关联处理器 create 之后运行
 * @param result 处理器运行结果
 */
function AfterCreate(result) {
  return result;
}

/**
 * 在关联处理器 update 之后运行
 * @param result 处理器运行结果
 */
function AfterUpdate(result) {
  return result;
}

/**
 * 在关联处理器 delete 之后运行
 * @param result 处理器运行结果
 */
function AfterDelete(result) {
  return result;
}

表单界面布局。显示字段、筛选器、批量编辑等

表单功能操作。设置表单操作按钮

{
  "preset": {
    // 保存按钮
    "save": {
      "back": true // back = true 操作后返回上一页
    },

    "back": {} // 返回上一页按钮
  },

  // 自定义操作按钮
  "actions": [
    {
      "title": "页面跳转", // 按钮名称
      "icon": "icon-airplay", // 按钮图标, 可用图标 https://feathericons.com/

      // 按钮响应操作 KEY: 执行动作, VALUE: 参数表
      "action": {
        "History.push": { "payload": "/404" }
      }
    },
    {
      "title": "治愈 {{name}}", // 使用 {{<字段名称>}} 引用表单数据
      "icon": "icon-check",
      "action": {
        "Form.save": { "id": ":id", "status": "cured" }
      },
      "style": "success",
      "confirm": { "title": "提示", "desc": "确认变更为治愈状态？{{name}}" }
    },
    {
      "title": "云函数",
      "icon": "icon-cloud",
      "action": {
        // 调用 /data/app/services/foo.js 中定义的 function Bar(...args){} 方法, 使用 {{<字段名称>}} 引用表单数据
        "Service.foo": { "method": "Bar", "args": ["{{id}}", "{{name}}"] }
      }
    },
    {
      "title": "Studio 方法",
      "icon": "icon-layers",
      "action": {
        // 调用 /data/app/studio/hello.js 中定义的 function World(...args){} 方法, 使用 {{<字段名称>}} 引用表单数据
        // **仅开发模式下有效**
        "Studio.hello": { "method": "World", "args": ["{{id}}", "{{name}}"] }
      }
    }
  ]
}

可用自定义操作 actions[*].action

表单布局。设置显示列，行操作按钮等

{
  "props": {},
  "config": { "showAnchor": true },
  "sections": [
    {
      "title": "基础信息", // 段落标题
      "desc": "宠物的一些基本信息", // 段落描述

      // 字段列表 在 fields.form 中定义的字段
      "columns": [
        { "name": "表格", "width": 24 }, // name: fields.form.<KEY> ,  width 字段显示宽度, 24栅格
        {
          "width": 24,

          // 标签页:
          "tabs": [
            {
              "title": "Base", // 标签名称
              "columns": [
                { "name": "ID", "width": 12 }, // name: fields.form.<KEY> ,  width 字段显示宽度, 24栅格
                { "name": "名称", "width": 12 }
              ]
            },
            {
              "title": "More",
              "columns": [{ "name": "状态", "width": 12 }]
            }
          ]
        }
      ]
    },
    {
      "title": "基础信息",
      "desc": "宠物的一些基本信息",
      "columns": [
        { "name": "ID", "width": 12 },
        { "name": "名称", "width": 12 },
        { "name": "状态", "width": 12 }
      ]
    }
  ]
}

表单字段定义。指定表单字段

fields.form Object

表单列字段定义

KEY: 表单列字段名称, VALUE: 字段定义

{
  "名称": {
    "bind": "name", // 默认绑定API接口返回字段名称

    // 字段数据呈现组件
    "view": {
      "bind": "name_view", // 绑定字段名称，如不指定使用默认值
      "type": "Text", // 组件名称, 可用组件参考文档 https://yaoapps.com/components

      // 数据数值计算
      // 参数表:
      //   $C(row) 当前行数据,
      //   $C(value) 当前行当前字段数值,
      //   $C(props) 当前组件 props,
      //   $C(type) 当前组件 type,
      //   $C(id) 当前 Widget ID
      //   'hello' 字符串常量
      //   1024 整形常量
      //   0.618 浮点型常量
      "compute": {
        "process": "Concat", // 处理器名称
        "args": ["$C(row.name)", "-", "$C(row.status)"]
      },

      "props": {}
    },

    // 字段数据编辑组件 (点击字段后弹出的编辑器)
    "edit": {
      "bind": "name", // 绑定字段名称，如不指定使用默认值
      "type": "Input", // 组件名称, 可用组件参考文档 https://yaoapps.com/components

      // 数据数值计算 (简写)
      // 默认参数表: ["$C(value)", "$C(props)", "$C(type)", "$C(id)"]
      "compute": "scripts.pet.FormatName",
      "props": { "placeholder": "请输入宠物名称" }
    }
  },
  "医生": {
    "bind": "doctor_id",
    "edit": {
      "type": "Select",
      "props": {
        "placeholder": "请选择医生",
        "xProps": {
          // 在字段名称前加 $ 前缀, 指定处理器名称和参数，自动将处理器解析为 API
          "$remote": {
            "process": "scripts.doctor.SelectOption",
            "query": { "pet_type": "{{ type }}" }
          }
        }
      }
    }
  }
}

内建 Compute 处理器

表单界面配置项。表单满屏显示等配置

Form Widget API

Form Widget 处理器