鸿蒙(HarmonyOS) 自定义弹窗组件

一、架构设计原理

1.分层结构

交互层 ：CustomDialogController 控制显示/隐藏生命周期

视图层 ：@CustomDialog 装饰的组件实现UI渲染

事件层：通过ArkTS事件总线传递操作指令

2.渲染机制

采用独立渲染树分离技术，弹窗层级通过zIndex自动提升至 10000，确保全局置顶显示

二、完整开发流程（带参数传递）

1.带参数的自定义弹窗

@CustomDialog
struct ParamDialog {
  private message: string = "默认内容"  // 可配置参数
  private onConfirm: () => void        // 回调函数参数

  constructor(controller: CustomDialogController, params: DialogParams) {
    this.controller = controller
    this.message = params.message || this.message
    this.onConfirm = params.onConfirm
  }

  build() {
    Column() {
      Text(this.message).fontColor('#333')
      // ...其他交互元素
    }
  }
}

2.控制器高级配置

const dialog = new CustomDialogController({
  builder: ParamDialog({
    message: '删除后将不可恢复',
    onConfirm: this.handleDelete
  }),
  alignment: DialogAlignment.Bottom, // 底部弹出式
  offset: { dx: 0, dy: -40 },        // 位置微调
  customStyle: true,                 
  openAnimation: {                   // 自定义入场动画
    duration: 300,
    curve: Curve.EaseOut,
    onStart: () => { /* 动画开始回调 */ }
  }
})

三、样式控制进阶

1. 玻璃模糊特效实现

Column() {
  // 内容区
}
.backgroundColor('rgba(255,255,255,0.8)')
.backdropBlur(10)  // 背景模糊强度
.border({
  width: 1,
  color: 'rgba(255,255,255,0.2)'
})

2.响应式布局方案

@Styles function adaptiveWidth() {
  .width(DeviceInfo.screenWidth * 0.9)  // 屏幕宽度90%
  .maxWidth(600)                       // 大屏设备最大宽度限制
}

build() {
  Column() {
    // ...
  }
  .apply(adaptiveWidth)
}

四、交互事件体系

1.事件类型

事件类型	触发条件	典型应用场景
onCancel	点击遮罩/物理返回键	数据回滚操作
onDismiss	弹窗完全关闭	释放资源
onDragStart	开始拖拽移动弹窗	可移动式弹窗

2.拖拽交互实现

@State offsetY: number = 0

Column()
  .onTouch((event: TouchEvent) => {
    if(event.type === TouchType.Move) {
      this.offsetY = event.touches[0].y
    }
  })
  .translate({ y: this.offsetY })

五、性能优化策略

1.渲染优化

使用@Reusable装饰器实现组件复用

对静态内容启用cachedRender缓存策略

2.内存管理

dialogController.close().then(() => {
  this.dialogController = null // 手动释放资源
})

3.防抖处理

private debounceConfirm = debounce(() => {
  // 实际提交逻辑
}, 300)

Button('提交').onClick(this.debounceConfirm)

六、测试方案

1.单元测试用例

// 测试弹窗显示状态
it('should_open_dialog_when_triggered', () => {
  comp.find('button').trigger('click')
  expect(comp.find('dialog').prop('visible')).toBe(true)
})

// 测试参数传递
it('should_display_custom_message', () => {
  const dialog = mount(Dialog, { props: { message: 'TEST' } })
  expect(dialog.text()).toContain('TEST')
})

七、扩展应用场景

动态表单弹窗

@Builder
function dynamicForm() {
  ForEach(this.formItems, item => {
    TextInput({ placeholder: item.label })
      .onChange(value => this.formData[item.id] = value)
  })
}