منسق JSON
نسّق JSON الصحيح بمسافات بادئة واضحة، وافحص البيانات المتداخلة، واختر مستوى إزاحة مناسباً من دون تغيير نموذج البيانات.
اجعل JSON أسهل للقراءة
يفيد JSON المضغوط في النقل، لكنه يصعب فحصه أثناء التطوير. يعرض منسق JSON النص على أسطر مرتبة مع مسافات بادئة متسقة، فتستطيع متابعة التعشيق ومقارنة الحقول وملاحظة البنية غير المتوقعة بسرعة أكبر.
التنسيق خطوة عرض. هدفها مساعدة القارئ على فهم مستند صحيح مع إبقاء القيم والعلاقات كما هي. إذا كان المصدر غير سليم، صحح بناءه أولاً؛ تغيير المسافات لا يصلح اقتباساً مفقوداً أو قوساً غير مغلق.
ماذا يعني تنسيق JSON؟
JSON صيغة نصية تتكون من كائنات ومصفوفات ونصوص وأرقام وقيم منطقية وnull. يقرأ المنسق هذه البنية ثم يعيد كتابتها مع أسطر ومسافات. خيار الإزاحة يحدد عرض كل مستوى متداخل، ولا يضيف حقولاً أو يرتب المفاتيح أو يحول JSON إلى صيغة أخرى أو يطبق قواعد JSON Schema.
تستخدم صيغة JSON القياسية علامتي اقتباس مزدوجتين لأسماء الأعضاء والنصوص. التعليقات والفاصلة الأخيرة وNaN وInfinity امتدادات شائعة في بعض اللغات وليست جزءاً من القواعد القياسية. لذلك قد يفشل كائن JavaScript المألوف عند التعامل معه على أنه JSON.
طريقة الاستخدام
- الصق مستند JSON أو اكتبه في حقل المصدر.
- اختر قيمة رقمية للإزاحة، مثل مسافتين أو أربع مسافات.
- شغّل المنسق واقرأ الناتج. إذا فشل التحليل، صحح المصدر ثم أعد المحاولة.
- قارن القيم والبنية قبل نسخ الناتج إلى ملف أو مراجعة برمجية.
منهج التنسيق
- التحليل أولاً
يجب تفسير المدخل على أنه قيمة JSON واحدة قبل ترتيبها. بهذا ينفصل خطأ الصياغة عن مشكلة شكل العرض.
- إزاحة القيم المتداخلة
تكتب الكائنات والمصفوفات على أسطر متعددة عندما يساعد التعشيق على القراءة. تتكرر الإزاحة المختارة في كل مستوى.
- إخراج نص مقروء
الناتج تمثيل نصي جديد للقيمة المحللة. قد تتغير المسافات بينما تبقى بنية البيانات المقصودة نفسها.
لا تعتبر التنسيق دليلاً على توافق البيانات مع مخطط أو قواعد عمل؛ تلك فحوص منفصلة.
قراءة الناتج
افحص الناتج كنص وكبيانات. تأكد من بقاء المفاتيح وترتيب المصفوفات وأنواع القيم ومحتوى النصوص كما تريد. الأسطر والمسافات الإضافية جزء متوقع من التنسيق.
تعني رسالة الخطأ أن المصدر لم يُفسر وفق قواعد JSON المقبولة. راجع الفواصل والاقتباسات والأقواس ومحارف الهروب والقيمة القريبة من موضع المشكلة.
أخطاء شائعة
من أسباب الفشل لصق كائن JavaScript أو YAML أو جزء JSON يحوي تعليقات. حوّل المصدر إلى JSON قياسي، مع اقتباس أسماء الخصائص والنصوص بعلامات مزدوجة.
تغيير الإزاحة ليس ترتيباً للمفاتيح ولا تحققاً من الحقول المطلوبة. افصل هذه المهام حتى لا تخلط بين سهولة القراءة واكتمال السجل.
حدود يجب تذكرها
الواجهة الموثقة تستقبل نص المصدر وقيمة الإزاحة. هذا لا يثبت دعم JSON Schema أو التحويل إلى صيغة أخرى أو JSON5 أو رفع الملفات أو الحفاظ على كل الحالات الخاصة بالمحلل.
تكون المسافات غالباً غير مؤثرة في قيمة JSON، لكن المستندات الضخمة والمفاتيح المكررة ودقة الأرقام والعادات الخاصة بالتطبيق تستحق اختباراً منفصلاً في النظام المستهلك للبيانات.
Examples
تنسيق كائن مضغوط
كيف يتحول الكائن ذي السطر الواحد إلى شكل مقروء؟
أرسل الكائن مع إزاحة من مسافتين.
ظهر كل حقل في سطر مستقل، ولم تتغير الأسماء أو القيم.
تنسيق مصفوفة متداخلة
كيف أفحص مصفوفة من الكائنات؟
شغّل المنسق مع مسافتين.
توضح الأقواس وحدود الكائنات تسلسل المصفوفة وطبقاتها.
اختيار أربع مسافات
متى تفيد الإزاحة الأوسع؟
اختر أربع مسافات ثم نسّق المصدر.
يظهر كل مستوى متداخل بعرض أكبر، وقد يساعد ذلك في المراجعة على شاشة واسعة.
اكتشاف اقتباس مفقود
ماذا يحدث إذا لم يوضع اسم الخاصية بين اقتباسين؟
أرسل المصدر واقرأ نتيجة التحقق.
هذا ليس JSON قياسياً لأن اسم العضو يجب أن يكون نصاً بين اقتباسين مزدوجين. أضف الاقتباسين قبل التنسيق.
الإبقاء على القيمة المنطقية
هل يحول التنسيق true إلى نص؟
نسّق الكائن وقارن أنواع القيم.
تبقى true قيمة منطقية، بينما تبقى yes نصاً لأنها بين اقتباسين.
الحفاظ على null
كيف تظهر null في الناتج المنسق؟
نسّق الكائن وافحص قيمة الخاصية.
تبقى null قيمة صريحة، وهي مختلفة عن حذف الخاصية أو وضع نص فارغ.
Frequently asked questions
هل التنسيق يتحقق من JSON؟
يحتاج المنسق إلى تحليل المصدر، لذلك قد تمنع أخطاء الصياغة ظهور الناتج. لكنه لا يتحقق من الحقول المطلوبة أو قواعد العمل أو JSON Schema.
هل سيغير التنسيق القيم؟
العملية المقصودة تغير المسافات وتخطيط الأسطر. مع ذلك قارن الناتج عندما توجد أرقام كبيرة جداً أو مفاتيح مكررة لأن سلوك المحلل قد يكون مهماً.
هل أستطيع استعمال الاقتباس المفرد؟
لا في JSON القياسي. يجب استعمال الاقتباس المزدوج للنصوص وأسماء الأعضاء؛ الاقتباس المفرد شائع في بعض لغات البرمجة وليس في قواعد JSON القياسية.
لماذا تفشل الفاصلة الأخيرة؟
تقبل بعض امتدادات اللغات فاصلة بعد آخر عنصر، لكن JSON القياسي لا يقبلها. احذفها قبل التنسيق.
هل أختار مسافتين أم أربعاً؟
اختر ما يناسب أسلوب مشروعك أو سياق المراجعة. الخيار يؤثر في القراءة والفراغات، لا في نموذج البيانات.
هل يرتب المنسق مفاتيح الكائن؟
لا تفترض ذلك. التنسيق يتعلق بالشكل؛ حافظ على الترتيب الظاهر ما لم توثق الأداة خياراً للترتيب.
هل يصلح التنسيق JSON غير السليم؟
لا. صحح الاقتباسات أو الفواصل أو الأقواس أو محارف الهروب أولاً. لا يستطيع المنسق استنتاج البنية المقصودة بأمان.
هل JSON المنسق أصغر حجماً؟
غالباً العكس، لأن الناتج الجميل يضيف فراغات. يفيد JSON المضغوط في النقل، بينما يفيد المنسق في مراجعة البشر.