HarmonyOS弹窗关闭动画与蒙层消失时序控制实践

1. 理解弹窗关闭动画与蒙层消失的时序问题

在HarmonyOS应用开发中，promptAction.openCustomDialog是一个常用的弹窗组件。当我们需要实现"弹窗关闭动画完成后蒙层才消失"的效果时，首先需要理解这两个元素的默认行为关系。

弹窗关闭过程通常包含三个阶段：

1. 触发关闭事件（用户点击关闭按钮或遮障层）
2. 执行关闭动画（如果有设置）
3. 完全移除弹窗DOM元素和蒙层

默认情况下，很多UI框架会将蒙层消失与弹窗关闭动画设置为同步执行，这会导致视觉上的不协调——动画还在播放时，蒙层已经突然消失，破坏了用户体验的连贯性。

2. 关键API与属性分析

要实现预期的效果，我们需要深入分析promptAction.openCustomDialog的相关参数：

2.1 autoCancel属性解析

typescript复制interface PromptParam {
  autoCancel?: boolean; // 点击遮障层时是否自动关闭
  // 其他参数...
}

• 当autoCancel=true时（默认值），点击蒙层会立即触发整个弹窗（包括蒙层）的关闭流程
• 设置为false可以阻止默认的蒙层点击关闭行为，但需要自行处理关闭逻辑

2.2 动画相关配置

typescript复制interface CustomDialogOptions {
  exitAnimation?: { // 退出动画配置
    duration: number;
    curve: string;
    // 其他动画参数...
  };
  // 其他配置...
}

通过exitAnimation可以自定义弹窗的关闭动画效果，但需要注意这个动画只作用于弹窗本身，不包含蒙层。

3. 完整解决方案实现

3.1 基础方案：利用动画回调

typescript复制import promptAction from '@ohos.promptAction';

function showCustomDialog() {
  const dialog = promptAction.openCustomDialog({
    // 禁用自动关闭
    autoCancel: false,
    // 配置退出动画
    exitAnimation: {
      duration: 300,
      curve: 'ease-out'
    },
    // 其他配置...
  });

  // 手动处理蒙层点击
  dialog.then((controller) => {
    // 获取蒙层元素
    const mask = controller.getMaskComponent();
    
    // 蒙层点击事件
    mask.onClick(() => {
      // 先执行弹窗关闭动画
      controller.close().then(() => {
        // 动画完成后手动移除蒙层
        mask.visibility = Visibility.None;
      });
    });
  });
}

3.2 进阶方案：封装可复用组件

对于需要多处使用的场景，可以封装高阶组件：

typescript复制class SmoothCloseDialog {
  private controller: promptAction.CustomDialogController;
  
  constructor(options: promptAction.CustomDialogOptions) {
    // 强制覆盖autoCancel
    const finalOptions = {
      ...options,
      autoCancel: false
    };
    
    this.controller = promptAction.openCustomDialog(finalOptions);
    this.setupMaskBehavior();
  }
  
  private setupMaskBehavior() {
    this.controller.then((ctrl) => {
      const mask = ctrl.getMaskComponent();
      
      mask.onClick(() => {
        ctrl.close().then(() => {
          // 添加淡出动画
          animateTo({
            duration: 150,
            curve: 'linear'
          }, () => {
            mask.visibility = Visibility.None;
          });
        });
      });
    });
  }
}

// 使用示例
new SmoothCloseDialog({
  // 原始配置...
});

4. 常见问题与调试技巧

4.1 动画不同步问题

可能出现弹窗动画与蒙层消失仍然不同步的情况，这时需要：

1. 检查动画duration是否一致
2. 确保没有其他CSS过渡干扰
3. 使用DevTools的动画调试工具检查时间轴

4.2 内存泄漏预防

由于手动控制蒙层显示/隐藏，需要注意：

typescript复制// 在页面销毁时确保清理
aboutToDisappear() {
  if (this.dialogController) {
    this.dialogController.close();
    this.dialogController = null;
  }
}

4.3 性能优化建议

对于复杂弹窗：

1. 避免在动画期间进行DOM操作
2. 使用will-change提示浏览器优化
3. 考虑使用transform代替top/left动画

5. 设计原理与扩展思考

5.1 为什么需要这种时序控制？

从用户体验角度分析：

1. 视觉连续性：蒙层作为弹窗的视觉背景，应该与主要内容保持同步
2. 焦点管理：过早移除蒙层可能导致背后的元素意外获取焦点
3. 动效完整性：保证用户完整感知关闭过程，避免"跳闪"

5.2 其他实现方案对比

1. CSS动画方案：

css复制.dialog-mask {
  transition: opacity 0.3s ease-out;
}

.dialog-closing .dialog-mask {
  opacity: 0;
}

优点：性能更好
缺点：需要精确控制时序

2. Web Animations API：

javascript复制const maskAnimation = mask.animate(
  [{opacity: 1}, {opacity: 0}],
  {duration: 300}
);
maskAnimation.onfinish = () => {
  mask.style.display = 'none';
};

优点：更精细的控制
缺点：兼容性考虑

6. 实际项目中的经验分享

在金融类App中实现这个效果时，我们遇到了几个关键问题：

1. Android低端机上动画卡顿：

• 解决方案：降级为简单的透明度动画
• 代码调整：

typescript复制exitAnimation: {
  duration: isLowEndDevice ? 200 : 300,
  curve: isLowEndDevice ? 'linear' : 'ease-out'
}

2. 弹窗内容动态高度导致的动画异常：

• 修复方法：在动画开始前锁定高度

typescript复制const content = controller.getContentComponent();
const originalHeight = content.height;
content.height = originalHeight; // 锁定高度

controller.close().then(() => {
  content.height = 'auto'; // 恢复
});

3. 无障碍访问优化：

typescript复制// 在动画期间保持可访问性
mask.accessibilityState = 'disabled';
controller.close().then(() => {
  mask.accessibilityState = 'none';
});