@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/33-/345/261/217/345/271/225.md

@@ -0,0 +1,747 @@
+# 豆包应用插件的端能力 API: 屏幕
+
+屏幕亮度、常亮和截屏/录屏相关能力。
+
+[返回目录](./groups.md) | [返回速查](./quick-reference.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [getScreenBrightness](#getscreenbrightness) | 获取屏幕亮度。 |
+| [setScreenBrightness](#setscreenbrightness) | 设置屏幕亮度。 |
+| [setKeepScreenOn](#setkeepscreenon) | 设置屏幕常亮状态。 |
+| [disableUserScreenRecord](#disableuserscreenrecord) | 禁止用户录屏。 |
+| [enableUserScreenRecord](#enableuserscreenrecord) | 允许用户录屏。 |
+| [onUserCaptureScreen](#onusercapturescreen) | 监听用户主动截屏事件。<br><br>返回取消监听函数。 |
+| [onUserScreenRecord](#onuserscreenrecord) | 监听用户录屏事件。<br><br>返回取消监听函数。 |
+
+## API 详情
+
+<a id="getscreenbrightness"></a>
+### getScreenBrightness()
+
+# getScreenBrightness
+
+获取屏幕亮度。
+
+## 扫码预览
+![扫码预览 getScreenBrightness](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fdevice%252Fget-screen-brightness%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.0.19`。
+
+## 支持平台
+
+<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>
+
+## 使用说明
+
+- 返回值为归一化后的 0 到 1 亮度
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+getScreenBrightness(params?: object): Promise<GetScreenBrightnessResult>
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```typescript
+import { getScreenBrightness } from '@doubao-dev/framework/api';
+
+const { value } = await getScreenBrightness();
+
+console.log(value);
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>value</code></td><td><code>number</code></td><td>是</td><td>取值范围 0 到 1，0 最暗，1 最亮</td><td>屏幕亮度值。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "value": 0.6
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./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="setscreenbrightness"></a>
+### setScreenBrightness()
+
+# setScreenBrightness
+
+设置屏幕亮度。
+
+## 扫码预览
+![扫码预览 setScreenBrightness](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fdevice%252Fget-screen-brightness%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.4.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>
+
+## 接入准备
+
+### 前置条件
+
+- value 必须是 0 到 1 之间的有限数字
+
+## 使用说明
+
+- 该设置仅在当前应用插件生命周期内生效，退出后自动恢复原亮度
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+setScreenBrightness(params: SetScreenBrightnessParams): Promise<object>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>value</code></td><td><code>number</code></td><td>是</td><td>-</td><td>取值范围 0 到 1，0 最暗，1 最亮</td><td>屏幕亮度值。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { setScreenBrightness } from '@doubao-dev/framework/api';
+
+await setScreenBrightness({ value: 0.8 });
+```
+
+## 成功返回
+
+无返回字段。
+
+### 返回示例
+
+```json
+{}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./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>
+<tr><td><code>103</code></td><td><code>feature not support</code></td><td>当前环境不支持该能力</td><td>Android、iOS</td></tr>
+<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>参数不合法</td><td>Android、iOS</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- **Android**：使用当前宿主窗口亮度，不修改系统全局亮度
+- **iOS**：应用插件进入后台时恢复系统亮度，回到前台时重新应用设置值
+
+<a id="setkeepscreenon"></a>
+### setKeepScreenOn()
+
+# setKeepScreenOn
+
+设置屏幕常亮状态。
+
+## 扫码预览
+![扫码预览 setKeepScreenOn](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fdevice%252Fset-keep-screen-on%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.0.25`。
+
+## 支持平台
+
+<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>
+
+## 使用说明
+
+- 不再需要常亮时应主动将 keepScreenOn 设为 false，避免额外功耗
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+setKeepScreenOn(params: SetKeepScreenOnParams): Promise<object>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>keepScreenOn</code></td><td><code>boolean</code></td><td>是</td><td>-</td><td>-</td><td>是否保持屏幕常亮。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { setKeepScreenOn } from '@doubao-dev/framework/api';
+
+await setKeepScreenOn({ keepScreenOn: true });
+```
+
+## 成功返回
+
+无返回字段。
+
+### 返回示例
+
+```json
+{}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./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>
+
+## 平台差异
+
+- **iOS**：页面销毁后常亮状态会自动恢复
+- **iOS**：设置常亮恒返回成功，无失败错误码
+
+<a id="disableuserscreenrecord"></a>
+### disableUserScreenRecord()
+
+# disableUserScreenRecord
+
+禁止用户录屏。
+
+## 支持版本
+
+前端库版本不低于 `0.0.37`。
+
+## 支持平台
+
+<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>
+
+## 使用说明
+
+- 需要恢复录屏能力时调用 `enableUserScreenRecord`
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+disableUserScreenRecord(params?: object): Promise<object>
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```typescript
+import { disableUserScreenRecord } from '@doubao-dev/framework/api';
+
+await disableUserScreenRecord();
+```
+
+## 成功返回
+
+无返回字段。
+
+### 返回示例
+
+```json
+{}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./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>
+
+## 平台差异
+
+- **Android**：对整个窗口生效，会同时影响截屏
+- **iOS**：仅对内容视图生效
+
+<a id="enableuserscreenrecord"></a>
+### enableUserScreenRecord()
+
+# enableUserScreenRecord
+
+允许用户录屏。
+
+## 支持版本
+
+前端库版本不低于 `0.0.37`。
+
+## 支持平台
+
+<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>
+
+## 使用说明
+
+- 与 `disableUserScreenRecord` 配对使用
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+enableUserScreenRecord(params?: object): Promise<object>
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```typescript
+import { enableUserScreenRecord } from '@doubao-dev/framework/api';
+
+await enableUserScreenRecord();
+```
+
+## 成功返回
+
+无返回字段。
+
+### 返回示例
+
+```json
+{}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./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="onusercapturescreen"></a>
+### onUserCaptureScreen()
+
+# onUserCaptureScreen
+
+监听用户主动截屏事件。
+
+## 扫码预览
+![扫码预览 onUserCaptureScreen](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fdevice%252Fon-user-capture-screen%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>
+
+## 使用说明
+
+- 事件不携带截图内容，仅通知发生了截屏
+
+## 调用方式
+
+### 事件监听 API
+
+```typescript
+onUserCaptureScreen(callback: (event: UserCaptureScreenEvent) => void): () => void
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```ts
+import { onUserCaptureScreen } from '@doubao-dev/framework/api';
+
+const off = onUserCaptureScreen(() => {
+  console.log('用户截屏了');
+});
+
+off();
+```
+
+## 回调参数
+
+无。
+
+## 返回值
+
+无返回字段。
+
+### 回调示例
+
+```json
+{}
+```
+
+<a id="onuserscreenrecord"></a>
+### onUserScreenRecord()
+
+# onUserScreenRecord
+
+监听用户录屏事件。
+
+## 扫码预览
+![扫码预览 onUserScreenRecord](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fdevice%252Fon-user-screen-record%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.0.37`。
+
+## 支持平台
+
+<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>
+
+## 使用说明
+
+- iOS 订阅成功后会立即回报一次当前录屏状态
+
+## 调用方式
+
+### 事件监听 API
+
+```typescript
+onUserScreenRecord(callback: (event: UserScreenRecordEvent) => void): () => void
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```ts
+import { onUserScreenRecord } from '@doubao-dev/framework/api';
+
+const off = onUserScreenRecord(({ state }) => {
+  console.log(state);
+});
+
+off();
+```
+
+## 回调参数
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>event.state</code></td><td><code>UserScreenRecordState</code></td><td>是</td><td>录屏状态，start 表示开始录屏，stop 表示停止录屏。</td></tr>
+</tbody>
+</table>
+
+## 返回值
+
+返回取消当前监听函数的函数。
+
+### 回调示例
+
+```json
+{
+  "state": "start"
+}
+```
+
+## 平台差异
+
+- **Android**：仅 Android 15 及以上上报录屏事件，低版本不生效
+
+## 相关类型
+
+<a id="getscreenbrightnessresult"></a>
+### GetScreenBrightnessResult
+
+#### Properties
+
+• **value**: `number` - 屏幕亮度值
+
+<a id="setscreenbrightnessparams"></a>
+### SetScreenBrightnessParams
+
+设置屏幕亮度的请求参数。
+
+#### Properties
+
+• **value**: `number` - 屏幕亮度值
+
+<a id="setkeepscreenonparams"></a>
+### SetKeepScreenOnParams
+
+设置屏幕常亮的请求参数。
+
+#### Properties
+
+• **keepScreenOn**: `boolean` - 是否保持屏幕常亮
+
+<a id="usercapturescreenevent"></a>
+### UserCaptureScreenEvent
+
+用户主动截屏事件。
+
+#### Properties
+
+无字段。
+
+<a id="userscreenrecordstate"></a>
+### UserScreenRecordState
+
+用户录屏状态。
+
+#### Type
+
+`'start' | 'stop'`
+
+<a id="userscreenrecordevent"></a>
+### UserScreenRecordEvent
+
+用户录屏事件。
+
+#### Properties
+
+• **state**: `UserScreenRecordState` - 录屏状态，start 表示开始录屏，stop 表示停止录屏