@doubao-apps/ai 0.0.33 → 0.0.34

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

@@ -0,0 +1,257 @@
+# Open API: 系统
+
+宿主基础信息、窗口信息和系统设置。
+
+[返回目录](./README.md) | [返回速查](../open-api.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [getWindowInfoSync](#getwindowinfosync) | 获取窗口信息。<br><br>同步 API。 |
+| [getSystemSetting](#getsystemsetting) | 获取设备设置。 |
+| [getAppBaseInfoSync](#getappbaseinfosync) | 获取应用基础信息。<br><br>同步 API。 |
+| [getWindowInfo](#getwindowinfo) | 获取窗口信息。 |
+| [getAppBaseInfo](#getappbaseinfo) | 获取应用基础信息。 |
+| [ThemeChangeListener](#themechangelistener) | 应用主题变化事件监听函数。<br><br>返回 void，不是 Promise。 |
+| [onThemeChange](#onthemechange) | 监听应用主题变化。 |
+
+## 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="themechangelistener"></a>
+### ThemeChangeListener()
+
+应用主题变化事件监听函数。
+
+## 代码示例
+
+```typescript
+// 暂无代码示例
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|theme|`AppTheme`|是|切换后的应用主题|
+
+**类型说明**
+
+- `AppTheme`: `"light" | "dark"`
+
+## 返回值
+
+返回 `void`。
+
+<a id="onthemechange"></a>
+### onThemeChange()
+
+监听应用主题变化。
+
+当用户在系统设置或宿主内切换浅色、深色主题时触发。回调参数中的 `theme` 表示切换后的主题，可与
+getAppBaseInfo 返回的 `theme` 字段配合使用。
+
+## 代码示例
+
+```typescript
+import { onThemeChange } from '@doubao-apps/framework/api';
+
+const offThemeChange = onThemeChange(({ theme }) => {
+  console.log('当前主题:', theme);
+});
+
+offThemeChange();
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回取消当前监听函数的函数。

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

@@ -0,0 +1,326 @@
+# Open API: 定位
+
+获取设备当前的地理位置信息。
+
+[返回目录](./README.md) | [返回速查](../open-api.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [LocationChangeListener](#locationchangelistener) | LocationChangeListener API。<br><br>返回 void，不是 Promise。 |
+| [LocationChangeErrorListener](#locationchangeerrorlistener) | LocationChangeErrorListener API。<br><br>返回 void，不是 Promise。 |
+| [getLocation](#getlocation) | 获取设备当前的地理位置信息。 |
+| [chooseLocation](#chooselocation) | 打开地图选择位置。 |
+| [openLocation](#openlocation) | 使用地图查看位置。 |
+| [startLocationUpdate](#startlocationupdate) | 开始接收位置更新。 |
+| [stopLocationUpdate](#stoplocationupdate) | 停止接收位置更新。 |
+| [onLocationChange](#onlocationchange) | 注册地理位置变化回调。<br><br>返回 void，不是 Promise。 |
+| [offLocationChange](#offlocationchange) | 取消注册地理位置变化回调。<br><br>返回 void，不是 Promise。 |
+| [onLocationChangeError](#onlocationchangeerror) | 注册位置更新异常回调。<br><br>返回 void，不是 Promise。 |
+| [offLocationChangeError](#offlocationchangeerror) | 取消注册位置更新异常回调。<br><br>返回 void，不是 Promise。 |
+
+## 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()
+
+获取设备当前的地理位置信息。
+
+## 代码示例
+
+```typescript
+import { getLocation } from '@doubao-apps/framework/api';
+
+async function fetchLocation() {
+  try {
+    const locationData = await getLocation();
+    console.log('纬度:', locationData.latitude);
+    console.log('经度:', locationData.longitude);
+    console.log('时间戳:', locationData.timestamp);
+    console.log('行进速度:', locationData.speed);
+    console.log('定位精度:', locationData.accuracy);
+  } catch (error) {
+    console.error('获取位置失败:', error);
+    // 处理错误，例如提示用户开启定位权限
+  }
+}
+
+fetchLocation();
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|maxCacheMs|`number`|否|缓存时间，单位毫秒，默认为0|
+|mode|`number`|否|定位模式<br>0：低功耗<br>1：仅设备<br>2：高精度（默认）|
+|source|`string`|否|调用业务方|
+|timeoutMs|`number`|否|超时时间，单位毫秒，默认 30000|
+
+## 返回值
+
+返回一个 Promise，成功时解析为包含地理位置信息的对象，包含：
+  - `latitude`: number - 纬度。
+  - `longitude`: number - 经度。
+  - `timestamp`: string - 时间戳。
+  - `speed`: number - 行进速度，单位：米/秒。
+  - `accuracy`: number - 定位精度，单位：米。
+  参考 GetLocationResponse。
+
+|字段名|类型|说明|
+|---|---|---|
+|accuracy|`number`|定位精度，单位：米|
+|latitude|`number`|纬度|
+|longitude|`number`|经度|
+|speed|`number`|行进速度，单位：米/秒|
+|timestamp|`string`|时间戳|
+
+<a id="chooselocation"></a>
+### chooseLocation()
+
+打开地图选择位置。
+
+## 代码示例
+
+```typescript
+import { chooseLocation } from '@doubao-apps/framework/api';
+
+const { name, latitude, longitude } = await chooseLocation();
+
+console.log(name, latitude, longitude);
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|latitude|`number`|否|目标地纬度|
+|longitude|`number`|否|目标地经度|
+
+## 返回值
+
+返回 `Promise<ChooseLocationResponse>`。
+
+|字段名|类型|说明|
+|---|---|---|
+|address|`string`|地址详情|
+|latitude|`number`|纬度，GCJ-02 坐标系|
+|longitude|`number`|经度，GCJ-02 坐标系|
+|name|`string`|位置名称|
+
+<a id="openlocation"></a>
+### openLocation()
+
+使用地图查看位置。
+
+## 代码示例
+
+```typescript
+import { openLocation } from '@doubao-apps/framework/api';
+
+await openLocation({
+  latitude: 39.908823,
+  longitude: 116.39747,
+  name: '目的地',
+  scale: 15
+});
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|address|`string`|否|地址详情|
+|latitude|`number`|是|纬度|
+|longitude|`number`|是|经度|
+|name|`string`|否|位置名称|
+|scale|`number`|否|缩放比例，范围 5 ~ 18|
+
+## 返回值
+
+返回 `Promise<object>`。
+
+<a id="startlocationupdate"></a>
+### startLocationUpdate()
+
+开始接收位置更新。
+
+## 代码示例
+
+```typescript
+import { startLocationUpdate } from '@doubao-apps/framework/api';
+
+await startLocationUpdate({ type: 'gcj02' });
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|type|`"wgs84" \| "gcj02"`|否|坐标系类型，支持 wgs84 或 gcj02|
+
+## 返回值
+
+返回 `Promise<object>`。
+
+<a id="stoplocationupdate"></a>
+### stopLocationUpdate()
+
+停止接收位置更新。
+
+## 代码示例
+
+```typescript
+import { stopLocationUpdate } from '@doubao-apps/framework/api';
+
+await stopLocationUpdate();
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回 `Promise<object>`。
+
+<a id="onlocationchange"></a>
+### onLocationChange()
+
+注册地理位置变化回调。
+
+## 代码示例
+
+```typescript
+import { onLocationChange } from '@doubao-apps/framework/api';
+
+onLocationChange(({ latitude, longitude }) => {
+  console.log(latitude, longitude);
+});
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回 `void`。
+
+<a id="offlocationchange"></a>
+### offLocationChange()
+
+取消注册地理位置变化回调。
+
+## 代码示例
+
+```typescript
+import { offLocationChange } from '@doubao-apps/framework/api';
+
+offLocationChange();
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回 `void`。
+
+<a id="onlocationchangeerror"></a>
+### onLocationChangeError()
+
+注册位置更新异常回调。
+
+## 代码示例
+
+```typescript
+import { onLocationChangeError } from '@doubao-apps/framework/api';
+
+onLocationChangeError(({ errMsg, errCode }) => {
+  console.log(errMsg, errCode);
+});
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回 `void`。
+
+<a id="offlocationchangeerror"></a>
+### offLocationChangeError()
+
+取消注册位置更新异常回调。
+
+## 代码示例
+
+```typescript
+import { offLocationChangeError } from '@doubao-apps/framework/api';
+
+offLocationChangeError();
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回 `void`。