# MessageBox 消息框

全局模态对话框系统，用于显示信息消息、确认对话框和用户交互，支持自定义按钮和样式。

## 功能特性

- **全局访问**: 通过 `window.MessageBox` 在整个应用中使用
- **多种类型**: 支持信息、警告和自定义消息类型
- **确认对话框**: 内置确认/取消功能
- **可拖拽**: 用户可以在屏幕上拖动消息框
- **自定义按钮**: 配置自定义按钮集合和不同操作
- **HTML内容**: 支持纯文本和HTML内容
- **基于Promise**: 返回Promise便于异步处理
- **自动定位**: 自动居中显示并支持拖拽
- **国际化**: 内置按钮标签的i18n支持

## 安装

```bash
npm install @ticatec/uniface-element
```

## 设置

首先，在你的根布局或应用组件中添加 MessageBoxBoard：

```svelte
<script>
  import MessageBoxBoard from '@ticatec/uniface-element/MessageBox';
</script>

<!-- 应用内容 -->
<main>
  <!-- 你的组件 -->
</main>

<!-- MessageBox 面板 - 全局实例 -->
<MessageBoxBoard appTitle="我的应用" />
```

## 基本用法

一旦 MessageBoxBoard 被挂载，你就可以使用全局 MessageBox 实例：

```javascript
// 显示信息消息
await window.MessageBox.showInfo('操作成功完成！', '成功');

// 显示确认对话框
const result = await window.MessageBox.showConfirm(
  '确定要删除这个项目吗？', 
  '确认删除'
);

if (result === ModalResult.MR_OK) {
  // 用户确认
  console.log('用户确认了操作');
} else {
  // 用户取消
  console.log('用户取消了操作');
}
```

## API 参考

### MessageBoxBoard 属性

| 属性 | 类型 | 默认值 | 描述 |
|------|------|---------|-------------|
| `appTitle` | `string` | `null` | 当未提供标题时的消息框默认标题 |

### 全局方法

#### `window.MessageBox.showInfo(message, title?, escapeHTML?)`

显示带有关闭按钮的信息消息。

**参数:**
- `message` (string): 要显示的消息
- `title` (string, 可选): 对话框标题
- `escapeHTML` (boolean, 可选): 是否转义HTML内容 (默认: true)

**返回:** `Promise<void>`

#### `window.MessageBox.showConfirm(message, title?, escapeHTML?, type?)`

显示带有确定/取消按钮的确认对话框。

**参数:**
- `message` (string): 要显示的消息
- `title` (string, 可选): 对话框标题
- `escapeHTML` (boolean, 可选): 是否转义HTML内容 (默认: true)
- `type` ('info' | 'warning', 可选): 要显示的图标类型 (默认: 'info')

**返回:** `Promise<ModalResult>`

### ModalResult 枚举

```typescript
enum ModalResult {
  MR_OK = 1,      // 用户点击确定/确认
  MR_CANCEL = 2,  // 用户点击取消
  MR_CLOSE = 3    // 用户点击关闭/X按钮
}
```

## 示例

### 基本信息消息

```javascript
// 简单信息消息
await window.MessageBox.showInfo('您的更改已成功保存。');

// 带自定义标题的信息消息
await window.MessageBox.showInfo(
  '操作完成，没有任何错误。',
  '操作完成'
);
```

### 确认对话框

```javascript
// 基本确认
const result = await window.MessageBox.showConfirm(
  '关闭前要保存更改吗？',
  '未保存的更改'
);

if (result === ModalResult.MR_OK) {
  // 保存更改
  saveChanges();
}

// 警告确认
const result = await window.MessageBox.showConfirm(
  '此操作无法撤销。继续吗？',
  '永久性操作',
  false,
  'warning'
);
```

### HTML 内容

```javascript
// 显示HTML内容 (escapeHTML = false)
await window.MessageBox.showInfo(
  '<strong>重要：</strong>请检查您的<em>邮箱</em>进行验证。',
  '邮箱验证',
  false
);

// 安全HTML转义 (默认行为)
await window.MessageBox.showInfo(
  '用户输入: <script>alert("xss")</script>', // 将被转义
  '用户数据'
);
```

### 错误处理

```javascript
try {
  const result = await window.MessageBox.showConfirm(
    '删除所有选中的项目？',
    '批量删除'
  );
  
  if (result === ModalResult.MR_OK) {
    await deleteItems();
    await window.MessageBox.showInfo('项目删除成功。', '成功');
  }
} catch (error) {
  await window.MessageBox.showInfo(
    '发生错误，请重试。',
    '错误',
    false,
    'warning'
  );
}
```

### 表单验证示例

```svelte
<script>
  import { ModalResult } from '@ticatec/uniface-element/MessageBox';
  
  async function handleSubmit() {
    if (!formData.name) {
      await window.MessageBox.showInfo(
        '提交前请输入您的姓名。',
        '必填字段'
      );
      return;
    }
    
    const result = await window.MessageBox.showConfirm(
      '使用提供的信息提交表单？',
      '确认提交'
    );
    
    if (result === ModalResult.MR_OK) {
      try {
        await submitForm(formData);
        await window.MessageBox.showInfo(
          '表单提交成功！',
          '成功'
        );
      } catch (error) {
        await window.MessageBox.showInfo(
          '表单提交失败，请重试。',
          '提交错误',
          false,
          'warning'
        );
      }
    }
  }
</script>
```

### 异步操作

```javascript
async function performAsyncOperation() {
  // 显示加载状态 (可以用自定义对话框实现)
  const confirmed = await window.MessageBox.showConfirm(
    '此操作可能需要几分钟。继续吗？',
    '长时间运行的操作'
  );
  
  if (confirmed === ModalResult.MR_OK) {
    try {
      await longRunningTask();
      await window.MessageBox.showInfo(
        '操作成功完成！',
        '成功'
      );
    } catch (error) {
      await window.MessageBox.showInfo(
        `操作失败: ${error.message}`,
        '错误',
        false,
        'warning'
      );
    }
  }
}
```

### 对话框链式示例

```javascript
async function handleDataLoss() {
  const saveFirst = await window.MessageBox.showConfirm(
    '您有未保存的更改。要先保存它们吗？',
    '未保存的更改'
  );
  
  if (saveFirst === ModalResult.MR_OK) {
    try {
      await saveData();
      await window.MessageBox.showInfo('数据保存成功。', '已保存');
    } catch (error) {
      const retry = await window.MessageBox.showConfirm(
        '保存数据失败。重试吗？',
        '保存错误',
        false,
        'warning'
      );
      
      if (retry === ModalResult.MR_OK) {
        return handleDataLoss(); // 递归重试
      }
    }
  }
  
  // 继续原始操作
  proceedWithAction();
}
```

### 防止多个MessageBox

```javascript
let messageBoxActive = false;

async function safeShowMessage(message, title) {
  if (messageBoxActive) {
    console.warn('MessageBox已激活');
    return;
  }
  
  messageBoxActive = true;
  try {
    await window.MessageBox.showInfo(message, title);
  } finally {
    messageBoxActive = false;
  }
}
```

## 样式

MessageBox 使用可自定义的CSS类：

```css
.uniface-message-board {
  /* 覆盖层背景 */
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  background: rgba(0, 0, 0, 0.5);
  z-index: 9999;
}

.uniface-message-box {
  /* 对话框容器 */
  position: fixed;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  background: white;
  border-radius: 8px;
  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.3);
}

.title-bar {
  /* 可拖拽标题区域 */
  cursor: move;
  padding: 8px;
  border-bottom: 1px solid #eee;
}

.box-content {
  /* 消息内容区域 */
  padding: 20px;
  display: flex;
  align-items: center;
  gap: 16px;
}

.control-bar {
  /* 按钮区域 */
  padding: 16px 20px;
  text-align: right;
  border-top: 1px solid #eee;
}
```

## 最佳实践

1. **使用有意义的标题**: 提供清晰、描述性的标题以获得更好的用户体验
2. **保持消息简洁**: 简短、清晰的消息更有效
3. **正确处理Promise**: 总是等待MessageBox调用或处理拒绝
4. **考虑用户上下文**: 使用适当的消息类型（信息 vs 警告）
5. **避免消息垃圾**: 防止多个MessageBox同时显示
6. **测试HTML内容**: 使用HTML时，确保内容安全且格式正确
7. **提供上下文**: 包含相关信息帮助用户做决定

## TypeScript 支持

MessageBox 包含完整的TypeScript定义：

```typescript
import { ModalResult, type IMessageBox } from '@ticatec/uniface-element/MessageBox';

declare global {
  interface Window {
    MessageBox: IMessageBox;
  }
}

// 带类型安全的用法
const result: ModalResult = await window.MessageBox.showConfirm(
  '删除这个项目？',
  '确认删除'
);
```

## 无障碍功能

- 适当的ARIA标签和角色
- 键盘导航支持 (ESC关闭)
- 焦点管理
- 屏幕阅读器兼容性
- 高对比度模式支持

## 相关组件

- [Dialog](../dialog/README.md) - 用于自定义模态对话框
- [Toast](../toast/README.md) - 用于非阻塞通知
- [Button](../button/README.md) - 用于对话框操作