@doubao-apps/ai 0.0.33 → 0.0.34

package/dist/skills/doubao-apps-dev/references/reference/open-api/07-/350/276/223/345/205/245.md

@@ -0,0 +1,63 @@
+# Open API: 输入
+
+键盘和输入框选区能力。
+
+[返回目录](./README.md) | [返回速查](../open-api.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [hideKeyboard](#hidekeyboard) | 收起当前键盘。 |
+| [getSelectedTextRange](#getselectedtextrange) | 获取当前输入框的选区范围。 |
+
+## API 详情
+
+<a id="hidekeyboard"></a>
+### hideKeyboard()
+
+收起当前键盘。
+
+## 代码示例
+
+```typescript
+import { hideKeyboard } from '@doubao-apps/framework/api';
+
+await hideKeyboard({});
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回 `Promise<object>`。
+
+<a id="getselectedtextrange"></a>
+### getSelectedTextRange()
+
+获取当前输入框的选区范围。
+
+## 代码示例
+
+```typescript
+import { getSelectedTextRange } from '@doubao-apps/framework/api';
+
+const { start, end } = await getSelectedTextRange();
+
+console.log(start, end);
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回 `Promise<GetSelectedTextRangeResult>`。
+
+|字段名|类型|说明|
+|---|---|---|
+|end|`number`|选区结束位置。|
+|start|`number`|选区起始位置。|

package/dist/skills/doubao-apps-dev/references/reference/open-api/08-/347/275/221/347/273/234.md

@@ -0,0 +1,124 @@
+# Open API: 网络
+
+网络请求与 WebSocket。
+
+[返回目录](./README.md) | [返回速查](../open-api.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [request](#request) | 发起网络请求。 |
+| [connectSocket](#connectsocket) | 创建一个 WebSocket 连接，并返回可操作该连接的 SocketTask。 |
+
+## API 详情
+
+<a id="request"></a>
+### request()
+
+发起网络请求。
+
+`request` 本身不接受泛型参数；如需业务数据类型，请读取 `result.data` 后再做类型收窄或断言。
+
+## 代码示例
+
+```typescript
+import { request } from '@doubao-apps/framework/api';
+
+const result = await request({
+  url: 'https://postman-echo.com/post',
+  method: 'POST',
+  dataType: 'json',
+  header: { 'content-type': 'application/json' },
+  data: { hello: 'world' }
+});
+
+console.log(result.statusCode, result.data);
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|data|`string \| Record<string, any> \| ArrayBuffer`|否|请求体数据。<br><br>传给服务器的数据最终会是 `String` 或 `ArrayBuffer`：<br>- 若 `data` 是 `string` 或 `ArrayBuffer`，直接使用；<br>- 若 `header['content-type']` 是 `application/x-www-form-urlencoded`，会被编码为 query string，例如：`encodeURIComponent(k)=encodeURIComponent(v)`；<br>- 若 `header['content-type']` 是 `application/json`，会执行 JSON 序列化；<br>- 若 `data` 是普通对象且未命中上述类型，也会执行 JSON 序列化；<br>- 其他类型会调用 `toString()`|
+|dataType|`"string" \| "json"`|否|期望返回的数据格式。<br>- `json`: 尝试按 JSON 解析；<br>- `string`: 按字符串返回。|
+|header|`Record<string, string>`|否|请求 Header。|
+|method|`RequestMethod`|否|请求方法。|
+|url|`string`|是|请求地址，需为完整的 **HTTPS** URL。|
+
+**类型说明**
+
+- `RequestMethod`: `"GET" | "POST" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE" | "CONNECT"`
+
+## 返回值
+
+返回一个 Promise，解析为 RequestResponse。
+
+|字段名|类型|说明|
+|---|---|---|
+|data|`string \| Record<string, any> \| ArrayBuffer`|响应数据，类型由 `dataType` 决定。|
+|header|`Record<string, string>`|HTTP 响应头。|
+|statusCode|`number`|HTTP 状态码。|
+
+<a id="connectsocket"></a>
+### connectSocket()
+
+创建一个 WebSocket 连接，并返回可操作该连接的 SocketTask。
+
+该 API 会同步返回 `SocketTask`，但连接创建本身是异步过程。调用方应先在返回的
+`SocketTask` 上注册事件回调，再等待 `onOpen` 表示连接可用。后续发送消息使用
+`SocketTask.send`，关闭连接使用 `SocketTask.close`。
+
+## 代码示例
+
+```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);
+});
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|header|`Record<string, string>`|否|WebSocket 握手阶段携带的 HTTP Header。<br><br>适合放置业务自定义 Header，例如鉴权 token、trace id、客户端能力标识等。<br>`referer` 由宿主侧统一生成和管理，不应依赖该字段被业务传入值覆盖。|
+|protocols|`string[]`|否|WebSocket 子协议数组。<br><br>会作为握手请求中的 `Sec-WebSocket-Protocol` 候选值传给服务端。<br>如果传入非空数组，服务端需要选择其中一个协议并在握手响应中返回；<br>服务端不支持或不返回匹配协议时，连接可能被宿主判定为创建失败。|
+|url|`string`|是|WebSocket 连接地址。<br><br>需要包含协议、域名、路径和可选 query，例如 `wss://example.com/socket?room=1`。<br>如果地址为空或不是字符串，本 API 会返回 `readyState` 为 `undefined` 的 SocketTask，<br>并异步触发 `onError`。|
+
+## 返回值
+
+当前 WebSocket 连接对应的 SocketTask。
+
+|字段名|类型|说明|
+|---|---|---|
+|CLOSED|`3`|表示 Socket 连接已关闭。<br><br>进入该状态后，该任务不会再收到新的消息，也不应继续调用 `send`。|
+|CLOSING|`2`|表示 Socket 连接关闭中。<br><br>调用 SocketTask.close 后、本地等待宿主侧完成关闭流程时通常处于该状态。|
+|CONNECTING|`0`|表示 Socket 正在连接。<br><br>`connectSocket` 刚返回且宿主尚未完成握手时通常处于该状态。|
+|OPEN|`1`|表示 Socket 连接已经打开。<br><br>进入该状态后可以调用 SocketTask.send 发送数据。|
+|readyState|`number \| undefined`|当前 Socket 连接状态 code。<br><br>可与 `CONNECTING`、`OPEN`、`CLOSING`、`CLOSED` 常量比较。<br>如果因为参数错误等原因导致连接请求没有被宿主成功创建，则为 `undefined`。|
+|close|`(params?: SocketTaskCloseParams) => void`|-|
+|onClose|`(callback: Function) => void`|-|
+|onError|`(callback: Function) => void`|-|
+|onMessage|`(callback: Function) => void`|-|
+|onOpen|`(callback: Function) => void`|-|
+|send|`(params: SocketTaskSendParams) => void`|-|

package/dist/skills/doubao-apps-dev/references/reference/open-api/09-/345/252/222/344/275/223.md

@@ -0,0 +1,192 @@
+# Open API: 媒体
+
+图片选择、预览、保存、压缩和信息读取。
+
+[返回目录](./README.md) | [返回速查](../open-api.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [saveImageToPhotosAlbum](#saveimagetophotosalbum) | 保存图片到系统相册。 |
+| [previewImage](#previewimage) | 预览图片。 |
+| [getImageInfo](#getimageinfo) | 获取图片信息。 |
+| [chooseImage](#chooseimage) | 选择图片。 |
+| [compressImage](#compressimage) | 压缩图片。 |
+
+## API 详情
+
+<a id="saveimagetophotosalbum"></a>
+### saveImageToPhotosAlbum()
+
+保存图片到系统相册。
+
+需要先确保应用已具备写入系统相册的权限。
+
+## 代码示例
+
+```typescript
+import { saveImageToPhotosAlbum } from '@doubao-apps/framework/api';
+
+await saveImageToPhotosAlbum({
+  filePath: '/path/to/image.png'
+});
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|filePath|`string`|是|需要保存的图片文件路径。支持临时文件路径或持久文件路径，不支持网络图片路径。|
+
+## 返回值
+
+返回 `Promise<object>`。
+
+<a id="previewimage"></a>
+### previewImage()
+
+预览图片。
+
+## 代码示例
+
+```typescript
+import { previewImage } from '@doubao-apps/framework/api';
+
+await previewImage({
+  urls: ['https://example.com/a.png', 'https://example.com/b.png'],
+  current: 0
+});
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|current|`string \| number`|否|当前显示图片的链接，或当前显示图片的下标，不填则默认为 urls 中的第一张|
+|referrerPolicy|`string`|否|预览页使用的 Referrer 策略。|
+|showmenu|`boolean`|否|是否显示长按菜单，菜单支持保存图片至本地相册|
+|urls|`string[]`|是|需要预览的图片链接列表。|
+
+## 返回值
+
+返回 `Promise<object>`。
+
+<a id="getimageinfo"></a>
+### getImageInfo()
+
+获取图片信息。
+
+## 代码示例
+
+```typescript
+import { getImageInfo } from '@doubao-apps/framework/api';
+
+const { width, height, path } = await getImageInfo({
+  src: '/tmp/image.png'
+});
+
+console.log(width, height, path);
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|src|`string`|是|图片路径，可以是相对路径、临时文件路径、存储文件路径或网络图片路径。|
+
+## 返回值
+
+返回 `Promise<GetImageInfoResult>`。
+
+|字段名|类型|说明|
+|---|---|---|
+|height|`number`|图片原始高度，单位 px，不考虑旋转。|
+|orientation|`ImageOrientation`|图片方向。|
+|path|`string`|图片的本地路径。|
+|type|`string`|图片格式。|
+|width|`number`|图片原始宽度，单位 px，不考虑旋转。|
+
+**类型说明**
+
+- `ImageOrientation`: `"up" | "up-mirrored" | "down" | "down-mirrored" | "left-mirrored" | "right" | "right-mirrored" | "left"`
+
+<a id="chooseimage"></a>
+### chooseImage()
+
+选择图片。
+
+## 代码示例
+
+```typescript
+import { chooseImage } from '@doubao-apps/framework/api';
+
+const { tempFilePaths } = await chooseImage({
+  count: 1,
+  sourceType: ['album']
+});
+
+console.log(tempFilePaths);
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|count|`number`|否|最多可选图片张数。|
+|imageId|`string`|否|H5 场景下可复用的 input 元素 ID。|
+|sizeType|`ChooseImageSizeType[]`|否|允许返回的图片尺寸类型。|
+|sourceType|`ChooseImageSourceType[]`|否|允许选择的图片来源。|
+
+**类型说明**
+
+- `ChooseImageSizeType`: `"original" | "compressed"`
+- `ChooseImageSourceType`: `"album" | "camera" | "user" | "environment"`
+
+## 返回值
+
+返回 `Promise<ChooseImageResult>`。
+
+|字段名|类型|说明|
+|---|---|---|
+|tempFilePaths|`string[]`|图片临时文件路径列表。|
+|tempFiles|`ChooseImageFile[]`|图片临时文件信息列表。|
+|tempFiles[].originalFileObj|`File`|原始浏览器 File 对象。|
+|tempFiles[].path|`string`|本地临时文件路径。|
+|tempFiles[].size|`number`|文件大小，单位 B。|
+|tempFiles[].type|`string`|文件 MIME 类型。|
+
+<a id="compressimage"></a>
+### compressImage()
+
+压缩图片。
+
+## 代码示例
+
+```typescript
+import { compressImage } from '@doubao-apps/framework/api';
+
+const { tempFilePath } = await compressImage({
+  src: '/tmp/image.png',
+  quality: 80
+});
+
+console.log(tempFilePath);
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|compressedHeight|`number`|否|压缩后图片高度，单位 px。|
+|compressedWidth|`number`|否|压缩后图片宽度，单位 px。|
+|quality|`number`|否|压缩质量，范围 0 - 100，仅对 jpg 生效。|
+|src|`string`|是|图片路径。|
+
+## 返回值
+
+返回 `Promise<CompressImageResult>`。
+
+|字段名|类型|说明|
+|---|---|---|
+|tempFilePath|`string`|压缩后图片的临时文件路径。|