ما هو JSON إلى TypeScript؟

يحوِّل JSON إلى TypeScript بيانات JSON إلى واجهات وتعريفات أنواع TypeScript. يتعرّف على السلاسل النصية والأرقام والقيم المنطقية والمصفوفات والكائنات المتداخلة، ويُعلِّم الحقول القابلة للإلغاء كاختيارية بأنواع الاتحاد. وفّر وقت كتابة الأنواع يدويًا لاستجابات API.

حين تحتوي المصفوفة على كائنات بأشكال متفاوتة قليلاً، يدمجها المولّد: المفاتيح الغائبة في بعض السجلات تصبح اختيارية بإضافة `?`. كل كائن متداخل يحصل على واجهة مستقلة باسم (User، UserAddress، UserAddressGeo). المصفوفات المختلطة تنتج أنواعًا اتحادية مثل `(string | number)[]`. تُوسَم سلاسل التاريخ بصيغة ISO 8601 بتعليق JSDoc، وحقول النص ذات المجموعة الصغيرة المتكررة من القيم تُستنتج اتحادًا لحرفيات نصية بدلًا من نوع string عام. إلى جانب مُخرَج TypeScript، يُنتج المُدخَل نفسه ثلاثة تبويبات إضافية: مخطط Zod مكافئ، وبيانات تجريبية مملوءة بقيم أمثلة واقعية، ومخطط JSON من إصدار draft-07. يمكنك التبديل بين الواجهة والاسم البديل للنوع، تفعيل كلمة export، ترتيب المفاتيح أبجديًا، وتفعيل camelCase لتحويل مفاتيح snake_case أو kebab-case إلى أسماء تتوافق مع أعراف TypeScript.

كيفية الاستخدام

1. الخطوة 1 — الصق كائن JSON أو مصفوفة، اسحب ملف .json إلى مربع الإدخال، أو اجلب JSON مباشرة من رابط. تحلِّل الأداة الهيكل وتستنتج أنواع TypeScript لكل حقل.
2. الخطوة 2 — خصِّص المخرج: حدِّد اسم الواجهة الجذر، واختر بين الواجهات والأسماء البديلة للأنواع، وفعِّل أو عطِّل الخصائص الاختيارية للحقول التي قد تكون خالية.
3. الخطوة 3 — انسخ المُخرَج أو نزِّله. تتشارك أربعة تبويبات الإعدادات نفسها: أنواع TypeScript، ومخطط Zod مكافئ للتحقق وقت التشغيل، وبيانات تجريبية جاهزة للاختبارات و Storybook، ومخطط JSON من إصدار draft-07 لمواصفات OpenAPI أو مكتبات النماذج. تحصل جميع الكائنات المتداخلة تلقائيًا على واجهاتها المُسمَّاة الخاصة.

متى تستخدم

• كتابة أنواع لرد API لا يوجد له ملف مواصفات OpenAPI/Swagger.
• توليد أنواع سريعة لملف إعدادات JSON (مثل tsconfig.json أو package.json) تقرأه من سكربت.
• بناء طبقة بأنواع فوق رد SDK طرف ثالث في ثوانٍ.

النتيجة

تُرجع واجهة برمجة التطبيقات الخاصة بك كائن مستخدم يحتوي على عنوان وتفضيلات متداخلة. الصق استجابة JSON، واضبط الاسم الجذر على User، واحصل على واجهات واضحة: User وUserAddress وUserPreferences — مع أنواع صحيحة مثل string | null للحقول الاختيارية.

الأسئلة الشائعة

كيف يقرّر المولّد أيّ الحقول اختيارية؟

إذا كان المدخل كائناً واحداً وفُعِّل خيار «اعتبار القابل لـ null اختيارياً»، فالحقول ذات القيمة null تُعلَّم اختيارية. أما في مصفوفات الكائنات، فيُجمَع اتحاد جميع المفاتيح، والمفاتيح الناقصة في سجلٍ واحد على الأقل تصبح اختيارية.

ماذا عن المصفوفات التي تختلف أشكال عناصرها؟

نفس المنطق: المفاتيح الموجودة في كل عنصر تظل إلزامية، الموجودة في بعضها تصبح اختيارية، والقيم ذات الأنواع البدائية المختلطة تصبح اتحاداً مثل `string | number`. النتيجة واجهة واحدة تصف المصفوفة كاملة.

هل أختار interface أم type alias؟

الـ interface أسهل في التوسيع عبر دمج التصريحات، وهي الخيار الشائع لأشكال API. الـ type alias أنسب حين تجمع لاحقاً بين اتحادات وتقاطعات وأنواع مُحوّلة. لا فرق وقت التشغيل، اختر ما يتبعه مشروعك.

لماذا تظهر بعض أسماء الخصائص بين علامات اقتباس؟

إذا احتوى المفتاح حروفاً لا تصلح كمعرّف في TypeScript (شرطة، فراغ، يبدأ برقم، نقطة)، يلفّه المولّد بعلامات اقتباس. النوع يبقى صحيحاً وتصل إلى الحقل في الشيفرة عبر `obj["weird-key"]`.

هل تلتقط الأنواع المتولِّدة تغيرات API إذا تغيّر شكل الرد؟

نعم، إن أعدت توليدها. الأنواع لقطة من JSON الذي لصقته ولا تتحدّث وحدها. الممارسة المعتادة إعادة التوليد عند ترقية إصدار API ومراجعة الفرق في مراجعة الشيفرة.

أدوات ذات صلة