> 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.

# showBottomSheet

显示豆包底部弹窗。

## 扫码预览

![扫码预览 showBottomSheet](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-bottom-sheet%252Findex)

## 使用限制

> \[!WARNING]
> **Android、iOS**：iOS 无法展示弹窗或不支持三按钮时返回 errNo 103 失败，Android 无法展示弹窗时返回 action=cancel、source=hostUnavailable 的成功结果，且不检测三按钮能力；调用方无法用统一逻辑处理弹窗不可用场景。

## 支持版本

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

## 支持平台

<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>

## 使用说明

`content` 接收受限 HTML 字符串，当前支持段落、加粗和链接；危险标签、事件属性和危险链接协议会被拦截。
链接会在豆包内打开，不会关闭弹窗。
Promise 在用户点击按钮或点击蒙层关闭后 resolve。

- content 为受限 HTML，仅支持段落、加粗和链接，危险标签、事件属性和非 http(s) 链接会被拦截并触发失败；链接点击打开 H5，不关闭弹窗。
- buttons 需 1-3 个且语义不重复；用户点击蒙层或下拉手势关闭时返回 action=cancel。当豆包无法展示弹窗时，iOS 返回失败、Android 返回 action=cancel 且 source=hostUnavailable，请对两种结果都做降级处理。

## 调用方式

### 异步 API

```typescript
showBottomSheet(params: ShowBottomSheetParams): Promise<ShowBottomSheetResult>
```

## 入参

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>behavior</code></td><td><code>BottomSheetBehavior</code></td><td>否</td><td><code>-</code></td><td>-</td><td>弹窗行为配置。</td></tr>
<tr><td><code>behavior.dismissOnMaskTap</code></td><td><code>boolean</code></td><td>否</td><td><code>true</code></td><td>-</td><td>是否允许点击蒙层关闭弹窗。</td></tr>
<tr><td><code>buttons</code></td><td><code>BottomSheetButtons</code></td><td>是</td><td>-</td><td>-</td><td>按钮配置，支持 1-3 个，展示顺序与数组顺序一致，按钮语义不可重复。</td></tr>
<tr><td><code>content</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>受限 HTML 字符串，支持段落、加粗和链接。</td></tr>
<tr><td><code>title</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>弹窗标题。</td></tr>
</tbody>
</table>

## 调用示例

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

const result = await showBottomSheet({
  title: '隐私协议提示',
  content:
    '<p>感谢您使用当前应用插件。</p><p><b>•</b> 详情请见<a href="https://www.doubao.com/chat/"><b>《应用插件条款》</b></a></p>',
  buttons: [
    { role: 'agreeMain', text: '同意并继续' },
    { role: 'reject', text: '暂不同意' }
  ]
});

if (result.action === 'buttonClick') {
  console.log(result.role);
}
```

## 成功返回

### `action = "buttonClick"`

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>action</code></td><td><code>&quot;buttonClick&quot;</code></td><td>是</td><td>弹窗结束动作。</td></tr>
<tr><td><code>role</code></td><td><code>BottomSheetButtonRole</code></td><td>是</td><td>被点击按钮的语义。</td></tr>
</tbody>
</table>

### `action = "cancel"`

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>action</code></td><td><code>&quot;cancel&quot;</code></td><td>是</td><td>弹窗结束动作。</td></tr>
<tr><td><code>source</code></td><td><code>BottomSheetCancelSource</code></td><td>是</td><td>取消来源。</td></tr>
</tbody>
</table>

### 返回示例

```json
{
  "action": "buttonClick",
  "role": "agreeMain"
}
```

## 错误处理

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

### 失败示例

```json
{
  "errNo": 104,
  "errMsg": "invalid parameter"
}
```

### 错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
</thead>
<tbody>
<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>Android、iOS</td><td>title 或 content 为空、content 含被拦截的标签/事件属性/危险链接、buttons 数量不在 1-3 范围；iOS 还会在按钮语义重复或按钮文案为空时返回</td><td>修正参数后重试。</td></tr>
<tr><td><code>103</code></td><td><code>feature not support</code></td><td>iOS</td><td>豆包 iOS 无法展示底部弹窗，或不支持包含 3 个按钮的弹窗</td><td>降级到自定义弹窗；同场景 Android 返回 action=cancel、source=hostUnavailable 的成功结果，请一并做降级处理。</td></tr>
</tbody>
</table>

## 平台差异

- **iOS**：无法展示底部弹窗或不支持三按钮时返回 errNo 103 失败；Android 无法展示底部弹窗时返回 action=cancel、source=hostUnavailable 的成功结果，且不校验三按钮能力。
