yumoqing/bricks
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
bricks/docs/cn/modal.md
yumoqing 53265bfa1d bugfix
2025-10-12 17:59:59 +08:00

9.0 KiB
Raw Blame History

bricks 模态组件技术文档

版本：1.0
模块：Modal, BaseModal, ModalForm

本文档描述了 bricks 框架中与模态窗口相关的类，包括 BaseModal、Modal 和 ModalForm。这些类用于创建可重用的弹出层（Modal）组件，支持自定义定位、样式、自动关闭、超时关闭等功能。

目录

概述

bricks 提供了一套基于布局系统的模态对话框系统：

  • BaseModal 是所有模态组件的基础类。
  • Modal 是一个带标题栏和内容区域的标准模态窗口。
  • ModalForm 是一个用于展示表单的模态窗口，集成 Form 组件并处理提交逻辑。
  • 所有模态窗口通过 Z-index 管理堆叠顺序，并支持锚点对齐（archor）、目标容器绑定等特性。

核心类结构

bricks.Layout
└── bricks.BaseModal
    ├── bricks.Modal
    └── bricks.ModalForm (extends PopupWindow)

注意：ModalForm 实际继承自 PopupWindow 而非 Modal，但功能上属于模态系列组件。

bricks.BaseModal

基础模态类，提供通用的模态行为，如显示/隐藏、Z-index 控制、目标挂载等。

构造函数参数 (Base Modal)

参数 类型 描述
target string 或 Layout 模态窗口挂载的目标容器。字符串表示 ID，对象为 Layout 实例。默认为 bricks.Body。
auto_open boolean 是否在添加子组件后自动打开模态。
auto_close boolean （未启用）是否点击背景关闭模态。
org_index number 初始 z-index 值（暂未使用）。
width string 内容面板宽度（如 '500px', '80%'）。
height string 内容面板高度。
bgcolor string 内容面板背景色，默认 #e8e8e8。
title string 标题文本（仅被 Modal 使用）。
timeout number 自动关闭延迟时间（毫秒），0 表示不自动关闭。
archor string 锚点位置，控制内容居中方式：
tl, tc, tr, cl, cc, cr, bl, bc, br
默认值：'cc'（居中）

属性 (Base Modal)

属性 类型 描述
panel VBox 实际内容容器，内部垂直布局。
timeout number 自动关闭延时（ms）。
timeout_task Task 定时任务句柄，用于取消定时关闭。
target_w Layout 解析后的目标挂载容器。
ancestor_add_widget Function 保存父类 add_widget 方法的引用。

方法 (Base Modal)

create()

创建模态外层 DOM 元素：

  • 使用 <div> 作为遮罩层。
  • 设置 position: fixed 遮罩全屏。
  • 背景颜色为半透明黑色 (rgba(0,0,0,0.4))。
  • 初始隐藏（display: none）。
  • 自动分配递增的 z-index。

get_zindex() → number

获取下一个可用的 z-index 值，从 bricks.min_zindex 开始递增。

默认起始值：5000

add_widget(widget, index)

向 panel 添加子控件。如果设置了 auto_open: true，则立即调用 open()。

open()

显示模态窗口：

  • 将 dom_element.style.display 设为空字符串（即显示）。
  • 若设置了 timeout > 0，启动延迟关闭任务。
  • 触发 opened 事件。

dismiss()

关闭并移除模态窗口：

  • 隐藏元素。
  • 取消超时任务。
  • 从父容器中移除自身。
  • 触发 dismissed 事件。
  • 异常捕获防止中断。

bricks.Modal

标准模态对话框，继承自 BaseModal，带有可关闭标题栏。

构造函数参数 (Modal)

同 BaseModal，额外支持：

参数 类型 描述
title string 显示在标题栏中的文字。

属性 (Modal)

属性 类型 描述
title_box HBox 水平布局的标题栏容器。
title_w Filler 标题文本占位容器。
content Filler 主体内容容器，填充剩余空间。

方法 (Modal)

create_title()

创建标题栏：

  • 包含一个水平盒子 HBox。
  • 左侧显示标题文本（使用 Text 组件，支持国际化 i18n 和动态尺寸 dynsize）。
  • 右侧放置关闭图标（SVG 图标，绑定 click → dismiss()）。
  • 添加 CSS 类名 title。

add_widget(widget, index)

将组件添加到 content 区域。若 auto_open 为真，则自动打开模态。

click_handler(event)

点击事件处理器（当前注释状态）：

  • 如果点击的是模态遮罩层（非内容区域），触发 dismiss()。
  • 用于实现“点击背景关闭”功能（目前未启用）。

⚠️ 当前该功能已被注释，需手动启用。

bricks.ModalForm

用于快速弹出表单的模态窗口，集成异步表单构建和提交处理。

构造函数参数 (ModalForm)

参数 类型 描述
title string 表单标题。
description string 表单描述信息。
fields Array<FieldOptions> 表单字段定义数组。
binds Array<BindConfig> 数据绑定配置。
user_data any 用户自定义数据（可选）。
submit_url string 提交 URL（可通过实例设置）。
其他 同 PopupWindow 如 width, height, archor 等。

属性 (ModalForm)

属性 类型 描述
form Form 动态生成的表单实例。
submit_url string 表单提交地址（可选）。

方法 (ModalForm)

build_form() → Promise<void>

异步构建表单：

  • 延迟 200ms 执行（确保 DOM 就绪）。
  • 使用 bricks.widgetBuild() 动态创建 Form 组件。
  • 添加至模态内容区。
  • 绑定以下事件：
    • submit: 触发 form_submit
    • submited: 转发服务器响应
    • cancel: 关闭模态
  • 最后调用 open() 显示。

_getValue() → any

获取原始表单数据（未经格式化）。

getValue() → any

获取经过验证和处理的表单数据。

form_submit()

处理表单提交：

  • 获取数据并派发 submit 事件。
  • 立即关闭模态（dismiss()）。

form_submited(event)

当表单成功提交后，转发 submited 事件及其参数。

注册与使用

// 注册工厂类，便于通过字符串创建
bricks.Factory.register('Modal', bricks.Modal);
bricks.Factory.register('ModalForm', bricks.ModalForm);

这意味着你可以使用如下方式动态创建：

let modal = bricks.Factory.create('Modal', { title: '提示', width: '400px' });

示例代码

创建一个简单模态窗口

let modal = new bricks.Modal({
  title: '欢迎',
  width: '500px',
  height: '300px',
  auto_open: true,
  archor: 'cc'
});

modal.add_widget(new bricks.Text({ otext: '这是模态内容！' }));

创建一个表单模态

let formModal = new bricks.ModalForm({
  title: '用户信息',
  description: '请填写以下信息',
  fields: [
    { name: 'name', label: '姓名', type: 'text' },
    { name: 'age', label: '年龄', type: 'number' }
  ],
  binds: [
    ['name', 'user.name'],
    ['age', 'user.age']
  ]
});

formModal.bind('submit', function(data) {
  console.log('提交数据:', data);
});

注意事项

  1. Z-index 管理：所有模态共享全局 last_zindex 计数器，确保新窗口总在最上层。
  2. 锚点定位：依赖外部函数 archorize(el, pos) 实现元素定位，请确保其存在。
  3. 资源路径：关闭图标使用 bricks_resource('imgs/delete.svg') 加载，需正确配置资源路径。
  4. 事件解绑：click_handler 的绑定/解绑逻辑目前被注释，如需启用请解除注释并测试。

依赖说明

  • bricks.Layout, bricks.VBox, bricks.HBox, bricks.Filler, bricks.Text, bricks.Svg —— 布局与基础组件。
  • bricks.widgetBuild() —— 异步组件构建工具。
  • schedule_once(fn, delay) —— 延迟执行工具函数。
  • objget(obj, key, default) —— 安全取值工具。
  • archorize(element, position) —— 锚点定位函数。

✅ 建议用途：适用于消息提示、确认框、登录弹窗、动态表单提交等场景。

🔧 扩展建议：

  • 支持键盘 ESC 关闭。
  • 添加动画过渡效果。
  • 支持拖拽移动（针对 ModalForm）。

📖 文档版本：1.0
📅 最后更新：2025年4月5日