@doubao-apps/create 0.0.31 → 0.0.32

package/dist/template-starter/AGENTS.md

@@ -215,6 +215,18 @@ export default defineWidget({
 - **路由编码**：入口页跳转含 `/` 的 case name 时必须 `encodeURIComponent`；开发模式 `delegate-page` 的 query 需要 encode/decode。
 - **响应式主题**：Playground 外壳和示例辅助 UI 使用 `--pg-*` 变量；不要在 Playground 任务中顺手修组件库自身主题。
 
+### API e2e 测试范式
+
+当任务新增或正式暴露 `@doubao-apps/framework/api` / Open API / JSB API 时，必须同步补充 `e2e/api` 自动化测试：
+
+- **测试目录**：Vitest case 放在 `e2e/api/__tests__/`，优先补到已有 domain 文件，如 `basic.test.ts`、`network.test.ts`、`storage.test.ts`、`device.test.ts`、`ui.test.ts`；没有合适分组时新建 `<domain>.test.ts`。
+- **测试小程序**：`examples/e2e-api-runner` 只负责建立 WebSocket 链接、接收 API 调用指令、执行 `@doubao-apps/framework/api` 并回传结果；不要把具体 e2e case 写在小程序或 playground 内。
+- **协议层**：WebSocket server、协议类型和 runner client 由 `@byted-doubao-apps/e2e-runner` 提供；不要在测试用例里重复实现通信协议。
+- **调用方式**：在测试中使用 `const session = await getApiSession()`，再通过 `await session.callApi<TResult>('<apiName>', [params], { timeoutMs })` 调用并在 Vitest 侧断言。
+- **稳定性原则**：只自动化稳定、低副作用、可断言的 API；强交互、权限弹窗、支付、路由退出、账号业务态或设备状态不稳定的 API 应 `it.skip` / `describe.skip` 并写明原因。
+- **本地依赖**：网络类 API 优先使用 `session.httpFixtureServer`，避免依赖公网。
+- **验证命令**：至少运行 `pnpm --filter @byted-doubao-apps/e2e-api typecheck`；有目标设备时再运行 `pnpm --filter @byted-doubao-apps/e2e-api test:api`。
+
 ### Lynx 组件
 
 Lynx 组件库完整参考文档请访问官方文档：

package/dist/template-starter/package.json

@@ -6,10 +6,10 @@
     "build": "doubao build"
   },
   "dependencies": {
-    "@doubao-apps/framework": "^0.0.31"
+    "@doubao-apps/framework": "^0.0.32"
   },
   "devDependencies": {
-    "@doubao-apps/kit": "^0.0.31",
+    "@doubao-apps/kit": "^0.0.32",
     "typescript": "5.5.3"
   },
   "version": "0.0.16"

package/dist/template-starter/references/reference/open-api/02-/345/256/232/344/275/215.md

@@ -9,6 +9,14 @@
 | API | 说明 |
 | --- | --- |
 | [getLocation](#getlocation) | 获取设备当前的地理位置信息。<br><br>可能涉及定位授权。 |
+| [chooseLocation](#chooselocation) | 打开地图选择位置。 |
+| [openLocation](#openlocation) | 使用地图查看位置。 |
+| [startLocationUpdate](#startlocationupdate) | 开始接收位置更新。<br><br>需配对调用 stopLocationUpdate。 |
+| [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 详情
 
@@ -65,6 +73,130 @@ async function fetchLocation() {
 fetchLocation();
 ```
 
+<a id="chooselocation"></a>
+### chooseLocation()
+
+> **chooseLocation**(`params`?): `Promise`\<[`ChooseLocationResponse`](#chooselocationresponse)\>
+
+打开地图选择位置。
+
+#### Parameters
+
+• **params?**: [`ChooseLocationParams`](#chooselocationparams)
+
+#### Returns
+
+`Promise`\<[`ChooseLocationResponse`](#chooselocationresponse)\>
+
+<a id="openlocation"></a>
+### openLocation()
+
+> **openLocation**(`params`): `Promise`\<`object`\>
+
+使用地图查看位置。
+
+#### Parameters
+
+• **params**: [`OpenLocationParams`](#openlocationparams)
+
+#### Returns
+
+`Promise`\<`object`\>
+
+<a id="startlocationupdate"></a>
+### startLocationUpdate()
+
+> **startLocationUpdate**(`params`?): `Promise`\<`object`\>
+
+开始接收位置更新。
+
+#### Parameters
+
+• **params?**: [`StartLocationUpdateParams`](#startlocationupdateparams)
+
+#### Returns
+
+`Promise`\<`object`\>
+
+#### Remarks
+
+需配对调用 stopLocationUpdate。
+
+<a id="stoplocationupdate"></a>
+### stopLocationUpdate()
+
+> **stopLocationUpdate**(`params`?): `Promise`\<`object`\>
+
+停止接收位置更新。
+
+#### Parameters
+
+• **params?**
+
+#### Returns
+
+`Promise`\<`object`\>
+
+<a id="onlocationchange"></a>
+### onLocationChange()
+
+> **onLocationChange**(`callback`): `void`
+
+注册地理位置变化回调。
+
+#### Parameters
+
+• **callback**: [`LocationChangeListener`](#locationchangelistener)
+
+#### Returns
+
+`void`
+
+<a id="offlocationchange"></a>
+### offLocationChange()
+
+> **offLocationChange**(`callback`?): `void`
+
+取消注册地理位置变化回调。
+
+#### Parameters
+
+• **callback?**: [`LocationChangeListener`](#locationchangelistener)
+
+#### Returns
+
+`void`
+
+<a id="onlocationchangeerror"></a>
+### onLocationChangeError()
+
+> **onLocationChangeError**(`callback`): `void`
+
+注册位置更新异常回调。
+
+#### Parameters
+
+• **callback**: [`LocationChangeErrorListener`](#locationchangeerrorlistener)
+
+#### Returns
+
+`void`
+
+<a id="offlocationchangeerror"></a>
+### offLocationChangeError()
+
+> **offLocationChangeError**(`callback`?): `void`
+
+取消注册位置更新异常回调。
+
+#### Parameters
+
+• **callback?**: [`LocationChangeErrorListener`](#locationchangeerrorlistener)
+
+#### Returns
+
+`void`
+
 ## 相关类型
 
 <a id="getlocationparams"></a>
@@ -133,3 +265,95 @@ fetchLocation();
 > **timestamp**: `string`
 
 时间戳
+
+<a id="chooselocationparams"></a>
+### ChooseLocationParams
+
+#### Properties
+
+##### latitude?
+
+> `optional` **latitude**: `number`
+
+目标地纬度
+
+##### longitude?
+
+> `optional` **longitude**: `number`
+
+目标地经度
+
+<a id="chooselocationresponse"></a>
+### ChooseLocationResponse
+
+#### Properties
+
+##### address?
+
+> `optional` **address**: `string`
+
+地址详情
+
+##### latitude
+
+> **latitude**: `number`
+
+纬度，GCJ-02 坐标系
+
+##### longitude
+
+> **longitude**: `number`
+
+经度，GCJ-02 坐标系
+
+##### name?
+
+> `optional` **name**: `string`
+
+位置名称
+
+<a id="openlocationparams"></a>
+### OpenLocationParams
+
+#### Properties
+
+##### address?
+
+> `optional` **address**: `string`
+
+地址详情
+
+##### latitude
+
+> **latitude**: `number`
+
+纬度
+
+##### longitude
+
+> **longitude**: `number`
+
+经度
+
+##### name?
+
+> `optional` **name**: `string`
+
+位置名称
+
+##### scale?
+
+> `optional` **scale**: `number`
+
+缩放比例，范围 5 ~ 18
+
+<a id="startlocationupdateparams"></a>
+### StartLocationUpdateParams
+
+#### Properties
+
+##### type?
+
+> `optional` **type**: `"wgs84"` \| `"gcj02"`
+
+坐标系类型，支持 wgs84 或 gcj02

package/dist/template-starter/references/reference/open-api/22-/350/256/276/345/244/207-/345/237/272/347/241/200/344/277/241/346/201/257.md

@@ -0,0 +1,133 @@
+# Open API: 设备 / 基础信息
+
+设备品牌、型号、系统、内存和性能等级。
+
+[返回目录](./README.md) | [返回速查](../open-api.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [getDeviceInfo](#getdeviceinfo) | 获取设备基础信息。 |
+| [getDeviceInfoSync](#getdeviceinfosync) | 同步获取设备基础信息。<br><br>同步 API。 |
+
+## API 详情
+
+<a id="getdeviceinfo"></a>
+### getDeviceInfo()
+
+> **getDeviceInfo**(`params`?): `Promise`\<[`GetDeviceInfoResult`](#getdeviceinforesult)\>
+
+获取设备基础信息。
+
+#### Parameters
+
+• **params?**
+
+#### Returns
+
+`Promise`\<[`GetDeviceInfoResult`](#getdeviceinforesult)\>
+
+返回设备品牌、型号、系统、内存和性能等级等字段，见 [GetDeviceInfoResult](#getdeviceinforesult)。
+
+#### Example
+
+```typescript
+import { getDeviceInfo } from '@doubao-apps/framework/api';
+
+const result = await getDeviceInfo();
+
+console.log(result.brand, result.model, result.system);
+console.log(result.platform, result.benchmarkLevel);
+```
+
+<a id="getdeviceinfosync"></a>
+### getDeviceInfoSync()
+
+> **getDeviceInfoSync**(`params`?): [`GetDeviceInfoResult`](#getdeviceinforesult)
+
+同步获取设备基础信息。
+
+#### Parameters
+
+• **params?**
+
+#### Returns
+
+[`GetDeviceInfoResult`](#getdeviceinforesult)
+
+返回设备品牌、型号、系统、内存和性能等级等字段，见 [GetDeviceInfoResult](#getdeviceinforesult)。
+
+#### Example
+
+```typescript
+import { getDeviceInfoSync } from '@doubao-apps/framework/api';
+
+const result = getDeviceInfoSync();
+
+console.log(result.brand, result.model, result.system);
+console.log(result.platform, result.benchmarkLevel);
+```
+
+## 相关类型
+
+<a id="getdeviceinforesult"></a>
+### GetDeviceInfoResult
+
+设备基础信息。
+
+#### Properties
+
+##### abi?
+
+> `optional` **abi**: `string`
+
+宿主 App 二进制接口类型，仅 Android 支持。
+
+##### benchmarkLevel
+
+> **benchmarkLevel**: `number`
+
+设备性能等级，值越高性能越好；-1 表示未知。
+
+##### brand
+
+> **brand**: `string`
+
+设备品牌。
+
+##### cpuType?
+
+> `optional` **cpuType**: `string`
+
+设备 CPU 型号，仅 Android 支持。
+
+##### deviceAbi?
+
+> `optional` **deviceAbi**: `string`
+
+设备二进制接口类型，仅 Android 支持。
+
+##### memorySize
+
+> **memorySize**: `string`
+
+设备内存大小，单位 MB。
+
+##### model
+
+> **model**: `string`
+
+设备型号。
+
+##### platform
+
+> **platform**: `string`
+
+客户端平台。
+
+##### system
+
+> **system**: `string`
+
+操作系统及版本。

package/dist/template-starter/references/reference/open-api/README.md

@@ -7,7 +7,7 @@
 | 分组 | 说明 | API 数量 | 详细文档 |
 | --- | --- | ---: | --- |
 | 基础 / 账号 / 系统 | 账号、授权、宿主基础信息、窗口信息和能力可用性。 | 9 | [查看](./01-基础-账号-系统.md) |
-| 定位 | 获取设备当前的地理位置信息。 | 1 | [查看](./02-定位.md) |
+| 定位 | 获取设备当前的地理位置信息。 | 9 | [查看](./02-定位.md) |
 | 存储 | 本地缓存；带 Sync 后缀的是同步 API。 | 10 | [查看](./03-存储.md) |
 | 路由 | 应用内页面跳转、返回、退出和关闭。 | 6 | [查看](./04-路由.md) |
 | 界面 / 交互 | Toast、Loading、Modal、ActionSheet 和返回前提醒。 | 9 | [查看](./05-界面-交互.md) |
@@ -27,13 +27,14 @@
 | 设备 / 网络 | 网络类型和本机局域网 IP。 | 3 | [查看](./19-设备-网络.md) |
 | 设备 / 短信 | 拉起系统短信发送面板。 | 1 | [查看](./20-设备-短信.md) |
 | 设备 / 无障碍 | 检测无障碍能力开关状态。 | 1 | [查看](./21-设备-无障碍.md) |
-| 设备 / 电池 | 电池信息读取与变化监听。 | 2 | [查看](./22-设备-电池.md) |
-| 设备 / 日历 | 向系统日历添加事件和重复事件。 | 2 | [查看](./23-设备-日历.md) |
-| 设备 / 剪贴板 | 读取和设置系统剪贴板内容。 | 2 | [查看](./24-设备-剪贴板.md) |
-| 设备 / 联系人 | 选择和添加手机联系人。 | 2 | [查看](./25-设备-联系人.md) |
-| 设备 / 加密 | 安全随机数能力。 | 1 | [查看](./26-设备-加密.md) |
-| 设备 / 电话 | 拨打电话。 | 1 | [查看](./27-设备-电话.md) |
-| 设备 / 扫码 | 调起扫码并读取扫码结果。 | 1 | [查看](./28-设备-扫码.md) |
-| 设备 / 屏幕 | 屏幕亮度、常亮和截屏/录屏相关能力。 | 5 | [查看](./29-设备-屏幕.md) |
-| 设备 / 震动 | 触发短震动和长震动。 | 2 | [查看](./30-设备-震动.md) |
-| 文件系统 | 文件读写、目录管理和文件信息操作。 | 1 | [查看](./31-文件系统.md) |
+| 设备 / 基础信息 | 设备品牌、型号、系统、内存和性能等级。 | 2 | [查看](./22-设备-基础信息.md) |
+| 设备 / 电池 | 电池信息读取与变化监听。 | 2 | [查看](./23-设备-电池.md) |
+| 设备 / 日历 | 向系统日历添加事件和重复事件。 | 2 | [查看](./24-设备-日历.md) |
+| 设备 / 剪贴板 | 读取和设置系统剪贴板内容。 | 2 | [查看](./25-设备-剪贴板.md) |
+| 设备 / 联系人 | 选择和添加手机联系人。 | 2 | [查看](./26-设备-联系人.md) |
+| 设备 / 加密 | 安全随机数能力。 | 1 | [查看](./27-设备-加密.md) |
+| 设备 / 电话 | 拨打电话。 | 1 | [查看](./28-设备-电话.md) |
+| 设备 / 扫码 | 调起扫码并读取扫码结果。 | 1 | [查看](./29-设备-扫码.md) |
+| 设备 / 屏幕 | 屏幕亮度、常亮和截屏/录屏相关能力。 | 5 | [查看](./30-设备-屏幕.md) |
+| 设备 / 震动 | 触发短震动和长震动。 | 2 | [查看](./31-设备-震动.md) |
+| 文件系统 | 文件读写、目录管理和文件信息操作。 | 1 | [查看](./32-文件系统.md) |