# ModalForm 弹窗表单

ModalForm 提供一套由 schema 驱动的弹窗表单能力，包含可视化设计器和运行态渲染器。

# 何时使用

需要通过配置动态生成业务弹窗时
需要将表单布局、校验、联动和提交方式保存为 JSON 时
需要在后台设计弹窗，并在业务页面复用同一份 schema 时

# 在线预览

下面的示例完全使用本地 mock 数据，不依赖后端接口。可以直接打开弹窗、触发校验、修改设计器属性，并再次打开弹窗查看效果。

# 运行态用法

<template>
  <cloud-modal-runtime
    :visible="visible"
    :schema="schema"
    :context="context"
    :fullscreen="fullscreen"
    @update:visible="visible = $event"
    @confirm="onConfirm"
  />
</template>

<script>
export default {
  data () {
    return {
      visible: false,
      fullscreen: false,
      context: {
        row: { id: 'row-001', name: '张三' }
      },
      schema: {
        version: '1.0.0',
        code: 'demo-modal',
        title: '处理 {{row.name}}',
        width: 480,
        height: 520,
        okText: '确定',
        cancelText: '取消',
        centered: true,
        maskClosable: false,
        layout: {
          labelWidth: 100,
          labelAlign: 'right',
          columns: 1,
          gutter: 16
        },
        widgets: [
          {
            id: 'remark',
            type: 'textarea',
            field: 'remark',
            label: '备注',
            span: 24,
            rules: { required: true },
            props: { placeholder: '请输入备注' }
          }
        ],
        confirm: { type: 'callback' }
      }
    }
  },
  methods: {
    onConfirm (result) {
      console.log(result.values)
    }
  }
}
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

# 命令式打开

列表行操作或批量操作可以使用 openModalForm，它会返回一个 Promise：

import { openModalForm } from '@h3/cloudpivot-nexus-ui'

const result = await openModalForm({
  schema,
  context: {
    ids: selectedIds,
    rows: selectedRows,
    row: selectedRows[0]
  },
  fullscreen: true
})

if (result.action === 'ok') {
  reloadList()
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 核心能力

能力	说明
Schema 驱动	弹窗标题、布局、控件和提交动作均可配置
可视化设计器	支持物料拖拽、属性编辑、复制、排序和 JSON 导入
表单控件	支持输入、数字、选择、日期、人员、关联表单等控件
复合控件	支持内嵌表格和穿梭多选
联动显示	控件可根据表单值或外部 context 条件显示
多步骤表单	支持分步校验和上一步/下一步交互
提交方式	支持业务规则、自定义接口和回调三种模式

# 主要组件

组件	说明
`ModalDesigner`	可视化弹窗设计器，触发 `save` 和 `change` 事件
`ModalRuntime`	根据 schema 渲染并提交弹窗
`openModalForm`	命令式打开弹窗并返回 Promise 结果

设计器和运行态都支持受控全屏：<cloud-modal-designer :fullscreen="fullscreen" />、<cloud-modal-runtime :fullscreen="fullscreen" />，退出设计全屏时监听 update:fullscreen，运行态全屏关闭时仍监听 update:visible。

# ModalRuntime 参数

参数	说明	类型	默认值
visible	是否显示弹窗	`boolean`	`false`
schema	弹窗 schema	`ModalFormSchema`	必填
context	外部入参，可用于变量插值和数据初始化	`ModalFormContext`	`{}`
data	直接传入的对象或数组数据，自动映射为 `row`、`rows`、`ids`，并随提交回调返回	`Record<string, any> \\| any[]`	-
onSubmit	自定义提交函数，返回 `false` 时阻止关闭	`Function`	-
fullscreen	是否铺满浏览器视口	`boolean`	`false`

# 事件

事件	说明	回调参数
`update:visible`	弹窗关闭或打开状态变化	`(visible)`
`confirm`	提交成功	`ModalFormResult`
`cancel`	用户取消	-
`change`	表单字段变化	`(field, value, values)`

# 变量插值

弹窗组件设计本身不绑定业务数据，标题只是组件自己的名称。云枢模型下的自定义按钮再选择这份组件，配置运行时标题和「对页面传参」的映射 key。标题、说明、文本、提示和默认值支持 {{变量}}，运行态打开时按传入的 row / rows 取值。弹窗编码由系统自动生成，不可编辑。

{{row.name}}
{{rows[0].title}}
{{context.schemaCode}}
{{amount}}

1
2
3
4

表单值优先于外部 context，因此可以直接使用当前弹窗内的字段参与展示和联动。

# ModalDesigner 参数

参数	说明	类型	默认值
value	初始弹窗 schema	`ModalFormSchema`	-
previewContext	预览时模拟的外部入参，组件设计默认不传业务数据	`ModalFormContext`	`{}`
showToolbar	是否展示顶部工具栏	`boolean`	`true`
fullscreen	是否铺满浏览器视口设计	`boolean`	`false`

设计器全屏退出时会触发 update:fullscreen，可用 @update:fullscreen="fullscreen = $event" 同步状态；按 Esc 也可以退出全屏。

弹窗属性支持配置宽度、高度、提交/取消按钮文字，以及提交方式。选择“自定义接口”后填写接口地址和请求方式，点击提交会执行接口；接口成功后仍会触发 confirm 回调，回调参数包含表单输入 values、外部传入的 context、接口返回值 response 和最终请求参数 payload。提交时控制台会打印表单输入与外部传入数据。

控件的“显示条件”配置暂不在第一期开放，运行时仍兼容已有 schema 中的 visibleWhen 字段，后续版本再开放设计器配置。

← RelevanceSelect 关联选择 Popper 弹出层 →