@doubao-dev/plugin-app-dev 0.0.0-stage → 0.0.40-canary-dea0ddc73-20261026073950

package/dist/skills/doubao-plugin-app/references/frontend/doubao-agentic-service-api/08-/344/272/244/344/272/222.md

@@ -0,0 +1,1319 @@
+# 豆包应用插件的端能力 API: 交互
+
+Toast、Loading、Modal、ActionSheet、BottomSheet 和返回前提醒。
+
+[返回目录](./groups.md) | [返回速查](./quick-reference.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [enableAlertBeforeUnload](#enablealertbeforeunload) | 开启页面返回前提醒。 当用户在应用插件的非最底层页面点击左上角返回按钮、左上角首页按钮或客户端返回键时,弹起询问弹窗 返回询问对话框只会对调用的当前页面生效，通过手势滑动返回时不会弹起询问对话框。 |
+| [disableAlertBeforeUnload](#disablealertbeforeunload) | 关闭页面返回前提醒。 |
+| [showModal](#showmodal) | 显示模态对话框。 |
+| [showLoading](#showloading) | 显示 loading 提示框。 |
+| [hideToast](#hidetoast) | 隐藏当前 Toast。 |
+| [hideLoading](#hideloading) | 隐藏当前 loading。 |
+| [showActionSheet](#showactionsheet) | 显示操作菜单。 |
+| [showBottomSheet](#showbottomsheet) | 显示豆包底部弹窗。 |
+| [getMenuButtonBoundingClientRect](#getmenubuttonboundingclientrect) | 取菜单按钮（右上角胶囊按钮）的布局位置信息。 |
+| [showToast](#showtoast) | 显示 Toast 提示。 |
+
+## API 详情
+
+<a id="enablealertbeforeunload"></a>
+### enableAlertBeforeUnload()
+
+# enableAlertBeforeUnload
+
+开启页面返回前提醒。
+当用户在应用插件的非最底层页面点击左上角返回按钮、左上角首页按钮或客户端返回键时,弹起询问弹窗
+
+返回询问对话框只会对调用的当前页面生效，通过手势滑动返回时不会弹起询问对话框
+
+## 扫码预览
+![扫码预览 enableAlertBeforeUnload](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%252Falert-before-unload%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.2.0`。
+
+## 支持平台
+
+<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>
+
+## 接入准备
+
+### 前置条件
+
+- 必须在页面容器内调用
+
+## 使用说明
+
+配合 disableAlertBeforeUnload 使用。
+
+- 仅非根页面的显式返回会展示提醒；根页面退出不拦截，iOS 侧滑返回不拦截。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+enableAlertBeforeUnload(params: EnableAlertBeforeUnloadParams): Promise<object>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>message</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>返回前确认弹窗的文案。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { enableAlertBeforeUnload } from '@doubao-dev/framework/api';
+
+await enableAlertBeforeUnload({ message: '确定离开当前页面吗？' });
+```
+
+## 成功返回
+
+无返回字段。
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 103,
+  "errMsg": "feature not support"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>103</code></td><td><code>feature not support</code></td><td>Android、iOS</td><td>当前调用不来自页面容器</td><td>请在页面生命周期内调用。</td></tr>
+<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>Android、iOS</td><td>message 缺失或类型不是字符串</td><td>传入字符串类型的 message。</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<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>
+
+<a id="disablealertbeforeunload"></a>
+### disableAlertBeforeUnload()
+
+# disableAlertBeforeUnload
+
+关闭页面返回前提醒。
+
+## 扫码预览
+![扫码预览 disableAlertBeforeUnload](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%252Falert-before-unload%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.2.0`。
+
+## 支持平台
+
+<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>
+
+## 接入准备
+
+### 前置条件
+
+- 必须在页面容器内调用
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+disableAlertBeforeUnload(params?: object): Promise<object>
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```typescript
+import { disableAlertBeforeUnload } from '@doubao-dev/framework/api';
+
+await disableAlertBeforeUnload();
+```
+
+## 成功返回
+
+无返回字段。
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 103,
+  "errMsg": "feature not support"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>103</code></td><td><code>feature not support</code></td><td>Android、iOS</td><td>当前调用不来自页面容器</td><td>请在页面生命周期内调用。</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<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>
+
+<a id="showmodal"></a>
+### showModal()
+
+# 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"
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./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>
+
+<a id="showloading"></a>
+### showLoading()
+
+# showLoading
+
+显示 loading 提示框。
+
+## 扫码预览
+![扫码预览 showLoading](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-loading%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>
+
+## 使用说明
+
+需调用 hideLoading 关闭。
+
+- loading 展示后需调用 hideLoading 手动关闭。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+showLoading(params?: ShowLoadingParams): Promise<object>
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```typescript
+import { hideLoading, showLoading } from '@doubao-dev/framework/api';
+
+await showLoading();
+await hideLoading();
+```
+
+## 成功返回
+
+无返回字段。
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./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>
+
+<a id="hidetoast"></a>
+### hideToast()
+
+# hideToast
+
+隐藏当前 Toast。
+
+## 扫码预览
+![扫码预览 hideToast](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-toast%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>
+
+## 使用说明
+
+- 当前没有 Toast 时调用无副作用。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+hideToast(params?: HideInteractionParams): Promise<object>
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```typescript
+import { hideToast } from '@doubao-dev/framework/api';
+
+await hideToast();
+```
+
+## 成功返回
+
+无返回字段。
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./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</td></tr>
+</tbody>
+</table>
+
+<a id="hideloading"></a>
+### hideLoading()
+
+# hideLoading
+
+隐藏当前 loading。
+
+## 扫码预览
+![扫码预览 hideLoading](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-loading%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>
+
+## 使用说明
+
+- 与 showLoading 配对使用；当前没有 loading 时调用无副作用。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+hideLoading(params?: HideInteractionParams): Promise<object>
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```typescript
+import { hideLoading } from '@doubao-dev/framework/api';
+
+await hideLoading();
+```
+
+## 成功返回
+
+无返回字段。
+
+<a id="showactionsheet"></a>
+### showActionSheet()
+
+# showActionSheet
+
+显示操作菜单。
+
+## 扫码预览
+![扫码预览 showActionSheet](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-action-sheet%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>
+
+## 使用说明
+
+- itemList 必填；用户点击菜单外区域取消时 Promise reject，请在 catch 中处理取消场景。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+showActionSheet(params: ShowActionSheetParams): Promise<ShowActionSheetResult>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>itemColor</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>十六进制颜色字符串，例如 #000000。</td><td>按钮文字颜色。</td></tr>
+<tr><td><code>itemList</code></td><td><code>string[]</code></td><td>是</td><td>-</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 { showActionSheet } from '@doubao-dev/framework/api';
+
+const result = await showActionSheet({
+  itemList: ['编辑', '删除']
+});
+
+console.log(result.tapIndex);
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>tapIndex</code></td><td><code>number</code></td><td>是</td><td>用户点击的按钮序号，从 0 开始。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "tapIndex": 0
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 114,
+  "errMsg": "operation cancelled"
+}
+```
+
+### 错误码
+
+<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>itemList 为空数组</td><td>传入至少一个菜单项后重试。</td></tr>
+<tr><td><code>114</code></td><td><code>operation cancelled</code></td><td>Android、iOS</td><td>用户点击 Cancel 按钮或点击蒙层关闭操作菜单</td><td>用户主动取消，按需静默处理。</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<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>
+
+<a id="showbottomsheet"></a>
+### showBottomSheet()
+
+# 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"
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./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 的成功结果，且不校验三按钮能力。
+
+<a id="getmenubuttonboundingclientrect"></a>
+### getMenuButtonBoundingClientRect()
+
+# getMenuButtonBoundingClientRect
+
+取菜单按钮（右上角胶囊按钮）的布局位置信息。
+
+## 扫码预览
+![扫码预览 getMenuButtonBoundingClientRect](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%252Fget-menu-button-bounding-client-rect%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>
+
+## 使用说明
+
+- 坐标单位为逻辑像素，与 CSS 像素一致，可直接用于页面布局定位。
+
+## 调用方式
+
+### 同步 API
+
+```typescript
+getMenuButtonBoundingClientRect(): MenuButtonBoundingClientRect
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```ts
+import { getMenuButtonBoundingClientRect } from '@doubao-dev/framework/api';
+
+const rect = getMenuButtonBoundingClientRect();
+
+console.log(rect.width, rect.height);
+console.log(rect.top, rect.right, rect.bottom, rect.left);
+```
+
+## 返回值
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>bottom</code></td><td><code>number</code></td><td>是</td><td>下边界坐标，单位 px。</td></tr>
+<tr><td><code>height</code></td><td><code>number</code></td><td>是</td><td>高度，单位 px。</td></tr>
+<tr><td><code>left</code></td><td><code>number</code></td><td>是</td><td>左边界坐标，单位 px。</td></tr>
+<tr><td><code>right</code></td><td><code>number</code></td><td>是</td><td>右边界坐标，单位 px。</td></tr>
+<tr><td><code>top</code></td><td><code>number</code></td><td>是</td><td>上边界坐标，单位 px。</td></tr>
+<tr><td><code>width</code></td><td><code>number</code></td><td>是</td><td>宽度，单位 px。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "width": 84,
+  "height": 36,
+  "top": 48,
+  "right": 363,
+  "bottom": 84,
+  "left": 279
+}
+```
+
+<a id="showtoast"></a>
+### showToast()
+
+# showToast
+
+显示 Toast 提示。
+
+## 扫码预览
+![扫码预览 showToast](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-toast%252Findex)
+
+## 使用限制
+
+> [!WARNING]
+> **Android、iOS**：Android、iOS 均只按 icon/type 渲染内置图标，不加载 customIcon；依赖 customIcon 展示图标的调用不会生效。
+
+## 支持版本
+
+前端库版本不低于 `0.0.9`。
+
+## 支持平台
+
+<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>
+
+## 使用说明
+
+Android 默认显示 3000 毫秒，iOS 默认显示 2000 毫秒；需要双端一致时请显式传入 `duration`。
+
+- message 必填，且 type 与 icon 至少传一个；customIcon 当前不会渲染，请通过 icon 使用内置图标。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+showToast(params: ShowToastParams): Promise<object>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>customIcon</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>自定义图标的 URL 或 base64 字符串。Android、iOS：Android、iOS 均只按 icon/type 渲染内置图标，不加载 customIcon。</td></tr>
+<tr><td><code>duration</code></td><td><code>number</code></td><td>否</td><td><code>Android 3000，iOS 2000</code></td><td>需双端保持一致时请显式传入。</td><td>提示的持续时间，单位毫秒。</td></tr>
+<tr><td><code>icon</code></td><td><code>&quot;success&quot; | &quot;error&quot; | &quot;warn&quot;</code></td><td>否</td><td><code>-</code></td><td>-</td><td>图标。</td></tr>
+<tr><td><code>message</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>提示的内容。</td></tr>
+<tr><td><code>type</code></td><td><code>&quot;default&quot; | &quot;success&quot; | &quot;error&quot; | &quot;warning&quot;</code></td><td>否</td><td><code>'default'</code></td><td>-</td><td>Toast 的类型。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { showToast } from '@doubao-dev/framework/api';
+
+// 显示一个成功的 Toast
+showToast({
+  message: '操作成功',
+  type: 'success',
+  icon: 'success',
+  duration: 1500
+}).then(() => {
+  console.log('Toast 显示完毕');
+});
+
+// 显示一个错误的 Toast
+showToast({
+  message: '网络错误',
+  type: 'error',
+  icon: 'error'
+});
+```
+
+## 成功返回
+
+无返回字段。
+
+### 返回示例
+
+```json
+{}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./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>message 为空；iOS 还会在 icon 取值非法或入参无法解析时返回（type 由前端归一化为合法值，非法 type 场景不会触发）</td><td>修正参数后重试。</td></tr>
+<tr><td><code>103</code></td><td><code>feature not support</code></td><td>iOS</td><td>豆包 UIService 未实现，无法展示 Toast</td><td>降级到其他提示方式。</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<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</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- **iOS**：参数校验失败统一返回 errNo 104；UIService 缺失时返回 errNo 103。Android 参数校验失败返回 errNo 104，豆包页面运行上下文缺失返回 errNo 102。
+
+## 相关类型
+
+<a id="enablealertbeforeunloadparams"></a>
+### EnableAlertBeforeUnloadParams
+
+开启返回前提醒的参数。
+
+#### Properties
+
+• **message**: `string` - 返回前确认弹窗的文案
+
+<a id="showmodalparams"></a>
+### ShowModalParams
+
+显示模态对话框的参数。
+
+#### Properties
+
+• **title?**: `string` - 模态对话框的标题
+• **content?**: `string` - 模态对话框的内容
+• **showCancel?**: `boolean` - 是否显示取消按钮
+• **cancelText?**: `string` - 取消按钮的文字
+• **cancelColor?**: `string` - 取消按钮的文字颜色
+• **confirmText?**: `string` - 确认按钮的文字
+• **confirmColor?**: `string` - 确认按钮的文字颜色
+• **editable?**: `boolean` - 是否显示输入框
+• **placeholderText?**: `string` - 显示输入框时的提示文本
+• **tapMaskToDismiss?**: `boolean` - 是否允许点击蒙层关闭对话框
+
+<a id="showmodalresult"></a>
+### ShowModalResult
+
+显示模态对话框的返回结果。
+
+#### Properties
+
+• **action**: `'confirm' | 'cancel' | 'mask'` - 用户点击的动作
+• **content?**: `string` - editable 为 true 时，用户点击确认后输入的文本
+
+<a id="showloadingparams"></a>
+### ShowLoadingParams
+
+显示 loading 提示框的参数。
+
+#### Properties
+
+无字段。
+
+<a id="hideinteractionparams"></a>
+### HideInteractionParams
+
+隐藏交互提示框的公共参数。
+
+#### Properties
+
+无字段。
+
+<a id="showactionsheetparams"></a>
+### ShowActionSheetParams
+
+显示操作菜单的参数。
+
+#### Properties
+
+• **title?**: `string` - 标题
+• **itemList**: `string[]` - 按钮文字数组
+• **itemColor?**: `string` - 按钮文字颜色
+
+<a id="showactionsheetresult"></a>
+### ShowActionSheetResult
+
+显示操作菜单的返回结果。
+
+#### Properties
+
+• **tapIndex**: `number` - 用户点击的按钮序号，从 0 开始
+
+<a id="bottomsheetbuttonrole"></a>
+### BottomSheetButtonRole
+
+底部弹窗按钮语义。
+
+#### Type
+
+`'agreeMain' | 'agreeSub' | 'reject'`
+
+<a id="bottomsheetcancelsource"></a>
+### BottomSheetCancelSource
+
+底部弹窗取消来源。
+
+#### Type
+
+`'mask' | 'gesture' | 'hostUnavailable' | 'unknown'`
+
+<a id="bottomsheetbuttons"></a>
+### BottomSheetButtons
+
+底部弹窗按钮配置，支持 1-3 个按钮。
+
+#### Type
+
+`| [BottomSheetButton]
+  | [BottomSheetButton, BottomSheetButton]
+  | [BottomSheetButton, BottomSheetButton, BottomSheetButton]`
+
+<a id="bottomsheetbehavior"></a>
+### BottomSheetBehavior
+
+底部弹窗行为配置。
+
+#### Properties
+
+• **dismissOnMaskTap?**: `boolean` - 是否允许点击蒙层关闭弹窗
+
+<a id="showbottomsheetparams"></a>
+### ShowBottomSheetParams
+
+显示底部弹窗的参数。
+
+#### Properties
+
+• **title**: `string` - 弹窗标题
+• **content**: `string` - 受限 HTML 字符串，支持段落、加粗和链接
+• **buttons**: `BottomSheetButtons` - 按钮配置，支持 1-3 个，展示顺序与数组顺序一致，按钮语义不可重复
+• **behavior?**: `BottomSheetBehavior` - 弹窗行为配置
+
+<a id="showbottomsheetresult"></a>
+### ShowBottomSheetResult
+
+显示底部弹窗的返回结果。
+
+#### Type
+
+`BottomSheetButtonClickResult | BottomSheetCancelResult`
+
+<a id="bottomsheetbutton"></a>
+### BottomSheetButton
+
+底部弹窗按钮配置。
+
+#### Properties
+
+• **role**: `BottomSheetButtonRole` - 按钮语义
+• **text**: `string` - 按钮展示文案
+
+<a id="bottomsheetbuttonclickresult"></a>
+### BottomSheetButtonClickResult
+
+底部弹窗点击按钮的返回结果。
+
+#### Properties
+
+• **action**: `'buttonClick'` - 弹窗结束动作
+• **role**: `BottomSheetButtonRole` - 被点击按钮的语义
+
+<a id="bottomsheetcancelresult"></a>
+### BottomSheetCancelResult
+
+底部弹窗取消关闭的返回结果。
+
+#### Properties
+
+• **action**: `'cancel'` - 弹窗结束动作
+• **source**: `BottomSheetCancelSource` - 取消来源
+
+<a id="menubuttonboundingclientrect"></a>
+### MenuButtonBoundingClientRect
+
+菜单按钮的布局位置信息。
+
+#### Properties
+
+• **width**: `number` - 宽度，单位 px
+• **height**: `number` - 高度，单位 px
+• **top**: `number` - 上边界坐标，单位 px
+• **right**: `number` - 右边界坐标，单位 px
+• **bottom**: `number` - 下边界坐标，单位 px
+• **left**: `number` - 左边界坐标，单位 px
+
+<a id="showtoastparams"></a>
+### ShowToastParams
+
+#### Properties
+
+• **message**: `string` - 提示的内容
+• **type?**: `'default' | 'success' | 'error' | 'warning'` - Toast 的类型
+• **duration?**: `number` - 提示的持续时间，单位毫秒
+• **icon?**: `'success' | 'error' | 'warn'` - 图标
+• **customIcon?**: `string` - 自定义图标的 URL 或 base64 字符串