@doubao-apps/create 0.0.29 → 0.0.30

package/dist/{template-starter/references/reference/open-api/04- → template-empty/references/reference/open-api/10-}/346/225/260/346/215/256/345/210/206/346/236/220.md

@@ -1,6 +1,6 @@
 # Open API: 数据分析
 
-监控上报、事件和数据分析上报
+监控上报、事件和数据分析上报。
 
 [返回目录](./README.md) | [返回速查](../open-api.md)
 

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

@@ -6,27 +6,33 @@
 
 | 分组 | 说明 | API 数量 | 详细文档 |
 | --- | --- | ---: | --- |
-| 基础 / 账号 / 系统 | 账号、授权、宿主基础信息、窗口信息和定位。 | 57 | [查看](./01-基础-账号-系统.md) |
-| 路由 | 应用内页面跳转和关闭。 | 1 | [查看](./02-路由.md) |
-| 界面 / 输入 | 键盘和输入框选区能力。 | 2 | [查看](./03-界面-输入.md) |
-| 数据分析 | 监控上报、事件和数据分析上报 | 1 | [查看](./04-数据分析.md) |
-| 设备 / 蓝牙 | 蓝牙和 BLE 能力；通常先打开适配器，再扫描、连接和读写。 | 19 | [查看](./05-设备-蓝牙.md) |
-| 设备 / Wi-Fi | Wi-Fi 模块能力；通常先 startWifi，再获取列表或连接。 | 6 | [查看](./06-设备-wi-fi.md) |
-| 设备 / 加速度计 | 加速度计监听能力。 | 3 | [查看](./07-设备-加速度计.md) |
-| 设备 / iBeacon | iBeacon 搜索和结果读取能力。 | 3 | [查看](./08-设备-ibeacon.md) |
-| 设备 / 罗盘 | 罗盘监听能力。 | 3 | [查看](./09-设备-罗盘.md) |
-| 设备 / 设备方向 | 设备方向监听能力。 | 3 | [查看](./10-设备-设备方向.md) |
-| 设备 / 陀螺仪 | 陀螺仪监听能力。 | 3 | [查看](./11-设备-陀螺仪.md) |
-| UI / 输入 | 键盘和输入框选区能力。 | 1 | [查看](./12-ui-输入.md) |
-| 设备 / 网络 | 网络类型和本机局域网 IP。 | 3 | [查看](./13-设备-网络.md) |
-| 设备 / 短信 | 拉起系统短信发送面板。 | 1 | [查看](./14-设备-短信.md) |
-| 设备 / 无障碍 | 检测无障碍能力开关状态。 | 1 | [查看](./15-设备-无障碍.md) |
-| 设备 / 电池 | 电池信息读取与变化监听。 | 2 | [查看](./16-设备-电池.md) |
-| 设备 / 日历 | 向系统日历添加事件和重复事件。 | 2 | [查看](./17-设备-日历.md) |
-| 设备 / 剪贴板 | 读取和设置系统剪贴板内容。 | 2 | [查看](./18-设备-剪贴板.md) |
-| 设备 / 联系人 | 选择和添加手机联系人。 | 2 | [查看](./19-设备-联系人.md) |
-| 设备 / 加密 | 安全随机数能力。 | 1 | [查看](./20-设备-加密.md) |
-| 设备 / 电话 | 拨打电话。 | 1 | [查看](./21-设备-电话.md) |
-| 设备 / 扫码 | 调起扫码并读取扫码结果。 | 1 | [查看](./22-设备-扫码.md) |
-| 设备 / 屏幕 | 屏幕亮度、常亮和截屏/录屏相关能力。 | 5 | [查看](./23-设备-屏幕.md) |
-| 设备 / 震动 | 触发短震动和长震动。 | 2 | [查看](./24-设备-震动.md) |
+| 基础 / 账号 / 系统 | 账号、授权、宿主基础信息、窗口信息和能力可用性。 | 9 | [查看](./01-基础-账号-系统.md) |
+| 定位 | 获取设备当前的地理位置信息。 | 1 | [查看](./02-定位.md) |
+| 存储 | 本地缓存；带 Sync 后缀的是同步 API。 | 10 | [查看](./03-存储.md) |
+| 路由 | 应用内页面跳转、返回、退出和关闭。 | 6 | [查看](./04-路由.md) |
+| 界面 / 交互 | Toast、Loading、Modal、ActionSheet 和返回前提醒。 | 9 | [查看](./05-界面-交互.md) |
+| 界面 / 输入 | 键盘和输入框选区能力。 | 2 | [查看](./06-界面-输入.md) |
+| 网络 | 网络请求与 WebSocket。 | 2 | [查看](./07-网络.md) |
+| 媒体 | 图片选择、预览、保存、压缩和信息读取。 | 5 | [查看](./08-媒体.md) |
+| 开放能力 / 业务能力 | 开放业务能力、支付、隐私设置、上下文和外部应用打开。 | 17 | [查看](./09-开放能力-业务能力.md) |
+| 数据分析 | 监控上报、事件和数据分析上报。 | 1 | [查看](./10-数据分析.md) |
+| 设备 / 蓝牙 | 蓝牙和 BLE 能力；通常先打开适配器，再扫描、连接和读写。 | 19 | [查看](./11-设备-蓝牙.md) |
+| 设备 / Wi-Fi | Wi-Fi 模块能力；通常先 startWifi，再获取列表或连接。 | 6 | [查看](./12-设备-wi-fi.md) |
+| 设备 / 加速度计 | 加速度计监听能力。 | 3 | [查看](./13-设备-加速度计.md) |
+| 设备 / iBeacon | iBeacon 搜索和结果读取能力。 | 3 | [查看](./14-设备-ibeacon.md) |
+| 设备 / 罗盘 | 罗盘监听能力。 | 3 | [查看](./15-设备-罗盘.md) |
+| 设备 / 设备方向 | 设备方向监听能力。 | 3 | [查看](./16-设备-设备方向.md) |
+| 设备 / 陀螺仪 | 陀螺仪监听能力。 | 3 | [查看](./17-设备-陀螺仪.md) |
+| UI / 输入 | 键盘和输入框选区能力。 | 1 | [查看](./18-ui-输入.md) |
+| 设备 / 网络 | 网络类型和本机局域网 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) |

package/dist/template-empty/references/reference/open-api.md

@@ -288,6 +288,66 @@ closePage();
 
 ***
 
+### connectSocket()
+
+> **connectSocket**(`params`): [`SocketTask`](doubao-apps-sdk-open-api.md#sockettask)
+
+创建一个 WebSocket 连接，并返回可操作该连接的 [SocketTask](doubao-apps-sdk-open-api.md#sockettask)。
+
+该 API 会同步返回 `SocketTask`，但连接创建本身是异步过程。调用方应先在返回的
+`SocketTask` 上注册事件回调，再等待 `onOpen` 表示连接可用。后续发送消息使用
+`SocketTask.send`，关闭连接使用 `SocketTask.close`。
+
+#### Parameters
+
+• **params**: [`ConnectSocketParams`](doubao-apps-sdk-open-api.md#connectsocketparams)
+
+创建连接所需参数，字段见 [ConnectSocketParams](doubao-apps-sdk-open-api.md#connectsocketparams)。
+
+#### Returns
+
+[`SocketTask`](doubao-apps-sdk-open-api.md#sockettask)
+
+当前 WebSocket 连接对应的 [SocketTask](doubao-apps-sdk-open-api.md#sockettask)。
+
+#### Remarks
+
+- 返回 `SocketTask` 不代表连接已经成功，连接成功以 `onOpen` 为准。
+- `send` 必须接收对象参数，并把要发送的内容放在 `data` 字段中。
+- 如果 `protocols` 非空，需要服务端支持并返回匹配的子协议。
+- 多次调用会创建多条连接，旧连接不会自动关闭；不再使用时应主动调用 `close`。
+- 连接失败、发送失败或关闭失败会通过 `SocketTask.onError` 通知。
+
+#### Example
+
+```typescript
+import { connectSocket } from '@doubao-apps/framework/api';
+
+const socketTask = connectSocket({
+  url: 'wss://example.com/socket',
+  header: { authorization: 'Bearer token' },
+  protocols: ['chat.v1']
+});
+
+socketTask.onOpen(() => {
+  socketTask.send({ data: 'hello' });
+});
+
+socketTask.onMessage((event) => {
+  console.log(event.data);
+});
+
+socketTask.onClose((event) => {
+  console.log(event.code, event.reason);
+});
+
+socketTask.onError((event) => {
+  console.error(event.errMsg);
+});
+```
+
+***
+
 ### connectWifi()
 
 > **connectWifi**(`params`): `Promise`\<`object`\>
@@ -3737,6 +3797,54 @@ H5 场景下可复用的 input 元素 ID。
 
 ***
 
+### ConnectSocketParams
+
+创建 WebSocket 连接的参数。
+
+`connectSocket` 会把这些参数透传给宿主侧创建连接。连接创建请求发出后，
+调用方会立即拿到一个 [SocketTask](doubao-apps-sdk-open-api.md#sockettask)，后续连接成功、失败、收到消息和关闭状态
+都通过 `SocketTask` 上注册的事件回调通知。
+
+#### Remarks
+
+- `url` 应填写完整的 WebSocket 地址。线上环境通常要求使用 `wss://` 协议，并由宿主侧按当前应用配置校验合法域名和证书。
+- `header` 用于补充握手请求头，`referer` 等由宿主管控的字段不会被业务代码覆盖。
+- `protocols` 非空时，服务端需要在握手响应中选择并返回匹配的子协议，否则连接可能失败。
+- 同一个页面多次调用会创建多个独立连接，已创建的旧连接不会因为新连接自动关闭。
+
+#### Properties
+
+##### header?
+
+> `optional` **header**: `Record`\<`string`, `string`\>
+
+WebSocket 握手阶段携带的 HTTP Header。
+
+适合放置业务自定义 Header，例如鉴权 token、trace id、客户端能力标识等。
+`referer` 由宿主侧统一生成和管理，不应依赖该字段被业务传入值覆盖。
+
+##### protocols?
+
+> `optional` **protocols**: `string`[]
+
+WebSocket 子协议数组。
+
+会作为握手请求中的 `Sec-WebSocket-Protocol` 候选值传给服务端。
+如果传入非空数组，服务端需要选择其中一个协议并在握手响应中返回；
+服务端不支持或不返回匹配协议时，连接可能被宿主判定为创建失败。
+
+##### url
+
+> **url**: `string`
+
+WebSocket 连接地址。
+
+需要包含协议、域名、路径和可选 query，例如 `wss://example.com/socket?room=1`。
+如果地址为空或不是字符串，本 API 会返回 `readyState` 为 `undefined` 的 [SocketTask](doubao-apps-sdk-open-api.md#sockettask)，
+并异步触发 `onError`。
+
+***
+
 ### ConnectWifiParams
 
 连接 Wi-Fi 的请求参数。
@@ -5938,6 +6046,362 @@ HTTP 状态码。
 
 ***
 
+### SocketTask
+
+通过 [connectSocket](doubao-apps-sdk-open-api.md#connectsocket) 获取的 WebSocket 任务实例。
+
+`SocketTask` 表示单条 WebSocket 连接的控制对象。它负责发送数据、关闭连接，
+并通过事件回调接收连接状态、服务端消息和错误通知。`connectSocket` 返回时连接
+仍可能处于创建中，调用方应先注册 `onOpen`、`onError`、`onClose`、`onMessage`
+等回调，再根据 `onOpen` 事件发送业务数据。
+
+#### Methods
+
+##### close()
+
+> **close**(`params`?): `void`
+
+关闭 WebSocket 连接。
+
+调用后会尝试向宿主侧发起关闭动作，并把 `readyState` 置为 `SocketTask.CLOSING`。
+最终关闭完成时触发 `onClose`；关闭动作失败时触发 `onError`。
+
+###### Parameters
+
+• **params?**: [`SocketTaskCloseParams`](doubao-apps-sdk-open-api.md#sockettaskcloseparams)
+
+###### Returns
+
+`void`
+
+##### onClose()
+
+> **onClose**(`callback`): `void`
+
+监听 WebSocket 与服务器连接断开的事件。
+
+主动关闭、服务端关闭、宿主侧回收连接都可能触发该回调。
+回调触发后当前任务会从内部连接表移除。
+
+###### Parameters
+
+• **callback**
+
+###### Returns
+
+`void`
+
+##### onError()
+
+> **onError**(`callback`): `void`
+
+监听 WebSocket 发生错误的事件。
+
+连接创建、发送、关闭或底层通道出现异常时触发。
+该回调只表示发生错误，不等同于连接一定已经关闭；是否关闭应结合 `readyState`
+或后续 `onClose` 事件判断。
+
+###### Parameters
+
+• **callback**
+
+###### Returns
+
+`void`
+
+##### onMessage()
+
+> **onMessage**(`callback`): `void`
+
+监听 WebSocket 接收到服务器发送信息的事件。
+
+服务端每下发一条消息都会触发一次回调。消息内容通过 `event.data` 返回，
+类型可能是 `string` 或 `ArrayBuffer`。
+
+###### Parameters
+
+• **callback**
+
+###### Returns
+
+`void`
+
+##### onOpen()
+
+> **onOpen**(`callback`): `void`
+
+监听 WebSocket 连接服务器成功的事件。
+
+可以注册多个回调。连接成功后触发回调，并携带握手响应 Header、协议类型等信息。
+通常应在该回调中或之后调用 [SocketTask.send](doubao-apps-sdk-open-api.md#send)。
+
+###### Parameters
+
+• **callback**
+
+###### Returns
+
+`void`
+
+##### send()
+
+> **send**(`params`): `void`
+
+通过 WebSocket 连接发送数据。
+
+该方法只发起发送动作，不返回发送结果。建议在 `readyState === SocketTask.OPEN`
+或收到 `onOpen` 事件后调用；如果连接未就绪、数据编码失败或宿主侧发送失败，
+会触发 `onError`。
+
+###### Parameters
+
+• **params**: [`SocketTaskSendParams`](doubao-apps-sdk-open-api.md#sockettasksendparams)
+
+###### Returns
+
+`void`
+
+#### Properties
+
+##### CLOSED
+
+> `readonly` **CLOSED**: `3`
+
+表示 Socket 连接已关闭。
+
+进入该状态后，该任务不会再收到新的消息，也不应继续调用 `send`。
+
+##### CLOSING
+
+> `readonly` **CLOSING**: `2`
+
+表示 Socket 连接关闭中。
+
+调用 [SocketTask.close](doubao-apps-sdk-open-api.md#close-1) 后、本地等待宿主侧完成关闭流程时通常处于该状态。
+
+##### CONNECTING
+
+> `readonly` **CONNECTING**: `0`
+
+表示 Socket 正在连接。
+
+`connectSocket` 刚返回且宿主尚未完成握手时通常处于该状态。
+
+##### OPEN
+
+> `readonly` **OPEN**: `1`
+
+表示 Socket 连接已经打开。
+
+进入该状态后可以调用 [SocketTask.send](doubao-apps-sdk-open-api.md#send) 发送数据。
+
+##### readyState
+
+> `readonly` **readyState**: `undefined` \| `number`
+
+当前 Socket 连接状态 code。
+
+可与 `CONNECTING`、`OPEN`、`CLOSING`、`CLOSED` 常量比较。
+如果因为参数错误等原因导致连接请求没有被宿主成功创建，则为 `undefined`。
+
+***
+
+### SocketTaskCloseEvent
+
+WebSocket 关闭事件。
+
+当前连接被主动关闭、服务端关闭或宿主侧因异常回收连接时触发。
+触发后 `readyState` 会变为 `SocketTask.CLOSED`，该 `SocketTask` 不应再继续发送数据。
+
+#### Properties
+
+##### code?
+
+> `optional` **code**: `number`
+
+关闭状态码。
+
+可能来自调用 [SocketTask.close](doubao-apps-sdk-open-api.md#close-1) 时传入的 `code`，也可能来自服务端或宿主侧。
+
+##### errMsg?
+
+> `optional` **errMsg**: `string`
+
+错误信息。
+
+非正常关闭时宿主侧可能通过该字段补充失败原因；正常关闭时通常为空。
+
+##### protocolType?
+
+> `optional` **protocolType**: `string`
+
+当前连接使用的网络传输层协议。
+
+该字段由宿主侧返回，部分运行环境可能不提供。
+
+##### reason?
+
+> `optional` **reason**: `string`
+
+关闭原因。
+
+可能来自调用 [SocketTask.close](doubao-apps-sdk-open-api.md#close-1) 时传入的 `reason`，也可能来自服务端或宿主侧。
+
+##### socketType?
+
+> `optional` **socketType**: `string`
+
+宿主侧使用的 WebSocket 实现类型。
+
+该字段由宿主侧返回，部分运行环境可能不提供。
+
+***
+
+### SocketTaskCloseParams
+
+[SocketTask.close](doubao-apps-sdk-open-api.md#close-1) 的参数。
+
+`close` 用于主动关闭当前 WebSocket 连接。调用后 `readyState` 会先进入
+`SocketTask.CLOSING`，最终关闭结果通过 `onClose` 或 `onError` 回调通知。
+
+#### Properties
+
+##### code?
+
+> `optional` **code**: `number`
+
+关闭连接状态码。
+
+不传时由宿主侧按正常关闭处理，通常等价于 `1000`。
+常见值包括：
+- `1000`: 正常关闭；
+- `1001`: 因页面进入后台、宿主回收连接等原因关闭。
+
+##### reason?
+
+> `optional` **reason**: `string`
+
+连接被关闭的原因。
+
+该字段会随关闭帧传递给服务端，是否被服务端记录或回传取决于服务端实现。
+
+***
+
+### SocketTaskErrorEvent
+
+WebSocket 错误事件。
+
+连接创建失败、发送失败、主动关闭失败、底层通道异常等错误都会通过该事件通知。
+如果错误发生在连接创建阶段，`readyState` 会变为 `undefined` 或 `SocketTask.CLOSED`。
+
+#### Properties
+
+##### errMsg
+
+> **errMsg**: `string`
+
+错误信息。
+
+由前端参数校验、编码过程或宿主侧返回的失败原因组成，可直接用于日志上报。
+
+***
+
+### SocketTaskMessageEvent
+
+WebSocket 收到服务端消息事件。
+
+服务端通过当前连接下发消息时触发。文本消息会以 `string` 形式返回；
+二进制消息会尽量还原为 `ArrayBuffer`。
+
+#### Properties
+
+##### data
+
+> **data**: `string` \| `ArrayBuffer`
+
+收到的服务端消息。
+
+- 文本消息返回 `string`；
+- 二进制消息返回 `ArrayBuffer`。
+
+如果运行环境不支持二进制解码能力，底层传回的内容可能仍保持字符串形式。
+
+##### protocolType?
+
+> `optional` **protocolType**: `string`
+
+当前消息所属连接使用的协议。
+
+该字段由宿主侧返回，部分运行环境可能不提供。
+
+##### socketType?
+
+> `optional` **socketType**: `string`
+
+宿主侧使用的 WebSocket 实现类型。
+
+该字段由宿主侧返回，部分运行环境可能不提供。
+
+***
+
+### SocketTaskOpenEvent
+
+WebSocket 连接成功事件。
+
+当宿主侧完成 WebSocket 握手并进入 open 状态后触发。
+收到该事件后，调用方可以开始通过 [SocketTask.send](doubao-apps-sdk-open-api.md#send) 发送数据。
+
+#### Properties
+
+##### header
+
+> **header**: `Record`\<`string`, `string`\>
+
+WebSocket 握手响应中的 Response Header。
+
+不同平台对 Header key 的大小写处理可能不同，读取时建议按业务需要做兼容。
+
+##### protocolType?
+
+> `optional` **protocolType**: `string`
+
+当前连接使用的网络传输层协议。
+
+该字段由宿主侧返回，部分运行环境可能不提供。
+
+##### socketType?
+
+> `optional` **socketType**: `string`
+
+宿主侧使用的 WebSocket 实现类型。
+
+可能的值由宿主实现决定，例如传统 WebSocket 实现或宿主网络库实现；
+部分运行环境可能不提供。
+
+***
+
+### SocketTaskSendParams
+
+[SocketTask.send](doubao-apps-sdk-open-api.md#send) 的参数。
+
+`send` 只负责向已打开的 WebSocket 连接写入一条消息，不返回 Promise。
+发送失败、连接未就绪或底层通道异常时，会通过同一个 `SocketTask` 的 `onError` 回调通知。
+
+#### Properties
+
+##### data
+
+> **data**: `string` \| `ArrayBuffer`
+
+需要发送给服务端的数据。
+
+- 传入 `string` 时按文本消息发送；
+- 传入 `ArrayBuffer` 时按二进制消息发送，内部会编码后交给宿主侧处理。
+
+建议只在 `onOpen` 回调触发后调用 `send`，此时 `readyState` 通常为 `SocketTask.OPEN`。
+
+***
+
 ### StartAccelerometerParams
 
 开始监听加速度的请求参数。

package/dist/template-starter/package.json

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