العودة إلى التحديثات
New releaseAug 17, 2026

JSONPath v10.4.1

فورك من JSONPath من http://goessner.net/articles/JsonPath/

مشاركة

npm

testing badge coverage badge

Known Vulnerabilities

Licenses badge

Node.js CI status

(انظر أيضًا تراخيص التبعيات التطويرية)

JSONPath Plus

تحليل البيانات وتحويلها واستخراجها بشكل انتقائي من مستندات JSON (وكائنات JavaScript).

تعمل jsonpath-plus على توسيع المواصفات الأصلية لإضافة بعض العوامل الإضافية وتوضح بعض السلوكيات التي لم تحددها المواصفات الأصلية.

جرّب العرض التوضيحي في المتصفح أو Runkit (Node).

يرجى ملاحظة: هذا المشروع لا يحظى حاليًا بصيانة نشطة. قد نقبل طلبات سحب موثقة جيدًا أو بعض التحديثات البسيطة، ولكننا لا ننوي إجراء إصلاحات أو إضافة ميزات جديدة بأنفسنا.

الميزات

  • متوافق مع مواصفات jsonpath الأصلية
  • إضافات أو توضيحات ملائمة غير موجودة في المواصفات الأصلية:
    • ^ للحصول على العنصر الأب لعنصر مطابق
    • ~ للحصول على أسماء الخصائص للعناصر المطابقة (كمصفوفة)
    • محددات النوع للحصول على:
      • أنواع JSON الأساسية: @null()، @boolean()، @number()، @string()، @array()، @object()
      • @integer()
      • النوع المركب @scalar() (الذي يقبل أيضًا undefined و الأعداد غير المنتهية عند الاستعلام عن كائنات JavaScript بالإضافة إلى جميع الأنواع الأساسية غير الكائنية وغير الدالية)
      • @other() يمكن استخدامه مع otherTypeCallback معرف من قبل المستخدم
      • أنواع غير JSON يمكن استخدامها مع ذلك عند الاستعلام عن كائنات JavaScript غير JSON (@undefined()، @function()، @nonFinite())
    • @path/@parent/@property/@parentProperty/@root محددات مختصرة داخل عوامل التصفية
    • الهروب
      • ` لهروب التسلسل المتبقي
      • صيغة @['...']/?@['...'] لهروب الأحرف الخاصة داخل أسماء الخصائص في عوامل التصفية
    • توثيق $.. (الحصول على جميع المكونات الأبوية)
  • تنسيقات تصدير ESM وUMD
  • بالإضافة إلى القيم المستعلم عنها، يمكن إرجاع معلومات وصفية متنوعة بما في ذلك المسارات أو المؤشرات إلى القيمة، وكذلك الكائن الأب واسم الخاصية الأب (للسماح بالتعديل).
  • أدوات للتحويل بين المسارات والمصفوفات والمؤشرات
  • خيار منع التقييمات المسموح بها في المواصفات الأصلية أو توفير بيئة معزولة للقيم المُقيَّمة.
  • خيار استدعاء لمعالجة النتائج عند الحصول عليها.

قياس الأداء

تتمتع jsonpath-plus بأداء ثابت مع مجموعات البيانات الكبيرة والصغيرة مقارنة بمكتبات الاستعلام عن JSON الأخرى وفقًا لـ json-querying-performance-testing. يمكنك التحقق من هذه النتائج من خلال تشغيل المشروع بنفسك وإضافة المزيد من حالات الأداء.

التثبيت```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 Module imports (للمتصفحات الحديثة):```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.

الخصائص

الخصائص التي يمكن توفيرها في كائن الخيارات أو في طريقة التقييم (كوسيطة أولى) تشمل:

  • path (مطلوب) - تعبير JSONPath كسلسلة نصية (normalized أو unnormalized) أو مصفوفة.
  • json (مطلوب) - كائن JSON المراد تقييمه (سواء كان من نوع null أو boolean أو number أو string أو object أو array).
  • autostart (الافتراضي: true) - إذا تم توفير هذه القيمة على أنها false، فيمكن للمرء استدعاء طريقة evaluate يدويًا.
  • flatten (الافتراضي: false) - ما إذا كانت مصفوفة النتائج المُرجعة ستُسطَّح إلى مصفوفة أحادية البعد.
  • resultType (الافتراضي: "value") - يمكن أن يكون بصيغة غير حساسة لحالة الأحرف من "value" أو "path" أو "pointer" أو "parent" أو "parentProperty" لتحديد ما إذا كانت النتائج ستُعاد كقيم العناصر التي تم العثور عليها، أو كمساراتها المطلقة، أو كـ مؤشرات JSON إلى المسارات المطلقة، أو ككائناتها الأم، أو كاسم خاصية العنصر الأصلي. إذا تم التعيين إلى "all"، فسيتم إرجاع كل هذه الأنواع على كائن مع النوع كاسم مفتاح.
  • sandbox (الافتراضي: {}) - خريطة مفتاح-قيمة للمتغيرات المتاحة لتقييمات التعليمات البرمجية مثل تعبيرات التصفية. (لاحظ أن المسار الحالي والقيمة سيكونان متاحين أيضًا لتلك التعبيرات؛ راجع قسم Syntax للحصول على التفاصيل.)
  • wrap (الافتراضي: true) - ما إذا كان سيتم تغليف النتائج في مصفوفة أم لا. إذا تم تعيين wrap إلى false، ولم يتم العثور على نتائج، فسيتم إرجاع undefined (على عكس مصفوفة فارغة عندما يتم تعيين wrap إلى true). إذا تم تعيين wrap إلى false وتم العثور على نتيجة واحدة غير مصفوفة، فستكون تلك النتيجة هي العنصر الوحيد المُعاد (وليست داخل مصفوفة). ومع ذلك، سيتم إرجاع مصفوفة إذا تم العثور على نتائج متعددة. لتجنب الغموض (في الحالة التي يكون فيها من الضروري التمييز بين نتيجة فاشلة ونتيجة تمثل مصفوفة فارغة)، يُنصح بتغيير الافتراضي إلى false.
  • eval (الافتراضي: "safe") - طريقة تقييم البرامج النصية. safe: في المتصفح، سيستخدم محرك برمجة نصية بسيطًا لا يستخدم eval أو Function ويلبي سياسة أمان المحتوى. في NodeJS، ليس له أي تأثير ويعادل native لأن البرمجة النصية آمنة هناك. native: يستخدم إمكانيات البرمجة النصية الأصلية. أي eval غير آمن أو Function في المتصفح وvm.Script في nodejs. false: تعطيل تعبيرات تقييم JavaScript وإلقاء استثناءات عند محاولة تنفيذ هذه التعبيرات. callback [ (code, context) => value]: تنفيذ مخصص يتم استدعاؤه مع code وcontext كوسيطات لإرجاع القيمة المُقيَّمة. class: فئة يتم إنشاؤها مع code كوسيطة منشئ ويتم تقييم البرنامج عن طريق استدعاء runInNewContext مع context. ``
  • ignoreEvalErrors (الافتراضي: false) - تجاهل الأخطاء التي تتم مواجهتها أثناء تقييم البرنامج النصي.
  • parent (الافتراضي: null) - في حال كان من الممكن أن يُرجع الاستعلام العقدة الجذرية، فإن هذا يسمح بإرجاع أصل العقدة الجذرية ضمن النتائج.
  • parentProperty (الافتراضي: null) - في حال كان من الممكن أن يُرجع الاستعلام العقدة الجذرية، فإن هذا يسمح بإرجاع parentProperty الخاص بتلك العقدة الجذرية ضمن النتائج. قد يكون اسم خاصية نصيًا أو فهرس مصفوفة رقميًا.
  • callback (الافتراضي: (لا شيء)) - إذا تم توفيره، فسيتم استدعاء دالة استدعاء فور استرداد قيمة نقطة نهاية. الوسيطات الثلاث المقدمة ستكون: قيمة الحمولة (وفقًا لـ resultType)، ونوع الحمولة (سواء كانت "value" عادية أو اسم "property")، وكائن حمولة كامل (مع جميع resultTypes).
  • otherTypeCallback (الافتراضي: <دالة ترمي خطأ عند مواجهة @other()>) - في غياب دعم مخطط JSON حاليًا، يمكن تحديد أنواع تتجاوز الأنواع المدمجة عن طريق إضافة العامل @other() في نهاية الاستعلام. إذا تم مواجهة مثل هذا المسار، فسيتم استدعاء otherTypeCallback مع قيمة العنصر ومساره وأصله واسم خاصية أصله، ويجب أن تُرجع قيمة منطقية تشير إلى ما إذا كانت القيمة المقدمة تنتمي إلى النوع "other" أم لا (أو قد تتعامل مع التحويلات وتُرجع false).

طرق المثيل

  • evaluate(path, json, callback, otherTypeCallback) أو 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() تتم إزالتها بصمت.

الصياغة من خلال الأمثلة

بالنظر إلى JSON التالي، المأخوذ من http://goessner.net/articles/JsonPath/:```json { "store": { "book": [ { "category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95 }, { "category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99 }, { "category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99 }, { "category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99 } ], "bicycle": { "color": "red", "price": 19.95 } } }

والتمثيل التالي بصيغة XML:```xml
<store>
    <book>
        <category>reference</category>
        <author>Nigel Rees</author>
        <title>Sayings of the Century</title>
        <price>8.95</price>
    </book>
    <book>
        <category>fiction</category>
        <author>Evelyn Waugh</author>
        <title>Sword of Honour</title>
        <price>12.99</price>
    </book>
    <book>
        <category>fiction</category>
        <author>Herman Melville</author>
        <title>Moby Dick</title>
        <isbn>0-553-21311-3</isbn>
        <price>8.99</price>
    </book>
    <book>
        <category>fiction</category>
        <author>J. R. R. Tolkien</author>
        <title>The Lord of the Rings</title>
        <isbn>0-395-19395-8</isbn>
        <price>22.99</price>
    </book>
    <bicycle>
        <color>red</color>
        <price>19.95</price>
    </bicycle>
</store>

يرجى ملاحظة أن أمثلة XPath أدناه لا تميّز بين استرجاع العناصر ومحتواها النصي (إلا عندما يكون ذلك مفيدًا لـ إجراء المقارنات أو لمنع الغموض). ملاحظة: لاختبار أمثلة XPath (بما في ذلك إصدارات 2.0)، هذا العرض التوضيحي قد يكون مفيدًا (اضبطه على xml أو xml-strict).| XPath | JSONPath | النتيجة | ملاحظات | |-------------------------------------------------------------------------------------|---------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | /store/book/author | $.store.book[*].author | مؤلفو جميع الكتب في المتجر | يمكن أيضاً تمثيلها بدون $. على النحو store.book[*].author (على الرغم من أن هذا غير موجود في المواصفة الأصلية)؛ لاحظ أن بعض الحروف الحرفية ($ و@) تتطلب escape، ومع ذلك | | //author | $..author | جميع المؤلفين | | | /store/* | $.store.* | كل الأشياء في المتجر، وهي كتبه (مصفوفة كتب) ودراجة حمراء (كائن دراجة). | | | /store//price | $.store..price | سعر كل شيء في المتجر. | | | //book[3] | $..book[2] | الكتاب الثالث (كائن كتاب) | | | //book[last()] | $..book[(@.length-1)]
$..book[-1:] | الكتاب الأخير بالترتيب. | للوصول إلى خاصية ذات حرف خاص، استخدم [(@['...'])] للفلتر (هذه الميزة بالذات غير موجودة في المواصفة الأصلية) | | //book[position()<3] | $..book[0,1]
$..book[:2] | أول كتابين | | | //book/*[self::category\|self::author] أو //book/(category,author) في XPath 2.0 | $..book[0][category,author] | تصنيفات ومؤلفو جميع الكتب | | | //book[isbn] | $..book[?(@.isbn)] | تصفية جميع الكتب التي تحتوي على رقم ISBN | للوصول إلى خاصية ذات حرف خاص، استخدم [?@['...']] للفلتر (هذه الميزة بالذات غير موجودة في المواصفة الأصلية) | | //book[price<10] | $..book[?(@.price<10)] | تصفية جميع الكتب الأرخص من 10 | | | //*[name() = 'price' and . != 8.95] | $..*[?(@property === 'price' && @ !== 8.95)] | الحصول على جميع قيم الخصائص للكائنات التي تكون خاصيتها price ولا تساوي 8.95 | مع @ المجردة التي تسمح بتصفية الكائنات حسب قيمة الخاصية (وليس بالضرورة داخل المصفوفات)، يمكنك إضافة ^ بعد التعبير للوصول إلى الكائن الذي يمتلك الخصائص التي تمت تصفيتها | | / | $ | جذر كائن JSON (أي الكائن بأكمله نفسه) | للحصول على $ حرفية (بمفردها أو في أي مكان في المسار)، يجب استخدام escape بالعلامة الخلفية (backtick) | | //*/*\|//*/*/text() | $..* | جميع العناصر (والنصوص) تحت الجذر في مستند XML. جميع أعضاء بنية JSON تحت الجذر. | | | //* | $.. | جميع العناصر في مستند XML. جميع المكونات الأصلية لبنية JSON بما في ذلك الجذر. | لم يتم تحديد هذا السلوك مباشرة في المواصفة الأصلية | | //*[price>19]/.. | $..[?(@.price>19)]^ | أصل تلك العناصر المحددة التي يزيد سعرها عن 19 (أي قيمة المتجر كأصل للدراجة ومصفوفة الكتب كأصل لكتاب فردي) | الأصل (علامة الإقحام ^) غير موجود في المواصفة الأصلية | | /store/*/name() (في XPath 2.0) | $.store.*~ | أسماء خصائص الكائن الفرعي للمتجر ("book" و"bicycle"). مفيدة مع خصائص wildcard. | اسم الخاصية (العلامة ~) غير موجود في المواصفة الأصلية | | /store/book[not(. is /store/book[1])] (في XPath 2.0) | $.store.book[?(@path !== "$['store']['book'][0]")] | جميع الكتب باستثناء ذلك الموجود في المسار الذي يشير إلى الأول | @path غير موجود في المواصفة الأصلية | | //book[parent::*/bicycle/color = "red"]/category | $..book[?(@parent.bicycle && @parent.bicycle.color === "red")].category | يلتقط جميع تصنيفات الكتب حيث يكون للكائن الأصل للكتاب عنصر فرعي دراجة بلون أحمر (أي جميع الكتب) | @parent غير موجود في المواصفة الأصلية | | //book/*[name() != 'category'] | $..book.*[?(@property !== "category")] | يلتقط جميع العناصر الفرعية لـ"book" باستثناء عناصر "category" | @property غير موجود في المواصفة الأصلية | | //book[position() != 1] | $..book[?(@property !== 0)] | يلتقط جميع الكتب التي تكون خاصيتها (والتي، نظراً لأننا نصل داخل مصفوفة، هي الفهرس الرقمي) ليست 0 | @property غير موجود في المواصفة الأصلية | | /store/*/*[name(parent::*) != 'book'] | $.store.*[?(@parentProperty !== "book")] | يلتقط أحفاد المتجر الذين ليست خاصيتهم الأصلية book (أي أطفال الدراجة، "color" و"price") | @parentProperty غير موجود في المواصفة الأصلية | | //book[count(preceding-sibling::*) != 0]/*/text() | $..book.*[?(@parentProperty !== 0)] | الحصول على قيم الخصائص لجميع حالات الكتب حيث لا تكون الخاصية الأصلية لهذه القيم (أي فهرس المصفوفة الذي يحتوي على الكائن الأصل لعنصر الكتاب) هي 0 | @parentProperty غير موجود في المواصفة الأصلية | | //book[price = /store/book[3]/price] | $..book[?(@.price === @root.store.book[2].price)] | تصفية جميع الكتب التي يساوي سعرها سعر الكتاب الثالث | @root غير موجود في المواصفة الأصلية | | //book/../*[. instance of element(*, xs:decimal)] (في XPath 2.0) | $..book..*@number() | الحصول على القيم الرقمية داخل مصفوفة الكتاب | @number()، والأنواع الأساسية الأخرى (@boolean()، @string())، والأنواع المشتقة الأخرى منخفضة المستوى (@null()، @object()، @array())، والنوع المضاف من JSONSchema، @integer()، والنوع المركب @scalar() (الذي يقبل أيضاً undefined والأرقام غير المنتهية لكائنات JavaScript بالإضافة إلى جميع الأنواع الأساسية غير الكائنية/غير الدوالية)، والنوع @other()، الذي يُستخدم بالتزامن مع دالة استدعاء معرّفة من قبل المستخدم (انظر otherTypeCallback)، والأنواع التالية غير JSON التي يمكن مع ذلك استخدامها مع JSONPath عند الاستعلام عن كائنات JavaScript غير JSON (@undefined()، @function()، @nonFinite()) غير موجودة في المواصفة الأصلية | | //book/*[name() = 'category' and matches(., 'tion$')] (XPath 2.0) | $..book.*[?(@property === "category" && @.match(/TION$/i))] | جميع تصنيفات الكتب التي تطابق التعبير النمطي (تنتهي بـ'TION' دون حساسية لحالة الأحرف) | @property غير موجود في المواصفة الأصلية. | | //book/*[matches(name(), 'bn$')]/parent::* (XPath 2.0) | $..book.*[?(@property.match(/bn$/i))]^ | جميع الكتب التي لديها خاصية تطابق التعبير النمطي (تنتهي بـ'TION' دون حساسية لحالة الأحرف) | @property غير موجود في المواصفة الأصلية. ملاحظة: يستخدم محدد الأصل ^ في نهاية التعبير للعودة إلى الكائن الأصل؛ بدون محدد الأصل، يطابق قيمتي مفتاح isbn. | | | ` (على سبيل المثال، `$ لمطابقة خاصية مسماة حرفياً $) | يهرب التسلسل بأكمله الذي يليها (ليُعامل كقيمة حرفية) | ` غير موجودة في المواصفة الأصلية؛ للحصول على backtick حرفية، استخدم backtick إضافية لعمل escape |أي متغيرات إضافية يتم توفيرها كخصائص على خيار الكائن الاختياري "sandbox" تكون متاحة أيضًا للتقييمات (المبنية على الأقواس).

مصادر الالتباس المحتملة لمستخدمي XPath

  1. في JSONPath، تعبير التصفية، بالإضافة إلى كون @ مرجعًا لأبنائه، يقوم فعليًا بتحديد الأبناء المباشرين أيضًا، بينما في XPath، لا تحدد شروط التصفية الأبناء بل تحدد أيًّا من العقد الأصلية سيتم الحصول عليه في النتيجة.
  2. في JSONPath، فهارس المصفوفات، كما في JavaScript، أساسها 0 (تبدأ من 0)، بينما في XPath، أساسها 1.
  3. في JSONPath، تستخدم اختبارات المساواة (كما في JavaScript) علامات يساوي متعددة بينما في XPath، تُستخدم علامة يساوي واحدة.

واجهة سطر الأوامر

يتم توفير واجهة سطر أوامر (CLI) أساسية. يمكن الوصول إليها باستخدام npx jsonpath-plus <json-file> <jsonpath-query>.

أفكار

  1. دعم OR خارج الفلاتر (كما في XPath |) والتجميع.
  2. إنشاء صيغة تعمل مثل فلاتر XPath في عدم تحديد الأبناء؟
  3. السماح بخيار يعادل parentNode (مع الحفاظ على السلسلة الكاملة من كائنات parent وparentProperty حتى الجذر)

التطوير

تشغيل الاختبارات على Node:```shell npm test

لإجراء الاختبارات داخل المتصفح:

- اخدم ملفات js/html:```shell
npm run browser-test

الأمان

يُرجى مراجعة SECURITY.md للاطلاع على اعتبارات الأمان المهمة وتعليمات الإبلاغ عن الثغرات.

الترخيص

رخصة MIT.

اقرأ المزيد

الفئات

أدوات عامةالتحليل الثابتتحليل الكودالبرمجة النصية والأتمتةالأدوات والمكونات