انتقل إلى المحتوى
Numio

تحويل JSON إلى تعليقات JSDoc — Numio

يبني تعليق JSDoc من نوع @typedef فيه سطر @property لكل مفتاح انطلاقًا من عيّنة JSON. تستخدم المفاتيح المتداخلة مسارات بالنقاط مثل address.city، ومفاتيح عناصر المصفوفة name[].key، والمفاتيح الاختيارية [أقواسًا مربعة].

الحصول على الإكمال التلقائي في المحرر لاستجابة API في مشروع JavaScript عادي.

JSON

JSDoc

متى تستخدمها

  • الحصول على الإكمال التلقائي في المحرر لاستجابة API في مشروع JavaScript عادي.
  • تفعيل فحص الأنواع عبر // @ts-check لبيانات JSON دون الانتقال إلى TypeScript.

طريقة الاستخدام

  1. الصق كائن JSON في المحرر.
  2. تحقق من أسطر @property على اليمين: تأتي الأنواع من قيم العيّنة، مثل string[] لـ tags وobject لـ address.
  3. انسخ التعليق، وأعد تسمية الـ typedef من json إلى اسم حقيقي، واستخدمه مع @type {YourName}.

إدخال JSON

{
  "id": 42,
  "name": "Ada",
  "tags": ["math", "poetry"],
  "address": { "city": "London", "zip": "NW1" },
  "orders": [
    { "sku": "A1", "qty": 2 },
    { "sku": "B7", "qty": 1, "gift": true }
  ],
  "deletedAt": null
}

JSDoc @typedef

/**
 * @typedef {object} json
 * @property {number} id
 * @property {string} name
 * @property {string[]} tags
 * @property {object} address
 * @property {string} address.city
 * @property {string} address.zip
 * @property {object[]} orders
 * @property {string} orders[].sku
 * @property {number} orders[].qty
 * @property {boolean} [orders[].gift]
 * @property {null} deletedAt
 */

التفاصيل والقيود

يُنشأ التعليق في متصفحك؛ ولا تُرسل أي بيانات إلى خادم. لا توجد إعدادات.

تُدمج كل عناصر المصفوفة: تُكتب المفاتيح المفقودة من بعض العناصر بين أقواس مربعة كاختيارية، مثل [orders[].gift].

القيمة التي هي null فقط تُعطى النوع {null}؛ ووجود null بجانب قيم حقيقية يعطي اتحادًا مثل {string|null}. وتُعطى المصفوفات الفارغة النوع {Array}.

أبقِ المعرّفات مثل 001 سلاسل نصية في الإدخال؛ فعند تحليلها كأرقام تضيع الأصفار البادئة.

FAQ

كيف تُوثَّق مصفوفات الكائنات؟

تُعطى المصفوفة النوع object[] وتُسرد مفاتيح العناصر بمسارات name[].key، مثل orders[].sku، مع جمع مفاتيح كل العناصر.

هل يمكنني تحويل مصفوفة JSON في المستوى الجذري؟

نعم. يصبح شكل العنصر @typedef {object} jsonItem مع خصائصه، يليه @typedef {jsonItem[]} json للمصفوفة.

هل يفهم TypeScript الـ typedef المُنشأ؟

نعم، يقرأ TypeScript @typedef مع مسارات @property المتداخلة في ملفات .js عند تفعيل checkJs أو // @ts-check. استبدل أي {null} مجرّد بالنوع الحقيقي أولًا.

المواصفات والمراجع