ms-vite-plugin 1.1.2 → 1.1.4

package/docs/apicn/thread.md

@@ -0,0 +1,269 @@
+# 多线程模块 ($线程)
+
+多线程模块提供了简单的多线程编程能力，允许您在后台执行任务而不阻塞主线程。配合 `$共享状态` 全局对象，可以实现线程间的数据共享和通信。
+
+## 功能概览
+
+- **异步执行**: 使用 `$线程.运行` 快速启动新线程。
+- **线程控制**: 支持取消线程、检查线程状态。
+- **状态共享**: 使用 `$共享状态` 在不同线程间共享数据。
+
+## 注意事项
+
+- **独立的执行环境**: 线程函数在独立的 JavaScript 环境中运行，无法访问主线程或其他作用域中的变量、函数或对象。
+- **闭包限制**: 即使线程函数是闭包形式，它也无法捕获外部变量。传递给 `$线程.运行` 的函数会被转换并在新的上下文中执行。
+- **数据通信**: 如果需要与主线程通信或使用外部数据，请使用 `$共享状态` 全局对象。
+- **文件名限制**:执行的线程 js 文件名称必须以 `_thread.js` 结尾，例如 `worker_thread.js`。
+
+## API 参考
+
+### 线程模块
+
+#### $线程.运行 - 异步执行代码
+
+启动一个新的线程来执行指定的函数。
+
+```typescript
+function 运行(线程函数: () => 无返回值): 线程;
+```
+
+**参数:**
+
+| 参数名     | 类型             | 描述                   |
+| ---------- | ---------------- | ---------------------- |
+| `线程函数` | `() => 无返回值` | 要在子线程中执行的函数 |
+
+**返回值:**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `线程` | 线程控制对象 |
+
+**示例:**
+
+```javascript
+// 启动一个简单的线程
+const t = $线程.运行("test_thread.js");
+```
+
+#### $线程.停止所有 - 停止所有线程
+
+停止当前所有正在运行的子线程。
+
+```typescript
+function 停止所有(): 布尔值;
+```
+
+**返回值:**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 是否停止成功 |
+
+**示例:**
+
+```javascript
+const stopped = $线程.停止所有();
+$打印信息日志("停止所有线程: " + stopped);
+```
+
+---
+
+### 线程对象
+
+`$线程.运行` 返回的对象，用于控制特定线程。
+
+#### 属性
+
+| 属性名     | 类型     | 描述     |
+| ---------- | -------- | -------- |
+| `线程名称` | `字符串` | 线程名称 |
+
+#### 方法
+
+##### 取消 - 取消线程
+
+```typescript
+取消(): 布尔值;
+```
+
+**返回值:** 是否取消成功。
+
+**示例:**
+
+```javascript
+// t 是 $线程.运行 返回的对象
+t.取消();
+```
+
+##### 是否已取消 - 检查是否已取消
+
+```typescript
+是否已取消(): 布尔值;
+```
+
+**返回值:** 如果线程已被取消则返回 `true`，否则返回 `false`。
+
+**示例:**
+
+```javascript
+if (t.是否已取消()) {
+  $打印信息日志("线程已取消");
+}
+```
+
+##### 是否正在执行 - 检查是否正在执行
+
+```typescript
+是否正在执行(): 布尔值;
+```
+
+**返回值:** 如果线程正在运行则返回 `true`，否则返回 `false`。
+
+**示例:**
+
+```javascript
+if (t.是否正在执行()) {
+  $打印信息日志("线程正在运行");
+}
+```
+
+---
+
+### 共享状态 ($共享状态)
+
+`$共享状态` 是一个全局对象，用于在主线程和子线程之间，或者不同子线程之间共享数据。
+
+#### $共享状态.设置 - 设置状态
+
+设置一个共享状态值。
+
+```typescript
+设置(key: 字符串, value: 任意类型): 无返回值;
+```
+
+**参数:**
+
+| 参数名  | 类型       | 描述     |
+| ------- | ---------- | -------- |
+| `key`   | `字符串`   | 状态键名 |
+| `value` | `任意类型` | 状态值   |
+
+**示例:**
+
+```javascript
+$共享状态.设置("count", 1);
+```
+
+#### $共享状态.获取 - 获取状态
+
+获取指定的共享状态值。
+
+```typescript
+获取(key: 字符串): 任意类型;
+```
+
+**参数:**
+
+| 参数名 | 类型     | 描述     |
+| ------ | -------- | -------- |
+| `key`  | `字符串` | 状态键名 |
+
+**返回值:** 对应的状态值。
+
+**示例:**
+
+```javascript
+const val = $共享状态.获取("count");
+```
+
+#### $共享状态.批量操作 - 批量操作
+
+在回调中执行一系列状态操作，保证操作的原子性（视具体实现而定，通常用于在一个锁周期内完成多个操作）。
+
+```typescript
+批量操作(block: () => 无返回值): 无返回值;
+```
+
+**参数:**
+
+| 参数名  | 类型             | 描述                 |
+| ------- | ---------------- | -------------------- |
+| `block` | `() => 无返回值` | 包含状态操作的代码块 |
+
+**示例:**
+
+```javascript
+$共享状态.批量操作(() => {
+  $共享状态.设置("a", 1);
+  $共享状态.设置("b", 2);
+});
+```
+
+#### $共享状态.清除 - 清除所有状态
+
+清除所有共享的状态数据。
+
+```typescript
+清除(): 无返回值;
+```
+
+**示例:**
+
+```javascript
+$共享状态.清除();
+```
+
+## 综合示例：线程通信
+
+下面的示例展示了如何使用 `$线程.运行` 启动线程，并通过 `$共享状态` 进行主线程与子线程之间的通信。
+
+### 1. 子线程代码 (worker_thread.js)
+
+```javascript
+// worker_thread.js
+$打印信息日志("子线程开始工作");
+
+for (let i = 1; i <= 5; i++) {
+  // 检查是否需要提前停止
+  if (!$共享状态.获取("isRunning")) {
+    $打印信息日志("子线程检测到停止信号，退出");
+    break; // 或 return
+  }
+
+  $延时(1000); // 模拟耗时操作
+
+  // 更新进度到共享状态
+  $共享状态.设置("progress", i * 20);
+  $打印信息日志(`子线程更新进度: ${i * 20}%`);
+}
+
+$打印信息日志("子线程工作完成");
+```
+
+### 2. 主线程代码 (main.js)
+
+```javascript
+// main.js
+
+// 1. 初始化状态
+$共享状态.设置("progress", 0);
+$共享状态.设置("isRunning", true);
+
+// 2. 启动子线程执行耗时任务
+const taskThread = $线程.运行("worker_thread.js");
+
+// 3. 主线程监控进度
+while (taskThread.是否正在执行()) {
+  const progress = $共享状态.获取("progress");
+  $打印信息日志(`主线程读取进度: ${progress}%`);
+
+  if (progress >= 100) {
+    break;
+  }
+
+  $延时(500);
+}
+
+$打印信息日志("任务结束");
+```

package/docs/apicn/tts.md

@@ -0,0 +1,338 @@
+# 文字转语音模块 ($文字转语音)
+
+TTS（文本转语音）模块提供了语音合成、播放控制等功能，支持多种语言和语音设置。
+
+## 接口定义
+
+### 语音信息结构
+
+```typescript
+interface 语音信息结构 {
+  /** 语音标识符 */
+  identifier: 字符串;
+  /** 语音名称 */
+  name: 字符串;
+  /** 语言代码 */
+  language: 字符串;
+  /** 语音质量等级 */
+  quality: 数字;
+}
+```
+
+**属性说明：**
+
+| 属性名       | 类型   | 描述                                      |
+| ------------ | ------ | ----------------------------------------- |
+| `identifier` | 字符串 | 语音的唯一标识符，用于设置特定语音        |
+| `name`       | 字符串 | 语音的显示名称                            |
+| `language`   | 字符串 | 语音支持的语言代码（如 "zh-CN", "en-US"） |
+| `quality`    | 数字   | 语音质量等级，数值越高质量越好            |
+
+## 语音播放
+
+### 播放语音
+
+#### 完整参数版本
+
+```typescript
+function 播放语音(
+  text: 字符串,
+  rate?: 数字,
+  pitch?: 数字,
+  volume?: 数字,
+  language?: 字符串
+): 布尔值;
+```
+
+**参数说明：**
+
+| 参数名     | 类型   | 是否必填 | 默认值  | 描述                         |
+| ---------- | ------ | -------- | ------- | ---------------------------- |
+| `text`     | 字符串 | 是       |         | 要转换为语音的文本内容       |
+| `rate`     | 数字   | 否       | 0.5     | 语速，范围 0.0-1.0，默认 0.5 |
+| `pitch`    | 数字   | 否       | 1.0     | 音调，范围 0.5-2.0，默认 1.0 |
+| `volume`   | 数字   | 否       | 1.0     | 音量，范围 0.0-1.0，默认 1.0 |
+| `language` | 字符串 | 否       | "zh-CN" | 语言代码，默认 "zh-CN"       |
+
+**返回值：**
+
+| 类型      | 描述             |
+| --------- | ---------------- |
+| `boolean` | 是否成功开始播放 |
+
+**示例：**
+
+```javascript
+// 使用简化参数播放中文文本
+$文字转语音.播放语音("欢迎使用 TTS 功能");
+
+// 使用完整参数播放中文语音
+const success = $文字转语音.播放语音("你好世界", 0.5, 1.0, 1.0, "zh-CN");
+if (success) {
+  logi("语音播放成功");
+}
+
+// 播放英文语音，调整语速和音调
+$文字转语音.播放语音("Hello World", 0.7, 1.2, 0.8, "en-US");
+
+// 慢速播放，低音调
+$文字转语音.播放语音("这是一段慢速语音", 0.3, 0.8, 1.0, "zh-CN");
+
+// 快速播放，高音调
+$文字转语音.播放语音("这是一段快速语音", 0.9, 1.5, 1.0, "zh-CN");
+```
+
+## 播放控制
+
+### 等待播放结束
+
+```typescript
+function 等待播放结束(): void;
+```
+
+**说明：**
+
+- 调用 `等待播放结束()` 会阻塞当前线程，直到当前播放的语音完成。
+- 通常在需要确保语音播放完成后再执行后续操作时使用。
+
+**示例：**
+
+```javascript
+// 播放一段文本
+$文字转语音.播放语音("这是一段需要等待播放完成的文本");
+
+// 等待播放完成
+$文字转语音.等待播放结束();
+
+$打印信息日志("语音播放完成");
+```
+
+### 停止播放
+
+```typescript
+function 停止播放(): void;
+```
+
+停止当前正在播放的语音。
+
+**示例：**
+
+```javascript
+// 开始播放
+$文字转语音.播放语音("这是一段很长的文本内容...");
+
+// 在某个条件下停止播放
+if (shouldStop) {
+  $文字转语音.停止播放();
+  $打印信息日志("语音播放已停止");
+}
+```
+
+### 是否正在播放
+
+```typescript
+function 是否正在播放(): 布尔值;
+```
+
+检查当前是否正在播放语音。
+
+**返回值：**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否正在播放 |
+
+**示例：**
+
+```javascript
+// 检查播放状态
+if ($文字转语音.是否正在播放()) {
+  $打印信息日志("正在播放语音");
+} else {
+  $打印信息日志("当前没有播放语音");
+}
+
+// 等待播放完成
+while ($文字转语音.是否正在播放()) {
+  $延时(100); // 等待 100ms
+}
+$打印信息日志("语音播放完成");
+```
+
+## 语音设置
+
+### 获取可用的语音列表
+
+```typescript
+function 获取可用的语音列表(): 数组<语音信息结构>;
+```
+
+获取系统中所有可用的语音信息。
+
+**返回值：**
+
+| 类型                 | 描述         |
+| -------------------- | ------------ |
+| `数组<语音信息结构>` | 语音信息数组 |
+
+**示例：**
+
+```javascript
+// 获取并显示所有可用语音
+const 语音列表 = $文字转语音.获取可用的语音列表();
+$打印信息日志(`找到 ${语音列表.length} 个可用语音：`);
+
+语音列表.forEach((voice, index) => {
+  $打印信息日志(`${index + 1}. 名称: ${voice.name}`);
+  $打印信息日志(`   语言: ${voice.language}`);
+  $打印信息日志(`   标识符: ${voice.identifier}`);
+  $打印信息日志(`   质量: ${voice.quality}`);
+  $打印信息日志("---");
+});
+
+// 筛选中文语音
+const chineseVoices = 语音列表.filter((voice) =>
+  voice.language.startsWith("zh")
+);
+$打印信息日志(`找到 ${chineseVoices.length} 个中文语音`);
+
+// 筛选英文语音
+const englishVoices = 语音列表.filter((voice) =>
+  voice.language.startsWith("en")
+);
+$打印信息日志(`找到 ${englishVoices.length} 个英文语音`);
+```
+
+### 设置播报音色
+
+```typescript
+function 设置播报音色(语音标识符: 字符串): 布尔值;
+```
+
+设置要使用的语音。
+
+**参数说明：**
+
+| 参数名       | 类型   | 是否必填 | 默认值 | 描述                                         |
+| ------------ | ------ | -------- | ------ | -------------------------------------------- |
+| `语音标识符` | 字符串 | 是       |        | 语音标识符，可从 `获取可用的语音列表()` 获取 |
+
+**返回值：**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 是否设置成功 |
+
+**示例：**
+
+```javascript
+// 获取可用语音并设置第一个中文语音
+const 语音列表 = $文字转语音.获取可用的语音列表();
+const chineseVoice = 语音列表.find((voice) => voice.language.startsWith("zh"));
+
+if (chineseVoice) {
+  const success = $文字转语音.设置播报音色(chineseVoice.identifier);
+  if (success) {
+    $打印信息日志(`成功设置语音: ${chineseVoice.name}`);
+    $文字转语音.播放语音("语音设置成功");
+  } else {
+    $打印错误日志("语音设置失败");
+  }
+}
+
+// 设置特定的系统语音
+const success = $文字转语音.设置播报音色(
+  "com.apple.ttsbundle.Samantha-compact"
+);
+if (success) {
+  $打印信息日志("成功设置为 Samantha 语音");
+  $文字转语音.播放语音("Hello, I am Samantha");
+}
+```
+
+## 资源管理
+
+### 释放资源
+
+```typescript
+function 释放资源(): 无返回值;
+```
+
+`$文字转语音.播放语音`方法调用时，会自动初始化 TTS 模块并在内存缓存，大概增加 20-30MB 的内存占用。
+
+默认缓存的情况下，`$文字转语音.播放语音`方法调用会更快，因为不需要重复初始化 TTS 模块。
+
+一般情况下，不需要手动调用`$文字转语音.释放资源`方法，除非内存资源有限。
+
+调用`$文字转语音.释放资源`时，会立即停止当前播放并释放 TTS 资源。
+
+**示例：**
+
+```javascript
+$文字转语音.释放资源();
+```
+
+## 实用示例
+
+### 语音提醒功能
+
+```javascript
+function 语音提醒(文本, 紧急) {
+  if (紧急) {
+    // 紧急提醒：快速、高音调
+    $文字转语音.播放语音(文本, 0.8, 1.5, 1.0, "zh-CN");
+  } else {
+    // 普通提醒：正常语速
+    $文字转语音.播放语音(文本, 0.5, 1.0, 0.8, "zh-CN");
+  }
+}
+
+// 使用示例
+$语音提醒("任务完成", false);
+$语音提醒("发现错误，请立即处理", true);
+```
+
+### 多语言播报
+
+```javascript
+function 播报多语言文本(文本, 语言) {
+  // 根据语言选择合适的语音
+  const 语音列表 = $文字转语音.获取可用的语音列表();
+  const 指定语音 = 语音列表.find((voice) => voice.language.startsWith(语言));
+
+  if (指定语音) {
+    $文字转语音.设置播报音色(指定语音.identifier);
+    $文字转语音.播放语音(文本, 0.5, 1.0, 1.0, 语言);
+  } else {
+    $打印警告日志(`未找到 ${语言} 语音，使用默认语音`);
+    $文字转语音.播放语音(文本);
+  }
+}
+
+// 使用示例
+播报多语言文本("Hello World", "en");
+播报多语言文本("你好世界", "zh");
+播报多语言文本("こんにちは", "ja");
+```
+
+## 注意事项
+
+1. **语音资源**：不同设备可用的语音可能不同，建议在使用前检查可用语音列表
+2. **播放状态**：在开始新的语音播放前，建议检查当前播放状态
+3. **语言匹配**：设置语音时要确保语音支持要播放的语言
+4. **性能考虑**：频繁的语音播放可能影响性能，建议合理控制播放频率
+5. **错误处理**：语音播放可能失败，建议检查返回值并进行适当的错误处理
+
+## 常见问题
+
+**Q: 为什么语音播放失败？**
+
+A: 可能的原因包括：文本为空、语音资源不可用、系统音频设置问题等。建议检查参数和系统设置。
+
+**Q: 如何实现更自然的语音效果？**
+
+A: 可以通过调整语速（rate）、音调（pitch）参数，选择高质量的语音，以及在文本中添加适当的标点符号来改善语音效果。
+
+**Q: 支持哪些语言？**
+
+A: 支持的语言取决于系统安装的语音包，可以通过 `getAvailableVoices()` 查看所有可用的语言和语音。