@doubao-apps/ai 0.0.34 → 0.0.35

package/dist/public/skills/doubao-apps-dev/references/reference/open-api/02-/347/263/273/347/273/237.md

@@ -0,0 +1,438 @@
+# Open API: 系统
+
+宿主基础信息、窗口信息和系统设置。
+
+[返回目录](./README.md) | [返回速查](../open-api.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [getWindowInfoSync](#getwindowinfosync) | 获取窗口信息。<br><br>同步 API。 |
+| [getSystemSetting](#getsystemsetting) | 获取设备设置。 |
+| [getAppBaseInfoSync](#getappbaseinfosync) | 获取应用基础信息。<br><br>同步 API。 |
+| [getWindowInfo](#getwindowinfo) | 获取窗口信息。 |
+| [getAppBaseInfo](#getappbaseinfo) | 获取应用基础信息。 |
+| [onThemeChange](#onthemechange) | 监听应用主题变化。 |
+| [getSystemInfo](#getsysteminfo) | 获取系统信息。 |
+| [getSystemInfoSync](#getsysteminfosync) | 同步获取系统信息。<br><br>同步 API。 |
+
+## API 详情
+
+<a id="getwindowinfosync"></a>
+### getWindowInfoSync()
+
+获取窗口信息。
+
+## 代码示例
+
+```typescript
+import { getWindowInfoSync } from '@doubao-apps/framework/api';
+
+const result = getWindowInfoSync();
+
+console.log(result.windowWidth, result.windowHeight);
+console.log(result.safeArea?.top, result.screenTop);
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回窗口尺寸、状态栏高度和安全区域等信息，字段见 GetWindowInfoResult。
+
+|字段名|类型|说明|
+|---|---|---|
+|pixelRatio|`number`|设备像素比|
+|safeArea|`WindowSafeArea`|安全区域|
+|safeArea.bottom|`number`|安全区域右下角纵坐标|
+|safeArea.height|`number`|安全区域高度|
+|safeArea.left|`number`|安全区域左上角横坐标|
+|safeArea.right|`number`|安全区域右下角横坐标|
+|safeArea.top|`number`|安全区域左上角纵坐标|
+|safeArea.width|`number`|安全区域宽度|
+|screenHeight|`number`|屏幕高度|
+|screenTop|`number`|窗口上边缘的 y 值|
+|screenWidth|`number`|屏幕宽度|
+|statusBarHeight|`number`|状态栏高度|
+|windowHeight|`number`|可使用窗口高度|
+|windowWidth|`number`|可使用窗口宽度|
+
+<a id="getsystemsetting"></a>
+### getSystemSetting()
+
+获取设备设置。
+
+## 代码示例
+
+```typescript
+import { getSystemSetting } from '@doubao-apps/framework/api';
+
+const result = getSystemSetting();
+
+console.log(result.bluetoothEnabled, result.locationEnabled);
+console.log(result.wifiEnabled, result.deviceOrientation);
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回蓝牙、定位、Wi-Fi 系统开关和设备方向等字段，见 GetSystemSettingResult。
+
+|字段名|类型|说明|
+|---|---|---|
+|bluetoothEnabled|`boolean`|蓝牙的系统开关|
+|deviceOrientation|`DeviceOrientation`|设备方向|
+|locationEnabled|`boolean`|地理位置的系统开关|
+|wifiEnabled|`boolean`|Wi-Fi 的系统开关|
+
+**类型说明**
+
+- `DeviceOrientation`: `"portrait" | "landscape"`
+
+<a id="getappbaseinfosync"></a>
+### getAppBaseInfoSync()
+
+获取应用基础信息。
+
+## 代码示例
+
+```typescript
+import { getAppBaseInfoSync } from '@doubao-apps/framework/api';
+
+const result = getAppBaseInfoSync();
+
+console.log(result.language, result.SDKVersion, result.theme);
+console.log(result.host?.appId, result.enableDebug);
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回 SDK 版本、调试开关、宿主信息、语言和主题等字段，见 GetAppBaseInfoResult。
+
+|字段名|类型|说明|
+|---|---|---|
+|enableDebug|`boolean`|是否已打开调试|
+|host|`AppBaseInfoHost`|当前豆包 App运行的宿主环境|
+|host.appId|`string`|宿主 app 对应的 appId|
+|language|`string`|当前语言|
+|SDKVersion|`string`|客户端基础库版本|
+|theme|`"light" | "dark"`|当前主题|
+|version|`string`|宿主版本号|
+
+<a id="getwindowinfo"></a>
+### getWindowInfo()
+
+获取窗口信息。
+
+## 代码示例
+
+```typescript
+import { getWindowInfo } from '@doubao-apps/framework/api';
+
+const result = await getWindowInfo();
+
+console.log(result.windowWidth, result.windowHeight);
+console.log(result.safeArea?.top, result.screenTop);
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回窗口尺寸、状态栏高度和安全区域等信息，字段见 GetWindowInfoResult。
+
+|字段名|类型|说明|
+|---|---|---|
+|pixelRatio|`number`|设备像素比|
+|safeArea|`WindowSafeArea`|安全区域|
+|safeArea.bottom|`number`|安全区域右下角纵坐标|
+|safeArea.height|`number`|安全区域高度|
+|safeArea.left|`number`|安全区域左上角横坐标|
+|safeArea.right|`number`|安全区域右下角横坐标|
+|safeArea.top|`number`|安全区域左上角纵坐标|
+|safeArea.width|`number`|安全区域宽度|
+|screenHeight|`number`|屏幕高度|
+|screenTop|`number`|窗口上边缘的 y 值|
+|screenWidth|`number`|屏幕宽度|
+|statusBarHeight|`number`|状态栏高度|
+|windowHeight|`number`|可使用窗口高度|
+|windowWidth|`number`|可使用窗口宽度|
+
+<a id="getappbaseinfo"></a>
+### getAppBaseInfo()
+
+获取应用基础信息。
+
+## 代码示例
+
+```typescript
+import { getAppBaseInfo } from '@doubao-apps/framework/api';
+
+const result = await getAppBaseInfo();
+
+console.log(result.language, result.SDKVersion, result.theme);
+console.log(result.host?.appId, result.enableDebug);
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回 SDK 版本、调试开关、宿主信息、语言和主题等字段，见 GetAppBaseInfoResult。
+
+|字段名|类型|说明|
+|---|---|---|
+|enableDebug|`boolean`|是否已打开调试|
+|host|`AppBaseInfoHost`|当前豆包 App运行的宿主环境|
+|host.appId|`string`|宿主 app 对应的 appId|
+|language|`string`|当前语言|
+|SDKVersion|`string`|客户端基础库版本|
+|theme|`"light" | "dark"`|当前主题|
+|version|`string`|宿主版本号|
+
+<a id="onthemechange"></a>
+### onThemeChange()
+
+监听应用主题变化。
+
+当用户在系统设置或宿主内切换浅色、深色主题时触发。回调参数中的 `theme` 表示切换后的主题，可与
+getAppBaseInfo 返回的 `theme` 字段配合使用。
+
+## 代码示例
+
+```typescript
+import { onThemeChange } from '@doubao-apps/framework/api';
+
+const offThemeChange = onThemeChange(({ theme }) => {
+  console.log('当前主题:', theme);
+});
+
+offThemeChange();
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回取消当前监听函数的函数。
+
+<a id="getsysteminfo"></a>
+### getSystemInfo()
+
+获取系统信息。
+
+## 代码示例
+
+```typescript
+import { getSystemInfo } from '@doubao-apps/framework/api';
+
+const result = await getSystemInfo();
+
+console.log(result.brand, result.model, result.system);
+console.log(result.screenWidth, result.screenHeight);
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回设备品牌、型号、屏幕尺寸、宿主信息和安全区域等字段，见 GetSystemInfoResult。
+
+|字段名|类型|说明|
+|---|---|---|
+|abi|`string`|宿主 App 二进制接口类型（如 arm64-v8a），仅 Android 返回|
+|benchmarkLevel|`number`|设备性能等级，-1 表示未知|
+|brand|`string`|设备品牌|
+|deviceOrientation|`"portrait" | "landscape"`|设备方向|
+|enableDebug|`boolean`|是否已打开调试|
+|language|`string`|系统语言，格式为 language_region，如 zh_CN、en_US|
+|model|`string`|设备型号|
+|pixelRatio|`number`|设备像素比，物理像素 = 逻辑像素 × pixelRatio|
+|platform|`string`|客户端平台，取值为 "ios" 或 "android"|
+|safeArea|`SystemInfoSafeArea`|在竖屏正方向下的安全区域，单位为逻辑像素|
+|safeArea.bottom|`number`|安全区域右下角纵坐标|
+|safeArea.height|`number`|安全区域高度|
+|safeArea.left|`number`|安全区域左上角横坐标|
+|safeArea.right|`number`|安全区域右下角横坐标|
+|safeArea.top|`number`|安全区域左上角纵坐标|
+|safeArea.width|`number`|安全区域宽度|
+|screenHeight|`number`|屏幕高度，单位为逻辑像素|
+|screenWidth|`number`|屏幕宽度，单位为逻辑像素|
+|SDKVersion|`string`|客户端基础库版本|
+|statusBarHeight|`number`|状态栏高度，单位为逻辑像素|
+|system|`string`|操作系统及版本，如 "Android 14"、"iOS 17.5"|
+|theme|`"light" | "dark"`|系统当前主题|
+|version|`string`|宿主版本号|
+|windowHeight|`number`|可使用窗口高度，单位为逻辑像素|
+|windowWidth|`number`|可使用窗口宽度，单位为逻辑像素|
+
+<a id="getsysteminfosync"></a>
+### getSystemInfoSync()
+
+同步获取系统信息。
+
+## 代码示例
+
+```typescript
+import { getSystemInfoSync } from '@doubao-apps/framework/api';
+
+const result = getSystemInfoSync();
+
+console.log(result.brand, result.model, result.system);
+console.log(result.screenWidth, result.screenHeight);
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回设备品牌、型号、屏幕尺寸、宿主信息和安全区域等字段，见 GetSystemInfoResult。
+
+|字段名|类型|说明|
+|---|---|---|
+|abi|`string`|宿主 App 二进制接口类型（如 arm64-v8a），仅 Android 返回|
+|benchmarkLevel|`number`|设备性能等级，-1 表示未知|
+|brand|`string`|设备品牌|
+|deviceOrientation|`"portrait" | "landscape"`|设备方向|
+|enableDebug|`boolean`|是否已打开调试|
+|language|`string`|系统语言，格式为 language_region，如 zh_CN、en_US|
+|model|`string`|设备型号|
+|pixelRatio|`number`|设备像素比，物理像素 = 逻辑像素 × pixelRatio|
+|platform|`string`|客户端平台，取值为 "ios" 或 "android"|
+|safeArea|`SystemInfoSafeArea`|在竖屏正方向下的安全区域，单位为逻辑像素|
+|safeArea.bottom|`number`|安全区域右下角纵坐标|
+|safeArea.height|`number`|安全区域高度|
+|safeArea.left|`number`|安全区域左上角横坐标|
+|safeArea.right|`number`|安全区域右下角横坐标|
+|safeArea.top|`number`|安全区域左上角纵坐标|
+|safeArea.width|`number`|安全区域宽度|
+|screenHeight|`number`|屏幕高度，单位为逻辑像素|
+|screenWidth|`number`|屏幕宽度，单位为逻辑像素|
+|SDKVersion|`string`|客户端基础库版本|
+|statusBarHeight|`number`|状态栏高度，单位为逻辑像素|
+|system|`string`|操作系统及版本，如 "Android 14"、"iOS 17.5"|
+|theme|`"light" | "dark"`|系统当前主题|
+|version|`string`|宿主版本号|
+|windowHeight|`number`|可使用窗口高度，单位为逻辑像素|
+|windowWidth|`number`|可使用窗口宽度，单位为逻辑像素|
+
+## 相关类型
+
+<a id="windowsafearea"></a>
+### WindowSafeArea
+
+#### Properties
+
+• **left**: `number` - 安全区域左上角横坐标
+• **right**: `number` - 安全区域右下角横坐标
+• **top**: `number` - 安全区域左上角纵坐标
+• **bottom**: `number` - 安全区域右下角纵坐标
+• **width**: `number` - 安全区域宽度
+• **height**: `number` - 安全区域高度
+
+<a id="getwindowinforesult"></a>
+### GetWindowInfoResult
+
+#### Properties
+
+• **pixelRatio**: `number` - 设备像素比
+• **screenWidth**: `number` - 屏幕宽度
+• **screenHeight**: `number` - 屏幕高度
+• **windowWidth**: `number` - 可使用窗口宽度
+• **windowHeight**: `number` - 可使用窗口高度
+• **statusBarHeight**: `number` - 状态栏高度
+• **safeArea?**: `WindowSafeArea` - 安全区域
+• **screenTop**: `number` - 窗口上边缘的 y 值
+
+<a id="deviceorientation"></a>
+### DeviceOrientation
+
+#### Type
+
+`'portrait' | 'landscape'`
+
+<a id="getsystemsettingresult"></a>
+### GetSystemSettingResult
+
+#### Properties
+
+• **bluetoothEnabled**: `boolean` - 蓝牙的系统开关
+• **locationEnabled**: `boolean` - 地理位置的系统开关
+• **wifiEnabled**: `boolean` - Wi-Fi 的系统开关
+• **deviceOrientation**: `DeviceOrientation` - 设备方向
+
+<a id="appbaseinfohost"></a>
+### AppBaseInfoHost
+
+#### Properties
+
+• **appId**: `string` - 宿主 app 对应的 appId
+
+<a id="getappbaseinforesult"></a>
+### GetAppBaseInfoResult
+
+#### Properties
+
+• **SDKVersion?**: `string` - 客户端基础库版本
+• **enableDebug?**: `boolean` - 是否已打开调试
+• **host?**: `AppBaseInfoHost` - 当前豆包 App运行的宿主环境
+• **language**: `string` - 当前语言
+• **version?**: `string` - 宿主版本号
+• **theme?**: `'light' | 'dark'` - 当前主题
+
+<a id="systeminfosafearea"></a>
+### SystemInfoSafeArea
+
+#### Properties
+
+• **left**: `number` - 安全区域左上角横坐标
+• **right**: `number` - 安全区域右下角横坐标
+• **top**: `number` - 安全区域左上角纵坐标
+• **bottom**: `number` - 安全区域右下角纵坐标
+• **width**: `number` - 安全区域宽度
+• **height**: `number` - 安全区域高度
+
+<a id="getsysteminforesult"></a>
+### GetSystemInfoResult
+
+#### Properties
+
+• **brand**: `string` - 设备品牌
+• **model**: `string` - 设备型号
+• **pixelRatio**: `number` - 设备像素比，物理像素 = 逻辑像素 × pixelRatio
+• **screenWidth**: `number` - 屏幕宽度，单位为逻辑像素
+• **screenHeight**: `number` - 屏幕高度，单位为逻辑像素
+• **windowWidth**: `number` - 可使用窗口宽度，单位为逻辑像素
+• **windowHeight**: `number` - 可使用窗口高度，单位为逻辑像素
+• **statusBarHeight**: `number` - 状态栏高度，单位为逻辑像素
+• **language**: `string` - 系统语言，格式为 language_region，如 zh_CN、en_US
+• **version?**: `string` - 宿主版本号
+• **system**: `string` - 操作系统及版本，如 "Android 14"、"iOS 17.5"
+• **platform**: `string` - 客户端平台，取值为 "ios" 或 "android"
+• **SDKVersion?**: `string` - 客户端基础库版本
+• **theme?**: `'light' | 'dark'` - 系统当前主题
+• **benchmarkLevel?**: `number` - 设备性能等级，-1 表示未知
+• **safeArea?**: `SystemInfoSafeArea` - 在竖屏正方向下的安全区域，单位为逻辑像素
+• **enableDebug?**: `boolean` - 是否已打开调试
+• **deviceOrientation?**: `'portrait' | 'landscape'` - 设备方向
+• **abi?**: `string` - 宿主 App 二进制接口类型（如 arm64-v8a），仅 Android 返回

package/dist/{skills → public/skills}/doubao-apps-dev/references/reference/open-api/03-/345/256/232/344/275/215.md

@@ -8,8 +8,6 @@
 
 | API | 说明 |
 | --- | --- |
-| [LocationChangeListener](#locationchangelistener) | LocationChangeListener API。<br><br>返回 void，不是 Promise。 |
-| [LocationChangeErrorListener](#locationchangeerrorlistener) | LocationChangeErrorListener API。<br><br>返回 void，不是 Promise。 |
 | [getLocation](#getlocation) | 获取设备当前的地理位置信息。 |
 | [chooseLocation](#chooselocation) | 打开地图选择位置。 |
 | [openLocation](#openlocation) | 使用地图查看位置。 |
@@ -22,58 +20,6 @@
 
 ## API 详情
 
-<a id="locationchangelistener"></a>
-### LocationChangeListener()
-
-LocationChangeListener API。
-
-## 代码示例
-
-```typescript
-// 暂无代码示例
-```
-
-## 入参
-
-|参数名|类型|必填|说明|
-|---|---|---|---|
-|accuracy|`number`|否|位置精确度，单位 m|
-|altitude|`number`|否|高度，单位 m|
-|city|`string`|否|城市信息|
-|district|`string`|否|区县信息|
-|horizontalAccuracy|`number`|否|水平精度，单位 m|
-|latitude|`number`|是|纬度|
-|longitude|`number`|是|经度|
-|province|`string`|否|省份信息|
-|speed|`number`|否|速度，单位 m/s|
-|verticalAccuracy|`number`|否|垂直精度，单位 m|
-
-## 返回值
-
-返回 `void`。
-
-<a id="locationchangeerrorlistener"></a>
-### LocationChangeErrorListener()
-
-LocationChangeErrorListener API。
-
-## 代码示例
-
-```typescript
-// 暂无代码示例
-```
-
-## 入参
-
-|参数名|类型|必填|说明|
-|---|---|---|---|
-|errCode|`number`|否|错误码|
-|errMsg|`string`|是|错误信息|
-
-## 返回值
-
-返回 `void`。
-
 <a id="getlocation"></a>
 ### getLocation()
 
@@ -101,6 +47,10 @@ async function fetchLocation() {
 fetchLocation();
 ```
 
+## 注意事项
+
+可能涉及定位授权。
+
 ## 入参
 
 |参数名|类型|必填|说明|
@@ -206,11 +156,15 @@ import { startLocationUpdate } from '@doubao-apps/framework/api';
 await startLocationUpdate({ type: 'gcj02' });
 ```
 
+## 注意事项
+
+需配对调用 stopLocationUpdate。
+
 ## 入参
 
 |参数名|类型|必填|说明|
 |---|---|---|---|
-|type|`"wgs84" \| "gcj02"`|否|坐标系类型，支持 wgs84 或 gcj02|
+|type|`"wgs84" | "gcj02"`|否|坐标系类型，支持 wgs84 或 gcj02|
 
 ## 返回值
 
@@ -324,3 +278,26 @@ offLocationChangeError();
 ## 返回值
 
 返回 `void`。
+
+## 相关类型
+
+<a id="getlocationresponse"></a>
+### GetLocationResponse
+
+#### Properties
+
+• **latitude**: `number` - 纬度
+• **longitude**: `number` - 经度
+• **timestamp**: `string` - 时间戳
+• **speed**: `number` - 行进速度，单位：米/秒
+• **accuracy**: `number` - 定位精度，单位：米
+
+<a id="chooselocationresponse"></a>
+### ChooseLocationResponse
+
+#### Properties
+
+• **latitude**: `number` - 纬度，GCJ-02 坐标系
+• **longitude**: `number` - 经度，GCJ-02 坐标系
+• **name?**: `string` - 位置名称
+• **address?**: `string` - 地址详情

package/dist/{skills → public/skills}/doubao-apps-dev/references/reference/open-api/04-/345/255/230/345/202/250.md

@@ -282,3 +282,21 @@ console.log(result.keys, result.currentSize, result.limitSize);
 |currentSize|`number`|当前占用的空间大小，单位 KB|
 |keys|`string[]`|当前 storage 中所有的 key|
 |limitSize|`number`|限制的空间大小，单位 KB|
+
+## 相关类型
+
+<a id="getstorageresult"></a>
+### GetStorageResult
+
+#### Properties
+
+• **data**: `TData` - key 对应的数据
+
+<a id="getstorageinforesult"></a>
+### GetStorageInfoResult
+
+#### Properties
+
+• **keys**: `string[]` - 当前 storage 中所有的 key
+• **currentSize**: `number` - 当前占用的空间大小，单位 KB
+• **limitSize**: `number` - 限制的空间大小，单位 KB

package/dist/{skills → public/skills}/doubao-apps-dev/references/reference/open-api/05-/350/267/257/347/224/261.md

@@ -122,6 +122,10 @@ import { exitApp } from '@doubao-apps/framework/api';
 await exitApp();
 ```
 
+## 注意事项
+
+会退出当前所有页面。
+
 ## 入参
 
 无入参。
@@ -135,6 +139,10 @@ await exitApp();
 
 关闭栈顶页面。
 
+::: warning
+已废弃：使用 navigateBack
+:::
+
 ## 代码示例
 
 ```typescript

package/dist/{skills → public/skills}/doubao-apps-dev/references/reference/open-api/06-/344/272/244/344/272/222.md

@@ -59,7 +59,7 @@ if (result.action === 'confirm') {
 
 |字段名|类型|说明|
 |---|---|---|
-|action|`"confirm" \| "cancel" \| "mask"`|用户点击的动作。|
+|action|`"confirm" | "cancel" | "mask"`|用户点击的动作。|
 
 <a id="showloading"></a>
 ### showLoading()
@@ -75,6 +75,10 @@ await showLoading();
 await hideLoading();
 ```
 
+## 注意事项
+
+需调用 hideLoading 关闭。
+
 ## 入参
 
 无入参。
@@ -207,6 +211,10 @@ import { enableAlertBeforeUnload } from '@doubao-apps/framework/api';
 await enableAlertBeforeUnload({ message: '确定离开当前页面吗？' });
 ```
 
+## 注意事项
+
+配合 disableAlertBeforeUnload 使用。
+
 ## 入参
 
 |参数名|类型|必填|说明|
@@ -275,16 +283,54 @@ showToast({
 });
 ```
 
+## 注意事项
+
+duration 和 icon 可控制提示表现。
+
 ## 入参
 
 |参数名|类型|必填|说明|
 |---|---|---|---|
 |customIcon|`string`|否|-|
 |duration|`number`|否|-|
-|icon|`"success" \| "error" \| "warn"`|否|-|
+|icon|`"success" | "error" | "warn"`|否|-|
 |message|`string`|是|-|
-|type|`"default" \| "success" \| "error" \| "warning"`|否|-|
+|type|`"default" | "success" | "error" | "warning"`|否|-|
 
 ## 返回值
 
 返回一个 Promise，在 Toast 显示结束时 resolve。
+
+## 相关类型
+
+<a id="showmodalresult"></a>
+### ShowModalResult
+
+显示模态对话框的返回结果。
+
+#### Properties
+
+• **action**: `'confirm' | 'cancel' | 'mask'` - 用户点击的动作
+
+<a id="showactionsheetresult"></a>
+### ShowActionSheetResult
+
+显示操作菜单的返回结果。
+
+#### Properties
+
+• **tapIndex**: `number` - 用户点击的按钮序号，从 0 开始
+
+<a id="menubuttonboundingclientrect"></a>
+### MenuButtonBoundingClientRect
+
+菜单按钮的布局位置信息。
+
+#### Properties
+
+• **width**: `number` - 宽度，单位 px
+• **height**: `number` - 高度，单位 px
+• **top**: `number` - 上边界坐标，单位 px
+• **right**: `number` - 右边界坐标，单位 px
+• **bottom**: `number` - 下边界坐标，单位 px
+• **left**: `number` - 左边界坐标，单位 px