@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/07-/347/225/214/351/235/242.md

@@ -0,0 +1,376 @@
+# 豆包应用插件的端能力 API: 界面
+
+对话框状态、Toast、Loading、Modal、ActionSheet、BottomSheet、返回前提醒、键盘和输入框能力。
+
+[返回目录](./groups.md) | [返回速查](./quick-reference.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [getChatPanelInfo](#getchatpanelinfo) | 获取当前对话框状态快照。 调用不会改变对话框状态，也不会触发高度变化事件。 |
+| [setChatPanelState](#setchatpanelstate) | 设置对话框展示状态。 |
+| [onChatPanelHeightChanged](#onchatpanelheightchanged) | 监听对话框高度或展示状态变化。 注册后不会立即回调当前值。需要当前状态时，先调用 getChatPanelInfo。<br><br>返回取消监听函数。 |
+
+## API 详情
+
+<a id="getchatpanelinfo"></a>
+### getChatPanelInfo()
+
+---
+internal: true
+---
+
+# getChatPanelInfo
+
+获取当前对话框状态快照。
+
+调用不会改变对话框状态，也不会触发高度变化事件。
+
+## 支持版本
+
+前端库版本不低于 `0.0.42`。
+
+## 支持平台
+
+<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>
+
+## 接入准备
+
+### 前置条件
+
+- 当前页面需在 app.config.ts 中声明 chat.enabled 为 true
+
+## 使用说明
+
+- 调用只读取当前状态，不会改变对话框状态或触发高度变化事件。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+getChatPanelInfo(params?: object): Promise<ChatPanelInfo>
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```typescript
+import { getChatPanelInfo } from '@doubao-dev/framework/api';
+
+const { height, state } = await getChatPanelInfo();
+console.log('current chat panel', { height, state });
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>height</code></td><td><code>number</code></td><td>是</td><td>大于等于 0；收起态高度也可能大于 0</td><td>对话框实际占用的垂直高度，单位为 px，包含被键盘抬高的区域，隐藏时为 0。</td></tr>
+<tr><td><code>state</code></td><td><code>ChatPanelState</code></td><td>是</td><td>-</td><td>对话框当前展示状态。<br><br>- `preview` 表示从收起态发送消息后、收到回复前的中间态。<br>- `invisible` 表示对话框当前不可见。<br>- `floating` 表示对话框当前以悬浮形态展示。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "height": 336,
+  "state": "expanded"
+}
+```
+
+<a id="setchatpanelstate"></a>
+### setChatPanelState()
+
+---
+internal: true
+---
+
+# setChatPanelState
+
+设置对话框展示状态。
+
+## 支持版本
+
+前端库版本不低于 `0.5.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>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- 当前页面需在 app.config.ts 中声明 chat.enabled 为 true
+
+## 使用说明
+
+- preview 是只读状态，不能作为目标状态；floating 用于将对话框切换为悬浮胶囊态；设置 invisible 后可通过 collapsed、expanded 或 floating 再次显示对话框。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+setChatPanelState(params: SetChatPanelStateParams): Promise<object>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>state</code></td><td><code>ChatPanelTargetState</code></td><td>是</td><td>-</td><td>-</td><td>目标状态。<br><br>- `collapsed`：显示对话框并完全收起面板。<br>- `expanded`：显示对话框并完全展开面板。<br>- `invisible`：隐藏对话框。<br>- `floating`：将对话框切换为悬浮胶囊态。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { setChatPanelState } from '@doubao-dev/framework/api';
+
+await setChatPanelState({ state: 'collapsed' });
+```
+
+## 成功返回
+
+无返回字段。
+
+### 返回示例
+
+```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>state 不是 collapsed、expanded、invisible 或 floating</td><td>传入受支持的目标状态后重试。</td></tr>
+<tr><td><code>116</code></td><td><code>resource not found</code></td><td>Android</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</td></tr>
+</tbody>
+</table>
+
+<a id="onchatpanelheightchanged"></a>
+### onChatPanelHeightChanged()
+
+---
+internal: true
+---
+
+# onChatPanelHeightChanged
+
+监听对话框高度或展示状态变化。
+
+注册后不会立即回调当前值。需要当前状态时，先调用 getChatPanelInfo。
+
+## 支持版本
+
+前端库版本不低于 `0.0.42`。
+
+## 支持平台
+
+<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>
+
+## 接入准备
+
+### 前置条件
+
+- 当前页面需在 app.config.ts 中声明 chat.enabled 为 true
+
+## 使用说明
+
+- 注册后不立即回调当前值；页面卸载前调用返回的取消函数。
+
+## 调用方式
+
+### 事件监听 API
+
+```typescript
+onChatPanelHeightChanged(callback: (event: ChatPanelInfo) => void): () => void
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```typescript
+import { onChatPanelHeightChanged } from '@doubao-dev/framework/api';
+
+const off = onChatPanelHeightChanged(({ height, state }) => {
+  console.log('chat panel changed', { height, state });
+});
+
+off();
+```
+
+## 回调参数
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>event.height</code></td><td><code>number</code></td><td>是</td><td>大于等于 0；收起态高度也可能大于 0</td><td>对话框实际占用的垂直高度，单位为 px，包含被键盘抬高的区域，隐藏时为 0。</td></tr>
+<tr><td><code>event.state</code></td><td><code>ChatPanelState</code></td><td>是</td><td>-</td><td>对话框当前展示状态。<br><br>- `preview` 表示从收起态发送消息后、收到回复前的中间态。<br>- `invisible` 表示对话框当前不可见。<br>- `floating` 表示对话框当前以悬浮形态展示。</td></tr>
+</tbody>
+</table>
+
+## 返回值
+
+返回 () => void。
+
+### 回调示例
+
+```json
+{
+  "height": 336,
+  "state": "expanded"
+}
+```
+
+## 相关类型
+
+<a id="chatpanelstate"></a>
+### ChatPanelState
+
+对话框展示状态。
+
+#### Type
+
+`'collapsed' | 'expanded' | 'preview' | 'invisible' | 'floating'`
+
+<a id="chatpanelinfo"></a>
+### ChatPanelInfo
+
+对话框状态快照。
+
+#### Properties
+
+• **height**: `number` - 对话框实际占用的垂直高度，单位为 px，包含被键盘抬高的区域，隐藏时为 0
+• **state**: `ChatPanelState` - 对话框当前展示状态。 - preview 表示从收起态发送消息后、收到回复前的中间态。 - invisible 表示对话框当前不可见。 - floating 表示对话框当前以悬浮形态展示
+
+<a id="chatpaneltargetstate"></a>
+### ChatPanelTargetState
+
+可主动设置的对话框展示状态。 preview 是对话回复过程中的只读状态，不能主动设置。
+
+#### Type
+
+`Exclude<ChatPanelState, 'preview'>`
+
+<a id="setchatpanelstateparams"></a>
+### SetChatPanelStateParams
+
+设置对话框状态的参数。
+
+#### Properties
+
+• **state**: `ChatPanelTargetState` - 目标状态。 - collapsed：显示对话框并完全收起面板。 - expanded：显示对话框并完全展开面板。 - invisible：隐藏对话框。 - floating：将对话框切换为悬浮胶囊态
+• **extra?**: `Record<string, string>` - 本次面板状态切换的扩展参数；show_reason 指定本次切换的展示原因