gio-web-nodes-parser

专为 GrowingIO Web SDK 设计的 DOM 节点解析库

一句话说明: 输入一个 DOM 元素，输出包含 XPath、内容、位置、列表索引等完整信息的节点数据，用于用户行为分析和页面元素追踪。

🎯 能解决什么问题

• ✅ 精确定位页面元素 - 生成多层次的 XPath 路径，确保元素唯一性
• ✅ 智能识别列表结构 - 自动计算列表项索引，支持真实列表和伪列表
• ✅ 收集父节点信息 - 根据事件类型智能决定是否收集父节点链
• ✅ 提取元素内容 - 获取用户可见的文本内容和链接信息
• ✅ 计算位置信息 - 提供精确的像素级位置数据（Hybrid 模式）

📦 安装

npm install gio-web-nodes-parser

🚀 基础使用

1. Web 端 - 单个元素解析

import { GioWebNode } from 'gio-web-nodes-parser';

// 解析按钮点击
const button = document.querySelector('#submit-btn');
const webNode = new GioWebNode(button, 'click');
const result = webNode.trackNodes();

console.log(result);
// 输出完整的节点信息数组

2. Hybrid 端 - 批量元素解析

import { GioHybridNode } from 'gio-web-nodes-parser';

// 配置设备信息
const deviceInfo = {
  scale: 2,
  winWidth: 375,
  winHeight: 667,
  webviewTop: 0,
  webviewLeft: 0,
  webviewWidth: 375,
  webviewHeight: 667,
  webviewZLevel: 0,
};

// 批量解析页面所有可追踪元素
const hybridNode = new GioHybridNode(deviceInfo);
const allNodes = hybridNode.trackNodes(document.body);

console.log(`找到 ${allNodes.length} 个可追踪元素`);

📊 输出什么数据

Web 端输出示例

点击一个列表中的按钮，会输出：

[
  {
    // 🎯 定位信息
    xpath: '/div/ul/li[2]/button', // 用于快速定位的路径
    fullXpath: '/div#header/ul.nav/li[2]/button.submit', // 包含ID和类名的完整路径
    skeleton: '/div/ul/li/button', // 结构骨架（忽略索引）
    xcontent: '/#header/.nav//.submit', // 样式内容部分

    // 📝 内容信息
    content: '立即购买', // 用户看到的文本
    hyperlink: 'https://shop.com/buy', // 链接地址（如果有）

    // 📊 列表信息
    index: 2, // 在列表中的位置
    isPureList: true, // 是真实的HTML列表
    isPseudoList: false, // 不是伪列表
    peerNodes: [li1, li2, li3], // 同级的列表项

    // ⚡ 事件信息
    triggerEvent: 'VIEW_CLICK', // 触发的事件类型
    isContainer: false, // 不是容器元素
    originNode: HTMLButtonElement, // 原始DOM节点
  },
];

Hybrid 端输出示例

在移动端 WebView 中，还会额外包含位置信息：

[
  {
    // 包含所有 Web 端信息 +

    // 📐 位置信息
    top: 120, // 距离顶部120像素
    left: 50, // 距离左侧50像素
    width: 100, // 宽度100像素
    height: 40, // 高度40像素
    zLevel: 5, // z-index层级
    outFlow: false, // 未脱离文档流
  },
];

🔧 常见使用场景

场景 1: 按钮点击追踪

// HTML: <button id="buy-now">立即购买</button>
const button = document.getElementById('buy-now');
const webNode = new GioWebNode(button, 'click');
const result = webNode.trackNodes();

// 得到: xpath="/div/button", content="立即购买", triggerEvent="VIEW_CLICK"

场景 2: 列表项点击追踪

// HTML: <ul><li>商品A</li><li>商品B</li><li>商品C</li></ul>
const listItem = document.querySelector('li:nth-child(2)');
const webNode = new GioWebNode(listItem, 'click');
const result = webNode.trackNodes();

// 得到: xpath="/div/ul/li[2]", content="商品B", index=2, isPureList=true

场景 3: 表单输入追踪

// HTML: <input type="text" placeholder="请输入用户名">
const input = document.querySelector('input[type="text"]');
const webNode = new GioWebNode(input, 'circleClick');
const result = webNode.trackNodes();

// circleClick + text input = 不收集父节点链，只返回input本身

场景 4: 自定义属性识别

// HTML: <li data-growing-index="5">特殊项目</li>
const customItem = document.querySelector('[data-growing-index]');
const webNode = new GioWebNode(customItem, 'click');
const result = webNode.trackNodes();

// 得到: index=5, isMarkedIndex=true (使用了自定义索引)

🎯 父节点链收集规则

这是库的核心特性之一，会根据事件类型智能决定是否收集父节点信息：

✅ 会收集父节点链的情况

// 1. 所有 click 事件
new GioWebNode(element, 'click').trackNodes(); // 总是收集父节点

// 2. circleClick + 非input元素
new GioWebNode(divElement, 'circleClick').trackNodes(); // 收集父节点

// 3. circleClick + 不支持change的input (如button、file等)
new GioWebNode(buttonInput, 'circleClick').trackNodes(); // 收集父节点

❌ 不会收集父节点链的情况

// circleClick + 支持change的input (如text、email、checkbox等)
const textInput = document.createElement('input');
textInput.type = 'text';
new GioWebNode(textInput, 'circleClick').trackNodes(); // 仅返回input本身

🔍 智能识别能力

列表自动识别

真实列表:

<ul>
  <li>项目1</li>
  <!-- 输出: isPureList=true, index=1 -->
  <li>项目2</li>
  <!-- 输出: isPureList=true, index=2 -->
</ul>

伪列表（相似结构的兄弟元素）:

<div class="products">
  <div class="item">商品A</div>
  <!-- 输出: isPseudoList=true, index=1 -->
  <div class="item">商品B</div>
  <!-- 输出: isPseudoList=true, index=2 -->
  <div class="item">商品C</div>
  <!-- 输出: isPseudoList=true, index=3 -->
</div>

自定义属性识别

<!-- 自定义索引 -->
<li data-growing-index="99">特殊项</li>
<!-- 输出: index=99, isMarkedIndex=true -->

<!-- 容器标记 -->
<div data-growing-container="true">容器</div>
<!-- 输出: isContainer=true -->

<!-- 忽略标记 -->
<div data-growing-ignore="true">被忽略</div>
<!-- 不会出现在输出中 -->

<!-- 自定义内容 -->
<button data-growing-title="确认提交">提交</button>
<!-- 输出: content="确认提交" -->

📋 完整的数据字段说明

基础字段（所有模式）

字段	类型	说明	示例
xpath	string	截取后的 xpath 路径	"/div/button"
fullXpath	string	完整 xpath（含 ID 和类名）	"/div#app/button.submit"
skeleton	string	结构骨架（仅标签）	"/div/button"
xcontent	string	样式内容部分	"/#app/.submit"
content	string	元素文本内容	"立即购买"
index	number	列表中的位置索引	2
hyperlink	string	链接地址	"https://example.com"
triggerEvent	string	事件类型	"VIEW_CLICK"
isContainer	boolean	是否为容器	true
isPureList	boolean	是否为真实列表	true
isPseudoList	boolean	是否为伪列表	false
isMarkedIndex	boolean	索引是否被标记	false

Hybrid 模式额外字段

字段	类型	说明	示例
top	number	距离顶部像素	120
left	number	距离左侧像素	50
width	number	元素宽度	100
height	number	元素高度	40
zLevel	number	z-index 层级	5
outFlow	boolean	是否脱离文档流	false

🛠️ 开发调试

查看解析结果

const webNode = new GioWebNode(element, 'click');
const result = webNode.trackNodes();

// 在控制台查看完整结果
console.table(result);

// 查看XPath计算过程
const xpathInfo = webNode.computeXpath(webNode.xNode);
console.log('XPath信息:', xpathInfo);

📄 许可证

ISC License

🔗 相关链接

• GrowingIO 官网
• GrowingIO WebJS SDK
• 问题反馈
• 更新日志