---
title: "弹窗"
doc_type: static
doc_category: static
doc_version: v20270301
source_url:
html: 'https://developer.shopline.com/zh-hans-cn/docs/apps/development-tool/app-bridge/actions/modal'
md: 'https://developer.shopline.com/zh-hans-cn/docs/apps/development-tool/app-bridge/actions/modal.md'
---
# 弹窗
Modal（弹窗）是一个对话框组件，用于在当前页面之上展示重要信息、警告提示或需要确认的操作。Modal 提供了多种类型（确认、警告、错误、成功等），帮助应用实现统一的弹窗交互体验。
## 快速开始{#RHlV2}
以下示例展示了弹窗的基本实现方式：
```javascript
import Client, { shared, Modal, ModalAction } from '@shoplineos/app-bridge';
// 1. 初始化 App Bridge
const app = Client.createApp({
appKey: 'your-app-key',
host: shared.getHost(),
});
// 2. 创建 Modal 实例
const modal = Modal.create(app);
// 3. 打开确认弹窗
modal.open({
type: 'confirm',
title: '确认删除',
content: '确定要删除这个商品吗？此操作无法撤销。',
});
// 4. 订阅确认事件
modal.subscribe(ModalAction.MODAL_SAVE, () => {
console.log('点击了确认');
// 执行删除操作
});
// 5. 订阅取消事件
modal.subscribe(ModalAction.MODAL_CLOSE, () => {
console.log('点击了取消');
});
```
当调用 `open()` 方法后，会在页面中弹出对应弹窗。确认弹窗的效果如下：
## API 方法{#QsuOr}
### open(){#ZsbNd}
```typescript
(config: ModalProps): void
```
打开弹窗。
#### 参数{#boqJo}
| 参数 | 类型 | 说明 | 必填 |
| ------ | ------------ | ---------------------------------------------------- | ---- |
| config | `ModalProps` | 弹窗配置，详见下方 [类型定义](#UciQx) 中的参数说明。 | 是 |
#### 使用示例{#w7cAd}
```javascript
// 确认弹窗
modal.open({
type: 'confirm',
title: '确认操作',
content: '确定要继续吗？',
});
// 危险操作弹窗
modal.open({
type: 'danger',
title: '危险操作',
content: '此操作将永久删除数据，无法恢复！',
});
// 错误提示弹窗
modal.open({
type: 'error',
title: '操作失败',
content: '保存失败，请稍后重试。',
});
// 成功提示弹窗
modal.open({
type: 'success',
title: '操作成功',
content: '商品已成功保存。',
});
// 警告弹窗
modal.open({
type: 'warn',
title: '警告',
content: '有未保存的更改，确定要离开吗？',
});
// 信息提示弹窗
modal.open({
type: 'info',
title: '提示',
content: '该功能即将上线，敬请期待。',
});
```
---
### subscribe(){#p9JNW}
```typescript
(action: ModalAction, callback: () => void, once?: boolean): () => void
```
订阅弹窗的动作事件（如确认、取消等）。
#### 参数{#HP6Xs}
| 参数 | 类型 | 说明 | 必填 |
| -------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| action | `ModalAction` | 订阅的动作类型，详见下方 [类型定义](#f34a4) 中的动作类型说明。 | 是 |
| callback | `() => void` | 动作触发时的回调函数。 | 是 |
| once | boolean | 是否在触发一次后自动取消订阅。
• `true`：表示触发一次后自动取消订阅。
• `false`：表示触发后不会自动取消订阅，需要手动取消订阅。 | 否 |
#### 返回值{#E2mtU}
返回一个取消订阅函数，调用它可以取消当前订阅。
#### 使用示例{#C1Jm2}
```javascript
// 订阅确认事件
const unsubscribe = modal.subscribe(ModalAction.MODAL_SAVE, () => {
console.log('确认了操作');
// 执行相应的业务逻辑
});
// 取消订阅
unsubscribe();
// 订阅一次性事件（触发后自动取消订阅）
modal.subscribe(
ModalAction.MODAL_SAVE,
() => {
console.log('这个回调只会执行一次');
},
true,
);
```
---
### unsubscribe(){#lEaS1}
```typescript
(action: ModalAction): void
```
取消指定动作的所有订阅。
#### 参数{#FX8iU}
| 参数 | 类型 | 说明 | 必填 |
| ------ | ------------- | ------------------------------------------------------------------ | ---- |
| action | `ModalAction` | 取消订阅的动作类型，详见下方 [类型定义](#f34a4) 中的动作类型说明。 | 是 |
#### 使用示例{#yzq3h}
```javascript
// 取消所有 MODAL_SAVE 动作的订阅
modal.unsubscribe(ModalAction.MODAL_SAVE);
```
---
## 类型定义{#uxO0T}
### ModalProps{#UciQx}
`open()` 方法的配置参数。
| 参数 | 类型 | 说明 | 必填 |
| ------- | ----------------------------------------------------------------------------- | -------------------------------- | ---- |
| type | `'confirm'` \| `'danger'` \| `'error'` \| `'warn'` \| `'info'` \| `'success'` | 弹窗类型，决定弹窗的样式和图标。 | 是 |
| title | string | 弹窗标题文本。 | 是 |
| content | string | 弹窗内容文本。 | 是 |
**弹窗类型说明：**
| 类型 | 说明 | 使用场景 |
| --------- | ------------ | ------------------ |
| `confirm` | 确认弹窗 | 需要用户确认的操作 |
| `danger` | 危险操作弹窗 | 危险或不可逆的操作 |
| `error` | 错误提示弹窗 | 操作失败或错误提示 |
| `warn` | 警告弹窗 | 警告信息或注意事项 |
| `info` | 信息提示弹窗 | 一般性信息提示 |
| `success` | 成功提示弹窗 | 操作成功的反馈 |
### ModalAction{#f34a4}
通过 `subscribe()` 方法订阅这些动作，监听弹窗的各种事件。
| 动作类型 | 说明 | 触发时机 | 回调参数 |
| ------------- | ---------- | ---------------------------- | -------- |
| `MODAL_SAVE` | 确认 | 点击确认按钮时触发 | 无 |
| `MODAL_CLOSE` | 取消或关闭 | 点击取消按钮或关闭弹窗时触发 | 无 |
## 使用示例{#L6N26}
### 示例 1：删除确认{#LUUFu}
```javascript
const handleDelete = (productId) => {
// 打开确认弹窗
modal.open({
type: 'danger',
title: '确认删除',
content: '确定要删除这个商品吗？此操作无法撤销。',
});
// 订阅确认事件（使用一次性订阅）
modal.subscribe(
ModalAction.MODAL_SAVE,
async () => {
try {
// 执行删除操作
await deleteProduct(productId);
// 显示成功提示
modal.open({
type: 'success',
title: '删除成功',
content: '商品已成功删除。',
});
} catch (error) {
// 显示错误提示
modal.open({
type: 'error',
title: '删除失败',
content: '删除商品时发生错误，请稍后重试。',
});
}
},
true, // 一次性订阅
);
};
```
### 示例 2：保存确认{#lCNvr}
```javascript
const handleSave = (formData) => {
modal.open({
type: 'confirm',
title: '确认保存',
content: '确定要保存当前的修改吗？',
});
modal.subscribe(
ModalAction.MODAL_SAVE,
async () => {
try {
await saveData(formData);
modal.open({
type: 'success',
title: '保存成功',
content: '数据已成功保存。',
});
} catch (error) {
modal.open({
type: 'error',
title: '保存失败',
content: error.message,
});
}
},
true,
);
};
```
### 示例 3：退出确认{#tD5Q2}
```javascript
const handleExit = () => {
if (hasUnsavedChanges) {
modal.open({
type: 'warn',
title: '未保存的更改',
content: '有未保存的更改，确定要离开吗？',
});
modal.subscribe(
ModalAction.MODAL_SAVE,
() => {
// 确认离开
window.location.href = '/dashboard';
},
true,
);
modal.subscribe(
ModalAction.MODAL_CLOSE,
() => {
// 取消离开
console.log('取消了退出');
},
true,
);
} else {
// 没有未保存的更改，直接离开
window.location.href = '/dashboard';
}
};
```