@doubao-apps/create 0.0.25 → 0.0.26

package/dist/template-starter/.ai/reference/open-api/06-network.md

@@ -0,0 +1,298 @@
+# Open API: Network
+
+网络请求、网络类型和本机局域网 IP。
+
+[返回目录](./README.md) | [返回速查](../open-api.md)
+
+## 速查
+
+| API | 签名 | 用途 | 参数类型 | 结果类型 | 注意点 |
+| --- | --- | --- | --- | --- | --- |
+| [`request`](#request) | `request(params): Promise<RequestResponse>` | 发起网络请求 | `params: RequestParams` | `Promise<RequestResponse>` | 返回 statusCode、header 和 data |
+| [`getNetworkType`](#getnetworktype) | `getNetworkType(params?): Promise<GetNetworkTypeResult>` | 获取当前网络类型 | `params?: GetNetworkTypeParams` | `Promise<GetNetworkTypeResult>` | - |
+| [`onNetworkStatusChange`](#onnetworkstatuschange) | `onNetworkStatusChange(handler): () => void` | 监听网络状态变化事件 | `handler` | `() => void` | 返回取消监听函数 |
+| [`getLocalIPAddress`](#getlocalipaddress) | `getLocalIPAddress(params?): Promise<GetLocalIPAddressResult>` | 获取局域网 IP 地址 | `params?` | `Promise<GetLocalIPAddressResult>` | - |
+
+## API 详情
+
+<a id="request"></a>
+### request()
+
+> **request**(`params`): `Promise`\<[`RequestResponse`](#requestresponse)\>
+
+发起网络请求。
+
+#### Parameters
+
+• **params**: [`RequestParams`](#requestparams)
+
+请求参数，字段见 [RequestParams](#requestparams)。
+
+#### Returns
+
+`Promise`\<[`RequestResponse`](#requestresponse)\>
+
+返回一个 Promise，解析为 [RequestResponse](#requestresponse)。
+
+#### Remarks
+
+返回 statusCode、header 和 data。
+
+#### Example
+
+```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);
+```
+
+<a id="getnetworktype"></a>
+### getNetworkType()
+
+> **getNetworkType**(`params`?): `Promise`\<[`GetNetworkTypeResult`](#getnetworktyperesult)\>
+
+获取当前网络类型。
+
+#### Parameters
+
+• **params?**: [`GetNetworkTypeParams`](#getnetworktypeparams)
+
+#### Returns
+
+`Promise`\<[`GetNetworkTypeResult`](#getnetworktyperesult)\>
+
+返回一个 Promise，解析为 [GetNetworkTypeResult](#getnetworktyperesult)。
+
+#### Example
+
+```ts
+import { getNetworkType } from '@doubao-apps/framework/api';
+
+const result = await getNetworkType();
+console.log(result.networkType);
+```
+
+<a id="onnetworkstatuschange"></a>
+### onNetworkStatusChange()
+
+> **onNetworkStatusChange**(`handler`): () => `void`
+
+监听网络状态变化事件。
+
+#### Parameters
+
+• **handler**
+
+#### Returns
+
+`Function`
+
+返回取消当前监听函数的函数。
+
+##### Returns
+
+`void`
+
+#### Example
+
+```ts
+import { onNetworkStatusChange } from '@doubao-apps/framework/api';
+
+const off = onNetworkStatusChange(({ isConnected, networkType }) => {
+  console.log(isConnected, networkType);
+});
+
+off();
+```
+
+<a id="getlocalipaddress"></a>
+### getLocalIPAddress()
+
+> **getLocalIPAddress**(`params`?): `Promise`\<[`GetLocalIPAddressResult`](#getlocalipaddressresult)\>
+
+获取局域网 IP 地址。
+
+#### Parameters
+
+• **params?**
+
+#### Returns
+
+`Promise`\<[`GetLocalIPAddressResult`](#getlocalipaddressresult)\>
+
+## 相关类型
+
+<a id="requestparams"></a>
+### RequestParams
+
+网络请求参数。
+
+#### Properties
+
+##### data?
+
+> `optional` **data**: `string` \| `Record`\<`string`, `any`\> \| `ArrayBuffer`
+
+请求体数据。
+
+传给服务器的数据最终会是 `String` 或 `ArrayBuffer`：
+- 若 `data` 是 `string` 或 `ArrayBuffer`，直接使用；
+- 若 `header['content-type']` 是 `application/x-www-form-urlencoded`，会被编码为 query string，例如：`encodeURIComponent(k)=encodeURIComponent(v)`；
+- 若 `header['content-type']` 是 `application/json`，会执行 JSON 序列化；
+- 若 `data` 是普通对象且未命中上述类型，也会执行 JSON 序列化；
+- 其他类型会调用 `toString()`
+
+##### dataType?
+
+> `optional` **dataType**: `"string"` \| `"json"`
+
+期望返回的数据格式。
+- `json`: 尝试按 JSON 解析；
+- `string`: 按字符串返回。
+
+###### Default
+
+```ts
+"json"
+```
+
+##### header?
+
+> `optional` **header**: `Record`\<`string`, `string`\>
+
+请求 Header。
+
+###### Default
+
+```ts
+{"content-type": "application/json"}
+```
+
+##### method?
+
+> `optional` **method**: [`RequestMethod`](#requestmethod)
+
+请求方法。
+
+###### Default
+
+```ts
+"GET"
+```
+
+##### url
+
+> **url**: `string`
+
+请求地址，需为完整的 **HTTPS** URL。
+
+<a id="requestresponse"></a>
+### RequestResponse
+
+网络请求返回结果。
+
+#### Properties
+
+##### data?
+
+> `optional` **data**: `string` \| `Record`\<`string`, `any`\> \| `ArrayBuffer`
+
+响应数据，类型由 `dataType` 决定。
+
+##### header
+
+> **header**: `Record`\<`string`, `string`\>
+
+HTTP 响应头。
+
+##### statusCode
+
+> **statusCode**: `number`
+
+HTTP 状态码。
+
+<a id="requestmethod"></a>
+### RequestMethod
+
+> **RequestMethod**: `"GET"` \| `"POST"` \| `"PUT"` \| `"DELETE"` \| `"HEAD"` \| `"OPTIONS"` \| `"TRACE"` \| `"CONNECT"`
+
+<a id="getnetworktypeparams"></a>
+### GetNetworkTypeParams
+
+获取网络类型的请求参数。
+
+当前无需传入任何字段，预留扩展位。
+
+<a id="getnetworktyperesult"></a>
+### GetNetworkTypeResult
+
+获取网络类型的返回结果。
+
+#### Properties
+
+##### hasSystemProxy?
+
+> `optional` **hasSystemProxy**: `boolean`
+
+设备是否使用了系统代理。
+
+##### networkType
+
+> **networkType**: [`NetworkType`](#networktype-2)
+
+当前网络类型。
+
+##### signalStrength?
+
+> `optional` **signalStrength**: `number`
+
+信号强弱，单位 dBm。
+
+##### weakNet?
+
+> `optional` **weakNet**: `boolean`
+
+是否处于弱网环境。
+
+<a id="networktype-2"></a>
+<a id="networktype"></a>
+### NetworkType
+
+> **NetworkType**: `"wifi"` \| `"2g"` \| `"3g"` \| `"4g"` \| `"5g"` \| `"unknown"` \| `"none"`
+
+网络类型。
+
+- `wifi` - Wi-Fi 网络
+- `2g` - 2G 网络
+- `3g` - 3G 网络
+- `4g` - 4G 网络
+- `5g` - 5G 网络
+- `unknown` - Android 下不常见的网络类型
+- `none` - 无网络
+
+<a id="getlocalipaddressresult"></a>
+### GetLocalIPAddressResult
+
+获取局域网 IP 的返回结果。
+
+#### Properties
+
+##### localIp
+
+> **localIp**: `string`
+
+本机局域网 IP 地址。
+
+##### netmask?
+
+> `optional` **netmask**: `string`
+
+子网掩码。

package/dist/template-starter/.ai/reference/open-api/07-media.md

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