ms-vite-plugin 1.1.1 → 1.1.3

package/docs/api/netCard.md

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

package/docs/api/node.md

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