ms-vite-plugin 1.1.2 → 1.1.3

package/docs/apicn/netCard.md

@@ -0,0 +1,200 @@
+# 卡密模块 ($卡密)
+
+卡密模块提供了卡密验证、备注设置以及键值对存储功能，用于管理网络卡密相关的操作。
+
+## 功能概览
+
+- **卡密验证**: 验证卡密的有效性
+- **备注管理**: 设置和管理卡密备注信息
+- **云变量存储**: 提供键值对形式的数据存储和读取功能
+
+## 注意事项
+
+1. **卡密安全**: 卡密信息应当妥善保管，避免在日志中明文输出
+2. **API 调用顺序**: 验证卡密后，其他 api 才能调用
+
+## API 参考
+
+### 卡密验证
+
+#### 验证 - 验证卡密
+
+```typescript
+function 验证(卡密: 字符串): 布尔值;
+```
+
+**参数说明：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述                 |
+| ------ | ------ | -------- | ------ | -------------------- |
+| `卡密` | 字符串 | 是       |        | 需要验证的卡密字符串 |
+
+**返回值：**
+
+| 类型     | 描述                                            |
+| -------- | ----------------------------------------------- |
+| `布尔值` | 验证结果，true 表示验证成功，false 表示验证失败 |
+
+**示例 1：**
+
+```typescript
+// 验证卡密
+const 卡号 = "ABC123456789";
+const 是否验证成功 = $卡密.验证(卡号);
+
+if (是否验证成功) {
+  $打印信息日志("卡密验证成功");
+} else {
+  $打印错误日志("卡密验证失败");
+  // 注意卡密验证失败退出程序
+  $退出脚本();
+}
+```
+
+**示例 2：**
+
+```typescript
+// 验证卡密 从配置中获取卡密
+const 卡号 = $配置.获取("cardNo");
+const 是否验证成功 = $卡密.验证(卡号);
+
+if (是否验证成功) {
+  $打印信息日志("卡密验证成功");
+} else {
+  $打印错误日志("卡密验证失败");
+  // 注意卡密验证失败退出程序
+  $退出脚本();
+}
+```
+
+### 获取卡密信息
+
+#### 获取卡密信息
+
+```typescript
+function 获取卡密信息(): 卡密信息 | null;
+```
+
+**返回值：**
+
+| 类型       | 描述                                 |
+| ---------- | ------------------------------------ |
+| `卡密信息` | 卡密信息对象，包含卡密及备注和时间等 |
+
+`卡密信息` 字段：
+
+- `cardNo`: 卡密号码
+- `batchCard`: 批量码
+- `remark`: 备注
+- `activeTime`: 激活时间
+- `expireTime`: 过期时间
+
+**示例：**
+
+```typescript
+// 获取卡密信息
+const 卡密信息 = $卡密.获取卡密信息();
+$打印信息日志(JSON.stringify(卡密信息));
+```
+
+### 备注管理
+
+#### 设置卡密备注
+
+```typescript
+function 设置卡密备注(备注: 字符串): 布尔值;
+```
+
+**参数说明：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述           |
+| ------ | ------ | -------- | ------ | -------------- |
+| `备注` | 字符串 | 是       |        | 备注信息字符串 |
+
+**返回值：**
+
+| 类型     | 描述                                            |
+| -------- | ----------------------------------------------- |
+| `布尔值` | 设置结果，true 表示设置成功，false 表示设置失败 |
+
+**示例：**
+
+```typescript
+// 设置卡密备注
+const remark = "测试用户卡密";
+const success = $卡密.设置卡密备注(remark);
+
+if (success) {
+  $打印信息日志("备注设置成功");
+} else {
+  $打印错误日志("备注设置失败");
+}
+```
+
+### 云变量
+
+#### 设置值 - 设置键值对
+
+```typescript
+function 设置值(键: 字符串, 值: 字符串): 字符串;
+```
+
+**参数说明：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述       |
+| ------ | ------ | -------- | ------ | ---------- |
+| `键`   | 字符串 | 是       |        | 存储的键名 |
+| `值`   | 字符串 | 是       |        | 存储的值   |
+
+**返回值：**
+
+| 类型     | 描述                                          |
+| -------- | --------------------------------------------- |
+| `字符串` | 成功时返回设置的 value 值，失败时返回空字符串 |
+
+**示例：**
+
+```typescript
+// 设置键值对
+const key = "userConfig";
+const value = "enableNotification";
+const result = $卡密.设置值(key, value);
+
+if (result === value) {
+  $打印信息日志(`成功设置 ${key}: ${value}`);
+} else {
+  $打印错误日志("设置失败");
+}
+```
+
+#### 获取值 - 获取键值对
+
+```typescript
+function 获取值(键: 字符串): 字符串;
+```
+
+**参数说明：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述         |
+| ------ | ------ | -------- | ------ | ------------ |
+| `键`   | 字符串 | 是       |        | 要获取的键名 |
+
+**返回值：**
+
+| 类型     | 描述                                             |
+| -------- | ------------------------------------------------ |
+| `字符串` | 成功时返回对应的值，失败或键不存在时返回空字符串 |
+
+**示例：**
+
+```typescript
+// 获取键值对
+const key = "userConfig";
+const value = $卡密.获取值(key);
+
+if (value) {
+  $打印信息日志(`获取到配置: ${key} = ${value}`);
+} else {
+  $打印警告日志(`配置 ${key} 不存在或获取失败"`);
+}
+```

package/docs/apicn/node.md

@@ -0,0 +1,362 @@
+# 节点模块
+
+节点模块提供了强大的 UI 元素访问和操作功能，可以通过各种条件选择和操作界面元素。
+
+**注意事项**
+
+- 此模块仅支持 快点 Agent 模式使用
+- 节点用完需要调用 `释放内存` 方法释放内存，找完节点就能释放，不需要点击后释放
+
+## 节点选择器 ($节点选择器)
+
+节点选择器是访问 UI 元素的核心工具，提供了灵活的筛选和查找机制。
+
+### 创建节点选择器
+
+#### $创建节点选择器
+
+创建一个新的节点选择器实例。
+
+```typescript
+function $创建节点选择器(params?: {
+  /**
+   * 代表要获取节点的层级，越少速度越快，默认 50
+   */
+  maxDepth?: 数字;
+}): $节点选择器;
+```
+
+**参数说明：**
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                        |
+| ---------- | ---- | -------- | ------ | --------------------------- |
+| `maxDepth` | 数字 | 否       | 50     | 遍历的最大层级深度，默认 50 |
+
+**返回值：**
+
+| 类型          | 描述                   |
+| ------------- | ---------------------- |
+| `$节点选择器` | 新创建的节点选择器实例 |
+
+**示例：**
+
+```typescript
+// 创建选择器
+const selector = $创建节点选择器({
+  maxDepth: 20, // 最大20层深度
+});
+```
+
+### 节点信息接口
+
+#### $节点位置信息
+
+```typescript
+interface $节点位置信息 {
+  x: 数字; // x坐标
+  y: 数字; // y坐标
+  width: 数字; // 宽度
+  height: 数字; // 高度
+  centerX: 数字; // 中心点x坐标
+  centerY: 数字; // 中心点y坐标
+}
+```
+
+#### $节点信息
+
+```typescript
+interface $节点信息 {
+  id: 字符串; // 节点ID
+  identifier: 字符串; // 节点标识符
+  label: 字符串; // 节点标签
+  type: 字符串; // 节点类型
+  value: 字符串; // 节点值
+  placeholderValue: 字符串; // 节点占位符值
+  title: 字符串; // 节点名称
+  visible: 布尔值; // 是否可见
+  enabled: 布尔值; // 是否启用
+  bounds: $节点位置信息; // 边界信息
+  depth: 数字; // 层级深度
+  index: 数字; // 索引
+  parentId: 字符串; // 父节点ID
+  childCount: 数字; // 子节点数量
+
+  // 操作方法
+  点击中心(): 布尔值; // 点击中心
+  点击随机范围(): 布尔值; // 随机点击
+  hittable(): 布尔值; // 节点是否可接收事件，用于判断节点是否在屏幕可见
+  parent(): $节点信息 | null; // 获取父节点
+  child(index: 数字): $节点信息 | null; // 获取子节点
+  allChildren(): $节点信息[]; // 获取所有子节点
+  siblings(): $节点信息[]; // 获取兄弟节点
+  previousSiblings(): $节点信息[]; // 获取前面的兄弟节点
+  nextSiblings(): $节点信息[]; // 获取后面的兄弟节点
+}
+```
+
+### 选择器方法
+
+#### 获取节点
+
+```typescript
+// 释放节点选择器占用的内存
+function 释放内存(): 无返回值;
+
+// xml - 获取当前页面的 XML 字符串
+function xml(超时时间?: 数字): 字符串 | null;
+
+// 获取多个节点
+function 获取所有节点(超时时间?: 数字): 数组<$节点信息>;
+
+// 获取单个节点
+function 获取一个节点(超时时间?: 数字): $节点信息 | null;
+
+// 加载节点数据
+function 加载节点数据(超时时间?: 数字): $节点选择器;
+
+// 清除所有选择条件
+function 清除所有选择条件(): $节点选择器;
+```
+
+**示例：**
+
+```typescript
+const 选择器 = $创建节点选择器();
+// 获取所有匹配的节点
+const allNodes = 选择器.获取所有节点(5000);
+$打印信息日志(`找到 ${allNodes.length} 个节点`);
+
+// 获取第一个匹配的节点
+const 第一个节点 = 选择器.获取一个节点(3000);
+if (第一个节点) {
+  $打印信息日志(`节点标签: ${第一个节点.label}`);
+}
+
+// 释放选择器内存
+选择器.释放内存();
+```
+
+#### 条件筛选
+
+##### 文本相关
+
+```typescript
+// 精确匹配标签
+label(label: 字符串): $节点选择器
+
+// 标签模糊匹配
+labelMatch(match: 字符串): $节点选择器
+
+// 精确匹配名称
+title(title: 字符串): $节点选择器
+
+// 名称模糊匹配
+titleMatch(match: 字符串): $节点选择器
+
+// 精确匹配标识符
+identifier(identifier: 字符串): $节点选择器
+
+// 标识符模糊匹配
+identifierMatch(match: 字符串): $节点选择器
+
+// 精确匹配值
+value(value: 字符串): $节点选择器
+
+// 值模糊匹配
+valueMatch(match: 字符串): $节点选择器
+```
+
+**示例：**
+
+```typescript
+const 选择器 = $创建节点选择器();
+// 查找标签为"确定"的按钮
+const confirmButton = 选择器.label("确定").获取一个节点(3000);
+
+// 查找包含"登录"的元素
+const loginElements = 选择器.labelMatch(".*登录.*").获取所有节点(3000);
+
+// 查找名称包含"button"的元素
+const buttons = 选择器.titleMatch("button").获取所有节点(3000);
+
+// 查找值为"submit"的元素
+const submitElement = 选择器.value("submit").获取一个节点(2000);
+
+// 通过标识符查找
+const 通过标识符 = 选择器.identifier("login_btn").获取一个节点(2000);
+const 标识符模糊 = 选择器.identifierMatch("^login_.*").获取所有节点(3000);
+```
+
+// 释放选择器内存
+选择器.释放内存();
+
+##### 类型和属性
+
+```typescript
+// 精确匹配类型
+type(type: string): $节点选择器
+
+// 类型模糊匹配
+typeMatch(match: string): $节点选择器
+
+// 启用状态
+enabled(enabled: boolean): $节点选择器
+
+// 可见性
+visible(visible: boolean): $节点选择器
+```
+
+**示例：**
+
+```typescript
+const 选择器 = $创建节点选择器();
+// 查找所有按钮
+const allButtons = 选择器.type("XCUIElementTypeButton").获取所有节点(3000);
+
+// 查找所有文本框
+const textFields = 选择器
+  .typeMatch("XCUIElementTypeTextField")
+  .获取所有节点(3000);
+
+// 查找启用的元素
+const enabledElements = 选择器.enabled(true).获取所有节点(3000);
+
+// 释放选择器内存
+选择器.释放内存();
+```
+
+##### 位置和结构
+
+```typescript
+// 索引位置
+index(index: number): $节点选择器
+
+// 层级深度
+depth(depth: number): $节点选择器
+
+// 子节点数量
+childCount(childCount: number | string): $节点选择器
+
+// 边界范围
+bounds(x: number, y: number, width: number, height: number): $节点选择器
+
+// XPath 路径
+xpath(path: string): $节点选择器
+```
+
+**示例：**
+
+```typescript
+const 选择器 = $创建节点选择器();
+// 查找第一个元素
+const firstElement = 选择器.index(0).获取一个节点(2000);
+
+// 查找特定深度的元素
+const level3Elements = 选择器.depth(3).获取所有节点(3000);
+
+// 查找有子节点的元素
+const parentElements = 选择器.childCount(">0").获取所有节点(3000);
+
+// 查找特定区域的元素
+const regionElements = 选择器.bounds(100, 100, 200, 50).获取所有节点(3000);
+
+// 使用 XPath 查找
+const xpathElements = 选择器.xpath("//*[@title='快点JS']").获取所有节点(3000);
+
+// 释放选择器内存
+选择器.释放内存();
+```
+
+### 节点操作
+
+#### 点击操作
+
+```typescript
+// 点击节点中心
+node.点击中心(): 布尔值;
+
+// 随机点击节点区域
+node.点击随机范围(): 布尔值;
+
+// 节点是否可接收事件（用于判断是否显示在屏幕上）
+node.hittable(): 布尔值;
+```
+
+**示例：**
+
+```typescript
+const 选择器 = $创建节点选择器();
+// 查找并点击确定按钮
+const confirmBtn = 选择器
+  .label("确定")
+  .type("XCUIElementTypeButton")
+  .获取一个节点(3000);
+
+if (confirmBtn) {
+  const isHittable = confirmBtn.hittable();
+  $打印信息日志(`是否可接收事件: ${isHittable}`);
+
+  const clicked = confirmBtn.点击中心();
+  if (clicked) {
+    $打印信息日志("成功点击确定按钮");
+  }
+}
+
+// 随机点击避免检测
+const randomClick = confirmBtn?.点击随机范围();
+if (randomClick) {
+  $打印信息日志("成功随机点击确定按钮");
+}
+
+// 释放选择器内存
+选择器.释放内存();
+```
+
+#### 节点导航
+
+```typescript
+// 获取父节点
+node.parent(): $节点信息 | null
+
+// 获取指定索引的子节点
+node.child(index: number): $节点信息 | null
+
+// 获取所有子节点
+node.allChildren(): $节点信息[]
+
+// 获取兄弟节点
+node.siblings(): $节点信息[]
+
+// 获取前面的兄弟节点
+node.previousSiblings(): $节点信息[]
+
+// 获取后面的兄弟节点
+node.nextSiblings(): $节点信息[]
+```
+
+**示例：**
+
+```typescript
+const 选择器 = $创建节点选择器();
+// 查找输入框并获取其父容器
+const textField = 选择器.type("XCUIElementTypeTextField").获取一个节点(3000);
+
+if (textField) {
+  const container = textField.parent();
+  if (container) {
+    $打印信息日志(`容器类型: ${container.type}`);
+
+    // 获取容器的所有子元素
+    const siblings = container.allChildren();
+    $打印信息日志(`容器包含 ${siblings.length} 个子元素`);
+
+    // 查找同级的按钮
+    const siblingButtons = siblings.filter(
+      (node) => node.type === "XCUIElementTypeButton"
+    );
+  }
+}
+
+// 释放选择器内存
+选择器.释放内存();
+```