Hello

Welcome

This is a simple Scripting HTTP server.

Partial Content

``` 加载一个 `UIImage` 对象。 - 适合轻量展示 - 不适合用于文件级处理或资源保真 *** ### loadLivePhoto ```ts loadLivePhoto(): Promise ``` 加载一个 `LivePhoto` 对象。 - 包含图片与配对视频 - 适合展示、保存或进一步处理 *** ### loadURL ```ts loadURL(): Promise ``` 加载一个 URL 字符串。 - 可能是网页 URL - 也可能是文件 URL *** ### loadText ```ts loadText(): Promise ``` 加载纯文本内容。 - 支持 plain text - 富文本会被降级为纯文本 *** ### loadData ```ts loadData(type: UTType): Promise ``` 加载指定类型的原始二进制数据。 - 数据会整体加载进内存 - 适合 JSON、配置文件、小体积资源 - 不适合视频、音频等大文件 *** ## 文件路径加载（安全作用域）文件路径的加载需要遵循系统的安全限制，所有文件访问都必须在指定的回调作用域内完成。 *** ### loadFilePath ```ts loadFilePath(type: UTType): Promise ``` 加载指定类型的文件路径，如果文件不存在或无法加载，返回 `null`。如果可以加载，文件会被复制到应用组的临时目录中，并返回文件路径。如果你不再需要文件，请删除它。示例： ```ts const filePath = provider.loadFilePath("public.movie") ``` *** ## 创建 ItemProvider ### fromUIImage ```ts ItemProvider.fromUIImage(image: UIImage): ItemProvider ``` 从 `UIImage` 创建 `ItemProvider`。 - 仅提供静态图片能力 - 不包含 Live Photo 或原始资源信息 *** ### fromText ```ts ItemProvider.fromText(text: string): ItemProvider ``` 从文本创建 `ItemProvider`。 *** ### fromURL ```ts ItemProvider.fromURL(url: string): ItemProvider | null ``` 从 URL 字符串创建 `ItemProvider`。 - URL 不合法时返回 `null` - 支持网页 URL 与文件 URL *** ### fromFilePath ```ts ItemProvider.fromFilePath(path: string): ItemProvider ``` 从文件路径创建 `ItemProvider`。 - 保留原始文件 - 适合视频、音频、文档等资源 - 支持原地访问能力判断 *** ## 使用建议 - 使用 `hasItemConforming` 进行内容类型判断 - 使用对象加载方法进行 UI 展示 - 使用文件路径加载方法处理大文件 - 文件路径只能在 `perform` 回调作用域内访问 - 不应在回调外部延迟访问安全作用域文件 --- url: /doc_v2/zh/guide/Utilities/OAuth2.md --- # OAuth2 `OAuth2` 类用于在脚本中实现 OAuth 2.0 授权流程。它支持标准的授权码流程、PKCE（Proof Key for Code Exchange）、访问令牌续期及多种配置选项。 *** ## 构造函数 ```ts new OAuth2(options: { consumerKey: string consumerSecret: string authorizeUrl: string accessTokenUrl?: string responseType: string contentType?: string }) ``` ### 参数说明 | 参数名 | 类型 | 是否必填 | 说明 | | -------------- | ------ | ---- | -------------------------------------------------------- | | consumerKey | string | 是 | 应用的客户端 ID（Client ID）或 Consumer Key。 | | consumerSecret | string | 是 | 应用的客户端密钥（Client Secret）。 | | authorizeUrl | string | 是 | 用于跳转用户授权的地址。 | | accessTokenUrl | string | 否 | 获取访问令牌（Access Token）的地址，若不提供则使用 authorizeUrl。 | | responseType | string | 是 | 一般为 `"code"`，表示使用授权码流程。 | | contentType | string | 否 | 请求令牌时使用的内容类型，默认值为 `"application/x-www-form-urlencoded"`。 | ### 抛出错误 - 当配置参数无效或实例化失败时抛出错误。 *** ## 属性 ### `accessTokenBasicAuthentification: boolean` 是否使用 Basic 认证方式发送获取访问令牌的请求。默认值为 `false`。 *** ### `allowMissingStateCheck: boolean` 是否禁用 `state` 参数校验（CSRF 保护）。**谨慎使用**，默认值为 `false`。 *** ### `encodeCallbackURL: boolean` 是否对回调地址进行 URL 编码。某些服务商要求必须编码。默认值为 `true`。 *** ### `encodeCallbackURLQuery: boolean` 是否对整个回调地址的查询参数进行编码。部分服务如 Imgur 要求此值为 `false`。默认值为 `true`。 *** ## 方法 ### `authorize(options): Promise` 发起 OAuth2 授权流程。将打开一个浏览器窗口，供用户登录并授权。 ```ts authorize(options: { callbackURL?: string scope: string state: string parameters?: Record headers?: Record } & ({ codeVerifier: string codeChallenge: string codeChallengeMethod: string } | { codeVerifier?: never codeChallenge?: never codeChallengeMethod?: never })): Promise ``` #### 参数说明 | 参数名 | 类型 | 是否必填 | 说明 | | ------------------- | ----------------------- | ---- | ------------------------------------------------- | | callbackURL | string | 否 | 授权成功后的回调地址，默认为 `scripting://oauth_callback/脚本名称`。 | | scope | string | 是 | 空格分隔的权限列表。 | | state | string | 是 | 防止 CSRF 攻击的随机字符串。 | | parameters | Record\ | 否 | 附加的授权请求参数。 | | headers | Record\ | 否 | 附加的请求头。 | | codeVerifier | string | 条件必填 | PKCE 流程中使用的随机码。 | | codeChallenge | string | 条件必填 | 由 `codeVerifier` 生成的哈希值。 | | codeChallengeMethod | `"plain"` \| `"S256"` | 条件必填 | PKCE 中的 challenge 加密方法，默认使用 `"S256"`。 | #### 返回值 - 返回一个包含授权结果的 `OAuthCredential` 对象。 #### 抛出错误 - 若用户拒绝授权或网络错误将抛出异常。 #### 示例 ```ts const oauth = new OAuth2({ consumerKey: '你的客户端ID', consumerSecret: '你的客户端密钥', authorizeUrl: 'https://provider.com/oauth/authorize', accessTokenUrl: 'https://provider.com/oauth/token', responseType: 'code' }) const credential = await oauth.authorize({ scope: 'profile email', state: 'secure_random_state', callbackURL: Script.createOAuthCallbackURLScheme('my_oauth_script') }) console.log(credential.oauthToken) ``` *** ### `renewAccessToken(options): Promise` 使用刷新令牌（refresh token）重新获取访问令牌。 ```ts renewAccessToken(options: { refreshToken: string parameters?: Record headers?: Record }): Promise ``` #### 参数说明 | 参数名 | 类型 | 是否必填 | 说明 | | ------------ | ----------------------- | ---- | -------------- | | refreshToken | string | 是 | 上一次授权返回的刷新令牌。 | | parameters | Record\ | 否 | 额外的 POST 请求参数。 | | headers | Record\ | 否 | 自定义请求头。 | #### 返回值 - 返回新的 `OAuthCredential` 对象。 #### 抛出错误 - 若刷新失败（如刷新令牌已过期），则抛出错误。 #### 示例 ```ts const newCredential = await oauth.renewAccessToken({ refreshToken: oldCredential.oauthRefreshToken }) console.log(newCredential.oauthToken) ``` *** ## OAuthCredential 类型定义授权成功后返回的凭证对象包含以下字段： ```ts type OAuthCredential = { oauthToken: string oauthTokenSecret: string oauthRefreshToken: string oauthTokenExpiresAt: number | null oauthVerifier: string version: string signatureMethod: string } ``` ### 字段说明 | 字段名 | 类型 | 说明 | | ------------------- | -------------- | ---------------------------------------- | | oauthToken | string | 用于访问资源的 Access Token。 | | oauthTokenSecret | string | 与访问令牌配套使用的 Token Secret，常用于 OAuth1.0 流程。 | | oauthRefreshToken | string | 用于获取新访问令牌的 Refresh Token。 | | oauthTokenExpiresAt | number \| null | 访问令牌的过期时间（Unix 毫秒时间戳），若无过期则为 `null`。 | | oauthVerifier | string | 在 PKCE 流程中使用的授权码验证器。 | | version | string | OAuth 协议版本（例如 `"2.0"`）。 | | signatureMethod | string | 请求签名方式（如 `"HMAC-SHA1"`、`"PLAINTEXT"`）。 | *** ## 使用建议 - 始终使用 `state` 参数防止 CSRF 攻击，除非明确关闭。 - 使用 `Script.createOAuthCallbackURLScheme(name)` 为脚本生成唯一回调地址。 - 若需要长期授权，请妥善保存 `oauthRefreshToken`。 - 对于公用客户端建议启用 PKCE 增强安全性。 --- url: /doc_v2/zh/guide/Utilities/Path.md --- # 文件路径工具 `Path` API 提供了一些实用函数，用于处理和转换文件与目录路径。它受到 Node.js 的 `path` 模块启发，提供了开发者熟悉的方法来高效地处理路径。 *** ## 概述 `Path` API 提供以下功能： - 规范化路径。 - 判断路径是否为绝对路径。 - 拼接路径段。 - 提取路径组件，例如目录名、基本名和扩展名。 - 将路径解析为结构化对象。它通过使用当前操作系统适合的路径分隔符，简化了跨平台的路径处理。 *** ### 静态方法 #### `Path.normalize(path: string): string` 通过解析 `..` 和 `.` 段，规范化给定的路径。 - **参数：** - `path`：要规范化的输入路径。 - **返回值：** - 一个规范化的路径字符串。 #### 示例： ```typescript const normalizedPath = Path.normalize('/foo/bar//baz/asdf/quux/..') console.log(normalizedPath) // '/foo/bar/baz/asdf' ``` *** #### `Path.isAbsolute(path: string): boolean` 判断给定路径是否为绝对路径。 - **参数：** - `path`：输入路径。 - **返回值：** - 如果路径是绝对路径，则返回 `true`，否则返回 `false`。 #### 示例： ```typescript console.log(Path.isAbsolute('/foo/bar')) // true console.log(Path.isAbsolute('foo/bar')) // false ``` *** #### `Path.join(...args: string[]): string` 将多个路径段拼接为一个路径，并进行规范化。 - **参数：** - `...args`：要拼接的路径段。 - **返回值：** - 一个规范化的路径字符串。 #### 示例： ```typescript const joinedPath = Path.join('/foo', 'bar', 'baz/asdf', 'quux', '..') console.log(joinedPath) // '/foo/bar/baz/asdf' ``` *** #### `Path.dirname(path: string): string` 返回路径的目录名。 - **参数：** - `path`：输入路径。 - **返回值：** - 目录名。 #### 示例： ```typescript console.log(Path.dirname('/foo/bar/baz/asdf/quux')) // '/foo/bar/baz/asdf' ``` *** #### `Path.basename(path: string, ext?: string): string` 返回路径的最后一部分，类似于 Unix 的 `basename` 命令。可选地移除文件扩展名。 - **参数：** - `path`：输入路径。 - `ext`（可选）：要移除的文件扩展名。 - **返回值：** - 路径的基本名。 #### 示例： ```typescript console.log(Path.basename('/foo/bar/baz/asdf/quux.html')) // 'quux.html' console.log(Path.basename('/foo/bar/baz/asdf/quux.html', '.html')) // 'quux' ``` *** #### `Path.extname(path: string): string` 返回路径的扩展名。 - **参数：** - `path`：输入路径。 - **返回值：** - 文件扩展名；如果没有扩展名，则返回空字符串。 #### 示例： ```typescript console.log(Path.extname('/foo/bar/baz/asdf/quux.html')) // '.html' console.log(Path.extname('/foo/bar/baz/asdf/quux')) // '' ``` *** #### `Path.parse(path: string): { root: string; dir: string; base: string; ext: string; name: string; }` 将路径解析为包含以下属性的对象： - `root`：路径的根目录。 - `dir`：目录名。 - `base`：包含扩展名的文件名。 - `ext`：文件扩展名。 - `name`：不带扩展名的文件名。 - **参数：** - `path`：输入路径。 - **返回值：** - 一个包含解析路径属性的对象。 #### 示例： ```typescript const parsed = Path.parse('/foo/bar/baz/asdf/quux.html') console.log(parsed) // { // root: '/', // dir: '/foo/bar/baz/asdf', // base: 'quux.html', // ext: '.html', // name: 'quux' // } ``` *** ## 常见用例 ### 规范化路径 ```typescript const normalizedPath = Path.normalize('./foo/bar/../baz') console.log(normalizedPath) // './foo/baz' ``` ### 检查路径是否为绝对路径 ```typescript console.log(Path.isAbsolute('/absolute/path')) // true console.log(Path.isAbsolute('relative/path')) // false ``` ### 拼接多个路径段 ```typescript const fullPath = Path.join('/home', 'user', 'documents', 'file.txt') console.log(fullPath) // '/home/user/documents/file.txt' ``` ### 提取文件名和扩展名 ```typescript const fileName = Path.basename('/path/to/file.txt') const fileExt = Path.extname('/path/to/file.txt') console.log(fileName) // 'file.txt' console.log(fileExt) // '.txt' ``` ### 解析路径 ```typescript const pathDetails = Path.parse('/path/to/file.txt') console.log(pathDetails) // { // root: '/', // dir: '/path/to', // base: 'file.txt', // ext: '.txt', // name: 'file' // } ``` *** ## 最佳实践 1. **使用规范化功能：** 始终规范化路径以确保跨平台的一致性。 2. **避免硬编码分隔符：** 使用类似 `join` 的方法代替直接拼接字符串 `/` 或 `\\`。 *** ## 完整示例 ```typescript import { Path } from 'scripting' function main() { const filePath = '/foo/bar/baz/asdf/quux.html' console.log("规范化路径:", Path.normalize(filePath)) console.log("是否为绝对路径:", Path.isAbsolute(filePath)) console.log("目录名:", Path.dirname(filePath)) console.log("基本名:", Path.basename(filePath)) console.log("扩展名:", Path.extname(filePath)) const parsedPath = Path.parse(filePath) console.log("解析路径:", parsedPath) const joinedPath = Path.join('/foo', 'bar', 'baz') console.log("拼接路径:", joinedPath) } main() ``` --- url: /doc_v2/zh/guide/Utilities/Request/FormData.md --- # 表单数据 `FormData` 类用于构造表单数据（`multipart/form-data`），以便在网络请求中上传文本字段或文件数据。它的行为与浏览器中的 **Fetch API FormData** 基本一致，但在 **Scripting app** 中进行了扩展以支持 `Data` 类型（原生二进制对象），从而更方便地上传文件或图片。你可以将 `FormData` 对象直接作为 `fetch()` 请求的 `body` 参数使用。系统会自动生成带有正确边界的 `multipart/form-data` 请求体。 *** ## 定义 ```ts class FormData { append(name: string, value: string): void append(name: string, value: Data, mimeType: string, filename?: string): void get(name: string): string | Data | null getAll(name: string): any[] has(name: string): boolean delete(name: string): void set(name: string, value: string): void set(name: string, value: Data, filename?: string): void forEach(callback: (value: any, name: string, parent: FormData) => void): void entries(): [string, any][] toJson(): Record } ``` *** ## 主要用途 - 构造带文本与文件混合的表单请求 - 用于文件上传接口（如图片、音频、文档等） - 代替 JSON 结构上传二进制文件或表单信息 *** ## 方法说明 ### `append(name: string, value: string): void` ### `append(name: string, value: Data, mimeType: string, filename?: string): void` 向表单中添加一个字段。可以用于添加文本字段或文件数据。 #### 参数说明 | 参数 | 类型 | 说明 | | | ------------ | ------------ | --------------------------------------------- | ----------------------------- | | **name** | `string` | 字段名称。 | | | **value** | `string` | `Data` | 字段值，可以是字符串或 `Data` 对象（二进制文件）。 | | **mimeType** | `string` | 文件的 MIME 类型（如 `"image/png"`）。仅在传入 `Data` 时需要。 | | | **filename** | `string`（可选） | 文件名，仅在上传文件时使用。 | | #### 示例 ```tsx const form = new FormData() form.append("username", "Tom") form.append("file", Data.fromFile("/path/to/image.png"), "image/png", "avatar.png") ``` *** ### `set(name: string, value: string): void` ### `set(name: string, value: Data, filename?: string): void` 设置一个字段的值。若该字段已存在，则会被覆盖。与 `append()` 的区别是：`set()` 仅保留一个值，而 `append()` 可重复添加同名字段。 #### 示例 ```tsx const form = new FormData() form.set("message", "Hello world") form.set("file", Data.fromFile("/path/to/file.txt"), "text/plain", "note.txt") ``` *** ### `get(name: string): string | Data | null` 获取指定字段的值。如果字段不存在，则返回 `null`。 #### 示例 ```tsx const form = new FormData() form.append("title", "My Post") console.log(form.get("title")) // 输出: "My Post" ``` *** ### `getAll(name: string): any[]` 获取同名字段的所有值（如果使用了多次 `append()`）。 #### 示例 ```tsx const form = new FormData() form.append("tag", "swift") form.append("tag", "ios") form.append("tag", "scripting") console.log(form.getAll("tag")) // ["swift", "ios", "scripting"] ``` *** ### `has(name: string): boolean` 检查表单中是否存在指定名称的字段。 #### 示例 ```tsx const form = new FormData() form.append("username", "Tom") console.log(form.has("username")) // true console.log(form.has("password")) // false ``` *** ### `delete(name: string): void` 删除指定名称的字段及其所有值。 #### 示例 ```tsx const form = new FormData() form.append("title", "Hello") form.append("file", Data.fromFile("/path/to/file.txt"), "text/plain") form.delete("file") ``` *** ### `forEach(callback: (value: any, name: string, parent: FormData) => void): void` 遍历所有表单字段，执行回调函数。 #### 示例 ```tsx const form = new FormData() form.append("user", "Tom") form.append("age", "25") form.forEach((value, name) => { console.log(`${name}: ${value}`) }) ``` *** ### `entries(): [string, any][]` 返回一个由 `[name, value]` 组成的键值对数组。 #### 示例 ```tsx const form = new FormData() form.append("username", "Tom") form.append("age", "25") console.log(form.entries()) // [["username", "Tom"], ["age", "25"]] ``` *** ### `toJson(): Record` 将表单数据转换为普通的 JavaScript 对象，用于调试或日志输出。 ⚠️ 注意：如果表单中包含文件（`Data` 类型），此方法不会输出二进制内容，而是显示为占位符信息。 #### 示例 ```tsx const form = new FormData() form.append("name", "Tom") form.append("photo", Data.fromFile("/path/to/avatar.png"), "image/png", "avatar.png") console.log(form.toJson()) // { name: "Tom", photo: "[Data: image/png]" } ``` *** ## 使用示例 ### 示例 1：上传文件 ```tsx const form = new FormData() form.append("file", Data.fromFile("/path/to/image.png"), "image/png", "avatar.png") form.append("userId", "1234") const response = await fetch("https://api.example.com/upload", { method: "POST", body: form, }) console.log(await response.json()) ``` *** ### 示例 2：同时上传多个文件 ```tsx const form = new FormData() form.append("files", Data.fromFile("/path/to/photo1.jpg"), "image/jpeg", "photo1.jpg") form.append("files", Data.fromFile("/path/to/photo2.jpg"), "image/jpeg", "photo2.jpg") await fetch("https://api.example.com/multi-upload", { method: "POST", body: form, }) ``` *** ### 示例 3：构造包含文本与文件的复合请求 ```tsx const form = new FormData() form.append("title", "Travel Memories") form.append("description", "A collection of my travel photos.") form.append("cover", Data.fromFile("/path/to/cover.png"), "image/png", "cover.png") const response = await fetch("https://example.com/uploadPost", { method: "POST", body: form, }) console.log(await response.text()) ``` *** ### 示例 4：遍历并调试表单内容 ```tsx const form = new FormData() form.append("name", "Alice") form.append("file", Data.fromFile("/path/to/file.txt"), "text/plain", "file.txt") form.forEach((value, name) => { console.log(`${name}:`, value instanceof Data ? "Binary Data" : value) }) ``` *** ## 与其他类的关系 | 类名 | 说明 | | -------------- | ----------------------------------------------------------- | | **`fetch()`** | 可直接使用 `FormData` 实例作为请求体。系统会自动设置请求头为 `multipart/form-data`。 | | **`Data`** | 用于表示文件或图片等二进制内容，作为 `FormData` 字段值传入。 | | **`Request`** | 可通过 `RequestInit.body` 设置 `FormData` 实例。 | | **`Response`** | 可使用 `response.formData()` 将响应解析为 `FormData`。 | *** ## 注意事项 - **自动设置 Content-Type**：使用 `FormData` 时，`fetch()` 会自动设置正确的 `Content-Type`（带边界）。不要手动覆盖。 - **同名字段**：支持使用 `append()` 为同一字段名添加多个值。 - **文件上传**：上传文件时需传入 MIME 类型，否则默认可能被识别为 `application/octet-stream`。 - **JSON 转换限制**：`toJson()` 仅用于调试显示，不适合用于真实数据传输。 *** ## 小结 `FormData` 是 **Scripting 网络请求体系中用于构造 multipart/form-data 请求的核心类**，具备以下特性： - 支持文本与文件混合上传 - 与 `fetch()` 无缝集成 - 支持 `Data` 类型文件传递 - 提供便利的 `forEach()`、`entries()`、`toJson()` 等辅助方法 - 完全兼容 Web 标准的 FormData 行为 --- url: /doc_v2/zh/guide/Utilities/Request/Headers.md --- # 请求头（Headers） `Headers` 类用于管理 HTTP 请求与响应的头部信息。它与浏览器 Fetch API 中的同名类保持一致，但在 **Scripting** 环境中提供了更友好的接口方法和 JSON 化能力，以方便脚本中对网络请求进行调试与序列化。 `Headers` 对象可以在以下场景中使用： - 构造请求时，通过 `RequestInit.headers` 设置请求头 - 从 `Response.headers` 中读取响应头 - 在脚本逻辑中动态添加、修改或删除头部字段 *** ## 定义 ```ts class Headers { constructor(init?: HeadersInit) append(name: string, value: string): void get(name: string): string | null has(name: string): boolean set(name: string, value: string): void delete(name: string): void forEach(callback: (value: string, name: string) => void): void keys(): string[] values(): string[] entries(): [string, string][] toJson(): Record } ``` *** ## HeadersInit 类型 `Headers` 的构造函数支持多种初始化格式： ```ts type HeadersInit = [string, string][] | Record | Headers ``` 你可以使用以下任意形式创建头部对象： ```tsx new Headers([["Content-Type", "application/json"]]) new Headers({ "Authorization": "Bearer token" }) new Headers(existingHeaders) ``` *** ## 构造函数 ### `new Headers(init?: HeadersInit)` 创建一个新的 `Headers` 对象。可选参数 `init` 用于以已有的头部结构初始化实例。 #### 参数说明 | 参数 | 类型 | 说明 | | -------- | ------------- | -------------------------------- | | **init** | `HeadersInit` | 初始头部数据，可为对象、数组或另一个 `Headers` 实例。 | *** ## 方法说明 ### `append(name: string, value: string): void` 向头部中添加一个字段。如果该字段已存在，则追加新的值（不会覆盖旧值）。 #### 示例 ```tsx const headers = new Headers() headers.append("Accept", "application/json") headers.append("Accept", "text/plain") // 此时 Accept 拥有两个值 ``` *** ### `set(name: string, value: string): void` 设置一个头部字段。如果该字段已存在，则会覆盖旧值。 #### 示例 ```tsx const headers = new Headers() headers.set("Content-Type", "application/json") headers.set("Authorization", "Bearer token-123") ``` *** ### `get(name: string): string | null` 获取指定头部字段的值。若字段不存在，返回 `null`。 #### 示例 ```tsx const headers = new Headers({ "Content-Type": "application/json" }) console.log(headers.get("Content-Type")) // 输出: application/json ``` *** ### `has(name: string): boolean` 判断指定字段是否存在。 #### 示例 ```tsx const headers = new Headers({ "Accept": "application/json" }) console.log(headers.has("Accept")) // true console.log(headers.has("Authorization")) // false ``` *** ### `delete(name: string): void` 删除指定的头部字段。 #### 示例 ```tsx const headers = new Headers({ "Accept": "application/json", "Cache-Control": "no-cache" }) headers.delete("Cache-Control") ``` *** ### `forEach(callback: (value: string, name: string) => void): void` 遍历所有头部字段并执行回调。 #### 示例 ```tsx const headers = new Headers({ "Accept": "application/json", "User-Agent": "ScriptingApp/1.0" }) headers.forEach((value, name) => { console.log(`${name}: ${value}`) }) ``` *** ### `keys(): string[]` 返回所有头部名称的数组。 ```tsx const headers = new Headers({ "Accept": "application/json", "User-Agent": "Scripting" }) console.log(headers.keys()) // ["accept", "user-agent"] ``` > 注意：头部字段名不区分大小写，返回的名称将被标准化为小写。 *** ### `values(): string[]` 返回所有头部字段的值数组。 ```tsx const headers = new Headers({ "Accept": "application/json", "User-Agent": "Scripting" }) console.log(headers.values()) // ["application/json", "Scripting"] ``` *** ### `entries(): [string, string][]` 以键值对数组形式返回所有头部字段。 #### 示例 ```tsx const headers = new Headers({ "Accept": "application/json", "Cache-Control": "no-cache" }) console.log(headers.entries()) // [["accept", "application/json"], ["cache-control", "no-cache"]] ``` *** ### `toJson(): Record` 将所有头部字段转换为普通对象格式，方便序列化或调试输出。 #### 示例 ```tsx const headers = new Headers({ "Content-Type": "application/json", "Authorization": "Bearer token" }) console.log(headers.toJson()) // { "content-type": "application/json", "authorization": "Bearer token" } ``` *** ## 使用示例 ### 示例 1：在请求中设置自定义 Headers ```tsx const headers = new Headers() headers.set("Content-Type", "application/json") headers.set("Authorization", "Bearer token-xyz") const response = await fetch("https://api.example.com/user", { method: "POST", headers, body: JSON.stringify({ name: "Tom" }) }) ``` *** ### 示例 2：读取响应头部信息 ```tsx const response = await fetch("https://example.com/data") console.log("Content-Type:", response.headers.get("Content-Type")) console.log("Server:", response.headers.get("Server")) ``` *** ### 示例 3：转换为 JSON 用于日志或持久化 ```tsx const response = await fetch("https://example.com/api") console.log("Response Headers:", response.headers.toJson()) ``` *** ### 示例 4：判断响应是否包含特定字段 ```tsx const response = await fetch("https://example.com/info") if (response.headers.has("Set-Cookie")) { console.log("响应包含 Cookie 设置") } ``` *** ## 与其他类的关系 | 类名 | 说明 | | -------------- | ------------------------------------------------ | | **`Request`** | 通过 `RequestInit.headers` 设置请求头。 | | **`Response`** | 可通过 `response.headers` 访问响应头。 | | **`fetch()`** | 请求与响应过程都会使用 `Headers` 实例来封装头部数据。 | | **`Cookie`** | 与 `Set-Cookie` 头对应的解析结果在 `response.cookies` 中访问。 | *** ## 注意事项 - **字段名大小写不敏感**：所有头部名称在内部会被标准化为小写形式。 - **多值字段处理**：使用 `append()` 方法可以为同一字段添加多个值，例如用于 `Accept` 或 `Cookie` 等字段。 - **安全性**：某些系统保留字段（如 `Host`、`Connection`）可能会被 iOS 网络层忽略或重写。 - **序列化输出**：使用 `toJson()` 可便于调试或日志记录，不影响实际请求头发送。 *** ## 小结 `Headers` 是 **Scripting 网络请求体系** 中的基础组件之一，提供了灵活的接口来： - 添加、修改或删除 HTTP 头部 - 以多种方式读取与遍历响应头 - 在脚本环境中实现与 Web 标准一致的行为 - 支持 JSON 化与日志输出 --- url: /doc_v2/zh/guide/Utilities/Request/ReadableStream.md --- # 可读流 `ReadableStream` 表示一个 **可读的数据流（data stream）**，用于逐步读取数据而不是一次性加载全部内容。在 **Scripting app** 中，`ReadableStream` 通常用于： - 处理网络响应中的流式数据（如 `Response.body`） - 实现大文件的分块读取或实时下载 - 支持长连接或持续推送的数据（如 SSE、分块 JSON、日志流）与标准 Web API 一致，Scripting 的 `ReadableStream` 允许异步迭代（`for await...of`）以及通过读取器 (`ReadableStreamDefaultReader`) 手动读取流内容。 *** ## 定义 ```ts class ReadableStream { constructor(underlyingSource?: UnderlyingSource) get locked(): boolean cancel(reason?: any): Promise getReader(): ReadableStreamDefaultReader tee(): [ReadableStream, ReadableStream] } ``` *** ## 基本概念 - `ReadableStream` 代表一个“流式可消费的数据源”。 - 它不会立即持有全部数据，而是按需从源（网络、文件、生成器等）获取。 - 每个流只能由一个读取器（reader）读取，一旦被锁定 (`locked = true`)，必须释放或取消后才能再次读取。 *** ## 属性说明 ### `locked: boolean` 指示当前流是否已被读取器（reader）锁定。若为 `true`，则其他代码无法再调用 `getReader()` 或消费该流。 #### 示例 ```tsx const reader = response.body.getReader() console.log(response.body.locked) // true ``` *** ## 方法说明 ### `getReader(): ReadableStreamDefaultReader` 返回一个 `ReadableStreamDefaultReader` 实例，用于逐步读取流中的数据块（chunk）。每次调用 `reader.read()` 会返回一个 Promise，解析为 `{ value, done }` 对象。 #### 示例 ```tsx const reader = response.body.getReader() while (true) { const { done, value } = await reader.read() if (done) break console.log("Received chunk:", value) } ``` *** ### `cancel(reason?: any): Promise` 取消流的读取操作。传入的 `reason` 可用于描述取消原因。 #### 示例 ```tsx const reader = response.body.getReader() await response.body.cancel("User aborted reading") ``` *** ### `tee(): [ReadableStream, ReadableStream]` 将当前流复制成两个新的流。每个分支都可独立消费数据，但需注意内存开销。 #### 示例 ```tsx const [stream1, stream2] = response.body.tee() const reader1 = stream1.getReader() const reader2 = stream2.getReader() ``` *** ## ReadableStreamDefaultReader（读取器）当通过 `getReader()` 获取读取器后，你可以手动控制数据的读取过程。 ### 读取器定义 ```ts interface ReadableStreamDefaultReader { read(): Promise<{ value: T; done: boolean }> releaseLock(): void cancel(reason?: any): Promise } ``` #### 方法说明： | 方法 | 说明 | | ------------------- | ------------------------------------------------------------ | | **read()** | 读取下一个数据块（chunk），返回 `{ value, done }`。当 `done = true` 时，流已结束。 | | **releaseLock()** | 释放读取器，使流可被其他消费者重新读取。 | | **cancel(reason?)** | 取消流读取。 | #### 示例：读取响应流数据 ```tsx const reader = response.body.getReader() while (true) { const { done, value } = await reader.read() if (done) break // 处理每个 Data 对象（chunk） const text = value.toRawString() console.log("Chunk:", text) } reader.releaseLock() ``` *** ## 与 `Response` 的关系 `Response.body` 属性是一个 `ReadableStream`，可用于流式读取响应内容。 ### 示例：实时处理网络响应 ```tsx const response = await fetch("https://example.com/stream") const reader = response.body.getReader() while (true) { const { done, value } = await reader.read() if (done) break console.log("Received:", value.toRawString()) } ``` 这种方式可在 **响应尚未完全结束时** 实时处理部分数据，非常适合： - 实时日志输出 - 大文件下载进度控制 - AI/LLM 流式生成内容（如 ChatGPT 的逐字输出） *** ## 与 `Data` 的关系在 `Scripting` 中，流的每个块（chunk）通常是一个 `Data` 实例。你可以使用 `Data` 提供的方法（如 `.toRawString()`、`.toUint8Array()`）读取或转换二进制内容。 #### 示例：将流数据保存到文件 ```tsx const reader = response.body.getReader() const chunks: Data[] = [] while (true) { const { done, value } = await reader.read() if (done) break chunks.push(value) } const fileData = Data.combine(chunks) FileManager.write(fileData, "/local/download.bin") ``` *** ## 示例：使用异步迭代器读取流 `ReadableStream` 支持异步迭代 (`for await...of`)，可简化读取逻辑： ```tsx for await (const chunk of response.body) { console.log("Chunk size:", chunk.size) } ``` 此语法会自动处理 `done` 状态，代码更简洁直观。 *** ## 使用场景 | 场景 | 示例 | | ------------ | ----------------------------- | | **大文件下载** | 按块读取网络响应并写入本地文件，避免内存占用过大。 | | **AI 输出流接收** | 实时接收服务器的推送内容（如 ChatGPT 流式响应）。 | | **本地流式处理** | 对本地文件或输入流实现增量读取或实时处理。 | *** ## 注意事项 - **单次锁定**：一个 `ReadableStream` 在被读取器锁定后，不能被多个消费者同时读取。 - **内存管理**：流式处理有助于降低内存占用，但应及时释放或取消读取器以防资源泄漏。 - **错误处理**：读取过程中出现错误（如网络断开）会导致 `read()` Promise 拒绝，应使用 `try...catch` 捕获。 - **Data 类型约定**：在 `Response.body` 中，流的每个块类型为 `Data`，而不是普通字符串或字节数组。 *** ## 小结 `ReadableStream` 是 **Scripting 数据流架构的核心组件**，为开发者提供了高效的流式数据读取方式： - 支持异步逐块读取 - 可与 `fetch()`、`Response`、`Data` 无缝集成 - 适用于实时处理、分块下载、长连接流等高级场景 - 完全兼容 Web 标准的 Streams API --- url: /doc_v2/zh/guide/Utilities/Request/Request & RequestInit.md --- # Request 和 RequestInit `Request` 类表示一次 HTTP 请求的完整配置。它可作为 `fetch()` 方法的参数使用，也可用于克隆、修改或重试请求。在 Scripting 中，`Request` 的行为与浏览器 Fetch API 中的同名接口一致，但额外支持了原生扩展功能，包括： - 支持二进制 `Data` 类型作为请求体 - 支持自定义重定向处理 - 支持请求超时、取消、与调试标签 - 支持允许不安全请求（HTTP 请求） *** ## 类定义 ```ts class Request { url: string; method: string; headers: Headers; body?: Data | FormData | string | ArrayBuffer; allowInsecureRequest?: boolean; handleRedirect?: (newRequest: RedirectRequest) => Promise; shouldAllowRedirect?: (newRequest: Request) => Promise; // 已废弃 timeout?: DurationInSeconds; signal?: AbortSignal; cancelToken?: CancelToken; // 已废弃 debugLabel?: string; constructor(input: string | Request, init?: RequestInit); clone(): Request; } ``` *** ## 构造函数 ### `new Request(input: string | Request, init?: RequestInit)` 创建一个新的 `Request` 实例。可通过字符串 URL 或现有的 `Request` 对象来构造。 #### 参数 \| 参数 | 类型 | 说明 | \| --------- | ------------- | ------------------------------------------------ | ------------------------------------------------- | \| **input** | `string` | `Request` | 要请求的 URL，或一个现有的 Request 对象用于克隆。 | \| **init** | `RequestInit` | 可选的初始化参数，用于配置请求的行为（见下文）。 | *** ## 属性 | 属性名 | 类型 | 说明 | | ------------------------ | ------------------------------------------------------------------- | ----------------------------------------------- | | **url** | `string` | 请求的完整 URL。 | | **method** | `string` | 请求方法（默认 `"GET"`）。 | | **headers** | `Headers` | 请求头部对象，可通过 `.get()`、`.set()`、`.append()` 等方法操作。 | | **body** | `Data` \| `FormData` \| `string` \| `ArrayBuffer` \| `undefined` | 请求体，仅用于非 `GET` 或 `HEAD` 请求。 | | **allowInsecureRequest** | `boolean` | 是否允许使用 HTTP 明文请求（默认 `false`）。 | | **handleRedirect** | `(newRequest: RedirectRequest) => Promise` | 自定义重定向逻辑；返回 `null` 表示阻止重定向。 | | **shouldAllowRedirect** | `(newRequest: Request) => Promise` | 已废弃。旧版重定向控制回调。 | | **timeout** | `number` | 请求超时时间（单位：秒）。超时会自动中止请求。 | | **signal** | `AbortSignal` | 用于中止请求的信号，由 `AbortController` 创建。 | | **cancelToken** | `CancelToken` | 已废弃。旧版取消机制，请改用 `signal`。 | | **debugLabel** | `string` | 调试标签，会在日志面板中显示以方便追踪。 | *** ## 方法 ### `clone(): Request` 创建并返回当前请求对象的副本。克隆后的对象可安全修改其属性（如 headers、body）而不影响原始请求。 #### 示例 ```tsx const req1 = new Request("https://api.example.com/user", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ name: "Alice" }), }); const req2 = req1.clone(); console.log(req2.method); // "POST" ``` *** ## 使用示例 ### 示例 1：创建一个简单的 Request 对象 ```tsx const request = new Request("https://api.example.com/data", { method: "GET", headers: { Accept: "application/json", }, debugLabel: "Fetch User Data", }); const response = await fetch(request); const result = await response.json(); console.log(result); ``` *** ### 示例 2：带请求体的 POST 请求 ```tsx const request = new Request("https://api.example.com/upload", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ fileId: "abc123" }), timeout: 15, }); const response = await fetch(request); console.log(await response.text()); ``` *** ### 示例 3：克隆并修改请求 ```tsx const base = new Request("https://api.example.com/posts", { method: "POST", headers: { "Content-Type": "application/json" }, }); const cloned = base.clone(); cloned.headers.set("Authorization", "Bearer token-123"); cloned.debugLabel = "Authorized Upload"; await fetch(cloned); ``` *** \##RequestInit 类型 `RequestInit` 是一个用于配置请求参数的对象类型，常用于 `fetch()` 或 `Request` 构造函数中。它与浏览器的标准 Fetch API 相同，但 Scripting 扩展了若干字段。 *** ## 类型定义 ```ts type RequestInit = { method?: string; headers?: HeadersInit; body?: Data | FormData | string | ArrayBuffer; allowInsecureRequest?: boolean; handleRedirect?: (newRequest: RedirectRequest) => Promise; shouldAllowRedirect?: (newRequest: Request) => Promise; // 已废弃 timeout?: DurationInSeconds; signal?: AbortSignal; cancelToken?: CancelToken; // 已废弃 debugLabel?: string; }; ``` *** ## 字段说明 | 字段名 | 类型 | 说明 | | | ------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------ | - | | **method** | `string` | HTTP 方法，如 `"GET"`, `"POST"`, `"PUT"`, `"DELETE"`，默认 `"GET"`。 | | | **headers** | `HeadersInit` | 请求头部信息，可以是：`Headers` 对象、普通对象 `{key: value}`、或 `[key, value][]` 数组。 | | | **body** | `Data` \| `FormData` \| `string` \| `ArrayBuffer` | 请求体，仅在非 `GET` / `HEAD` 请求中使用。 | | | **allowInsecureRequest** | `boolean` | 是否允许发送 HTTP 请求。默认 `false`。 | | | **handleRedirect** | `(newRequest: RedirectRequest) => Promise` | 自定义重定向回调。返回新的请求对象以继续，返回 `null` 以阻止跳转。 | | | **shouldAllowRedirect** | `(newRequest: Request) => Promise` | 已废弃。旧的布尔型重定向控制回调。 | | | **timeout** | `number` | 请求超时时间（秒），超时后会自动中止请求。 | | | **signal** | `AbortSignal` | 中止信号，可由 `AbortController` 触发，用于主动取消请求。 | | | **cancelToken** | `CancelToken` | 已废弃。旧版取消机制，请使用 `signal` 替代。 | | | **debugLabel** | `string` | 调试标签，在日志面板中显示，用于标识请求。 | | *** ## 与 `fetch()` 的关系 `RequestInit` 是 `fetch()` 的第二个参数，用于定义请求配置： ```tsx const response = await fetch("https://example.com/data", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ id: 123 }), timeout: 10, debugLabel: "Upload JSON", }); ``` *** ## 与其他类的关系 | 类名 | 用途 | | ------------------------------------- | -------------------------------------------- | | **`Headers`** | 管理请求头部的集合，可与 `headers` 字段一起使用。 | | **`Data`** | 表示二进制数据，可作为请求体（body）上传文件或原始字节数据。 | | **`FormData`** | 用于构造 multipart/form-data 表单请求。 | | **`AbortController` / `AbortSignal`** | 用于在请求过程中主动取消网络操作。 | | **`CancelToken`** | 旧版取消机制，仅为兼容保留。 | | **`RedirectRequest`** | 当发生重定向时传入 `handleRedirect` 回调的参数，包含新请求的详细信息。 | *** ## 示例 ### 示例 1：使用自定义重定向回调 ```tsx const response = await fetch("https://example.com/start", { handleRedirect: async (newRequest) => { console.log("收到重定向:", newRequest.url); if (newRequest.url.includes("blocked")) return null; return newRequest; }, }); ``` *** ### 示例 2：允许不安全请求 ```tsx const response = await fetch("http://insecure.example.com/data", { allowInsecureRequest: true, }); console.log(await response.text()); ``` *** ### 示例 3：带调试标签的请求 ```tsx await fetch("https://example.com/api/ping", { debugLabel: "Ping Request", }); // 调试面板中将显示标签 “Ping Request” ``` *** 以下是 **`handleRedirect` 回调中 `RedirectRequest` 接口的中文说明文档**，可直接插入至 `Request` 类文档的相关部分，用于解释自定义重定向逻辑的参数结构和用法。 *** ## RedirectRequest 接口说明当请求发生 **重定向 (Redirect)** 时，若在 `Request` 或 `RequestInit` 中设置了 `handleRedirect` 回调函数，系统会在跳转前调用该回调。 `handleRedirect` 的参数类型为 `RedirectRequest`，用于描述即将执行的重定向请求的完整信息。你可以在回调中检查该对象的属性，并决定是否允许继续重定向，或修改请求后再继续。 *** ### 接口定义 ```ts interface RedirectRequest { method: string; url: string; headers: Record; cookies: Cookie[]; body?: Data; timeout?: number; } ``` *** ### 字段说明 | 字段 | 类型 | 说明 | | ----------- | ------------------------ | --------------------------------------------- | | **method** | `string` | 即将执行的重定向请求方法（例如 `"GET"`、`"POST"`）。 | | **url** | `string` | 重定向目标的完整 URL。 | | **headers** | `Record` | 该重定向请求的 HTTP 头部信息。你可以根据需要修改或记录这些头部。 | | **cookies** | `Cookie[]` | 当前请求中携带的 Cookie 列表，类型与 `Response.cookies` 一致。 | | **body** | `Data`（可选） | 若为非 `GET` 请求，则包含请求体数据（例如表单或二进制数据）。 | | **timeout** | `number`（可选） | 请求的超时时间（单位：秒）。 | *** ### 使用场景通过 `handleRedirect` 回调，你可以： - 检查重定向目标地址是否安全或符合业务逻辑。 - 修改重定向请求（如添加自定义头部、调整方法或携带 Token）。 - 阻止不必要或可疑的重定向。当回调返回： - 一个 `RedirectRequest` 对象 → 表示允许重定向，并使用你返回的对象继续请求。 - `null` → 表示阻止此次重定向，`fetch()` 将在当前响应结束。 *** ### 示例：拦截与控制重定向请求 ```tsx const response = await fetch("https://example.com/start", { handleRedirect: async (redirect) => { console.log("即将重定向至:", redirect.url); // 如果跳转到外部域名，则阻止 if (!redirect.url.startsWith("https://example.com")) { console.warn("阻止外部重定向:", redirect.url); return null; } // 向重定向请求添加授权头 redirect.headers["Authorization"] = "Bearer my-token"; return redirect; }, }); ``` *** ### 示例：修改重定向请求方法与体 ```tsx const response = await fetch("https://api.example.com/login", { handleRedirect: async (redirect) => { // 如果重定向目标为 POST 接口，则保持原始请求体 if (redirect.url.includes("/finalize")) { redirect.method = "POST"; redirect.body = Data.fromRawString("action=confirm", "utf-8"); } return redirect; }, }); ``` *** ### 注意事项 - 若未设置 `handleRedirect`，所有重定向将默认自动执行。 - 若设置了 `handleRedirect` 且返回 `null`，`fetch()` 不会继续跳转。 - 该机制不会自动携带 Cookie，需要手动在 `RedirectRequest.cookies` 中读取并决定是否传递。 - 修改 `RedirectRequest` 返回后，系统会基于修改后的内容重新发起请求。 *** ## 小结 `Request` 与 `RequestInit` 是 **Scripting 网络请求系统的核心基础**： - `Request` 封装了完整的 HTTP 请求对象，可复用、克隆与传递。 - `RequestInit` 定义请求参数，提供灵活的初始化方式。 - 二者与 `fetch()`、`Response`、`Headers`、`Data`、`FormData` 等类型紧密配合。 --- url: /doc_v2/zh/guide/Utilities/Request/Response.md --- # 响应（Response） `Response` 类表示通过 `fetch()` 方法发起的网络请求返回的响应结果。它提供了访问响应体（body）、头部（headers）、状态码、MIME 类型、以及服务器返回的 Cookies 的接口。在 **Scripting app** 中，`Response` 的设计基于标准 Fetch API，但进行了原生扩展，支持： - 原生级 **Cookie 访问与解析** - **二进制数据 (`Data`)** 支持 - **流式响应 (`ReadableStream`)** 读取 - 响应的 MIME 类型、编码信息与预期长度 - 完整兼容标准 Web Fetch 行为 *** ## 定义 ```ts class Response { readonly body: ReadableStream constructor(body: ReadableStream, init?: ResponseInit) get bodyUsed(): boolean get cookies(): Cookie[] json(): Promise text(): Promise data(): Promise bytes(): Promise arrayBuffer(): Promise formData(): Promise get status(): number get statusText(): string get headers(): Headers get ok(): boolean get url(): string get mimeType(): string | undefined get expectedContentLength(): number | undefined get textEncodingName(): string | undefined } ``` *** ## 属性说明 | 属性 | 类型 | 说明 | | ------------------------- | ---------------------- | ------------------------------------ | | **body** | `ReadableStream` | 响应体数据的可读流。 | | **bodyUsed** | `boolean` | 指示响应体是否已被读取。 | | **cookies** | `Cookie[]` | 服务器通过 `Set-Cookie` 返回的 Cookie 列表。 | | **status** | `number` | HTTP 状态码（如 `200`、`404`、`500`）。 | | **statusText** | `string` | 状态描述（如 `"OK"`、`"Not Found"`）。 | | **headers** | `Headers` | 响应头对象。 | | **ok** | `boolean` | 当状态码在 200–299 范围内时为 `true`。 | | **url** | `string` | 响应的最终 URL（可能经过重定向）。 | | **mimeType** | `string \| undefined` | 响应的 MIME 类型（如 `"application/json"`）。 | | **expectedContentLength** | `number \| undefined` | 响应体的预期长度（字节），由服务器提供。 | | **textEncodingName** | `string \| undefined` | 文本编码方式（如 `"utf-8"`）。 | *** ## 方法说明 ### `json(): Promise` 将响应体解析为 JSON 对象。 #### 示例 ```tsx const response = await fetch("https://api.example.com/user") const data = await response.json() console.log(data.name) ``` *** ### `text(): Promise` 将响应体读取为字符串。默认使用 UTF-8 编码，若服务器返回了编码信息则自动识别。 #### 示例 ```tsx const response = await fetch("https://example.com/message.txt") const text = await response.text() console.log(text) ``` *** ### `data(): Promise` 将响应体读取为二进制数据对象 `Data`，适合文件下载、图片处理、或转换为 Base64。 #### 示例 ```tsx const response = await fetch("https://example.com/image.png") const imageData = await response.data() FileManager.write(imageData, "/local/image.png") ``` *** ### `bytes(): Promise` 将响应体读取为字节数组。 #### 示例 ```tsx const response = await fetch("https://example.com/file.bin") const bytes = await response.bytes() console.log("Received", bytes.length, "bytes") ``` *** ### `arrayBuffer(): Promise` 将响应体读取为 `ArrayBuffer`，适合进行底层二进制操作。 #### 示例 ```tsx const response = await fetch("https://example.com/file") const buffer = await response.arrayBuffer() console.log(buffer.byteLength) ``` *** ### `formData(): Promise` 将响应体解析为 `FormData`（适用于 `multipart/form-data` 类型的响应）。 #### 示例 ```tsx const response = await fetch("https://example.com/form") const form = await response.formData() console.log(form.get("username")) ``` *** ## Cookies 支持 ### `cookies: Cookie[]` Scripting 的 `Response` 支持直接访问服务器返回的 `Set-Cookie` 信息。返回值为一个 `Cookie` 对象数组，每个元素包含完整的 Cookie 元数据。 #### Cookie 类型定义 ```ts interface Cookie { name: string value: string domain: string path: string isSecure: boolean isHTTPOnly: boolean isSessionOnly: boolean expiresDate?: Date | null } ``` | 字段 | 类型 | 说明 | | ----------------- | -------------- | ---------------------- | | **name** | `string` | Cookie 名称。 | | **value** | `string` | Cookie 值。 | | **domain** | `string` | 所属域名。 | | **path** | `string` | 作用路径。 | | **isSecure** | `boolean` | 是否仅通过 HTTPS 发送。 | | **isHTTPOnly** | `boolean` | 是否为 HTTP-only，无法被脚本访问。 | | **isSessionOnly** | `boolean` | 是否为会话 Cookie（无过期时间）。 | | **expiresDate** | `Date \| null` | 过期时间（若有设置）。 | *** ### 示例：读取响应中的 Cookies ```tsx const response = await fetch("https://example.com/login") for (const cookie of response.cookies) { console.log(`${cookie.name} = ${cookie.value}`) } ``` *** ### 示例：手动管理 Cookie（跨请求复用）默认情况下，**Scripting 的 `fetch()` 不会自动存储或携带 Cookie**。如果希望在多次请求中复用 Cookie，可以手动拼接 `Cookie` 头： ```tsx const response = await fetch("https://example.com/login") const cookies = response.cookies const cookieHeader = cookies.map(c => `${c.name}=${c.value}`).join("; ") const next = await fetch("https://example.com/dashboard", { headers: { "Cookie": cookieHeader }, }) ``` 这种方式让开发者能够像浏览器开发者工具一样 **完全掌控 Cookie 的发送与存储**。 *** ## 与其他类的关系 | 类名 | 说明 | | -------------- | --------------------------------- | | **`Request`** | 表示生成此响应的请求对象。 | | **`Headers`** | 用于访问响应头部信息。 | | **`Data`** | 表示响应体的二进制数据。 | | **`FormData`** | 表示 `multipart/form-data` 格式的表单响应。 | | **`Cookie`** | 表示服务器返回的单个 Cookie 对象。 | *** ## 使用示例 ### 示例 1：处理 JSON API 响应 ```tsx const response = await fetch("https://api.example.com/profile") if (response.ok) { const user = await response.json() console.log(user.email) } else { console.log("请求失败:", response.status, response.statusText) } ``` *** ### 示例 2：下载文件并保存 ```tsx const response = await fetch("https://example.com/photo.jpg") const fileData = await response.data() FileManager.write(fileData, "/local/photo.jpg") ``` *** ### 示例 3：读取服务器返回的 Cookies ```tsx const response = await fetch("https://example.com/login") for (const cookie of response.cookies) { console.log(`Cookie: ${cookie.name} = ${cookie.value}`) } ``` *** ### 示例 4：跨请求手动复用 Cookies ```tsx const loginResponse = await fetch("https://example.com/login", { method: "POST", body: JSON.stringify({ username: "Tom", password: "1234" }), headers: { "Content-Type": "application/json" }, }) // 读取 Cookie 并拼接成请求头 const cookieHeader = loginResponse.cookies.map(c => `${c.name}=${c.value}`).join("; ") // 携带 Cookie 发起新请求 const dashboard = await fetch("https://example.com/dashboard", { headers: { "Cookie": cookieHeader }, }) console.log(await dashboard.text()) ``` *** ### 示例 5：读取响应的元信息 ```tsx const response = await fetch("https://example.com/video.mp4") console.log("MIME 类型:", response.mimeType) console.log("预期长度:", response.expectedContentLength) ``` *** ## 小结 `Response` 是 Scripting 网络请求体系中最核心的组成部分之一，具有以下特性： - 完整兼容标准 Fetch API 行为 - 新增 **原生 Cookie 访问与控制** 能力 - 支持 `Data` 类型的 **二进制数据处理** - 支持响应流式读取、MIME 类型、编码与长度信息 - 可与 `Request`、`Headers`、`FormData`、`AbortController` 等类型无缝配合 --- url: /doc_v2/zh/guide/Utilities/Request/fetch.md --- # fetch 函数 `fetch()` 是用于发起 HTTP/HTTPS 网络请求的通用方法，返回一个表示响应 (`Response`) 的 Promise。它在 Scripting 中的行为与浏览器标准 Fetch API 基本一致，但进行了原生增强以更好地支持 iOS 本地运行环境（包括文件请求、Data 对象、FormData 上传、可控重定向、信号中止与调试标签等）。 *** ## 方法定义 ```ts function fetch(url: string, init?: RequestInit): Promise function fetch(request: Request): Promise ``` *** ## 参数说明 ### 1. `url: string` 要请求的资源地址。可以是： - 网络地址（例如 `"https://api.example.com/data"`） - 本地文件 URL（例如 `"file:///var/mobile/Containers/Data/Application/..."`） *** ### 2. `init?: RequestInit` 可选配置对象，用于自定义请求方法、头部、正文、超时、信号等。定义如下： ```ts type RequestInit = { method?: string; headers?: HeadersInit; body?: Data | FormData | string | ArrayBuffer; allowInsecureRequest?: boolean; handleRedirect?: (newRequest: RedirectRequest) => Promise; shouldAllowRedirect?: (newRequest: Request) => Promise; // 已废弃 timeout?: number; // 秒 signal?: AbortSignal; cancelToken?: CancelToken; // 已废弃 debugLabel?: string; } ``` #### 参数详解： | 参数 | 类型 | 说明 | | | ------------------------ | ------------------------------------------------------------------- | ---------------------------------------------------------------- | - | | **method** | `string` | 请求方法，如 `"GET"`, `"POST"`, `"PUT"`, `"DELETE"`。默认为 `"GET"`。 | | | **headers** | `HeadersInit` | 请求头，可以是 `Headers` 实例、键值对象或 `[key, value]` 数组。 | | | **body** | `Data` \| `FormData` \| `string` \| `ArrayBuffer` | 请求正文，仅对非 GET/HEAD 请求有效。 | | | **allowInsecureRequest** | `boolean` | 允许通过 HTTP 发送请求。默认 `false`。如果主进程运行在 HTTPS 环境下而 URL 为 HTTP，需要显式启用。 | | | **handleRedirect** | `(newRequest: RedirectRequest) => Promise` | 自定义重定向处理逻辑。如果返回 `null`，则阻止重定向。 | | | **shouldAllowRedirect** | `(newRequest: Request) => Promise` | 已废弃，用于兼容旧版重定向判断。 | | | **timeout** | `number` | 请求超时时间（秒）。超时将抛出 `AbortError`。 | | | **signal** | `AbortSignal` | 可通过 `AbortController` 控制的中止信号，用于主动取消请求。 | | | **cancelToken** | `CancelToken` | 已废弃，用于取消请求的旧机制。建议改用 `signal`。 | | | **debugLabel** | `string` | 调试标签，会显示在日志面板中，方便识别请求来源。 | | *** ## 返回值返回一个 `Promise` 对象。 `Response` 表示请求的响应数据。即使返回的 HTTP 状态码为 4xx 或 5xx，`fetch` 仍然会 **成功解析并返回 Response 对象**。只有当请求本身出错（如网络错误、无效 URL、超时、中止）时，Promise 才会被拒绝。 *** ## 异常与错误处理以下情况会触发 `Promise` 拒绝： | 错误类型 | 抛出条件 | | ------------ | -------------------------------- | | `TypeError` | URL 无效、协议不受支持或请求体类型不兼容。 | | `AbortError` | 请求被 `AbortController` 主动中止或超时触发。 | *** ## 示例 ### 示例 1：基础 GET 请求 ```tsx const response = await fetch("https://api.example.com/data") if (response.ok) { const json = await response.json() console.log(json) } else { console.log("请求失败:", response.status) } ``` *** ### 示例 2：POST 请求（JSON） ```tsx const response = await fetch("https://api.example.com/posts", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ title: "Hello", content: "World" }), }) const result = await response.json() console.log(result) ``` *** ### 示例 3：上传文件（FormData） ```tsx const form = new FormData() form.append("file", Data.fromFile("/path/to/image.png"), "image/png", "image.png") form.append("user", "Tom") const response = await fetch("https://api.example.com/upload", { method: "POST", body: form, }) console.log(await response.json()) ``` *** ### 示例 4：带超时的请求 ```tsx try { const response = await fetch("https://example.com/slow", { timeout: 10 }) const text = await response.text() console.log(text) } catch (err) { if (err.name === "AbortError") { console.log("请求超时被中止") } } ``` *** ### 示例 5：通过 AbortController 主动中止请求 ```tsx const controller = new AbortController() setTimeout(() => { controller.abort("用户取消了请求") }, 3000) try { const response = await fetch("https://example.com/large", { signal: controller.signal }) const data = await response.text() console.log(data) } catch (err) { if (err.name === "AbortError") { console.log("请求已被用户中止") } } ``` *** ### 示例 6：自定义重定向处理 ```tsx const response = await fetch("https://example.com/redirect", { handleRedirect: async (newRequest) => { console.log("收到重定向:", newRequest.url) if (newRequest.url.includes("forbidden")) { return null // 阻止跳转 } return newRequest // 允许继续 }, }) ``` *** ### 示例 7：调试标签与日志 ```tsx await fetch("https://api.example.com/status", { debugLabel: "Health Check", }) // 日志面板中将显示标签 "Health Check" ``` *** ## 与其他类的关系 | 类名 | 说明 | | ------------------------------------- | ---------------------------------------------------- | | **`Request`** | 可直接创建一个请求对象并传入 `fetch(request)`。用于重复请求或在多个函数间复用请求配置。 | | **`Response`** | 表示响应结果，可通过 `.json()`, `.text()`, `.data()` 等方法获取内容。 | | **`AbortController` / `AbortSignal`** | 用于主动中止请求。 | | **`FormData`** | 用于构造 multipart/form-data 请求体。 | | **`Headers`** | 管理请求与响应头部。 | | **`Data`** | 表示二进制数据，可用于请求体或响应数据处理。 | *** ## 特性说明 - **Cookie 管理**：Scripting 中的 `fetch` 默认不自动保存或携带 Cookie。响应中的 `Set-Cookie` 可通过 `response.cookies` 获取。 - **重定向行为**：默认自动跟随，除非设置了 `handleRedirect`。 - **并发安全**：多个并行请求相互独立。 - **文件支持**：可通过 `Data.fromFile()` 直接上传文件内容。 *** ## 小结 `fetch()` 是 Scripting 网络请求体系的核心方法，兼容标准 Web API，同时提供更强的原生扩展能力： - 支持本地文件访问 - 支持二进制 `Data` 类型 - 支持自定义重定向逻辑 - 支持中止与超时机制 - 支持调试标识与原生日志追踪 --- url: /doc_v2/zh/guide/Utilities/SSH/SFTP Client.md --- # SFTP 客户端 `SFTPClient` 用于通过 SSH 连接访问远程文件系统，基于 **SFTP 协议**。它提供目录操作、文件操作、路径解析等能力，并可通过 `openFile()` 获得更强大的 `SFTPFile` 对象执行读取、写入等低层操作。该类实例通常由： ```ts const sftp = await ssh.openSFTP(); ``` 返回。 *** ## 属性 ### `readonly isActive: boolean` 指示当前 SFTP 连接是否仍然有效。 - `true`：连接仍然处于活跃状态 - `false`：连接已关闭或发生错误 *** ## 方法 *** ## `close(): Promise` 关闭当前 SFTP 连接。 #### 返回值： - `Promise`：关闭成功后 resolve #### 示例： ```ts await sftp.close(); ``` *** ## `readDirectory(atPath: string): Promise` 读取指定目录下的文件与子目录。 #### 参数： - **`atPath`**：远程目录路径 #### 返回值： **`DirectoryEntry[]`** 数组，结构如下： ```ts { filename: string longname: string attributes: { size?: number userId?: number groupId?: number accessTime?: Date modificationTime?: Date permissions?: number } }[] ``` #### 示例： ```ts const items = await sftp.readDirectory("/var/log"); ``` *** ## `createDirectory(atPath: string): Promise` 在指定路径创建一个目录。 #### 参数： - `atPath`：目标目录路径 #### 返回值： - `Promise`：创建成功后 resolve #### 示例： ```ts await sftp.createDirectory("/home/user/new-folder"); ``` *** ## `removeDirectory(atPath: string): Promise` 删除一个目录（需为空目录）。 #### 参数： - `atPath`：要删除的目录路径 #### 返回值： - `Promise` #### 示例： ```ts await sftp.removeDirectory("/home/user/empty-dir"); ``` *** ## `rename(oldPath: string, newPath: string): Promise` 重命名或移动文件 / 目录。 #### 参数： - `oldPath`：原路径 - `newPath`：目标路径 #### 返回值： - `Promise` #### 示例： ```ts await sftp.rename("/home/user/a.txt", "/home/user/b.txt"); ``` *** ## `getAttributes(atPath: string): Promise` 读取文件或目录的信息。 #### 返回值： ```ts { size?: number userId?: number groupId?: number accessTime?: Date modificationTime?: Date permissions?: number } ``` #### 示例： ```ts const attrs = await sftp.getAttributes("/etc/hosts"); ``` *** ## `openFile(filePath: string, flags: SFTPOpenFileFlags | SFTPOpenFileFlags[]): Promise` 以指定模式打开远程文件，返回 `SFTPFile` 对象进行读写。 #### 参数： - `filePath`：文件路径 - `flags`：打开文件的模式，可为单个 flag 或数组可用的 flag： ``` "read" | "write" | "append" | "create" | "truncate" | "forceCreate" ``` #### 返回值： - `Promise`：一个可读写、可关闭的文件对象 #### 示例： ```ts const file = await sftp.openFile("/home/user/log.txt", ["read"]); const data = await file.readAll(); await file.close(); ``` *** ## `remove(atPath: string): Promise` 删除指定路径的文件。 #### 参数： - `atPath`：要删除的文件路径 #### 示例： ```ts await sftp.remove("/home/user/old.txt"); ``` *** ## `getRealPath(atPath: string): Promise` 解析符号链接、相对路径、`~` 等，返回绝对路径。 #### 示例： ```ts const real = await sftp.getRealPath("~/documents"); ``` *** \##使用示例 ```ts const ssh = await SSHClient.connect({ host: "192.168.1.10", authenticationMethod: SSHAuthenticationMethod.passwordBased("user", "pass"), }); const sftp = await ssh.openSFTP(); // 查看目录内容 const list = await sftp.readDirectory("/home/user"); // 打开文件读取 const file = await sftp.openFile("/home/user/info.txt", "read"); const data = await file.readAll(); await file.close(); // 创建目录 await sftp.createDirectory("/home/user/new-folder"); // 删除文件 await sftp.remove("/home/user/temp.txt"); await sftp.close(); ``` --- url: /doc_v2/zh/guide/Utilities/SSH/SFTP File.md --- # SFTP 文件 `SFTPFile` 表示一个已经通过 SFTP 打开的远程文件句柄。通过该类，你可以对文件执行读取、写入、获取属性、关闭等底层操作。实例通常通过： ```ts const file = await sftp.openFile(path, flags); ``` 获得。 *** ## 属性 *** ### `readonly isActive: boolean` 指示当前文件是否仍然处于打开状态。 - `true`：文件句柄有效，可继续读写 - `false`：文件已关闭或出现错误 *** ## 方法 *** \##`readAttributes(): Promise` 读取文件的元数据属性。 ### 返回值：一个包含文件属性的对象： ```ts { size?: number userId?: number groupId?: number accessTime?: Date modificationTime?: Date permissions?: number } ``` ### 示例： ```ts const attrs = await file.readAttributes(); console.log(attrs.size); ``` *** \##`read(options?: { from?: number, length?: number }): Promise` 按指定范围读取文件内容。 ### 参数： - `from?`：读取的起始偏移（字节），默认从 `0` 开始 - `length?`：读取的字节数，默认读取到文件末尾 ### 返回值： - 一个 `Promise`，包含读取到的数据 ### 示例： ```ts const data = await file.read({ from: 100, length: 50 }); ``` *** \##`readAll(): Promise` 读取文件的全部内容。 ### 返回值： - 一个 `Promise`，包含完整的文件数据 ### 示例： ```ts const data = await file.readAll(); ``` *** \##`write(data: Data, at?: number): Promise` 向文件写入数据。 ### 参数： - `data`：要写入的二进制数据 - `at?`：写入的起始偏移（字节）。 - 若未提供，则根据 flags 的模式决定： - 若使用 `"append"` 打开，则追加到文件末尾 - 若使用 `"write"` 打开，则从当前偏移或默认 0 写入 ### 返回值： - `Promise`，写入成功后 resolve ### 示例： ```ts await file.write(Data.fromRawString("Hello world")); ``` *** \##`close(): Promise` 关闭文件句柄。关闭后，`isActive` 将变为 `false`，无法继续读写。 ### 示例： ```ts await file.close(); ``` *** \##使用示例 ```ts // 打开文件（读取模式） const file = await sftp.openFile("/home/user/info.txt", ["read"]); // 获取文件属性 const attrs = await file.readAttributes(); // 读取内容 const allData = await file.readAll(); // 部分读取 const partial = await file.read({ from: 50, length: 100 }); // 关闭文件 await file.close(); ``` --- url: /doc_v2/zh/guide/Utilities/SSH/SSH Authentication Method.md --- # SSH 认证方法表示 SSH 身份验证方法。该类提供多个静态方法用于创建不同类型的 SSH 身份验证方式，包括基于密码、RSA 私钥、ED25519 私钥，以及 ECDSA（P-256、P-384、P-521）私钥的认证方式。你可以将本类创建的实例传递给 `SSHClient.connect()` 方法中的 `authenticationMethod` 参数，用于连接 SSH 服务器。 ## 静态方法 *** ### `static passwordBased(username: string, password: string): SSHAuthenticationMethod` 创建一个基于用户名和密码的 SSH 身份验证方法。 #### 参数： - `username`（字符串）： SSH 登录使用的用户名。 - `password`（字符串）：用户名对应的密码。 #### 返回值： - 一个 `SSHAuthenticationMethod` 实例，使用用户名密码进行身份验证。 #### 示例： ```ts const auth = SSHAuthenticationMethod.passwordBased("user1", "mypassword") ``` *** ### `static ras(username: string, sshRsa: Data, decryptionKey?: Data): SSHAuthenticationMethod | null` 创建一个基于 RSA 私钥的身份验证方法。 #### 参数： - `username`（字符串）： SSH 登录使用的用户名。 - `sshRsa`（`Data` 对象）： OpenSSH 格式的 RSA 私钥内容，通常通过 `Data.fromString()` 读取。 - `decryptionKey`（可选的 `Data` 对象）：如果私钥加密了，请提供解密密码（同样为 `Data` 类型）。 #### 返回值： - 一个 `SSHAuthenticationMethod` 实例。如果密钥无效，则返回 `null`。 #### 示例： ```ts const rsaKey = Data.fromString(privateKeyContent)! const auth = SSHAuthenticationMethod.ras("user1", rsaKey) ``` *** ### `static ed25519(username: string, sshEd25519: Data, decryptionKey?: Data): SSHAuthenticationMethod | null` 创建一个基于 ED25519 私钥的身份验证方法。 #### 参数： - `username`（字符串）： SSH 登录用户名。 - `sshEd25519`（`Data` 对象）： ED25519 格式的私钥内容。 - `decryptionKey`（可选的 `Data` 对象）：私钥若加密，需提供对应的解密密码。 #### 返回值： - 一个 `SSHAuthenticationMethod` 实例。如果密钥无效，则返回 `null`。 #### 示例： ```ts const edKey = Data.fromString(ed25519KeyContent)! const auth = SSHAuthenticationMethod.ed25519("user1", edKey) ``` *** ### `static p256(username: string, pemRepresentation: string): SSHAuthenticationMethod | null` 使用 PEM 格式的 P-256（ECDSA）私钥创建身份验证方法。 #### 参数： - `username`（字符串）： SSH 登录用户名。 - `pemRepresentation`（字符串）： PEM 格式的 P-256 私钥内容。 #### 返回值： - 一个 `SSHAuthenticationMethod` 实例。如果 PEM 格式无效，则返回 `null`。 #### 示例： ```ts const auth = SSHAuthenticationMethod.p256("user1", pemKeyContent) ``` *** ### `static p384(username: string, pemRepresentation: string): SSHAuthenticationMethod | null` 使用 PEM 格式的 P-384（ECDSA）私钥创建身份验证方法。 #### 参数： - `username`（字符串）： SSH 登录用户名。 - `pemRepresentation`（字符串）： PEM 格式的 P-384 私钥内容。 #### 返回值： - 一个 `SSHAuthenticationMethod` 实例，如果无效则返回 `null`。 *** ### `static p521(username: string, pemRepresentation: string): SSHAuthenticationMethod | null` 使用 PEM 格式的 P-521（ECDSA）私钥创建身份验证方法。 #### 参数： - `username`（字符串）： SSH 登录用户名。 - `pemRepresentation`（字符串）： PEM 格式的 P-521 私钥内容。 #### 返回值： - 一个 `SSHAuthenticationMethod` 实例，如果无效则返回 `null`。 *** ## 使用示例 ```ts // 使用用户名密码认证 const passwordAuth = SSHAuthenticationMethod.passwordBased("root", "secret123") // 使用 RSA 私钥认证 const privateKey = await FileManager.readAsData("/path/to/id_rsa") const rsaAuth = SSHAuthenticationMethod.ras("root", privateKey) // 建立 SSH 连接 const ssh = await SSHClient.connect({ host: "192.168.0.1", authenticationMethod: rsaAuth }) ``` --- url: /doc_v2/zh/guide/Utilities/SSH/SSH Client.md --- # SSH 客户端 `SSHClient` 类用于连接远程 SSH 服务器，支持执行命令、打开 TTY/PTY 会话、使用 SFTP 进行文件传输，以及通过跳板主机进行多级 SSH 跳转。该类是建立和管理 SSH 会话的核心接口。 *** ## 静态方法 ### `SSHClient.connect(options): Promise` 建立与远程 SSH 服务器的连接。 #### 参数： - `options`（对象）： - `host`（字符串）：服务器的主机名或 IP 地址。 - `port?`（数字）：连接端口，默认是 `22`。 - `authenticationMethod`（`SSHAuthenticationMethod`）： SSH 身份验证方式，例如密码或私钥。 - `trustedHostKeys?`（字符串数组）：可选的受信任服务器公钥列表。如果提供，客户端将验证服务器公钥。 - `reconnect?`（`"never" | "once" | "always"`）：可选的重连策略，默认是 `"never"`。 #### 返回值： - 成功连接时返回 `Promise` 实例。 #### 示例： ```ts const ssh = await SSHClient.connect({ host: "192.168.0.10", authenticationMethod: SSHAuthenticationMethod.passwordBased("root", "password") }) ``` *** ## 属性 ### `onDisconnect: (() => void) | null` SSH 连接断开时触发的回调函数。 #### 示例： ```ts ssh.onDisconnect = () => { console.log("SSH 已断开") } ``` *** ## 实例方法 ### `executeCommand(command: string, options?): Promise` 在远程服务器上执行命令，并返回结果字符串。 #### 参数： - `command`（字符串）：要执行的命令。 - `options?`（对象）： - `maxResponseSize?`（数字）：最大响应字节数。 - `includeStderr?`（布尔）：是否包含标准错误输出，默认为 `false`。 - `inShell?`（布尔）：是否在 shell 中执行命令（如 `sh -c`），默认是 `false`。 #### 返回值： - 返回一个 `Promise`，为命令的输出。 #### 示例： ```ts const result = await ssh.executeCommand("uname -a") ``` *** ### `executeCommandStream(command, onOutput, options?): Promise` 以流的形式逐行执行命令并获取输出。 #### 参数： - `command`（字符串）：要执行的命令。 - `onOutput`（函数）：每一行输出都会调用该回调函数 `(data: Data, isStderr: boolean) => boolean`。返回 `false` 可提前终止输出接收。 - `options?`（对象）： - `inShell?`（布尔）：是否在 shell 中执行。 #### 返回值： - 返回一个 `Promise`，命令执行完毕后 resolve。 #### 示例： ```ts const output = Data.fromIntArray([]) await ssh.executeCommandStream("ping -c 4 google.com", (data, isStderr) => { output.append(data) return true }) console.log(output.toDecodedString()()) ``` *** ### `withPTY(options): Promise` 打开一个 PTY（伪终端）会话，支持交互式终端程序（如 `top`、`vim`）。 #### 参数： - `options`（对象）： - `wantReply?`（布尔）：是否等待服务器回应，默认 `true`。 - `term?`（字符串）：终端类型，默认是 `"xterm"`。 - `terminalCharacterWidth?`（数字）：字符宽度，默认 `80`。 - `terminalRowHeight?`（数字）：字符行数，默认 `24`。 - `terminalPixelWidth?`（数字）：像素宽度，默认 `0`。 - `terminalPixelHeight?`（数字）：像素高度，默认 `0`。 - `onOutput`（函数）：每一行输出的回调 `(data: Data, isStderr: boolean) => boolean`。 - `onError?`（函数）：出错时的回调 `(error: string) => void`。 #### 返回值： - 一个 `Promise`，可用于写入输入和调整终端大小。 #### 示例： ```ts let output: Data | undefined let timerId: number | undefined const writer = await ssh.withPTY({ onOutput: (data, isStderr) => { if (output == null) { output = data } else { output.append(data) } clearTimeout(timerId) timerId = setTimeout(() => { console.log(output.toDecodedString()()) output = undefined }, 500) return true } }) await writer.write("top\n") ``` *** ### `withTTY(options): Promise` 打开一个简化的 TTY 会话（不包含终端尺寸设置）。 #### 参数： - `options`（对象）： - `onOutput`（函数）：每一行输出的回调 `(data: Data, isStderr: boolean) => boolean`。 - `onError?`（函数）：出错时的回调 `(error: string) => void`。 #### 返回值： - 一个 `Promise` 实例。 *** ### `openSFTP(): Promise` 打开一个 SFTP 会话，用于远程文件读写、目录管理等操作。 #### 返回值： - 一个 `Promise` 实例。 #### 示例： ```ts const sftp = await ssh.openSFTP() await sftp.writeFile("/tmp/test.txt", "Hello world") ``` *** ### `jump(options): Promise` 从当前连接跳转（跳板）至另一个远程 SSH 主机。 #### 参数： - `options`（对象）： - `host`（字符串）：目标主机地址。 - `port?`（数字）：端口，默认为 `22`。 - `authenticationMethod`（`SSHAuthenticationMethod`）：跳转主机的身份验证方式。 - `trustedHostKeys?`（字符串数组）：可选的受信任主机公钥。 #### 返回值： - 一个新的 `SSHClient` 实例，表示跳转后的连接。 #### 示例： ```ts const nextHop = await ssh.jump({ host: "10.0.0.2", authenticationMethod: SSHAuthenticationMethod.passwordBased("user2", "pass2") }) ``` *** ### `close(): Promise` 关闭 SSH 连接并释放资源。 > **注意：** 当不再需要 SSH 连接时应显式调用该方法，以防资源或 socket 泄漏。 #### 返回值： - 一个 `Promise`，成功关闭连接时 resolve。 #### 示例： ```ts await ssh.close() ``` *** ## 使用示例 ```ts const ssh = await SSHClient.connect({ host: "192.168.1.10", authenticationMethod: SSHAuthenticationMethod.passwordBased("user", "password") }) const output = await ssh.executeCommand("uptime") console.log("系统运行时间：", output) const sftp = await ssh.openSFTP() await sftp.writeFile("/tmp/hello.txt", "Hello SSH") await ssh.close() ``` --- url: /doc_v2/zh/guide/Utilities/SSH/TTY Stdin Writer.md --- # TTY 标准输入写入器表示一个可写的 TTY（终端）标准输入流，用于通过 SSH 建立的伪终端（PTY）或 TTY 会话。该类支持将数据写入远程终端的 `stdin`，以及动态调整终端窗口大小。通常由 `SSHClient.withPTY()` 或 `SSHClient.withTTY()` 方法返回。 *** ## 方法 ### `write(data: string): Promise` 向远程 TTY 会话的标准输入写入文本数据。 #### 参数： - `data`（字符串）：要发送给远程终端标准输入的字符串，可以包含控制字符（如 `"\r"` 表示回车，`\x03` 表示 Ctrl+C）。 #### 返回值： - 一个 `Promise`，在数据成功写入后 resolve。 #### 示例： ```ts const writer = await ssh.withTTY({ onOutput: (text) => { console.log("输出：", text) return true } }) await writer.write("ls -la\n") ``` *** ### `changeSize(options: { cols: number; rows: number; pixelWidth: number; pixelHeight: number }): Promise` 更改远程终端的窗口尺寸，适用于需要特定终端尺寸的程序（如 `vim`、`htop` 等）。 #### 参数： - `options`（对象）：一个包含终端尺寸信息的对象： - `cols`（数字）：终端的字符列数，例如 80。 - `rows`（数字）：终端的字符行数，例如 24。 - `pixelWidth`（数字）：终端的像素宽度（如果不适用可设为 0）。 - `pixelHeight`（数字）：终端的像素高度（如果不适用可设为 0）。 #### 返回值： - 一个 `Promise`，在终端尺寸更改成功后 resolve。 #### 示例： ```ts await writer.changeSize({ cols: 100, rows: 30, pixelWidth: 0, pixelHeight: 0 }) ``` *** ## 使用示例 ```ts const ssh = await SSHClient.connect({ host: "192.168.1.10", authenticationMethod: SSHAuthenticationMethod.passwordBased("user", "password") }) const writer = await ssh.withPTY({ term: "xterm", onOutput: (text, isStderr) => { console.log(text) return true } }) // 写入命令 await writer.write("top\n") // 2 秒后调整终端尺寸 await new Promise(resolve => setTimeout(resolve, 2000)) await writer.changeSize({ cols: 120, rows: 40, pixelWidth: 0, pixelHeight: 0 }) ``` --- url: /doc_v2/zh/guide/Utilities/Storage.md --- # 本地存储 `Storage` 模块为脚本提供轻量级的持久化存储能力。开发者可以在脚本中保存与读取简单的数据类型（如字符串、数字、布尔值、JSON 对象）以及二进制数据（`Data`）。所有数据默认存储在 **当前脚本的私有存储域**，不会被其他脚本访问。若希望在多个脚本之间共享数据，可将 `shared: true` 作为选项传入，使数据写入 **共享存储域**。数据会在后台异步持久化到磁盘，但写入方法同步返回执行结果。 *** \##支持的数据类型 Storage 支持以下类型的数据： - `string` - `number` - `boolean` - `JSON`（符合 JSON 可序列化类型的结构） - `Data`（需使用 `setData` / `getData`）以上类型均可安全持久化。 *** \##存储域说明 | 类型 | 默认 | 可访问性 | 适用场景 | | ----------- | --------------------- | -------- | --------------------- | | 私有（Private） | 是 | 仅当前脚本 | 保存当前脚本的配置、状态、用户数据等 | | 共享（Shared） | 否（需设置 `shared: true`） | 所有脚本都可访问 | 多脚本之间共享数据，如全局设置、用户偏好等 | *** \##API 参考 ## 1. `Storage.set(key, value, options?)` ```ts function set(key: string, value: T, options?: { shared: boolean }): boolean; ``` 将值保存到持久化存储中。支持 `string`、`number`、`boolean` 和 `JSON` 类型。 ### 参数 | 名称 | 类型 | 必须 | 说明 | | -------------- | --------- | -- | --------------------- | | key | `string` | 是 | 要保存的键名 | | value | `T` | 是 | 要持久化的值 | | options.shared | `boolean` | 否 | 如果为 `true`，将数据写入共享存储域 | ### 返回值 - `boolean`：表示操作是否成功。 *** ## 2. `Storage.get(key, options?)` ```ts function get(key: string, options?: { shared: boolean }): T | null; ``` 读取已保存的值。如果不存在，返回 `null`。 ### 参数 | 名称 | 类型 | 必须 | 说明 | | -------------- | --------- | -- | ---------- | | key | `string` | 是 | 要读取的键名 | | options.shared | `boolean` | 否 | 是否从共享存储域读取 | ### 返回值 - `T | null`：对应的值或 `null`。 *** ## 3. `Storage.setData(key, data, options?)` ```ts function setData(key: string, data: Data, options?: { shared: boolean }): void; ``` 保存二进制数据 `Data` 到持久化存储。 ### 参数 - 与 `set` 的参数格式一致，但 `value` 替换为 `Data`。 *** ## 4. `Storage.getData(key, options?)` ```ts function getData(key: string, options?: { shared: boolean }): Data | null; ``` 读取保存的二进制数据。不存在时返回 `null`。 *** ## 5. `Storage.remove(key, options?)` ```ts function remove(key: string, options?: { shared: boolean }): void; ``` 移除指定键的数据。 *** ## 6. `Storage.contains(key, options?)` ```ts function contains(key: string, options?: { shared: boolean }): boolean; ``` 检测存储中是否包含某个键。 *** ## 7. `Storage.clear()` ```ts function clear(): void; ``` 清空所有存储的键值对。 **注意：该操作仅清空当前脚本的私有存储，不会影响共享存储域。** *** ## 8. `Storage.keys()` ```ts function keys(): string[]; ``` 返回当前存储域中所有键名数组。 *** \##使用示例 ## 示例 1：保存与读取简单类型 ```ts import { Storage } from "scripting"; Storage.set("username", "Thom"); const name = Storage.get("username"); console.log(name); // "Thom" ``` *** ## 示例 2：保存 JSON 对象 ```ts Storage.set("profile", { name: "Alice", age: 30, }); const profile = Storage.get<{ name: string; age: number }>("profile"); console.log(profile?.age); // 30 ``` *** ## 示例 3：保存与读取 Data ```ts import { Data, Storage } from "scripting"; const bytes = Data.fromUTF8("hello"); Storage.setData("payload", bytes); const result = Storage.getData("payload"); console.log(result?.toUTF8()); // "hello" ``` *** ## 示例 4：使用 shared 共享数据 ```ts Storage.set("theme", "dark", { shared: true }); const value = Storage.get("theme", { shared: true }); console.log(value); // "dark" ``` *** ## 示例 5：检测与删除键 ```ts if (Storage.contains("token")) { Storage.remove("token"); } ``` *** ## 示例 6：获取所有键 ```ts console.log(Storage.keys()); // ["username", "profile", ...] ``` *** \##注意事项 1. 所有写入操作异步持久化，但 API 会立即返回成功与否。 2. `Data` 类型不能通过 `Storage.set()` 保存，必须使用 `setData()`。 3. JSON 类型必须是可序列化的结构。 4. 避免将大型二进制数据保存在 Storage；此功能用于轻量级数据存储。 5. `Storage.clear()` 不会清空 shared 存储域。 --- url: /doc_v2/zh/guide/Utilities/Thread.md --- # 线程（Thread） Scripting 的 UI 渲染系统以及绝大多数 JavaScript 执行逻辑默认运行在主线程中，因此通常开发者无需主动切换线程。为了确保 UI 更新安全、避免主线程阻塞，并在必要时执行后台任务，Scripting 提供了全局 `Thread` API。部分系统 API 或运行时逻辑可能会在后台执行，此 API 能帮助你安全地处理复杂场景。 `Thread` 为全局命名空间，无需导入即可使用。 *** ## `Thread.isMainThread: boolean` 指示当前 JavaScript 执行环境是否在主线程。在大多数情况下此值为 `true`，但某些系统回调或内部任务可能会切换到后台线程。在需要进行 UI 更新时，可以通过此属性确认当前线程是否安全。 ```ts if (Thread.isMainThread) { console.log('当前在主线程') } else { console.log('当前不在主线程') } ``` *** ## `Thread.runInMain(execute: () => void): void` 在主线程中执行指定的函数。由于 JavaScript 默认运行在主线程，通常无需手动调用此方法。它主要用于以下情况： - 某些系统 API 回调在后台线程触发，开发者需要确保 UI 更新在主线程执行 - 希望严格保证某段逻辑在主线程中执行此方法不会返回值，也不会切回执行前的线程，仅保证同步在主线程执行。 ```ts Thread.runInMain(() => { title.value = 'Updated on main thread' }) ``` *** ## `Thread.runInBackground(execute: () => T | Promise): Promise` 在后台线程执行指定函数，并以 Promise 形式将结果切回到调用处所在的线程（通常是主线程）。适用于： - 计算密集型任务 - 大型数据处理 - 不希望阻塞 UI 的耗时操作 `execute` 可以返回值或 Promise。 ```ts const sum = await Thread.runInBackground(() => { let v = 0 for (let i = 0; i < 5_000_000; i++) v += i return v }) console.log('结果:', sum) ``` 异步示例： ```ts const image = await Thread.runInBackground(async () => { const raw = await loadImage() return processImage(raw) }) Thread.runInMain(() => { setImage(image) }) ``` *** ## 异步 I/O 的自动线程切换行为 Scripting 中 **大量异步 I/O 方法**（包括文件、网络、数据库等）会自动在后台线程执行，无需开发者手动使用 `runInBackground`。例如： ```ts const content = await FileManager.readAsString(path) ``` `readAsString` 会自动切换到后台线程执行文件读取操作，然后将结果以 Promise 的方式切回调用时所在的线程（通常是主线程）。这意味着你可以放心地直接调用异步 API，而无需担心阻塞 UI。 ### 只有同步方法会在主线程执行例如： ```ts const content = FileManager.readAsStringSync(path) ``` 同步方法不会切线程，会在主线程直接执行 I/O 操作。因此： - 不建议在同步方法中处理大型文件或执行耗时操作 - 如果需要高性能且不阻塞 UI，应使用异步版本（如 readAsString） *** ## 使用建议 - JavaScript 默认在主线程运行，大部分场景不需要调用 `runInMain` - 异步 I/O（如 FileManager.readAsString）已经自动在后台线程执行 - 仅在执行计算密集型任务或同步 I/O 时需要使用 `runInBackground` - 如果某些系统 API 回调在后台线程中触发，可使用 `runInMain` 保证 UI 更新安全 - 不应在后台线程中直接访问 UI，应在后台任务完成后再回到主线程处理 --- url: /doc_v2/zh/guide/Utilities/UIImage.md --- # UIImage `UIImage` 类表示一个图像对象，可用于加载、编码、转换与显示。它支持从文件路径、二进制数据或 Base64 字符串中创建图像，并提供多种格式转换方法（PNG/JPEG）。 `UIImage` 可直接用于 `Image` 组件显示，也可与 `Data` 类配合用于图像存储、上传、加密等操作。 *** ## 概述 `UIImage` 是脚本环境中处理图像的核心类，常用于以下场景： - 从本地文件、二进制数据、网络URL或 Base64 字符串中加载图像 - 获取图像的像素宽高与缩放比例 - 转换图像格式（如 PNG、JPEG） - 生成 Base64 字符串 - 调整渲染模式与可拉伸区域 - 对图像进行翻转或着色 - 生成缩略图 - 支持浅色/深色模式切换的动态图像显示 *** ## 属性 ### `width: number` 图像的宽度（单位：像素）。 ```ts const image = UIImage.fromFile("/path/to/image.png") console.log(image?.width) ``` *** ### `height: number` 图像的高度（单位：像素）。 ```ts const image = UIImage.fromFile("/path/to/image.png") console.log(image?.height) ``` *** ### `scale: number` 图像的缩放比例（Scale Factor），通常为 `1` 或 `2`（Retina 屏幕）。 ```ts console.log(image?.scale) ``` *** ### `imageOrientation: string` 图像的方向，可能的值包括： - `"up"` - `"down"` - `"left"` - `"right"` - `"upMirrored"` - `"downMirrored"` - `"leftMirrored"` - `"rightMirrored"` - `"unknown"` ```ts console.log(image?.imageOrientation) ``` *** ### `isSymbolImage: boolean` 指示该图像是否为 SFSymbol 符号图像。 ```ts const symbol = UIImage.fromSFSymbol("heart.fill") console.log(symbol?.isSymbolImage) // true ``` *** ### `renderingMode: "automatic" | "alwaysOriginal" | "alwaysTemplate" | "unknown"` 图像的渲染模式。 - `automatic`: 系统自动决定渲染方式 - `alwaysOriginal`: 显示原始颜色 - `alwaysTemplate`: 使用模板渲染（可通过 tintColor 着色） *** ### `resizingMode: "tile" | "stretch" | "unknown"` 图像的拉伸模式： - `"tile"`：平铺重复绘制 - `"stretch"`：直接拉伸 *** ### `capInsets: { top: number, left: number, bottom: number, right: number }` 定义图像的可拉伸区域边距（Cap Insets）。 *** ### `flipsForRightToLeftLayoutDirection: boolean` 是否为右到左（RTL）布局方向自动翻转图像。 *** ## 实例方法 ### `preparingThumbnail(size: Size): UIImage | null` 生成指定尺寸的缩略图。 - **参数：** - `size.width`: 缩略图宽度 - `size.height`: 缩略图高度 - **返回值：** - 新的 `UIImage` 实例或 `null` **示例：** ```ts const image = UIImage.fromFile("/path/to/photo.jpg") const thumb = image?.preparingThumbnail({ width: 200, height: 200 }) ``` *** ### `withBaselineOffset(offset: number): UIImage` 设置图像的基线偏移量（Baseline Offset），用于调整图像在垂直方向上的显示位置，在文本布局中很有用。 ```ts const image = UIImage.fromFile("/path/to/image.png") const offset = image?.withBaselineOffset(10) ``` *** ### `withHorizontallyFlippedOrientation(): UIImage` 水平翻转图像方向，返回新的 `UIImage` 实例。 ```ts const flipped = image?.withHorizontallyFlippedOrientation() ``` *** ### `withTintColor(color: string, renderingMode?: "automatic" | "alwaysOriginal" | "alwaysTemplate"): UIImage | null` 为图像应用指定的渲染模式和颜色着色。 - **参数：** - `color`: 要应用的颜色字符串，例如 `"#ffcc00"` 或 `"rgb(255,128,0)"` - `renderingMode`: 渲染模式，默认为 `"automatic"` **示例：** ```ts const symbol = UIImage.fromSFSymbol("star.fill") const tinted = symbol?.withTintColor("#ffcc00", "alwaysTemplate") ``` *** ### `withRenderingMode(renderingMode: "automatic" | "alwaysOriginal" | "alwaysTemplate"): UIImage | null` 返回使用指定渲染模式的新图像。 ```ts const templated = image?.withRenderingMode("alwaysTemplate") ``` *** ### `resizableImage(capInsets, resizingMode?): UIImage | null` 返回带有指定可拉伸区域和模式的新图像。 - **参数：** - `capInsets`: `{ top, left, bottom, right }` - `resizingMode`: `"tile"` 或 `"stretch"`，默认 `"tile"` **示例：** ```ts const resizable = image?.resizableImage( { top: 10, left: 10, bottom: 10, right: 10 }, "stretch" ) ``` *** ### `renderedInCircle(radius?: number | null, fitEntireImage?: boolean): UIImage` 返回一个新的圆形渲染版本的图像，可选指定圆的半径和是否完整显示整个图像。 - **参数：** - `radius`（可选）：圆的半径（单位：点）。 - 如果未指定： - 当 `fitEntireImage` 为 `false` 时，圆形将使用图像的**最短边**作为直径； - 当 `fitEntireImage` 为 `true` 时，圆形将使用图像的**最长边**作为直径。 - `fitEntireImage`（可选）：是否让整个图像内容都适应在圆形范围内。 - 默认值为 `true`。 - 若为 `false`，图像会填满圆形区域，但可能出现内容裁剪。 - **返回值：** - 返回一个新的 `UIImage` 实例，表示圆形渲染结果。 **示例 1：创建默认的圆形头像** ```ts const image = UIImage.fromFile("/path/to/avatar.jpg") const circle = image?.renderedInCircle() ``` **示例 2：指定半径并完整显示整个图像** ```ts const image = UIImage.fromFile("/path/to/photo.png") const circle = image?.renderedInCircle(60, true) ``` **示例 3：填充模式（可能裁剪图像部分内容）** ```ts const image = UIImage.fromFile("/path/to/icon.png") const circle = image?.renderedInCircle(50, false) ``` *** ### `renderedIn(size: { width: number, height: number }, source?: { position?: ..., size?: ... }): UIImage | null` 返回一个新的图像，将源图像缩放到指定大小，可选指定源图像的位置和尺寸。 - **参数：** - `size`: `{ width: number, height: number }`，目标图像的尺寸（单位：点） - `source`: `{ position?: { x: number, y: number }, size?: { width: number, height: number } }`，源图像的位置和尺寸。 - **返回值：** - 成功时返回新的 `UIImage` 实例；失败时返回 `null`。 **示例 1：将整张图片缩放绘制到矩形区域** ```ts const image = UIImage.fromFile("/path/to/photo.jpg") const rendered = image?.renderedIn({width: 200, height: 200 }) ``` **示例 2：从源图像中裁剪指定区域并绘制** ```ts const image = UIImage.fromFile("/path/to/landscape.jpg") const cropped = image?.renderedIn({ width: 150, height: 150 }, { position: { x: 100, y: 50 }, size: { width: 300, height: 300 } }) ``` *** ### `applySymbolConfiguration(config: UIImageSymbolConfiguration | UIImageSymbolConfiguration[]): UIImage | null` 返回一个应用指定符号配置（`UIImageSymbolConfiguration`）的新图像实例。该方法主要用于自定义 **SF Symbols** 图标的外观（如颜色、粗细、大小、配色模式等）。 - **参数：** - `config`: 要应用的符号配置对象。 - 可以是单个 `UIImageSymbolConfiguration` 实例； - 或由多个配置组成的数组，多个配置将按顺序依次应用（后者可覆盖前者）。 - **返回值：** - 返回一个新的 `UIImage` 实例，表示应用配置后的图像。如果应用失败，返回 `null`。 **示例 1：设置符号图标为多色显示** ```ts const image = UIImage.fromFile("/path/to/sf_symbol.png") const config = UIImageSymbolConfiguration.preferringMulticolor() const colored = image?.applySymbolConfiguration(config) ``` **示例 2：同时应用缩放和权重配置** ```ts const image = UIImage.fromFile("/path/to/sf_symbol.png") const config = [ UIImageSymbolConfiguration.scale("large"), UIImageSymbolConfiguration.weight("bold") ] const boldLarge = image?.applySymbolConfiguration(config) ``` **示例 3：设置分层颜色与调色板颜色** ```ts const image = UIImage.fromFile("/path/to/symbol.png") const config = [ UIImageSymbolConfiguration.hierarchicalColor(Color.blue()), UIImageSymbolConfiguration.paletteColors([Color.red(), Color.orange()]) ] const customized = image?.applySymbolConfiguration(config) ``` *** ## UIImageSymbolConfiguration `UIImageSymbolConfiguration` 是用于配置 **符号图像（SF Symbols）** 外观的类。可通过其静态方法创建不同的配置对象，并在 `applySymbolConfiguration()` 中使用。 ### 可用静态方法 | 方法 | 说明 | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `preferringMonochrome()` | 优先使用单色显示符号。 | | `preferringMulticolor()` | 优先使用多色显示符号。 | | `scale(value)` | 设置符号缩放比例，可选值：`"default"`, `"large"`, `"medium"`, `"small"`, `"unspecified"`。 | | `weight(value)` | 设置符号线条粗细，可选值：`"ultraLight"`, `"thin"`, `"light"`, `"regular"`, `"medium"`, `"semibold"`, `"bold"`, `"heavy"`, `"black"`。 | | `pointSize(value)` | 设置符号点大小。 | | `paletteColors(value)` | 设置符号调色板颜色数组（用于多层符号）。 | | `hierarchicalColor(value)` | 设置符号的层级颜色（分层阴影样式）。 | | `variableValueMode(value)` | 设置符号的动态数值显示模式，可选值：`"automatic"`, `"color"`, `"draw"`。 | | `colorRenderingMode(value)` | 设置颜色渲染模式，可选值：`"automatic"`, `"flat"`, `"gradient"`。 | | `locale(identifier)` | 设置用于符号本地化的语言标识符（如 `"en"`, `"zh-Hans"`）。 | *** **示例：组合配置符号图标外观** ```ts const config = [ UIImageSymbolConfiguration.scale("medium"), UIImageSymbolConfiguration.weight("semibold"), UIImageSymbolConfiguration.preferringMonochrome(), UIImageSymbolConfiguration.colorRenderingMode("flat") ] const image = UIImage.fromFile("/path/to/symbol.png") const result = image?.applySymbolConfiguration(config) ``` *** ### `toJPEGData(compressionQuality?: number): Data | null` 将图像转换为 JPEG 格式的二进制数据。 - **参数：** - `compressionQuality`（可选）: 压缩质量（0–1，默认 1） - **返回值：** - `Data` 实例或 `null` *** ### `toPNGData(): Data | null` 将图像转换为 PNG 格式的二进制数据。返回 `Data` 实例或 `null`。 *** ### `toJPEGBase64String(compressionQuality?: number): string | null` 将图像转换为 Base64 编码的 JPEG 字符串。 *** ### `toPNGBase64String(): string | null` 将图像转换为 Base64 编码的 PNG 字符串。 *** ## 静态方法 ### `UIImage.fromData(data: Data): UIImage | null` 通过 `Data` 创建图像。 *** ### `UIImage.fromFile(filePath: string): UIImage | null` 从文件路径加载图像（支持 PNG/JPEG）。 *** ### `UIImage.fromBase64String(base64String: string): UIImage | null` 通过 Base64 字符串创建图像。 *** ### `UIImage.fromSFSymbol(name: string): UIImage | null` 从 **SFSymbol 名称** 创建系统图标。 **示例：** ```ts const heart = UIImage.fromSFSymbol("heart.fill") ``` *** ### `UIImage.fromURL(url: string): Promise` 通过 URL 加载图像（支持 PNG/JPEG）。 **示例：** ```ts const image = await UIImage.fromURL("https://example.com/image.jpg") ``` *** ## 在 UI 中使用 UIImage `UIImage` 可以直接用于 `` 组件中显示图像。 ### 组件定义 ```ts declare const Image: FunctionComponent ``` *** ### 属性定义 ```ts type UIImageProps = { image: UIImage | DynamicImageSource } ``` *** ### 类型定义 ```ts type DynamicImageSource = { light: T dark: T } ``` *** ### 示例：显示单张图片 ```ts const image = UIImage.fromFile("/path/to/avatar.png") ``` *** ### 示例：适配浅色与深色模式 ```ts const lightImage = UIImage.fromFile("/path/to/light-logo.png") const darkImage = UIImage.fromFile("/path/to/dark-logo.png") ``` *** ## 常见用法示例 ### 1. 图像转 Base64 ```ts const image = UIImage.fromFile("/path/to/image.png") const base64 = image?.toPNGBase64String() ``` *** ### 2. 压缩为 JPEG 数据并保存 ```ts const image = UIImage.fromFile("/path/to/photo.jpg") const jpegData = image?.toJPEGData(0.6) if (jpegData) { // 写入到本地文件 } ``` *** ### 3. 从 Base64 字符串还原图片并显示 ```ts const base64 = "iVBORw0KGgoAAAANSUhEUgAA..." const image = UIImage.fromBase64String(base64) ``` *** ### 4. 将 PNG 图片转换为 JPEG 并上传 ```ts const image = UIImage.fromFile("/path/to/logo.png") const jpegData = image?.toJPEGData(0.8) if (jpegData) { const response = await fetch("https://example.com/upload", { method: "POST", body: jpegData.toUint8Array() }) } ``` *** ### 5. 创建 SFSymbol 图像并着色 ```ts const symbol = UIImage.fromSFSymbol("star.fill") const colored = symbol?.withTintColor("#ffcc00", "alwaysTemplate") ``` *** ### 6. 生成缩略图 ```ts const image = UIImage.fromFile("/path/to/large.jpg") const thumb = image?.preparingThumbnail({ width: 120, height: 120 }) ``` *** ## 总结 `UIImage` 是 Scripting 脚本环境中图像操作的核心类，具备以下特性： - 从文件、二进制或 Base64 加载图像 - 支持 SFSymbol 系统图标 - 读取图像宽高、比例、方向与渲染信息 - 可进行翻转、着色与可拉伸处理 - 支持 PNG/JPEG 格式转换与 Base64 编码 - 生成缩略图与自定义渲染模式 - 可直接用于 `` 组件显示，支持浅色/深色模式自动切换 --- url: /doc_v2/zh/guide/Utilities/URLSession/BackgroundURLSession.md --- # 后台网络会话 `BackgroundURLSession` 提供在 **Scripting app** 中发起、恢复与查询「后台可持续」的下载与上传任务的能力。 > **可用性：** 仅当脚本运行在主应用 (`Script.env === "index"`) 时可用。 *** ## 命名空间：`BackgroundURLSession` ### 1) `startDownload(options): URLSessionDownloadTask` **作用**：启动一个新的后台下载任务。 **签名** ```ts function startDownload(options: { url: string destination: string headers?: Record notifyOnFinished?: { success: string failure: string } }): URLSessionDownloadTask ``` **参数说明** - `url` (`string`)：要下载的文件 URL。 - `destination` (`string`)：下载完成后保存的目标文件路径。 - `headers` (`Record`, 可选)：HTTP 请求头。 - `notifyOnFinished` (`{ success: string, failure: string }`, 可选)：下载完成后是否发送本地通知, `success` 为成功通知标题，`failure` 为失败通知标题。 **返回值** - `URLSessionDownloadTask`：下载任务对象（任务会自动启动）。 **示例** ```ts const task = BackgroundURLSession.startDownload({ url: 'https://example.com/file.zip', destination: '/var/mobile/Containers/.../Downloads/file.zip', headers: { 'User-Agent': 'Scripting/1.0' }, notifyOnFinished: { success: '下载成功', failure: '下载失败' } }) // 开始下载 task.resume() // 监听进度与完成事件 task.onProgress = d => console.log('进度：', d.progress) task.onFinishDownload = (err, info) => { if (!err) console.log('下载完成，文件保存于：', info.destination) } ``` *** ### 2) `resumeDownload(options): URLSessionDownloadTask` **作用**：从断点续传数据恢复一个下载任务。 **签名** ```ts function resumeDownload(options: { resumeData: Data destination: string notifyOnFinished?: { success: string failure: string } }): URLSessionDownloadTask ``` **参数说明** - `resumeData` (`Data`)：通过 `cancelByProducingResumeData()` 获取的断点数据。 - `destination` (`string`)：下载完成后的目标保存路径。 - `notifyOnFinished` (`{ success: string, failure: string }`, 可选)：下载完成后是否发送本地通知, `success` 为成功通知标题，`failure` 为失败通知标题。 **返回值** - `URLSessionDownloadTask`：下载任务对象（任务会自动启动）。 **示例** ```ts const task = BackgroundURLSession.resumeDownload({ resumeData, destination: '/.../Downloads/file.zip', notifyOnFinished: true }) // 开始续传 task.resume() task.onFinishDownload = (err, info) => { if (!err) console.log('续传完成：', info.destination) } ``` *** ### 3) `getDownloadTasks(): Promise` **作用**：获取当前系统中仍存在的后台下载任务。脚本被终止或重启后，可通过该方法重新获取任务实例并重新设置回调。 **签名** ```ts function getDownloadTasks(): Promise ``` **返回值** - `Promise`：下载任务对象数组。 **示例** ```ts const tasks = await BackgroundURLSession.getDownloadTasks() for (const task of tasks) { console.log('任务ID:', task.id, '状态:', task.state) task.onComplete = err => { if (err) console.error('下载失败：', err) } } ``` *** ### 4) `startUpload(options): URLSessionUploadTask` **作用**：启动一个新的后台上传任务。 **签名** ```ts function startUpload(options: { filePath: string toURL: string method?: string headers?: Record notifyOnFinished?: { success: string failure: string } }): URLSessionUploadTask ``` **参数说明** - `filePath` (`string`)：要上传的本地文件路径。 - `toURL` (`string`)：服务器目标 URL。 - `method` (`string`, 可选，默认 `"POST"`)：HTTP 请求方法。 - `headers` (`Record`, 可选)：HTTP 请求头。 - `notifyOnFinished` (`{ success: string, failure: string }`, 可选)：上传完成后是否发送本地通知, `success` 为成功通知标题，`failure` 为失败通知标题。 **返回值** - `URLSessionUploadTask`：上传任务对象（任务会自动启动）。 **示例** ```ts const task = BackgroundURLSession.startUpload({ filePath: '/.../upload.bin', toURL: 'https://api.example.com/upload', method: 'PUT', headers: { Authorization: 'Bearer token' }, notifyOnFinished: { success: '上传成功', failure: '上传失败' } }) // 开始上传 task.resume() task.onComplete = err => { if (!err) console.log('上传完成') else console.error('上传失败：', err) } ``` *** ### 5) `resumeUpload(options): URLSessionUploadTask` **作用**：恢复一个可续传的上传任务。 **签名** ```ts function resumeUpload(options: { resumeData: Data notifyOnFinished?: { success: string failure: string } }): URLSessionUploadTask ``` **参数说明** - `resumeData` (`Data`)：先前上传任务失败时生成的续传数据。 - `notifyOnFinished` (`{ success: string, failure: string }`, 可选)：上传完成后是否发送本地通知, `success` 为成功通知标题，`failure` 为失败通知标题。 **返回值** - `URLSessionUploadTask`：新的上传任务对象（任务会自动启动）。 **示例** ```ts const task = BackgroundURLSession.resumeUpload({ resumeData, notifyOnFinished: { success: '上传成功', failure: '上传失败' } }) // 开始续传 task.resume() task.onComplete = err => { if (!err) console.log('上传续传完成') } ``` *** ### 6) `getUploadTasks(): Promise` **作用**：获取系统中仍存在的后台上传任务，用于脚本重启后恢复任务状态与回调。 **签名** ```ts function getUploadTasks(): Promise ``` **返回值** - `Promise`：上传任务数组。 **示例** ```ts const tasks = await BackgroundURLSession.getUploadTasks() for (const t of tasks) { console.log('任务ID:', t.id, '状态:', t.state) t.onComplete = err => { if (err) console.error('上传失败：', err) } } ``` *** ## 使用说明与建议 - **暂停与恢复：** 如果调用了 `task.suspend()` 暂停任务，则可通过 `task.resume()` 恢复。 - **断点续传：** 下载任务可通过 `cancelByProducingResumeData()` 生成续传数据；上传任务是否支持续传取决于服务器。 - **任务恢复：** 当脚本被系统终止后，后台任务仍会继续。重新启动脚本后，可使用 `getDownloadTasks()` 或 `getUploadTasks()` 取回并重新绑定事件回调。 - **通知提示：** `notifyOnFinished` 仅影响任务完成时的本地通知显示，不影响任务执行流程。 --- url: /doc_v2/zh/guide/Utilities/URLSession/URLSessionDownloadTask.md --- # 下载任务 `URLSessionDownloadTask` 表示一个后台下载任务实例。它由 `BackgroundURLSession.startDownload()` 或 `BackgroundURLSession.resumeDownload()` 创建，用于在前台或后台下载文件，并可在脚本被终止后继续运行。每个下载任务都由系统负责调度与执行，并提供进度、状态和事件回调等信息。任务在创建后需手动调用 `resume()` 开始任何。 *** ## 属性（Properties） ### `id: string` 下载任务的唯一标识符。可用于在脚本重启后识别同一个下载任务。 **示例** ```ts console.log(task.id) // 输出任务唯一 ID ``` *** ### `state: URLSessionTaskState` 当前任务的状态。可能的值包括： - `"running"`：任务正在进行中 - `"suspended"`：任务已暂停 - `"canceling"`：任务正在取消中 - `"completed"`：任务已完成 - `"unknown"`：状态未知（通常表示任务已被系统移除） **示例** ```ts if (task.state === "running") { console.log("下载中…") } ``` *** ### `progress: URLSessionProgress` 任务的实时进度信息。包含以下字段： - `fractionCompleted: number`：完成比例（0–1） - `totalUnitCount: number`：总字节数 - `completedUnitCount: number`：已完成字节数 - `isFinished: boolean`：是否已完成 - `estimatedTimeRemaining: number | null`：预计剩余时间（秒），可能为 `null` **示例** ```ts const p = task.progress console.log(`已完成 ${(p.fractionCompleted * 100).toFixed(2)}%`) ``` *** ### `priority: number` 任务的优先级（0.0–1.0），默认值为 `0.5`。值越高，系统越可能优先调度此任务。 **示例** ```ts task.priority = 0.8 ``` *** ### `earliestBeginDate?: Date | null` 任务可开始执行的最早时间。可用于延迟任务开始（例如在网络空闲时再执行）。 **示例** ```ts task.earliestBeginDate = new Date(Date.now() + 10_000) // 延迟 10 秒后可开始 ``` *** ### `countOfBytesClientExpectsToSend: number` 客户端预计将要发送的字节数（仅供系统参考，不影响任务执行）。 ### `countOfBytesClientExpectsToReceive: number` 客户端预计将要接收的字节数（仅供系统参考，不影响任务执行）。 *** ## 回调函数（Callbacks） ### `onProgress?: (details) => void` 当下载进度变化时调用。 `details` 参数包含： - `progress: number`：完成比例（0–1） - `bytesWritten: number`：本次写入的字节数 - `totalBytesWritten: number`：已下载的总字节数 - `totalBytesExpectedToWrite: number`：预期的总下载字节数 **示例** ```ts task.onProgress = details => { console.log(`下载进度：${(details.progress * 100).toFixed(1)}%`) } ``` *** ### `onFinishDownload?: (error, details) => void` 当下载完成（或失败）后调用。 **参数说明** - `error: Error | null`：若下载失败则为错误对象，否则为 `null`。 - `details.temporary: string`：临时文件路径。 - `details.destination: string | null`：目标文件路径（如果下载成功则为目标路径，否则可能为 `null`）。 **注意**：文件在下载完成后系统会自动移动到指定 `destination` 路径。 **示例** ```ts task.onFinishDownload = (error, details) => { if (error) { console.error("下载失败：", error) } else { console.log("下载完成，文件保存于：", details.destination) } } ``` *** ### `onComplete?: (error, resumeData) => void` 任务完全结束时调用，无论成功或失败都会触发。 **参数说明** - `error: Error | null`：若任务失败则为错误对象，否则为 `null`。 - `resumeData: Data | null`：如果任务支持断点续传且失败，可通过此数据恢复下载。 **示例** ```ts task.onComplete = (error, resumeData) => { if (error) { console.error("下载失败：", error) if (resumeData) { console.log("可使用 resumeData 续传") } } else { console.log("任务成功完成") } } ``` *** ## 方法（Methods） ### `suspend(): void` 暂停任务。暂停后不会再产生网络流量，也不会超时。稍后可通过 `resume()` 继续。 **示例** ```ts task.suspend() console.log("任务已暂停") ``` *** ### `resume(): void` 恢复被暂停的任务。仅在任务处于 `"suspended"` 状态时可调用。 **示例** ```ts task.resume() console.log("任务已恢复") ``` *** ### `cancel(): void` 取消任务。调用后立即返回，任务状态变为 `"canceling"`，完成后触发 `onComplete` 回调并带上错误信息。 **示例** ```ts task.cancel() console.log("任务已取消") ``` *** ### `cancelByProducingResumeData(): Promise` 取消任务并生成可续传的数据。若任务支持断点续传，返回的 `Data` 可用于恢复下载；否则返回 `null`。可在之后使用： ```ts BackgroundURLSession.resumeDownload({ resumeData, destination }) ``` **示例** ```ts const resumeData = await task.cancelByProducingResumeData() if (resumeData) { console.log("任务已取消，可通过 resumeData 续传") } ``` *** ## 示例代码（完整流程） ```ts const task = BackgroundURLSession.startDownload({ url: "https://example.com/largefile.zip", destination: "/.../Downloads/largefile.zip", notifyOnFinished: { success: "下载成功", failure: "下载失败" } }) // 开始任务 task.resume() task.onProgress = ({ progress }) => { console.log(`下载进度：${(progress * 100).toFixed(1)}%`) } task.onFinishDownload = (error, details) => { if (error) { console.error("下载出错：", error) } else { console.log("下载完成：", details.destination) } } task.onComplete = async (error, resumeData) => { if (error && resumeData) { console.log("可继续下载，保存 resumeData 以备后续恢复") } } ``` *** ## 注意事项与最佳实践 - 任务创建后需调用 `resume()` 开始下载。 - 任务暂停后（`suspend()`）可稍后用 `resume()` 继续执行。 - 使用 `cancelByProducingResumeData()` 可实现**断点续传**功能。 - 即使脚本退出或被系统终止，下载仍会在后台继续执行。 - 重新启动脚本后可通过 `BackgroundURLSession.getDownloadTasks()` 找回任务并重新绑定回调。 - 建议为长时间任务设置 `notifyOnFinished` 以便用户了解进度完成状态。 --- url: /doc_v2/zh/guide/Utilities/URLSession/URLSessionUploadTask.md --- # 上传任务 `URLSessionUploadTask` 表示一个后台上传任务实例。它由 `BackgroundURLSession.startUpload()` 或 `BackgroundURLSession.resumeUpload()` 创建，用于在前台或后台上传文件。上传任务由系统管理，可以在应用或脚本被暂停、切换到后台甚至被终止后继续执行。每个上传任务都提供状态、进度信息，以及多个回调事件以便追踪上传过程。 *** ## 属性（Properties） ### `id: string` 任务的唯一标识符。可用于脚本重启后识别并恢复同一个上传任务。 **示例** ```ts console.log(task.id) // 输出任务唯一ID ``` *** ### `state: URLSessionTaskState` 上传任务的当前状态。可能的值包括： - `"running"`：任务正在上传中 - `"suspended"`：任务已暂停 - `"canceling"`：任务正在取消 - `"completed"`：任务已完成 - `"unknown"`：状态未知（可能任务已被系统清除） **示例** ```ts if (task.state === "running") { console.log("文件上传中…") } ``` *** ### `progress: URLSessionProgress` 任务的实时进度信息。包含以下字段： - `fractionCompleted: number`：完成比例（0–1） - `totalUnitCount: number`：总字节数 - `completedUnitCount: number`：已上传的字节数 - `isFinished: boolean`：是否已完成 - `estimatedTimeRemaining: number | null`：预计剩余时间（秒），可能为 `null` **示例** ```ts const p = task.progress console.log(`上传进度 ${(p.fractionCompleted * 100).toFixed(1)}%`) ``` *** ### `priority: number` 任务优先级（范围 0.0–1.0），默认值为 `0.5`。数值越高，系统越倾向于优先调度此任务。 **示例** ```ts task.priority = 0.8 ``` *** ### `earliestBeginDate?: Date | null` 任务可以开始的最早时间。可用于延迟任务启动，例如等到网络空闲或充电时执行。 **示例** ```ts task.earliestBeginDate = new Date(Date.now() + 5_000) // 5秒后可开始上传 ``` *** ### `countOfBytesClientExpectsToSend: number` 客户端预估将要上传的字节数，仅供系统参考。 ### `countOfBytesClientExpectsToReceive: number` 客户端预估将要接收的字节数，仅供系统参考。 *** ## 回调函数（Callbacks） ### `onReceiveData?: (data: Data) => void` 当服务器返回响应数据时触发。参数 `data` 为服务端返回的二进制内容（`Data` 对象）。 **示例** ```ts task.onReceiveData = data => { console.log("收到响应数据：", data.length, "字节") } ``` *** ### `onComplete?: (error: Error | null, resumeData: Data | null) => void` 当上传任务完成（成功或失败）后触发。 **参数说明** - `error`：若上传失败则为错误对象，否则为 `null`。 - `resumeData`：若上传失败且支持断点续传，包含可用于恢复的 `Data` 对象，否则为 `null`。 **示例** ```ts task.onComplete = (error, resumeData) => { if (error) { console.error("上传失败：", error) if (resumeData) { console.log("任务支持断点续传，可稍后恢复") } } else { console.log("上传完成！") } } ``` *** ## 方法（Methods） ### `suspend(): void` 暂停上传任务。暂停后不会再产生网络流量，也不会超时。可通过 `resume()` 继续。 **示例** ```ts task.suspend() console.log("任务已暂停") ``` *** ### `resume(): void` 恢复被暂停的上传任务。新创建的任何任务都处于暂停状态，需要调用 `resume()` 才能开始上传。 **示例** ```ts task.resume() console.log("任务已恢复上传") ``` *** ### `cancel(): void` 取消上传任务。调用后任务会立即进入 `"canceling"` 状态，完成取消后触发 `onComplete` 回调并返回错误信息。 **示例** ```ts task.cancel() console.log("任务已取消") ``` *** ## 示例代码（完整上传流程） ```ts const task = BackgroundURLSession.startUpload({ filePath: "/path/to/file.txt", toURL: "https://api.example.com/upload", method: "POST", headers: { Authorization: "Bearer my_token" }, notifyOnFinished: true }) task.resume() task.onReceiveData = data => { console.log("收到服务器响应：", data.length, "字节") } task.onComplete = (error, resumeData) => { if (error) { console.error("上传出错：", error) if (resumeData) console.log("可以使用 resumeData 恢复上传") } else { console.log("上传成功！") } } ``` *** ## 注意事项与最佳实践 - 任务暂停（`suspend()`）后可通过 `resume()` 恢复。 - 某些服务器支持断点续传，可利用 `resumeData` 实现上传恢复。 - 即使脚本被终止或应用切换到后台，上传任务仍可继续执行。 - 可通过 `BackgroundURLSession.getUploadTasks()` 在脚本重启后找回仍在执行的任务，并重新绑定回调。 - 使用 `notifyOnFinished` 可在上传完成时显示本地通知，方便用户获知任务状态。 - 若需要携带鉴权信息（如 `Authorization`），请务必安全地管理凭证并在请求头中配置。 --- url: /doc_v2/zh/guide/Utilities/UUID.md --- # UUID `UUID` 模块提供了简便的方法来生成唯一的 UUID 字符串。 *** ## 函数 ### `string(): string` 生成一个新的 UUID（通用唯一标识符）字符串。 - **返回值**：\ 一个 UUID 格式的字符串，例如 `"550e8400-e29b-41d4-a716-446655440000"`。 *** ## 使用示例 ```tsx const id = UUID.string() console.log('生成的 UUID：', id) ``` --- url: /doc_v2/zh/guide/Utilities/WebScoket.md --- # WebScoket `WebSocket` 类提供了创建和管理 WebSocket 连接的接口，允许与服务器进行实时通信。你可以通过 WebSocket 连接发送和接收文本和二进制数据，包括字节缓冲区。 *** ## 概述 WebSocket 是一种通信协议，允许客户端与服务器之间进行全双工通信。这使其非常适用于实时应用程序，如即时消息、通知或数据流。 *** ## 类：`WebSocket` ### 构造函数 #### `new WebSocket(url: string)` 创建一个新的 WebSocket 连接到指定的 URL，并立即尝试建立连接。 - **参数**： - `url: string`：要连接的 WebSocket 服务器 URL。示例：`"ws://example.com/socket"` 或 `"wss://example.com/socket"`（对于安全的 WebSocket 连接）。 - **返回**：一个表示连接的 `WebSocket` 对象。 *** ### 属性 - **`url: string`**\ WebSocket 连接的 URL。此属性为只读。 - **`onopen?: () => void`**\ 可选的回调函数，当 WebSocket 连接成功建立时触发。 - **`onerror?: (error: Error) => void`**\ 可选的回调函数，当 WebSocket 连接或通信发生错误时触发。 - **`onmessage?: (message: string | Data) => void`**\ 可选的回调函数，当从 WebSocket 服务器接收到消息时触发。`message` 参数可以是字符串或二进制数据（由 `Data` 类表示）。 - **`onclose?: (reason?: string) => void`**\ 可选的回调函数，当 WebSocket 连接关闭时触发。`reason` 参数提供了关闭连接的可选解释。 *** ### 方法 #### `send(message: string | Data): void` 通过 WebSocket 连接向服务器发送数据。 - **参数**： - `message: string | Data`：要发送到服务器的数据。可以是字符串或 `Data` 类的实例。 - **返回**：`void` #### `close(code?: 1000 | 1001 | 1002 | 1003, reason?: string): void` 关闭 WebSocket 连接。如果连接已经关闭，则此方法不执行任何操作。 - **参数**： - `code?: 1000 | 1001 | 1002 | 1003`：可选的 WebSocket 连接关闭代码。常见的代码包括： - `1000`：正常关闭 - `1001`：离开 - `1002`：协议错误 - `1003`：不支持的数据类型 - `reason?: string`：可选的关闭连接原因。此字符串的长度不得超过 123 字节（UTF-8 编码）。 - **返回**：`void` *** ### 事件处理你可以使用 `addEventListener` 来监听 WebSocket 事件，并使用 `removeEventListener` 来移除事件监听器。 #### `addEventListener(event: "open", listener: () => void): void` 为 `"open"` 事件添加事件监听器，该事件在 WebSocket 连接建立时触发。 #### `addEventListener(event: "error", listener: (error: Error) => void): void` 为 `"error"` 事件添加事件监听器，该事件在 WebSocket 连接发生错误时触发。 #### `addEventListener(event: "message", listener: (message: string | Data) => void): void` 为 `"message"` 事件添加事件监听器，该事件在从 WebSocket 服务器接收到消息时触发。 #### `addEventListener(event: "close", listener: (reason?: string) => void): void` 为 `"close"` 事件添加事件监听器，该事件在 WebSocket 连接关闭时触发。 #### `removeEventListener(event: "open", listener: () => void): void` 移除 `"open"` 事件的事件监听器。 #### `removeEventListener(event: "error", listener: (error: Error) => void): void` 移除 `"error"` 事件的事件监听器。 #### `removeEventListener(event: "message", listener: (message: string | Data) => void): void` 移除 `"message"` 事件的事件监听器。 #### `removeEventListener(event: "close", listener: (reason?: string) => void): void` 移除 `"close"` 事件的事件监听器。 *** ## 示例使用 ### 建立 WebSocket 连接 ```ts const ws = new WebSocket("wss://example.com/socket") // 设置事件监听器 ws.addEventListener("open", () => { console.log("连接已建立！") ws.send("你好，服务器！") }) ws.addEventListener("message", (message) => { console.log("接收到消息：", message) }) ws.addEventListener("error", (error) => { console.log("WebSocket 错误：", error) }) ws.addEventListener("close", (reason) => { console.log("连接已关闭：", reason) }) ``` ### 发送字符串消息 ```ts const ws = new WebSocket("wss://example.com/socket") ws.addEventListener("open", () => { ws.send("你好，这是测试消息！") }) ``` ### 使用 `Data` 发送二进制数据 ```ts const ws = new WebSocket("wss://example.com/socket") ws.addEventListener("open", () => { const data = Data.fromString("一些消息") ws.send(data) // 发送二进制数据 }) ``` ### 处理二进制数据 ```ts const ws = new WebSocket("wss://example.com/socket") ws.addEventListener("message", (message) => { if (message instanceof Data) { const byteArray = message.getBytes() if (byteArray) { console.log("接收到的二进制数据：", byteArray) } } }) ``` ### 关闭 WebSocket 连接 ```ts const ws = new WebSocket("wss://example.com/socket") ws.addEventListener("open", () => { console.log("连接已建立！") // 使用自定义原因关闭连接 ws.close(1000, "测试后关闭连接") }) ``` *** ## 注意事项 - `send()` 方法可以处理文本和二进制数据。对于二进制数据，你可以使用 `Data` 类来处理字节缓冲区。 - 对于二进制数据，请确保你的 WebSocket 服务器能够处理二进制数据，例如 `ArrayBuffer` 或 `Uint8Array`。 - `close()` 方法可以接受 `code` 和可选的 `reason` 参数来指定 WebSocket 连接如何关闭。 --- url: /doc_v2/zh/guide/Utilities/socket.io.md --- # socket.io `Socket.IO` API 提供强大的工具，用于管理客户端与服务器之间的实时双向通信。它包括 `SocketManager`（用于管理多个命名空间）和 `SocketIOClient`（用于单个 socket 连接）。以下是该 API 的详细使用指南，包括设置、配置和常见用例。 *** ## 入门通过 `SocketManager` 创建和管理 WebSocket 连接。每个 `SocketManager` 可以管理多个命名空间和配置。 ### 示例： ```typescript // 创建一个 SocketManager 实例 const manager = new SocketManager("http://localhost:8080", { reconnects: true, reconnectAttempts: 5, compress: true }) // 获取默认命名空间的 socket const defaultSocket = manager.defaultSocket // 创建特定命名空间的 socket const roomASocket = manager.socket("/roomA") ``` *** ## API 参考 ### `SocketManager` #### 构造函数 **`constructor(url: string, config?: SocketManagerConfig)`** - **`url`**：Socket.IO 服务器的 URL。 - **`config`**：可选的配置对象。 #### 属性 - **`socketURL: string`**：服务器 URL。 - **`status: SocketIOStatus`**：连接状态（如 `connected`、`connecting`、`disconnected` 等）。 - **`defaultSocket: SocketIOClient`**：默认命名空间（`"/"`）的 socket。 #### 方法 - **`socket(namespace: string): SocketIOClient`**\ 返回指定命名空间的 `SocketIOClient`。 - **`setConfigs(config: SocketManagerConfig): void`**\ 更新管理器配置。 - **`disconnect(): void`**\ 断开所有由此实例管理的 socket 连接。 - **`reconnect(): void`**\ 尝试重新连接服务器。 *** ### `SocketIOClient` #### 属性 - **`id: string | null`**：socket 连接的唯一标识符。 - **`status: SocketIOStatus`**：客户端连接状态（如 `connected`、`connecting` 等）。 #### 方法 - **`connect(): void`**\ 发起连接。 - **`disconnect(): void`**\ 断开连接。 - **`emit(event: string, data: any): void`**\ 向服务器发送带有数据的事件。 - **`on(event: string, callback: (data: any[], ack: (value?: any) => void) => void): void`**\ 注册事件监听器。 *** ## 配置通过 `SocketManagerConfig` 对象自定义连接行为。 ### 关键选项： - **`compress`**：启用 WebSocket 传输的压缩。 - **`connectParams`**：连接 URL 中包含的 GET 参数。 - **`cookies`**：在初始连接中发送的 cookies。 - **`forceNew`**：确保每次连接都创建一个新的引擎实例。 - **`reconnects`**：启用自动重连。 - **`reconnectAttempts`**：最大重连次数。 - **`reconnectWait`**：重连尝试之间的最小时间（秒）。 ### 示例： ```typescript const config: SocketManagerConfig = { compress: true, reconnects: true, reconnectAttempts: 5, reconnectWait: 2, extraHeaders: { Authorization: "Bearer token" } } const manager = new SocketManager("http://example.com", config) ``` *** ## 常见用例 ### 发送和监听事件 ```typescript const socket = manager.defaultSocket socket.on("connect", () => { console.log("成功连接服务器") socket.emit("joinRoom", { room: "roomA" }) }) socket.on("message", (data) => { console.log("收到消息：", data) }) ``` ### 处理重连 ```typescript manager.setConfigs({ reconnects: true, reconnectAttempts: 10 }) manager.defaultSocket.on("reconnect", () => { console.log("已重新连接服务器") }) ``` ### 使用命名空间 ```typescript const chatSocket = manager.socket("/chat") chatSocket.on("newMessage", (data) => { console.log("聊天中收到新消息：", data) }) ``` *** ## 最佳实践 1. **生命周期管理**：不再需要时调用 `disconnect()`。 2. **命名空间隔离**：为逻辑上不同的通信通道使用独立命名空间。 3. **重连策略**：根据应用需求配置重连参数。 4. **错误处理**：注册 `on("error")` 监听器以优雅地处理连接问题。 5. **安全连接**：对于敏感数据，使用安全 WebSocket（WSS），并配置 `secure: true`。 *** ## 完整示例 ```typescript // 创建一个带配置的 SocketManager const manager = new SocketManager("https://example.com", { reconnects: true, reconnectAttempts: -1, reconnectWait: 1 }) // 获取默认命名空间 const socket = manager.defaultSocket // 注册事件处理器 socket.on("connect", () => { console.log("已连接到服务器") socket.emit("join", { room: "lobby" }) }) socket.on("message", (data) => { console.log("收到消息：", data) }) socket.on("disconnect", () => { console.log("已断开连接") }) // 发送自定义事件 socket.emit("sendMessage", { text: "你好，世界！" }) // 完成后断开连接 setTimeout(() => { manager.disconnect() }, 60000) ``` --- url: /doc_v2/zh/guide/View Modifiers/Animation and Transition.md --- # 动画和过渡 Scripting 通过 `Observable` / `useObservable`、`Animation`、`Transition`、`withAnimation` 以及视图的 `animation` / `transition` 属性，基本对齐了 SwiftUI 的动画能力，包括： - **属性动画**：数值、颜色、布局等属性随状态变化平滑过渡 - **过渡动画**：视图插入 / 移除时的进出效果（如淡入淡出、滑入滑出、翻转） - **显式动画**：通过 `withAnimation` 包裹一段「状态更新代码」统一加动画 ## Animation 类 `Animation` 用来描述「属性变化的时间曲线与节奏」，类似 SwiftUI 的 `Animation`。 ### 工厂方法（创建动画） #### `Animation.default()` ```ts static default(): Animation ``` - 创建一个默认动画（通常是系统预设的 ease-in-out 曲线） - 无需配置，适合「只想要一个普通的过渡效果」的场景示例： ```tsx 默认动画 ``` *** #### `Animation.linear(duration?)` ```ts static linear(duration?: DurationInSeconds | null): Animation ``` - 匀速动画，整段时间内速度保持恒定 - `duration`：动画持续时间（秒），可选，不传时使用默认时长适合：进度条数值增长、颜色线性变化等。 *** #### `Animation.easeIn(duration?)` ```ts static easeIn(duration?: DurationInSeconds | null): Animation ``` - 开始慢、后面加速 - 适合：元素「加速进入」的感觉 *** #### `Animation.easeOut(duration?)` ```ts static easeOut(duration?: DurationInSeconds | null): Animation ``` - 开始快、结尾慢 - 适合：元素「减速停止」的感觉，如卡片滑入后停在目标位置 *** #### `Animation.bouncy(options?)` ```ts static bouncy(options?: { duration?: DurationInSeconds extraBounce?: number }): Animation ``` - 带回弹效果的动画 - 参数： - `duration`：总时长（秒） - `extraBounce`：额外弹性，越大越明显适合：按钮点击放大回弹、卡片弹出等「有趣」的动效。 *** #### `Animation.smooth(options?)` ```ts static smooth(options?: { duration?: DurationInSeconds extraBounce?: number }): Animation ``` - 相对柔和、过渡自然的动画 - 与 `bouncy` 相比，弹性感更弱，更偏「丝滑」 *** #### `Animation.snappy(options?)` ```ts static snappy(options?: { duration?: DurationInSeconds extraBounce?: number }): Animation ``` - 动作「干脆利落」，响应速度快 - 常见于触控反馈、选中高亮等瞬间反馈场景 *** #### `Animation.spring(options?)` ```ts static spring(options?: { blendDuration?: number } & ({ duration?: DurationInSeconds bounce?: number response?: never dampingFraction?: never } | { response?: number dampingFraction?: number duration?: never bounce?: never })): Animation ``` 支持两种配置方式（注意互斥）： 1. **基于时长的弹簧动画** - `duration`: 动画持续时间 - `bounce`: 弹性大小 2. **物理参数模式** - `response`: 响应速度（值越小反馈越快） - `dampingFraction`: 阻尼系数（0\~1，越大越「稳」，越小越「弹」）额外参数： - `blendDuration`：动画混合时长，用于多动画衔接场景（可选）示例： ```tsx // 简单弹簧 const anim1 = Animation.spring({ duration: 0.4, bounce: 0.3 }) // 高级弹簧 const anim2 = Animation.spring({ response: 0.25, dampingFraction: 0.7 }) ``` *** #### `Animation.interactiveSpring(options?)` ```ts static interactiveSpring(options?: { response?: number dampingFraction?: number blendDuration?: number }): Animation ``` - 面向「交互驱动」的弹簧动画，例如拖拽结束后的回弹 - 参数与 `spring` 的物理参数模式类似，语义更偏向手势交互 *** #### 0 `Animation.interpolatingSpring(options?)` ```ts static interpolatingSpring(options?: { mass?: number stiffness: number damping: number initialVelocity?: number } | { duration?: DurationInSeconds bounce?: number initialVelocity?: number mass?: never stiffness?: never damping?: never }): Animation ``` 两种配置方式（互斥）： 1. **物理参数模式** - `mass`: 质量 - `stiffness`: 刚度 - `damping`: 阻尼 - `initialVelocity`: 初速度（可选） 2. **时长 + 弹性模式** - `duration`: 动画时长 - `bounce`: 弹性 - `initialVelocity`: 初速度（可选）适合对动态效果「非常在意手感」的高级场景。 *** ### 修改已有动画（链式 API） #### `delay(time)` ```ts delay(time: DurationInSeconds): Animation ``` - 使动画延迟 `time` 秒后再开始 - 返回一个新的 `Animation` 实例（原动画不变）示例： ```tsx const [animValue, setAnimValue] = useState(0) const anim = Animation .spring({ duration: 0.4, bounce: 0.3 }) .delay(0.2) 延迟弹簧 ``` *** #### `repeatCount(count, autoreverses?)` ```ts repeatCount(count: number, autoreverses?: boolean): Animation ``` - 重复执行动画 `count` 次 - `autoreverses`（默认 `true`）：是否来回反向播放示例： ```tsx const pulse = Animation .easeIn(0.6) .repeatCount(3, true) 闪烁三次 ``` *** #### `repeatForever(autoreverses?)` ```ts repeatForever(autoreverses?: boolean): Animation ``` - 无限次重复动画 - 适合加载动画、呼吸灯效果等 *** ### Animation 实战示例 #### 示例 1：基本大小动画 ```tsx import { VStack, Button, Rectangle, useObservable, Animation, withAnimation } from "scripting" export function Demo() { const size = useObservable(80) return

` - 整个 `` *** ## `listItemTint` 设置该行及其内容使用的 **前景色（tint）**。 ### 类型 ```ts listItemTint?: Color ``` ### 说明 - 设置为 `null` 表示不覆盖继承颜色。 - 可使用关键词颜色、Hex、或 rgba。 ### 示例 ```tsx 带颜色的行 ``` *** ## `listRowInsets` 设置该行的 **内边距（insets）**。 ### 类型 ```ts listRowInsets?: number | EdgeInsets ``` ### 说明 - 使用单个数字表示上下左右相同的内边距； - 使用 `EdgeInsets` 对象设置四个方向的独立间距。 ### 示例 ```tsx 自定义边距的行 ``` *** ## `listRowSpacing` 设置 **相邻两行之间的垂直间距**。 ### 类型 ```ts listRowSpacing?: number ``` ### 示例 ```tsx 第一行第二行 ``` *** ## `listRowSeparator` 设置当前行的 **分隔线可见性**。 ### 类型 ```ts listRowSeparator?: Visibility | { visibility: Visibility edges: VerticalEdgeSet } ``` ### 可选值（Visibility）： - `"visible"`：始终显示分隔线 - `"hidden"`：隐藏分隔线 - `"automatic"`：系统默认行为 ### 示例 ```tsx 隐藏底部分隔线的行 ``` *** ## `listRowSeparatorTint` 设置该行的 **分隔线颜色**。 ### 类型 ```ts listRowSeparatorTint?: Color | { color: Color edges: VerticalEdgeSet } ``` ### 示例 ```tsx 带红色分隔线的行 ``` *** ## `listRowBackground` 为该行设置一个自定义的 **背景视图**。 ### 类型 ```ts listRowBackground?: VirtualNode ``` ### 示例 ```tsx } > 带灰色背景的行 ``` *** ## `listSectionSpacing` 设置 **区块（Section）之间的垂直间距**。 ### 类型 ```ts listSectionSpacing?: number | "compact" | "default" ``` ### 示例 ```tsx

...

``` *** ## `listSectionSeparator` 控制某个区块的 **顶部或底部分隔线显示情况**。 ### 类型 ```ts listSectionSeparator?: Visibility | { visibility: Visibility edges: VerticalEdgeSet } ``` ### 示例 ```tsx

内容

``` *** ## `listSectionSeparatorTint` 设置区块分隔线的 **颜色**。 ### 类型 ```ts listSectionSeparatorTint?: Color | { color: Color edges: VerticalEdgeSet } ``` ### 示例 ```tsx

灰色底部分隔线

``` *** ## 辅助类型定义 ## `EdgeInsets` 示例 ```ts { top: number bottom: number leading: number trailing: number } ``` ## `Visibility` ```ts "automatic" | "visible" | "hidden" ``` ## `VerticalEdgeSet` ```ts "top" | "bottom" | "all" ``` ## `Color` 可接受格式： - 关键词颜色（如 `"green"`、`"label"`） - Hex 色值（如 `"#ff0000"`） - RGBA 字符串（如 `"rgba(255,0,0,1)"`） *** ## 修饰符汇总表 | 修饰符 | 作用说明 | | -------------------------- | -------------------- | | `listItemTint` | 设置该行内容的前景色 | | `listRowInsets` | 设置该行的内边距 | | `listRowSpacing` | 设置相邻两行之间的间距 | | `listRowSeparator` | 控制该行分隔线的显示 | | `listRowSeparatorTint` | 设置该行分隔线的颜色 | | `listRowBackground` | 设置该行的背景视图 | | `listSectionSpacing` | 设置两个 Section 之间的垂直间距 | | `listSectionSeparator` | 控制区块的顶部或底部分隔线是否显示 | | `listSectionSeparatorTint` | 设置区块分隔线的颜色 | --- url: /doc_v2/zh/guide/View Modifiers/List and Section View Modifiers/New List View Modifiers.md --- # 新的 List 视图修饰符 \##属性概览 | 属性名 | 类型 | 系统要求 | 说明 | | ---------------------------- | ----------------------------------------------------------- | --------- | -------------------------- | | `listSectionIndexVisibility` | `Visibility` | iOS 26.0+ | 控制 List 右侧 Section 索引条的可见性 | | `listSectionMargins` | `number \| EdgeSets \| { edges: EdgeSets; length: number }` | iOS 26.0+ | 自定义 Section 边距，替换系统默认边距规则 | | `sectionIndexLabel` | `string` | iOS 26.0+ | 设置 Section 在索引条中的字符标签 | | `sectionActions` | `VirtualNode` | iOS 18.0+ | 为 Section 添加自定义操作区域 | *** \##1. listSectionIndexVisibility ```ts /** * Sets the visibility of the list section index. * @available iOS 26.0+. */ listSectionIndexVisibility?: Visibility ``` ### 功能说明控制 List 的右侧索引条是否显示。常用于需要类似通讯录 A-Z 快速跳转的场景。可选值： - `"visible"` - `"hidden"` - `"automatic"`（系统自行判断） ### 示例 ```tsx (

{group.title}} sectionIndexLabel={group.title}> {group.items.map((item) => ( {item} ))}

)} /> ``` *** \##2. listSectionMargins ```ts /** * Set the section margins for the specific edges. * @available iOS 26.0+. */ listSectionMargins?: number | EdgeSets | { edges: EdgeSets length: number } ``` ### 功能说明设置 Section 的外边距，完全替换系统默认边距。可使用数值、 EdgeSets，或指定边的写法。 ### 三种写法说明 ### 2.1 使用单一数字作为四边边距 ```tsx listSectionMargins={12} ``` ### 2.2 使用 EdgeInsets ```tsx listSectionMargins={"all"} ``` ### 2.3 针对特定边设置长度 ```tsx listSectionMargins={{ edges: "horizontal", length: 20 }} ``` 此写法等同于 SwiftUI 中： ```swift .listSectionMargins(.horizontal, 20) ``` ### 示例 ```tsx

Favorites} listSectionMargins={{ edges: "vertical", 12 }} > Item A Item B

``` *** \##3. sectionIndexLabel ```ts /** * Sets the label that is used in a section index. * @available iOS 26.0+. */ sectionIndexLabel?: string ``` ### 功能说明为 Section 设置索引条的显示字符，一般为单字母，如 “A”、“B”、“C”。 ### 示例 ```tsx

A} sectionIndexLabel="A"> Adam Ana

``` *** \##4. sectionActions ```ts /** * Adds custom actions to a section. * @available iOS 18.0+ */ sectionActions?: VirtualNode ``` ### 功能说明为 Section 添加自定义操作按钮、菜单等 UI，位置通常显示在 Section Header 区域的右侧。 ### 示例：添加刷新按钮 ```tsx

Downloads} sectionActions={

自定义网页视图

自定义网页视图

Welcome

Welcome to Scripting Server

Inline HTML Body

Welcome