（另请参阅开发依赖的许可证）

JSONPath Plus

分析、转换并从 JSON 文档（以及 JavaScript 对象）中选择性地提取数据。

jsonpath-plus 在原始规范的基础上进行了扩展，新增了一些额外的运算符，并明确了原始规范未明确说明的一些行为。

试试浏览器演示或 Runkit (Node)。

请注意：本项目目前没有积极维护。我们可能会接受有良好文档的 PR 或一些简单的更新，但不打算自行修复问题或添加新功能。

功能

符合原始 jsonpath 规范
原始规范未提供的便捷添加或补充：
- ^ 用于获取匹配项的父级
- ~ 用于获取匹配项的属性名（以数组形式）
- 类型选择器，用于获取：
  - 基本 JSON 类型：@null()、@boolean()、@number()、@string()、@array()、@object()
  - @integer()
  - 复合类型 @scalar()（在查询 JavaScript 对象时，它还接受 undefined 和非有限数字，以及所有基本的非对象/非函数类型）
  - @other() 可与用户定义的 otherTypeCallback 结合使用
  - 查询非 JSON JavaScript 对象时仍可使用的非 JSON 类型（@undefined()、@function()、@nonFinite()）
- 过滤器中的 @path/@parent/@property/@parentProperty/@root 简写选择器
- 转义
  - ` 用于转义剩余序列
  - @['...']/?@['...'] 语法用于转义过滤器中属性名内的特殊字符
- 记录 $..（获取所有父级组件）
ESM 和 UMD 导出格式
除了查询到的值之外，还能返回各种元信息，包括值的路径或指针，以及父对象和父属性名（以便进行修改）。
用于在路径、数组和指针之间进行转换的工具
可选阻止评估原始规范中允许的表达式，或为被评估的值提供沙箱。
可选回调函数，在获取结果时进行处理。

基准测试

根据 json-querying-performance-testing，与其他 json 查询库相比，jsonpath-plus 在处理大型和小型数据集时都表现稳定。您可以通过自行运行该项目并添加更多性能测试用例来验证这些发现。

安装```shell

npm install jsonpath-plus

## 设置

### Node.js```js
const {JSONPath} = require('jsonpath-plus');

const result = JSONPath({path: '...', json});

浏览器

对于浏览器使用，你可以直接包含 dist/index-browser-umd.cjs；无需任何 Browserify 魔法：```html

### ESM（现代浏览器）

您也可以使用 ES6 模块导入（适用于现代浏览器）：```html
<script type="module">

import {
    JSONPath
} from './node_modules/jsonpath-plus/dist/index-browser-esm.js';

const result = JSONPath({path: '...', json: {}});

</script>

ESM (打包器)

或者，如果你正在打包你的 JavaScript（例如，使用 Rollup），只需使用，注意 mainFields 应包含 browser 用于浏览器构建（对于 Node，默认情况下，检查 module，应该没问题）：```js import {JSONPath} from 'jsonpath-plus';

const result = JSONPath({path: '...', json});

## 用法

可用完整签名如下：```
const result = JSONPath([options,] path, json, callback, otherTypeCallback);

参数 path、json、callback 和 otherTypeCallback 也可以（连同任何其他可用属性）在 options 上表达。

请注意，result 将包含找到的所有项（可选择包装到数组中），而 callback 可用于在发现每个项时执行某些操作，回调函数将根据结果中独立项的数量执行 0 到 N 次。有关 JSONPath 可用参数的更多信息，请参阅下面的文档。

另请参阅 API 文档。

属性

可以在 options 对象或 evaluate 方法（作为第一个参数）上提供的属性包括：

path（必需） - 作为（规范化或非规范化）字符串或数组的 JSONPath 表达式
json（必需） - 要求值的 JSON 对象（可以是 null、布尔值、数字、字符串、对象或数组类型）。
autostart（默认值：true） - 如果将其提供为 false，则可以手动调用 evaluate 方法。
flatten（默认值：false） - 返回的结果数组是否会被展平为单维数组。
resultType（默认值："value"） - 可以是 "value"、"path"、"pointer"、"parent" 或 "parentProperty" 的不区分大小写形式，用于确定分别是否将结果作为找到项的值、作为其绝对路径、作为 JSON 指针指向绝对路径、作为其父对象，还是作为其父对象的属性名返回。如果设置为 "all"，则所有这些类型都将返回在一个对象上，并以类型作为键名。
sandbox（默认值：{}） - 键值对映射，其中的变量可用于代码求值（如过滤表达式）。（请注意，当前路径和值也将可用于这些表达式；有关详细信息，请参阅语法部分。）
wrap（默认值：true） - 是否将结果包装在数组中。如果 wrap 设置为 false，且没有找到结果，则将返回 undefined（而当 wrap 设置为 true 时，则返回空数组）。如果 wrap 设置为 false 且找到单个非数组结果，则只返回该结果（不在数组中）。不过，如果找到多个结果，仍将返回一个数组。为避免歧义（在需要区分某个结果是失败还是空数组的情况下），建议将默认值改为 false。
eval（默认值："safe"） - 脚本求值方法。 safe：在浏览器中，它将使用一个极简的脚本引擎，该引擎不使用 eval 或 Function，并满足内容安全策略。在 NodeJS 中，它没有效果，等同于 native，因为在那里脚本是安全的。 native：使用原生脚本能力。即在浏览器中使用不安全的 eval 或 Function，在 nodejs 中使用 vm.Script。false：禁用 JavaScript 求值表达式，并在尝试这些表达式时抛出异常。 callback [ (code, context) => value]：一个自定义实现，调用时以 code 和 context 作为参数，返回求值后的值。 class：一个以 code 作为构造函数参数创建的类，代码通过使用 context 调用 runInNewContext 来求值。 ``
ignoreEvalErrors（默认值：false） - 忽略脚本求值期间遇到的错误。
parent（默认值：null） - 如果某个查询可能被设置为返回根节点，此选项允许将根节点的父节点在结果中返回。
parentProperty（默认值：null） - 如果某个查询可能被设置为返回根节点，此选项允许在结果中返回该根节点的 parentProperty。这可以是字符串属性名或数字数组索引。
callback（默认值：（无）） - 如果提供，则在检索到端点值后立即调用回调。提供的三个参数将是有效载荷的值（根据 resultType）、有效载荷的类型（是普通的 "value" 还是 "property" 名称），以及完整的有效载荷对象（包含所有 resultType）。
otherTypeCallback（默认值：<一个抛出错误的函数 ，当遇到 @other() 时>） - 在目前缺乏 JSON Schema 支持的情况下，可以通过在查询末尾添加运算符 @other() 来确定内置类型之外的类型。如果遇到这样的路径，则将使用项目的值、其路径、其父对象及其父对象的属性名来调用 otherTypeCallback，并且它应返回一个布尔值，指示所提供的值是否属于 "other" 类型（或者它可以处理转换并返回 false）。

实例方法

evaluate(path, json, callback, otherTypeCallback) OR evaluate({path: <path>, json: <json object>, callback: <callback function>, otherTypeCallback: <otherTypeCallback function>}) - 仅当 autostart 属性设置为 false 时才需要此方法。它可用于使用相同配置重复求值。除了列出的属性外，后一种方法形式可以接受任何其他允许的实例属性（除了 autostart，因为它在这里没有相关性）。

类属性与方法

JSONPath.clearCache() - 清除内部缓存的已解析路径和编译后的脚本。缓存内容不会暴露；当需要使缓存失效时，调用此方法。
JSONPath.toPathArray(pathAsString) - 接受规范化或非规范化的路径字符串，并将其转换为数组：例如， ['$', 'aProperty', 'anotherProperty']。
JSONPath.toPathString(pathAsArray) - 接受路径数组并将其转换为规范化路径字符串。该字符串的形式将类似于： $['aProperty']['anotherProperty][0]。JSONPath 的终端结构 ~ 和 ^ 以及像 @string() 这样的类型运算符会被静默剥离。
JSONPath.toPointer(pathAsArray) - 接受路径数组并将其转换为 JSON 指针。该字符串的形式将类似于：/aProperty/anotherProperty/0 （任何内部的 ~ 和 / 字符都按照 JSON 指针规范进行转义）。 JSONPath 的终端结构 ~ 和 ^ 以及像 @string() 这样的类型运算符会被静默剥离。

JSONPath v10.4.1