NWMatcher 技术文档

安装指南

在标准网页中使用

要在标准网页中使用 NWMatcher，只需在 HTML 文件中引入 nwmatcher.js 文件：

<script type="text/javascript" src="nwmatcher.js"></script>

在 Node.js 中使用

要在 Node.js 环境中使用 NWMatcher，可以通过 npm 安装：

$ npm install nwmatcher

NWMatcher 目前支持浏览器（作为全局对象 NW.Dom）和无头环境（作为 CommonJS 模块）。

项目使用说明

NWMatcher 是一个快速的 CSS 选择器引擎和匹配器。它支持 CSS2 和 CSS3 选择器，并提供了丰富的 API 来帮助开发者进行 DOM 选择和操作。

支持的选择器

NWMatcher 支持多种 CSS2 和 CSS3 选择器，具体列表可以参考 CSS 支持的选择器。

功能和兼容性

关于 NWMatcher 的功能和兼容性，可以参考 功能和兼容性。

项目 API 使用文档

DOM 选择

first( selector, context )

返回与 selector 匹配的第一个元素的引用，从 context 开始查找。

match( element, selector, context )

如果 element 匹配 selector，则返回 true，否则返回 false。

select( selector, context, callback )

返回与 selector 匹配的所有元素的数组，从 context 开始查找。如果提供了 callback，则会对每个匹配的元素调用该回调函数。

DOM 辅助函数

byId( id, from )

返回具有指定 id 的第一个元素的引用，可以选择性地过滤为 from 元素的后代。

byTag( tag, from )

返回具有指定标签名 tag 的所有元素的数组，可以选择性地过滤为 from 元素的后代。

byClass( class, from )

返回具有指定类名 class 的所有元素的数组，可以选择性地过滤为 from 元素的后代。

byName( name, from )

返回具有指定 name 属性值的所有元素的数组，可以选择性地过滤为 from 元素的后代。

getAttribute( element, attribute )

返回 element 元素的 attribute 属性的值，作为字符串。

hasAttribute( element, attribute )

如果 element 具有 attribute 属性，则返回 true，否则返回 false。

引擎配置

configure( options )

配置 NWMatcher 的选项。以下是当前可用的配置选项及其默认值和描述：

• CACHING: false - 禁用结果集缓存，true 启用缓存
• ESCAPECHR: true - 允许 CSS 转义标识符，false 不允许
• NON_ASCII: true - 允许包含非 ASCII (utf-8) 字符的标识符
• SELECTOR3: true - 使用 Level 3 语法，false 使用 Level 2 语法
• UNICODE16: true - 允许包含 Unicode (utf-16) 字符的标识符
• SHORTCUTS: false - 禁用类似 "+div" 或 "ul>" 的简写选择器字符串
• SIMPLENOT: true - 不允许在 ':not()' 类中嵌套复杂选择器
• SVG_LCASE: false - 禁用匹配 SVG 元素的小写标签名
• UNIQUE_ID: true - 不允许具有相同 id 的多个元素（严格模式）
• USE_HTML5: true - 使用 HTML5 规范中的 ":checked" 和类似 UI 状态
• USE_QSAPI: true - 如果可用，使用浏览器的原生 Query Selector API
• VERBOSITY: true - 抛出异常，false 跳过抛出异常
• LOGERRORS: true - 打印控制台错误或警告，false 静默

示例：

NW.Dom.configure( { USE_QSAPI: false, VERBOSITY: false } );

registerOperator( symbol, resolver )

在操作符表中注册一个新的符号及其匹配的解析器。示例：

NW.Dom.registerOperator( '!=', 'n!="%m"' );

registerSelector( name, rexp, func )

在选择器表中注册一个新的选择器，带有匹配的正则表达式和适当的解析器函数。