ms-vite-plugin 1.4.49 → 1.4.51

package/docs/apilua/netCard.md

@@ -0,0 +1,224 @@
+# 卡密模块 (NetCard)
+
+卡密模块提供了卡密验证、备注设置以及键值对存储功能，用于管理网络卡密相关的操作。
+
+## 功能概览
+
+- **卡密验证**: 验证卡密的有效性
+- **备注管理**: 设置和管理卡密备注信息
+- **云变量存储**: 提供键值对形式的数据存储和读取功能
+
+## 注意事项
+
+1. **卡密安全**: 卡密信息应当妥善保管，避免在日志中明文输出
+2. **普通卡密模式**: 需要先调用 `netCard.verify(cardNo)` 验证卡密，验证通过后才能调用获取卡密信息、备注和云变量等接口
+3. **授权卡密模式**: App 打开加密 UI 或运行脚本前会完成授权和卡密验证，脚本中不需要重复让用户输入卡密，也不需要重复调用 `netCard.verify`
+4. **兼容旧脚本**: 授权卡密模式下调用 `netCard.verify` 会直接返回 `true`，用于兼容原来已经写了 `verify` 的脚本
+
+## API 参考
+
+### 卡密验证
+
+#### isAuthCardMode - 判断是否为授权卡密模式
+
+```lua
+---@return boolean
+function isAuthCardMode() end
+```
+
+**示例:**
+
+```lua
+local netcard = require("netcard")
+if netcard.isAuthCardMode() then
+  print("当前为授权卡密模式，不需要重复调用 verify")
+end
+```
+
+#### verify - 验证卡密
+
+```lua
+---@param cardNo string
+---@return boolean
+function verify(cardNo) end
+```
+
+**参数说明：**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述                 |
+| -------- | ------ | -------- | ------ | -------------------- |
+| `cardNo` | string | 是       |        | 需要验证的卡密字符串 |
+
+**返回值：**
+
+| 类型      | 描述                                            |
+| --------- | ----------------------------------------------- |
+| `boolean` | 验证结果，true 表示验证成功，false 表示验证失败 |
+
+**说明：**
+
+普通卡密模式下，该方法会请求普通卡密验证接口，验证成功后才能继续使用卡密信息、备注和云变量相关能力。
+
+授权卡密模式下，App 层已经完成授权和卡密验证，脚本侧不需要重复调用该方法；如果旧脚本仍然调用，方法会直接返回 `true`。
+
+**示例 1：普通卡密模式**
+
+```lua
+local netcard = require("netcard")
+-- 验证卡密
+local cardNo = "ABC123456789"
+local isValid = netcard.verify(cardNo)
+
+if isValid then
+  print("卡密验证成功")
+else
+  logger.error("卡密验证失败")
+-- 注意卡密验证失败退出程序
+  return
+end
+```
+
+
+### 获取卡密信息
+
+#### getCardInfo - 获取卡密信息
+
+```lua
+---@return CardInfo | nil
+function getCardInfo() end
+```
+
+**返回值：**
+
+| 类型       | 描述                                 |
+| ---------- | ------------------------------------ |
+| `CardInfo` | 卡密信息对象，包含卡密及备注和时间等 |
+
+`CardInfo` 字段：
+
+- `cardNo`: 卡密号码
+- `batchCard`: 批量码
+- `remark`: 备注
+- `activeTime`: 激活时间
+- `expireTime`: 过期时间
+
+**示例：**
+
+```lua
+local netcard = require("netcard")
+-- 获取卡密信息
+local cardInfo = netcard.getCardInfo()
+print(ToJsonString(cardInfo))
+```
+
+### 备注管理
+
+#### setCardRemark - 设置卡密备注
+
+```lua
+---@param remark string
+---@return boolean
+function setCardRemark(remark) end
+```
+
+**参数说明：**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述           |
+| -------- | ------ | -------- | ------ | -------------- |
+| `remark` | string | 是       |        | 备注信息字符串 |
+
+**返回值：**
+
+| 类型      | 描述                                            |
+| --------- | ----------------------------------------------- |
+| `boolean` | 设置结果，true 表示设置成功，false 表示设置失败 |
+
+**示例：**
+
+```lua
+local netcard = require("netcard")
+-- 设置卡密备注
+local remark = "测试用户卡密"
+local success = netcard.setCardRemark(remark)
+
+if success then
+  print("备注设置成功")
+else
+  logger.error("备注设置失败")
+end
+```
+
+### 云变量
+
+#### setValue - 设置键值对
+
+```lua
+---@param key string
+---@param value string
+---@return string
+function setValue(key, value) end
+```
+
+**参数说明：**
+
+| 参数名  | 类型   | 是否必填 | 默认值 | 描述       |
+| ------- | ------ | -------- | ------ | ---------- |
+| `key`   | string | 是       |        | 存储的键名 |
+| `value` | string | 是       |        | 存储的值   |
+
+**返回值：**
+
+| 类型     | 描述                                          |
+| -------- | --------------------------------------------- |
+| `string` | 成功时返回设置的 value 值，失败时返回空字符串 |
+
+**示例：**
+
+```lua
+local netcard = require("netcard")
+-- 设置键值对
+local key = "userConfig"
+local value = "enableNotification"
+local result = netcard.setValue(key, value)
+
+if result == value then
+  print("成功设置 [" .. tostring(key) .. "] = " .. tostring(value))
+else
+  logger.error("设置失败")
+end
+```
+
+#### getValue - 获取键值对
+
+```lua
+---@param key string
+---@return string
+function getValue(key) end
+```
+
+**参数说明：**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述         |
+| ------ | ------ | -------- | ------ | ------------ |
+| `key`  | string | 是       |        | 要获取的键名 |
+
+**返回值：**
+
+| 类型     | 描述                                             |
+| -------- | ------------------------------------------------ |
+| `string` | 成功时返回对应的值，失败或键不存在时返回空字符串 |
+
+**示例：**
+
+```lua
+local netcard = require("netcard")
+-- 获取键值对
+local key = "userConfig"
+local value = netcard.getValue(key)
+
+if value then
+  print("获取到配置: " .. tostring(key) .. " = " .. tostring(value))
+else
+  print("配置 " .. tostring(key) .. " 不存在或获取失败")
+end
+```

package/docs/apilua/node.md

@@ -0,0 +1,264 @@
+# 节点模块 (Node)
+
+用于查找和操作当前界面上的控件节点。
+
+**注意**
+
+- 仅支持快点 Agent 模式
+- 用完调用 `releaseNode()` 释放；找完节点即可释放，不必等点击结束
+
+**基本流程**
+
+```text
+createNodeSelector → 设置筛选条件 → getOneNodeInfo / getNodeInfo
+→ 点击 / 输入 / 设值等 → releaseNode
+```
+
+---
+
+## 创建选择器
+
+```lua
+---@param params table?
+---@return NodeSelector
+function node.createNodeSelector(params) end
+```
+
+| 参数 | 默认 | 说明 |
+| --- | --- | --- |
+| `maxDepth` | `50` | 抓取深度，深层控件抓不到时可调大 |
+| `mode` | `1` | 抓取模式，可选 `1` / `2` / `3`，默认 `1` |
+
+```lua
+local selector = node.createNodeSelector()
+local shallow = node.createNodeSelector({ maxDepth = 15 })
+local listPage = node.createNodeSelector({ mode = 2 })
+```
+
+---
+
+## 节点信息
+
+### 位置 `NodeBoundsInfo`
+
+| 字段 | 说明 |
+| --- | --- |
+| `x` / `y` | 左上角 |
+| `width` / `height` | 宽高 |
+| `centerX` / `centerY` | 中心点 |
+
+### 节点 `NodeInfo`
+
+**属性**
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 节点 ID（内部定位用，不要改） |
+| `identifier` | 控件标识符 |
+| `label` | 标签文案 |
+| `type` | 类型，如 `XCUIElementTypeButton` |
+| `value` | 当前值 |
+| `title` | 标题 |
+| `enabled` | 是否启用 |
+| `visible` | 是否可见 |
+| `bounds` | 位置大小 |
+| `depth` | 层级 |
+| `index` | 在父节点下的序号 |
+| `parentId` | 父节点 ID |
+| `childCount` | 子节点数量 |
+
+**方法**
+
+| 方法 | 说明 |
+| --- | --- |
+| `clickCenter()` | 点击中心坐标（坐标点击，不会自动滚动） |
+| `clickRandom()` | 在节点范围内随机点击（坐标点击，不会自动滚动） |
+| `parent()` | 父节点 |
+| `child(index)` | 第 `index` 个子节点 |
+| `allChildren()` | 全部子节点 |
+| `siblings()` | 全部兄弟节点 |
+| `previousSiblings()` | 前面的兄弟 |
+| `nextSiblings()` | 后面的兄弟 |
+
+---
+
+## 选择器方法
+
+### 加载与结果
+
+| 方法 | 说明 |
+| --- | --- |
+| `releaseNode()` | 释放内存 |
+| `loadNode(timeout?)` | 重新加载界面节点，默认超时 5000ms |
+| `clearSelector()` | 清除已设置的筛选条件 |
+| `xml(timeout?)` | 获取界面 XML，失败返回 `nil` |
+| `getNodeInfo(timeout?)` | 获取所有匹配节点 |
+| `getOneNodeInfo(timeout?)` | 获取第一个匹配节点，没有则 `nil` |
+
+`timeout` 单位均为毫秒，默认 `5000`。
+
+```lua
+local selector = node.createNodeSelector()
+local nodes = selector:label("确定"):getNodeInfo(5000)
+local one = selector:getOneNodeInfo(3000)
+local xml = selector:xml()
+selector:releaseNode()
+```
+
+### 筛选条件
+
+可链式调用，多个条件同时满足（并且关系）。  
+带 `Match` 的为模糊/正则匹配。
+
+**文本**
+
+| 方法 | 说明 |
+| --- | --- |
+| `label` / `labelMatch` | 标签 |
+| `title` / `titleMatch` | 标题 |
+| `identifier` / `identifierMatch` | 标识符 |
+| `value` / `valueMatch` | 值 |
+
+**类型与状态**
+
+| 方法 | 说明 |
+| --- | --- |
+| `type` / `typeMatch` | 类型，如 `XCUIElementTypeButton` |
+| `enabled` | 是否启用 |
+| `visible` | 是否可见 |
+
+**位置与结构**
+
+| 方法 | 说明 |
+| --- | --- |
+| `index` | 序号 |
+| `depth` | 层级 |
+| `childCount` | 子节点数，支持数字或如 `">0"` |
+| `bounds(x, y, width, height)` | 区域 |
+| `xpath` | XPath |
+| `id` | 按节点 ID |
+
+```lua
+-- 精确
+selector:label("确定"):type("XCUIElementTypeButton"):getOneNodeInfo(3000)
+-- 模糊
+selector:labelMatch(".*登录.*"):getNodeInfo(3000)
+selector:identifierMatch("^login_"):getNodeInfo(3000)
+-- 组合
+selector
+  :type("XCUIElementTypeTextField")
+  :enabled(true)
+  :getOneNodeInfo(3000)
+```
+
+常见类型：`XCUIElementTypeButton`、`StaticText`、`TextField`、`SecureTextField`、`TextView`、`SearchField`、`Cell`、`Table`、`CollectionView`、`PickerWheel`、`Switch`、`Slider` 等。
+
+---
+
+## 节点操作说明
+
+### 点击
+
+| 方法 | 说明 |
+| --- | --- |
+| `clickCenter()` | 点中心坐标，不自动滚动 |
+| `clickRandom()` | 范围内随机点，不自动滚动 |
+
+输入请配合 `ime` 或 `action.input`。
+
+```lua
+local node = require("node")
+local selector = node.createNodeSelector()
+local btn = selector:label("确定"):type("XCUIElementTypeButton"):getOneNodeInfo(3000)
+
+if btn then
+  btn:clickCenter()
+end
+```
+
+
+### 树导航
+
+```lua
+local field = selector:type("XCUIElementTypeTextField"):getOneNodeInfo(3000)
+if field then
+  local parent = field:parent()
+  local children = parent:allChildren()  or  []
+  local prev = field:previousSiblings()
+  local next = field:nextSiblings()
+  local second = parent:child(1)
+end
+```
+
+---
+
+## 示例
+
+### 登录
+
+```lua
+local node = require("node")
+local ime = require("ime")
+local selector = node.createNodeSelector()
+
+local user = selector:type("XCUIElementTypeTextField"):getOneNodeInfo(5000)
+if user then
+  user:clickCenter()
+  ime.clearText()
+  ime.input("demo_user")
+end
+
+local pass = selector
+  :clearSelector()
+  :type("XCUIElementTypeSecureTextField")
+  :getOneNodeInfo(3000)
+if pass then
+  pass:clickCenter()
+  ime.clearText()
+  ime.input("password")
+end
+
+local login = selector
+  :clearSelector()
+  :labelMatch(".*登录.*")
+  :type("XCUIElementTypeButton")
+  :getOneNodeInfo(3000)
+if login then
+  login:clickCenter()
+end
+```
+
+### 列表里靠后的项
+
+```lua
+local node = require("node")
+local selector = node.createNodeSelector({ mode = 2 })
+local item = selector:label("第 30 项"):getOneNodeInfo(5000)
+if item then
+  item:clickCenter()
+end
+```
+
+### 查看界面结构
+
+```lua
+local selector = node.createNodeSelector()
+local xml = selector:xml(8000)
+if xml then
+  print(xml)
+end
+selector:releaseNode()
+```
+
+---
+
+## 常见问题
+
+**找不到节点**  
+加大超时；减少条件或改用 `*Match`；换 `mode`；用 `xml()` 看实际文案和类型。
+
+**点了没反应**  
+确认点到的是目标控件；用 `clickCenter()` / `clickRandom()` 按坐标点击。
+
+**输入叠在旧文字后面**  
+节点没有输入方法，请先 `ime.clearText()` 再 `ime.input()`。