# OhDialogManager

**Repository Path**: Guangling_admin_admin_admin_admin/oh-dialog-manager

## Basic Information

- **Project Name**: OhDialogManager
- **Description**: OhDialogManager
- **Primary Language**: TypeScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-02
- **Last Updated**: 2026-06-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HarmonyOS 弹窗管理系统使用文档

## 一、概述

本弹窗管理系统采用 **BaseDialog + DialogManager** 架构，实现了弹窗的统一管理、复用和扩展。

### 架构特点

- **单例模式**：DialogManager 采用单例设计，全局统一管理
- **泛型支持**：BaseDialog 支持泛型参数，灵活适配不同弹窗
- **弹窗栈管理**：使用栈结构管理弹窗层级，支持多弹窗叠加
- **自动适配**：自动检测屏幕方向，适配横竖屏布局

---

## 二、文件结构

```
pages/
├── BaseDialog.ets          # 弹窗基类
├── DialogManger.ets        # 弹窗管理器
└── PrivacyPolicyDialog.ets # 隐私政策弹窗示例
```

---

## 三、核心类说明

### 3.1 BaseDialog<T>

弹窗基类，封装通用弹窗逻辑。

| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `show(params, options?)` | params: T, options?: DialogOptions | Promise<void> | 显示弹窗 |
| `hide()` | - | Promise<void> | 隐藏弹窗 |
| `update(params)` | params: T | void | 更新弹窗内容 |
| `getIsShowing()` | - | boolean | 获取弹窗显示状态 |
| `getDialogType()` | - | DialogType | 获取弹窗类型 |

### 3.2 DialogManager

弹窗管理器，统一管理所有弹窗。

| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `getInstance()` | - | DialogManager | 获取单例实例 |
| `init()` | - | DialogManager | 初始化管理器 |
| `registerDialog(type, builder)` | DialogType, WrappedBuilder | DialogManager | 注册弹窗 |
| `show(type, params?, options?)` | DialogType, T?, DialogOptions? | Promise<void> | 显示弹窗 |
| `hide(type)` | DialogType | Promise<void> | 隐藏弹窗 |
| `hideAll()` | - | Promise<void> | 隐藏所有弹窗 |
| `hideTop()` | - | Promise<void> | 隐藏最顶层弹窗 |
| `isShowing(type)` | DialogType | boolean | 检查弹窗是否显示 |
| `hasDialogShowing()` | - | boolean | 检查是否有弹窗显示 |

### 3.3 DialogType 枚举

```typescript
export enum DialogType {
  PRIVACY_POLICY = 'privacy_policy',  // 隐私政策弹窗
  USER_PROTOCOL = 'user_protocol',    // 用户协议弹窗
  EXIT_CONFIRM = 'exit_confirm',      // 退出确认弹窗
  LOADING = 'loading',                // 加载弹窗
  ALERT = 'alert',                    // 提示弹窗
  CONFIRM = 'confirm',                // 确认弹窗
  CUSTOM = 'custom'                   // 自定义弹窗
}
```

### 3.4 DialogOptions 配置

```typescript
export interface DialogOptions {
  alignment?: DialogAlignment;           // 弹窗位置，默认 Center
  isModal?: boolean;                     // 是否模态，默认 true
  autoCancel?: boolean;                  // 点击遮罩是否关闭，默认 false
  keyboardAvoidMode?: KeyboardAvoidMode; // 键盘避让模式，默认 NONE
  maskColor?: ResourceColor;             // 遮罩颜色
  onWillDismiss?: (action) => void;      // 弹窗即将关闭回调
}
```

---

## 四、使用示例

### 4.1 初始化（在 EntryAbility 中）

```typescript
import { DialogManager } from '../pages/DialogManger';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // 初始化弹窗管理器
    DialogManager.getInstance().init();
  }
}
```

### 4.2 显示/隐藏弹窗

```typescript
import { DialogManager } from '../pages/DialogManger';
import { DialogType } from '../pages/BaseDialog';

// 方式一：使用便捷方法
await DialogManager.getInstance().showPrivacyPolicyDialog();
await DialogManager.getInstance().hidePrivacyPolicyDialog();

// 方式二：使用通用方法
await DialogManager.getInstance().show(DialogType.PRIVACY_POLICY);
await DialogManager.getInstance().hide(DialogType.PRIVACY_POLICY);

// 方式三：带参数显示
const params = new PrivacyPolicyParams();
params.title = "自定义标题";
await DialogManager.getInstance().show(DialogType.PRIVACY_POLICY, params);
```

### 4.3 自定义弹窗配置

```typescript
import { DialogOptionsImpl } from '../pages/BaseDialog';

const options = new DialogOptionsImpl();
options.alignment = DialogAlignment.Bottom;
options.isModal = true;
options.autoCancel = true;
options.maskColor = '#80000000';

await DialogManager.getInstance().show(DialogType.PRIVACY_POLICY, params, options);
```

### 4.4 批量关闭弹窗

```typescript
// 关闭所有弹窗
await DialogManager.getInstance().hideAll();

// 关闭最顶层弹窗
await DialogManager.getInstance().hideTop();
```

### 4.5 查询弹窗状态

```typescript
// 检查特定弹窗是否显示
if (DialogManager.getInstance().isShowing(DialogType.PRIVACY_POLICY)) {
  console.log('隐私政策弹窗正在显示');
}

// 检查是否有任何弹窗显示
if (DialogManager.getInstance().hasDialogShowing()) {
  console.log(`当前有 ${DialogManager.getInstance().getShowingCount()} 个弹窗`);
}

// 获取所有正在显示的弹窗类型
const showingDialogs = DialogManager.getInstance().getShowingDialogs();
```

---

## 五、自定义弹窗开发指南

### 5.1 创建弹窗参数类

```typescript
import { IBaseDialogParams } from './BaseDialog';

export class MyDialogParams implements IBaseDialogParams {
  flag?: boolean;           // 必须：屏幕方向标志
  title?: string;           // 自定义参数
  content?: string;
  onConfirm?: () => void;
  onCancel?: () => void;
  
  constructor() {
    this.title = "默认标题";
  }
}
```

### 5.2 创建弹窗组件

```typescript
@Component
export struct MyDialog {
  param: MyDialogParams = new MyDialogParams();

  build() {
    Column() {
      Text(this.param.title)
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
      
      Text(this.param.content)
        .fontSize(16)
        .margin({ top: 10 })
      
      Row() {
        Button('取消')
          .onClick(() => {
            DialogManager.getInstance().hide(DialogType.CUSTOM);
            this.param.onCancel?.();
          })
        
        Button('确认')
          .onClick(() => {
            DialogManager.getInstance().hide(DialogType.CUSTOM);
            this.param.onConfirm?.();
          })
      }
      .margin({ top: 20 })
    }
    .width(this.param.flag ? '80%' : '40%')  // 横竖屏适配
    .padding(20)
    .backgroundColor(Color.White)
    .borderRadius(12)
  }
}

@Builder
export function myDialogBuilder(params: MyDialogParams) {
  MyDialog({ param: params })
}
```

### 5.3 注册弹窗

```typescript
// 方式一：在 DialogManager.registerDefaultDialogs() 中添加
private registerDefaultDialogs(): void {
  this.registerDialog<PrivacyPolicyParams>(
    DialogType.PRIVACY_POLICY,
    wrapBuilder(privacyPolicyDialogBuilder)
  );
  
  // 添加自定义弹窗
  this.registerDialog<MyDialogParams>(
    DialogType.CUSTOM,
    wrapBuilder(myDialogBuilder)
  );
}

// 方式二：动态注册
DialogManager.getInstance().registerDialog<MyDialogParams>(
  DialogType.CUSTOM,
  wrapBuilder(myDialogBuilder)
);
```

### 5.4 使用自定义弹窗

```typescript
const params = new MyDialogParams();
params.title = "提示";
params.content = "确定要执行此操作吗？";
params.onConfirm = () => {
  console.log('用户点击了确认');
};
params.onCancel = () => {
  console.log('用户点击了取消');
};

await DialogManager.getInstance().show(DialogType.CUSTOM, params);
```

---

## 六、最佳实践

### 6.1 在弹窗内部关闭自身

```typescript
// 推荐：通过 DialogManager 关闭
DialogManager.getInstance().hide(DialogType.PRIVACY_POLICY);

// 不推荐：直接调用 promptAction（会导致状态不同步）
```

### 6.2 处理返回键

```typescript
const options = new DialogOptionsImpl();
options.onWillDismiss = (action: DismissDialogAction) => {
  if (action.reason === DismissReason.PRESS_BACK) {
    // 阻止返回键关闭
    action.dismiss;
    // 或执行自定义逻辑
  }
};
```

### 6.3 弹窗生命周期管理

```typescript
// 页面销毁时关闭所有弹窗
aboutToDisappear(): void {
  DialogManager.getInstance().hideAll();
}
```

---

## 七、注意事项

1. **必须初始化**：使用前必须调用 `DialogManager.getInstance().init()`
2. **异步操作**：`show()` 和 `hide()` 都是异步方法，需要使用 `await`
3. **参数传递**：弹窗参数中的 `flag` 会自动设置，无需手动指定
4. **弹窗注册**：使用前必须先注册弹窗，否则会抛出异常
5. **ArkTS 兼容**：代码已适配 ArkTS 严格模式，避免使用对象展开等不支持的语法

---

## 八、版本历史

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0.0 | 2025-09-03 | 初始版本，支持基础弹窗管理 |
| 2.0.0 | 2025-09-04 | 重构为 BaseDialog + DialogManager 架构 |