2025-10-12 17:59:59 +08:00

11 KiB

Raw Blame History

`DynamicAccordion` 技术文档

模块名称： bricks.DynamicAccordion
继承自： bricks.VScrollPanel
用途： 动态可折叠列表组件，支持分页加载、内容动态渲染、编辑操作（增删改）、工具栏扩展等高级功能。

1. 概述

bricks.DynamicAccordion 是一个基于 VScrollPanel 的高级可折叠面板组件，用于展示大量条目数据。每个条目由标题区域和可展开的内容区组成，支持：

分页异步加载数据
可配置的记录视图模板（record_view）
展开后动态加载详细内容（content_view）
行内工具栏（支持自定义按钮及编辑操作）
增删改查（CRUD）交互支持
条件性内容显示（依赖字段值）

适用于需要高效展示并操作大量结构化数据的场景，如后台管理界面中的日志、订单、用户列表等。

2. 核心类结构

2.1 `bricks.AccordionItem`

class extends bricks.VBox

表示单个可折叠项的容器，包含两个子部件：

AccordionInfo：点击触发展开/收起的头部
VBox：隐藏的内容区域（默认不显示）

构造函数

constructor(opts) {
  super(opts);
  this.set_css('accordion-item');
}

特性

自动添加 CSS 类 accordion-item
继承 VBox 布局特性（垂直排列）

2.2 `bricks.AccordionInfo`

class extends bricks.FHBox

代表折叠项的标题部分，通常用于显示摘要信息，并绑定点击事件以切换内容可见性。

构造函数

constructor(opts) {
  super(opts);
  this.set_css('accordion-item-info');
}

特性

使用 FHBox 实现水平布局
添加 CSS 类 accordion-item-info
存储关联的数据记录在 user_data 属性中

2.3 `bricks.DynamicAccordion`

主控件类，负责整体逻辑调度、数据加载、UI 构建与交互响应。

class extends bricks.VScrollPanel

注册方式

bricks.Factory.register('DynamicAccordion', bricks.DynamicAccordion);

允许通过工厂方法创建实例：

bricks.createWidget("DynamicAccordion", {...});

3. 配置选项 (`opts`)

参数	类型	说明
`data_url`	String	获取数据的 API 地址
`data_method`	String (可选)	请求方法，默认为 `'GET'`
`data_params`	Object (可选)	发送请求时附加的参数
`cache_limit`	Number (可选)	缓存页数上限
`page_rows`	Number (可选)	每页返回的行数
`row_cheight`	Number (可选, 默认: `1.5`)	每行高度倍率（影响布局计算）
`record_view`	Widget 描述对象	定义每行摘要区域的 UI 结构
`content_rely_on`	String (可选)	控制是否展开内容的字段名
`content_rely_value`	Any (可选)	上述字段应匹配的值才能展开内容
`editable`	Object (可选)	启用编辑模式的相关配置
`.add_icon`, `.update_icon`, `.delete_icon`	String	图标路径或资源引用
`.form_cheight`	Number	表单高度系数
`.new_data_url`, `.update_data_url`, `.delete_data_url`	String	对应操作的提交 URL
`fields`	Array<Field>	字段定义数组，用于表单和列头渲染
`record_toolbar`	Object (可选)	自定义行工具栏按钮配置
`record_toolbar_collapsable`	Boolean (可选)	工具栏是否可折叠（未完全实现）
`header`	Object (可选)	头部固定行配置（暂未启用）
`content_view`	Widget 描述对象	展开后显示的详情内容模板
`title`	String (可选)	页面标题文本（i18n 支持）
`description`	String (可选)	页面描述文本

⚠️ 所有字符串文本均支持国际化（i18n: true）。

4. 生命周期与构建流程

build_all() 方法是初始化入口，在构造完成后延迟执行（schedule_once(..., 0.1)）：

async build_all() {
  if (this.title)        this.build_title();
  if (this.description)  this.build_description();
  await this.build_toolbar();
  await this.build_header();

  this.container = new bricks.VScrollPanel({});
  this.add_widget(new bricks.Filler().add_widget(this.container));

  this.container.bind('min_threshold', this.load_previous_page.bind(this));
  this.container.bind('max_threshold', this.load_next_page.bind(this));

  await this.render();
}

流程图解：

[初始化] 
   ↓
build_title() → 添加标题
build_description() → 添加描述
build_toolbar() → 添加全局工具栏
build_header() → 创建表头（模拟）
   ↓
创建内部容器 container (VScrollPanel)
   ↓
绑定滚动触底/触顶事件 → 分页加载
   ↓
render() → 加载并渲染第一页数据

5. 主要方法说明

5.1 渲染控制

`render(params)`

根据参数重新加载数据并刷新 UI。

若参数未变，则跳过
调用 loader.loadData(params) 获取数据
成功后调用 dataHandle(d)

`dataHandle(d)`

处理服务器返回的数据包：

{
  rows: [...],       // 当前页数据
  add_page: 2,       // 新增页码
  delete_page: 1     // 应删除的旧页码（超出缓存限制）
}

调用 renderAccordionItems(data, page) 渲染新项，并清理过期页。

5.2 内容生成

`build_item(record)`

构建单个可折叠项：

创建 AccordionItem
调用 build_info(item, record) 构建标题区
创建隐藏的 content 区域
绑定点击事件：line_clicked(info, content, record)
返回完整 item

若 record === null，则作为“表头”使用。

`build_info(item, record)`

生成标题区域 UI：

使用 widgetBuild(this.record_view, info, record) 渲染摘要内容
插入 record_toolbar（含编辑图标）
设置 info.user_data = record
返回 AccordionInfo 实例

当无 record 时，用于生成列头标签。

5.3 数据处理与分页

`load_previous_page() / load_next_page()`

滚动接近边界时自动加载前后页：

显示加载动画（Running 提示）
设置 this.loading = true 防止重复请求
调用 loader.loadPreviousPage() 或 loadNextPage()
成功后调用 dataHandle() 并恢复滚动位置
错误捕获并输出调试日志

`delete_page(page)`

移除指定页的所有 DOM 元素：

querySelectorAll('[data-page="X"]')
→ 移除对应 widget

确保内存和 DOM 不泄漏。

5.4 编辑功能

新增记录

add_record(info)：打开内嵌表单
add_record_abort()：取消新增
add_record_finish()：提交成功后刷新列表

更新记录

update_record(info, record)：弹出编辑表单
update_cancel()：取消编辑
update_record_finish()：保存后更新视图或提示

删除记录

delete_record(info, record)：弹出确认框
delete_record_act()：发送删除请求，删除成功则移除该项

新建表单快捷入口

build_new_form()：顶部添加“+”按钮和隐藏表单
点击按钮展开/收起新建表单
提交后自动调用 render() 刷新列表

5.5 事件系统

内部事件绑定

info.bind('click', line_clicked)：行点击展开内容
IconBar 工具按钮绑定各种事件（add, update, delete）
自定义工具按钮通过 fire_event(name, data) 派发事件

外部可监听事件

事件名	触发时机	参数
`row_selected`	用户点击某一行	`info` widget
`conformed`	删除确认后	——
`submited`	表单提交成功	响应对象
`[custom_tool_name]`	自定义工具按钮被点击	`record` 数据

可通过 bind(event, handler) 监听。

6. CSS 类名约定

类名	作用
`.accordion-item`	整个折叠项外层容器
`.accordion-item-info`	折叠项标题区域
`.accordion-item-info-selected`	当前行被选中状态
`.accordion-item-content`	内容区域样式基类
`.filler`	占位填充容器（用于自适应高度）

建议配合 SCSS 定义主题风格，例如圆角、阴影、过渡动画等。

7. 使用示例

var accordion = new bricks.DynamicAccordion({
  title: "User List",
  description: "Manage all registered users.",
  data_url: "/api/users",
  page_rows: 10,
  cache_limit: 5,

  fields: [
    { name: "name", label: "Name" },
    { name: "email", label: "Email" },
    { name: "status", label: "Status" }
  ],

  record_view: {
    widgettype: "HBox",
    options: { cheight: 1.5 },
    subwidgets: [
      { widgettype: "Text", options: { otext: "{{name}}" } },
      { widgettype: "Text", options: { otext: "{{email}}", halign: "right" } }
    ]
  },

  content_view: {
    widgettype: "Form",
    options: {
      fields: [
        { name: "name", uitype: "text" },
        { name: "email", uitype: "email" },
        { name: "bio", uitype: "textarea" }
      ]
    }
  },

  editable: {
    form_cheight: 8,
    new_data_url: "/api/users/create",
    update_data_url: "/api/users/update",
    delete_data_url: "/api/users/delete",
    add_icon: "/static/icons/add.svg"
  },

  record_toolbar: {
    tools: [
      { name: "view_logs", tip: "View operation logs", icon: "/icons/logs.svg" }
    ]
  }
});

// 监听自定义操作
accordion.bind("view_logs", function(record){
  console.log("查看日志:", record);
});

8. 注意事项

性能优化
- 支持分页缓存，避免一次性加载过多数据
- 滚动加载机制减少初始等待时间
- cache_limit 应合理设置以防内存占用过高
内容懒加载
- content_view 仅在点击展开时构建，节省资源
- 再次点击会清除内容（clear_widgets()），防止状态残留
国际化支持
- 所有文本建议使用 otext + i18n: true 配合语言包
DOM 清理
- 删除页面时主动移除 widgets 和事件监听（依赖框架 GC）
扩展性
- 可通过 record_toolbar 添加自定义操作按钮
- fire_event() 支持插件式开发
兼容性
- 依赖 bricks.PageDataLoader, bricks.HttpJson, bricks.widgetBuild 等基础模块
- 需确保这些模块已正确加载

✅ 推荐搭配组件：

bricks.Form：用于编辑表单
bricks.Conform：删除确认对话框
bricks.Running：加载指示器
bricks.IconBar：工具栏按钮组

📦 此组件适合集成于管理系统、数据看板等复杂前端应用中。

11 KiB Raw Blame History Unescape Escape

DynamicAccordion 技术文档

目录

1. 概述

2. 核心类结构

2.1 bricks.AccordionItem

构造函数

特性

2.2 bricks.AccordionInfo

构造函数

特性

2.3 bricks.DynamicAccordion

注册方式

3. 配置选项 (opts)

4. 生命周期与构建流程

流程图解：

5. 主要方法说明

5.1 渲染控制

render(params)

dataHandle(d)

5.2 内容生成

build_item(record)

build_info(item, record)

5.3 数据处理与分页

load_previous_page() / load_next_page()

delete_page(page)

5.4 编辑功能

新增记录

更新记录

删除记录

新建表单快捷入口

5.5 事件系统

内部事件绑定

外部可监听事件

6. CSS 类名约定

7. 使用示例

8. 注意事项

11 KiB

Raw Blame History

`DynamicAccordion` 技术文档

2.1 `bricks.AccordionItem`

2.2 `bricks.AccordionInfo`

2.3 `bricks.DynamicAccordion`

3. 配置选项 (`opts`)

`render(params)`

`dataHandle(d)`

`build_item(record)`

`build_info(item, record)`

`load_previous_page() / load_next_page()`

`delete_page(page)`