> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# showModal

显示模态对话框。

## 扫码预览

![扫码预览 showModal](https://api.qrserver.com/v1/create-qr-code/?size=200x200\&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fui%252Fshow-modal%252Findex)

## 支持版本

前端库版本不低于 `0.0.26`。

## 支持平台

<table>
<thead>
<tr><th>平台</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>Android</td><td>支持</td></tr>
<tr><td>iOS</td><td>支持</td></tr>
<tr><td>PC</td><td>不支持</td></tr>
<tr><td>HarmonyOS</td><td>不支持</td></tr>
</tbody>
</table>

## 支持场景

<table>
<thead>
<tr><th>场景</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>页面</td><td>支持</td></tr>
<tr><td>卡片</td><td>支持</td></tr>
</tbody>
</table>

## 使用说明

- 仅当 showCancel 为 true 时展示取消按钮；仅当 tapMaskToDismiss 为 true 时点击蒙层可关闭；editable 为 true 且用户确认时返回输入 content。

## 调用方式

### 异步 API

```typescript
showModal(params?: ShowModalParams): Promise<ShowModalResult>
```

## 入参

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>cancelColor</code></td><td><code>string</code></td><td>否</td><td><code>#000000</code></td><td>必须是 16 进制格式的颜色字符串。</td><td>取消按钮的文字颜色。</td></tr>
<tr><td><code>cancelText</code></td><td><code>string</code></td><td>否</td><td><code>取消</code></td><td>最多 4 个字符。</td><td>取消按钮的文字。</td></tr>
<tr><td><code>confirmColor</code></td><td><code>string</code></td><td>否</td><td><code>#F85959</code></td><td>必须是 16 进制格式的颜色字符串。</td><td>确认按钮的文字颜色。</td></tr>
<tr><td><code>confirmText</code></td><td><code>string</code></td><td>否</td><td><code>确定</code></td><td>最多 4 个字符。</td><td>确认按钮的文字。</td></tr>
<tr><td><code>content</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>模态对话框的内容。</td></tr>
<tr><td><code>editable</code></td><td><code>boolean</code></td><td>否</td><td><code>false</code></td><td>-</td><td>是否显示输入框。</td></tr>
<tr><td><code>placeholderText</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>显示输入框时的提示文本。</td></tr>
<tr><td><code>showCancel</code></td><td><code>boolean</code></td><td>否</td><td><code>true</code></td><td>-</td><td>是否显示取消按钮。</td></tr>
<tr><td><code>tapMaskToDismiss</code></td><td><code>boolean</code></td><td>否</td><td><code>true</code></td><td>-</td><td>是否允许点击蒙层关闭对话框。</td></tr>
<tr><td><code>title</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>模态对话框的标题。</td></tr>
</tbody>
</table>

## 调用示例

```ts
import { showModal } from '@doubao-dev/framework/api';

const result = await showModal({
  title: '提示',
  content: '确认删除这条记录吗？',
  confirmText: '删除',
  cancelText: '取消'
});

if (result.action === 'confirm') {
  console.log('用户确认删除');
}
```

## 成功返回

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>action</code></td><td><code>&quot;confirm&quot; | &quot;cancel&quot; | &quot;mask&quot;</code></td><td>是</td><td>用户点击的动作。</td></tr>
<tr><td><code>content</code></td><td><code>string</code></td><td>否</td><td>`editable` 为 true 时，用户点击确认后输入的文本。</td></tr>
</tbody>
</table>

### 返回示例

```json
{
  "action": "confirm"
}
```

## 错误处理

错误对象和通用错误码见 [通用错误处理](/apps-plugin/docs/js-api/common-errors.md#错误返回)。

### 错误码

#### 通用错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
</thead>
<tbody>
<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
</tbody>
</table>
