@doubao-apps/create 0.0.25 → 0.0.26

package/dist/template-empty/.ai/reference/open-api/01-/345/237/272/347/241/200-/350/264/246/345/217/267-/347/263/273/347/273/237.md

@@ -0,0 +1,699 @@
+# Open API: 基础 / 账号 / 系统
+
+账号、授权、宿主基础信息、窗口信息和定位。
+
+[返回目录](./README.md) | [返回速查](../open-api.md)
+
+## 速查
+
+| API | 签名 | 用途 | 参数类型 | 结果类型 | 注意点 |
+| --- | --- | --- | --- | --- | --- |
+| [`getAccountInfo`](#getaccountinfo) | `getAccountInfo(params?): Promise<GetAccountInfoResult>` | 异步获取账号信息 | `params?` | `Promise<GetAccountInfoResult>` | - |
+| [`getAccountInfoSync`](#getaccountinfosync) | `getAccountInfoSync(params?): GetAccountInfoResult` | 同步获取账号信息 | `params?` | `GetAccountInfoResult` | 同步 API |
+| [`authorize`](#authorize) | `authorize(params): Promise<object>` | 初始化授权 | `params: AuthorizeRequest` | `Promise<object>` | 按 scope 申请授权 |
+| [`canIUse`](#caniuse) | `canIUse(params): Promise<CanIUseResult>` | 检测当前宿主是否支持指定 API 或能力 | `params: CanIUseParams` | `Promise<CanIUseResult>` | 用于兼容性判断 |
+| [`getLocation`](#getlocation) | `getLocation(params?): Promise<GetLocationResponse>` | 获取设备当前的地理位置信息 | `params?: GetLocationParams` | `Promise<GetLocationResponse>` | 可能涉及定位授权 |
+| [`login`](#login) | `login(params?): Promise<LoginResult>` | 发起登录并获取登录凭证 | `params?: LoginRequest` | `Promise<LoginResult>` | - |
+| [`getWindowInfoSync`](#getwindowinfosync) | `getWindowInfoSync(_param?): GetWindowInfoResult` | 获取窗口信息 | `_param?` | `GetWindowInfoResult` | 同步 API |
+| [`getSystemSetting`](#getsystemsetting) | `getSystemSetting(params?): GetSystemSettingResult` | 获取设备设置 | `params?` | `GetSystemSettingResult` | - |
+| [`getAppBaseInfoSync`](#getappbaseinfosync) | `getAppBaseInfoSync(_params?): GetAppBaseInfoResult` | 获取应用基础信息 | `_params?` | `GetAppBaseInfoResult` | 同步 API |
+| [`getWindowInfo`](#getwindowinfo) | `getWindowInfo(_params?): Promise<GetWindowInfoResult>` | 获取窗口信息 | `_params?` | `Promise<GetWindowInfoResult>` | - |
+| [`getAppBaseInfo`](#getappbaseinfo) | `getAppBaseInfo(params?): Promise<GetAppBaseInfoResult>` | 获取应用基础信息 | `params?` | `Promise<GetAppBaseInfoResult>` | - |
+
+## API 详情
+
+<a id="getaccountinfo"></a>
+### getAccountInfo()
+
+> **getAccountInfo**(`params`?): `Promise`\<[`GetAccountInfoResult`](#getaccountinforesult)\>
+
+异步获取账号信息。
+
+#### Parameters
+
+• **params?**
+
+#### Returns
+
+`Promise`\<[`GetAccountInfoResult`](#getaccountinforesult)\>
+
+#### Example
+
+```typescript
+import { getAccountInfo } from '@doubao-apps/framework/api';
+
+const result = await getAccountInfo();
+console.log(result.miniProgram.appId);
+```
+
+<a id="getaccountinfosync"></a>
+### getAccountInfoSync()
+
+> **getAccountInfoSync**(`params`?): [`GetAccountInfoResult`](#getaccountinforesult)
+
+同步获取账号信息。
+
+#### Parameters
+
+• **params?**
+
+#### Returns
+
+[`GetAccountInfoResult`](#getaccountinforesult)
+
+#### Example
+
+```typescript
+import { getAccountInfoSync } from '@doubao-apps/framework/api';
+
+const result = getAccountInfoSync();
+console.log(result.miniProgram.appId, result.miniProgram.envVersion, result.miniProgram.version);
+```
+
+<a id="authorize"></a>
+### authorize()
+
+> **authorize**(`params`): `Promise`\<`object`\>
+
+初始化授权
+
+#### Parameters
+
+• **params**: [`AuthorizeRequest`](#authorizerequest)
+
+授权参数
+
+#### Returns
+
+`Promise`\<`object`\>
+
+Promise 对象，授权成功时会返回授权结果
+
+#### Remarks
+
+按 scope 申请授权。
+
+<a id="caniuse"></a>
+### canIUse()
+
+> **canIUse**(`params`): `Promise`\<[`CanIUseResult`](#caniuseresult)\>
+
+检测当前宿主是否支持指定 API 或能力。
+
+#### Parameters
+
+• **params**: [`CanIUseParams`](#caniuseparams)
+
+#### Returns
+
+`Promise`\<[`CanIUseResult`](#caniuseresult)\>
+
+#### Remarks
+
+用于兼容性判断。
+
+<a id="getlocation"></a>
+### getLocation()
+
+> **getLocation**(`params`?): `Promise`\<[`GetLocationResponse`](#getlocationresponse)\>
+
+获取设备当前的地理位置信息。
+
+#### Parameters
+
+• **params?**: [`GetLocationParams`](#getlocationparams)
+
+#### Returns
+
+`Promise`\<[`GetLocationResponse`](#getlocationresponse)\>
+
+返回一个 Promise，成功时解析为包含地理位置信息的对象，包含：
+  - `latitude`: number - 纬度。
+  - `longitude`: number - 经度。
+  - `timestamp`: string - 时间戳。
+  - `speed`: number - 行进速度，单位：米/秒。
+  - `accuracy`: number - 定位精度，单位：米。
+  参考 [GetLocationResponse](#getlocationresponse)。
+
+#### Throws
+
+如果调用失败（例如，用户拒绝权限、定位服务关闭等），则抛出此错误。
+
+#### Remarks
+
+可能涉及定位授权。
+
+#### Example
+
+```typescript
+import { getLocation } from '@doubao-apps/framework';
+
+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();
+```
+
+<a id="login"></a>
+### login()
+
+> **login**(`params`?): `Promise`\<[`LoginResult`](#loginresult)\>
+
+发起登录并获取登录凭证。
+
+#### Parameters
+
+• **params?**: [`LoginRequest`](#loginrequest)
+
+登录参数。
+
+#### Returns
+
+`Promise`\<[`LoginResult`](#loginresult)\>
+
+返回包含登录凭证 code 的 Promise。
+
+<a id="getwindowinfosync"></a>
+### getWindowInfoSync()
+
+> **getWindowInfoSync**(`_param`?): [`GetWindowInfoResult`](#getwindowinforesult)
+
+获取窗口信息。
+
+#### Parameters
+
+• **\_param?**
+
+#### Returns
+
+[`GetWindowInfoResult`](#getwindowinforesult)
+
+返回窗口尺寸、状态栏高度和安全区域等信息，字段见 [GetWindowInfoResult](#getwindowinforesult)。
+
+#### Example
+
+```typescript
+import { getWindowInfoSync } from '@doubao-apps/framework/api';
+
+const result = getWindowInfoSync();
+
+console.log(result.windowWidth, result.windowHeight);
+console.log(result.safeArea?.top, result.screenTop);
+```
+
+<a id="getsystemsetting"></a>
+### getSystemSetting()
+
+> **getSystemSetting**(`params`?): [`GetSystemSettingResult`](#getsystemsettingresult)
+
+获取设备设置。
+
+#### Parameters
+
+• **params?**
+
+#### Returns
+
+[`GetSystemSettingResult`](#getsystemsettingresult)
+
+返回蓝牙、定位、Wi-Fi 系统开关和设备方向等字段，见 [GetSystemSettingResult](#getsystemsettingresult)。
+
+#### Example
+
+```typescript
+import { getSystemSetting } from '@doubao-apps/framework/api';
+
+const result = getSystemSetting();
+
+console.log(result.bluetoothEnabled, result.locationEnabled);
+console.log(result.wifiEnabled, result.deviceOrientation);
+```
+
+<a id="getappbaseinfosync"></a>
+### getAppBaseInfoSync()
+
+> **getAppBaseInfoSync**(`_params`?): [`GetAppBaseInfoResult`](#getappbaseinforesult)
+
+获取应用基础信息。
+
+#### Parameters
+
+• **\_params?**
+
+#### Returns
+
+[`GetAppBaseInfoResult`](#getappbaseinforesult)
+
+返回 SDK 版本、调试开关、宿主信息、语言和主题等字段，见 [GetAppBaseInfoResult](#getappbaseinforesult)。
+
+#### Example
+
+```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);
+```
+
+<a id="getwindowinfo"></a>
+### getWindowInfo()
+
+> **getWindowInfo**(`_params`?): `Promise`\<[`GetWindowInfoResult`](#getwindowinforesult)\>
+
+获取窗口信息。
+
+#### Parameters
+
+• **\_params?**
+
+#### Returns
+
+`Promise`\<[`GetWindowInfoResult`](#getwindowinforesult)\>
+
+返回窗口尺寸、状态栏高度和安全区域等信息，字段见 [GetWindowInfoResult](#getwindowinforesult)。
+
+#### Example
+
+```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);
+```
+
+<a id="getappbaseinfo"></a>
+### getAppBaseInfo()
+
+> **getAppBaseInfo**(`params`?): `Promise`\<[`GetAppBaseInfoResult`](#getappbaseinforesult)\>
+
+获取应用基础信息。
+
+#### Parameters
+
+• **params?**
+
+#### Returns
+
+`Promise`\<[`GetAppBaseInfoResult`](#getappbaseinforesult)\>
+
+返回 SDK 版本、调试开关、宿主信息、语言和主题等字段，见 [GetAppBaseInfoResult](#getappbaseinforesult)。
+
+#### Example
+
+```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);
+```
+
+## 相关类型
+
+<a id="getaccountinforesult"></a>
+### GetAccountInfoResult
+
+获取当前账号信息。
+
+#### Properties
+
+##### miniProgram
+
+> **miniProgram**: [`DoubaoAppAccountInfo`](#doubaoappaccountinfo)
+
+豆包 App账号信息
+
+##### plugin?
+
+> `optional` **plugin**: [`PluginAccountInfo`](#pluginaccountinfo)
+
+插件账号信息（仅在插件中调用时包含）
+
+<a id="doubaoappaccountinfo"></a>
+### DoubaoAppAccountInfo
+
+豆包 App 账号信息。
+
+#### Properties
+
+##### appId
+
+> **appId**: `string`
+
+豆包 App appId
+
+##### envVersion
+
+> **envVersion**: `"develop"` \| `"trial"` \| `"release"`
+
+豆包 App 运行环境。
+
+- develop: 开发版
+- trial: 体验版
+- release: 正式版
+
+##### version
+
+> **version**: `string`
+
+线上豆包 App 版本号。
+
+<a id="pluginaccountinfo"></a>
+### PluginAccountInfo
+
+插件账号信息（仅在插件中调用时包含）。
+
+#### Properties
+
+##### appId
+
+> **appId**: `string`
+
+插件 appId
+
+##### version
+
+> **version**: `string`
+
+插件版本号，'a.b.c' 形式
+
+<a id="authorizerequest"></a>
+### AuthorizeRequest
+
+#### Properties
+
+##### scope
+
+> **scope**: [`Scope`](#scope-1)
+
+授权范围
+
+<a id="scope-1"></a>
+<a id="scope"></a>
+### Scope
+
+> **Scope**: `"scope.userLocation"` \| `"scope.userFuzzyLocation"` \| `"scope.userLocationBackground"` \| `"scope.payment"` \| `"scope.record"` \| `"scope.bluetooth"` \| `"scope.camera"` \| `"scope.addPhoneContact"` \| `"scope.addPhoneCalendar"`
+
+<a id="caniuseparams"></a>
+### CanIUseParams
+
+#### Properties
+
+##### schema
+
+> **schema**: `string`
+
+<a id="caniuseresult"></a>
+### CanIUseResult
+
+#### Properties
+
+##### result
+
+> **result**: `boolean`
+
+<a id="getlocationparams"></a>
+### GetLocationParams
+
+#### Properties
+
+##### maxCacheMs?
+
+> `optional` **maxCacheMs**: `number`
+
+缓存时间，单位毫秒，默认为0
+
+##### mode?
+
+> `optional` **mode**: `number`
+
+定位模式
+0：低功耗
+1：仅设备
+2：高精度（默认）
+
+##### source?
+
+> `optional` **source**: `string`
+
+调用业务方
+
+##### timeoutMs?
+
+> `optional` **timeoutMs**: `number`
+
+超时时间，单位毫秒，默认 30000
+
+<a id="getlocationresponse"></a>
+### GetLocationResponse
+
+#### Properties
+
+##### accuracy
+
+> **accuracy**: `number`
+
+定位精度，单位：米
+
+##### latitude
+
+> **latitude**: `number`
+
+纬度
+
+##### longitude
+
+> **longitude**: `number`
+
+经度
+
+##### speed
+
+> **speed**: `number`
+
+行进速度，单位：米/秒
+
+##### timestamp
+
+> **timestamp**: `string`
+
+时间戳
+
+<a id="loginrequest"></a>
+### LoginRequest
+
+#### Properties
+
+##### timeout?
+
+> `optional` **timeout**: `number`
+
+Timeout in milliseconds
+
+<a id="loginresult"></a>
+### LoginResult
+
+#### Properties
+
+##### code
+
+> **code**: `string`
+
+Login credential code
+
+<a id="getwindowinforesult"></a>
+### GetWindowInfoResult
+
+#### Properties
+
+##### pixelRatio
+
+> **pixelRatio**: `number`
+
+设备像素比
+
+##### safeArea?
+
+> `optional` **safeArea**: [`WindowSafeArea`](#windowsafearea)
+
+安全区域
+
+##### screenHeight
+
+> **screenHeight**: `number`
+
+屏幕高度
+
+##### screenTop
+
+> **screenTop**: `number`
+
+窗口上边缘的 y 值
+
+##### screenWidth
+
+> **screenWidth**: `number`
+
+屏幕宽度
+
+##### statusBarHeight
+
+> **statusBarHeight**: `number`
+
+状态栏高度
+
+##### windowHeight
+
+> **windowHeight**: `number`
+
+可使用窗口高度
+
+##### windowWidth
+
+> **windowWidth**: `number`
+
+可使用窗口宽度
+
+<a id="windowsafearea"></a>
+### WindowSafeArea
+
+#### Properties
+
+##### bottom
+
+> **bottom**: `number`
+
+安全区域右下角纵坐标
+
+##### height
+
+> **height**: `number`
+
+安全区域高度
+
+##### left
+
+> **left**: `number`
+
+安全区域左上角横坐标
+
+##### right
+
+> **right**: `number`
+
+安全区域右下角横坐标
+
+##### top
+
+> **top**: `number`
+
+安全区域左上角纵坐标
+
+##### width
+
+> **width**: `number`
+
+安全区域宽度
+
+<a id="getsystemsettingresult"></a>
+### GetSystemSettingResult
+
+#### Properties
+
+##### bluetoothEnabled
+
+> **bluetoothEnabled**: `boolean`
+
+蓝牙的系统开关
+
+##### deviceOrientation
+
+> **deviceOrientation**: [`DeviceOrientation`](#deviceorientation-1)
+
+设备方向
+
+##### locationEnabled
+
+> **locationEnabled**: `boolean`
+
+地理位置的系统开关
+
+##### wifiEnabled
+
+> **wifiEnabled**: `boolean`
+
+Wi-Fi 的系统开关
+
+<a id="deviceorientation-1"></a>
+<a id="deviceorientation"></a>
+### DeviceOrientation
+
+> **DeviceOrientation**: `"portrait"` \| `"landscape"`
+
+<a id="getappbaseinforesult"></a>
+### GetAppBaseInfoResult
+
+#### Properties
+
+##### SDKVersion?
+
+> `optional` **SDKVersion**: `string`
+
+客户端基础库版本
+
+##### enableDebug?
+
+> `optional` **enableDebug**: `boolean`
+
+是否已打开调试
+
+##### host?
+
+> `optional` **host**: [`AppBaseInfoHost`](#appbaseinfohost)
+
+当前豆包 App运行的宿主环境
+
+##### language
+
+> **language**: `string`
+
+当前语言
+
+##### theme?
+
+> `optional` **theme**: `"light"` \| `"dark"`
+
+当前主题
+
+##### version?
+
+> `optional` **version**: `string`
+
+宿主版本号
+
+<a id="appbaseinfohost"></a>
+### AppBaseInfoHost
+
+#### Properties
+
+##### appId
+
+> **appId**: `string`
+
+宿主 app 对应的 appId