إضافة DevTools

تضيف إضافة ⁦Text.js DevTools⁩ لوحة Text.js بجانب «وحدة التحكم». تفحص هذه اللوحة التطبيق الذي يُعرض في وحدة التحكم.

• المكوّنات: شجرة React لكل جذر لوحدة التحكم، مع الخصائص والخطافات والمفاتيح وعقد المشهد tx-box / tx-text التي تقابلها، بتخطيط قائم على الخلايا.
• الإطار: الإطار الحالي على هيئة شبكة خلايا. مرّر المؤشر فوق خلية لمعرفة المكوّن الذي رسمها. انقر لتحديد العقدة. تُميّز العقدة في وحدة التحكم المباشرة.
• المخطط الزمني: أزمنة React والتخطيط والرسم والترميز لكل إطار، والإطارات المتجاوزة مقابل المُخرجة، وتوقيت الإطارات وعناصر span من نوع %c.
• عناصر التحكم: إيقاف الإخراج مؤقتًا واستئنافه، وإظهار الهيكل السلكي للتخطيط أو إخفاؤه، وتثبيت حجم الشبكة أو ملاءمته، ونسخ الإطار كنص.

#التثبيت

تُبنى الإضافة من packages/devtools-extension وتُحمّل دون حزم:

bun run --cwd packages/devtools-extension build

1. افتح chrome://extensions وفعّل وضع المطوّر.
2. انقر تحميل إضافة تم فك حزمتها واختر packages/devtools-extension/dist.
3. أعد تحميل التطبيق وافتح DevTools. تظهر لوحة Text.js بمجرد أن تنشئ الصفحة جذرًا لوحدة التحكم.

تكتب عملية البناء أيضًا الملف release/textjs-devtools-<version>.zip، جاهزًا لمتجر Chrome الإلكتروني.

#المكوّنات

اختر مكوّنًا لعرض خصائصه وخطافاته بترتيب استدعائها (State و Ref و Memo و Effect وغيرها، مع القيم الحالية) وعقدة المشهد التي يعرضها، مع الموضع والحجم والمسافات الداخلية للصندوق بوحدة الخلية. يميّز تمرير المؤشر فوق صف العقدة في وحدة التحكم. يُظهر خيار العقد المضيفة عنصري tx-box و tx-text بين المكوّنات أو يخفيهما.

تتحدث الشجرة بعد عمليات التثبيت ما دامت اللوحة مفتوحة. القيم ملخصات للعرض، وليست كائنات حية.

#الإطار

يرسم فاحص الإطار مخزن الخلايا المؤقت الخاص بالعارض: كل رمز ولون أمامي وخلفية وسمة. يعرض تمرير المؤشر فوق خلية محرفها وألوانها، وعقدة المشهد التي تعلوها في ترتيب الرسم (مع مراعاة overflow وإزاحات التمرير و zIndex)، والمكوّنات التي عرضت تلك العقدة. يحدد النقر العقدة في المكوّنات ويميّزها في وحدة التحكم المباشرة باستخدام طبقة التمييز الخاصة بالعارض.

#المخطط الزمني

يمثل كل شريط إطارًا واحدًا للعارض:

تُرسم الإطارات المتجاوزة بلون باهت: لم يتغير شيء، لذا لم يُسجّل شيء. يعرض مخطط التوقيت الفاصل بين الإطارات المُخرجة مقارنة بالحد الأدنى للفاصل البالغ 66 ms.

يتوقف قياس الزمن عند console.log(). يحدث تنسيق الرسالة ورسمها داخل DevTools ولا يمكن رصدهما من الصفحة، لذا لا يعرضهما المخطط الزمني. تُحسب عمليات العرض المتزامنة التي تُثبّت بين الإطارات كعمليات تثبيت، دون قياس زمنها.

#آلية العمل

مثل ⁦React DevTools⁩، تثبّت الإضافة خطافًا عامًا قبل تشغيل الصفحة:

globalThis.__TEXTJS_DEVTOOLS_HOOK__

يسجّل كل جذر لوحدة التحكم نفسه لدى الخطاف عند إنشائه. لا يوجد الخطاف دون الإضافة، ويتحقق الجذر من وجوده مرة واحدة فقط ولا ينفّذ أي عمل لكل إطار. عند تثبيت الإضافة مع إغلاق اللوحة، تقتصر تكلفة الإطارات على قراءة خاصية واحدة. لا تُحسب الأشجار والإطارات إلا عندما تطلبها اللوحة.

تتدفق الرسائل من الصفحة → نص المحتوى البرمجي → عامل الخدمة → اللوحة. تعمل نصوص المحتوى البرمجية على كل صفحة ليكون الخطاف موجودًا قبل بدء تشغيل التطبيق. هذه هي صلاحية الوصول الوحيدة التي تطلبها الإضافة. لا تحمّل أي شيفرة عن بُعد ولا ترسل شيئًا خارج الجهاز.

#الخصوصية

لا تجمع الإضافة أي بيانات. لا ترسل طلبات شبكة، ولا تخزّن شيئًا، ولا تستخدم أدوات تحليل. تنتقل أشجار المكوّنات والإطارات وقياسات الزمن بين الصفحة ولوحة DevTools في المتصفح نفسه فقط، وتُحذف عند إغلاق DevTools. يكتب خيار نسخ الإطار نص الإطار إلى الحافظة عند النقر عليه.

#القيود

• متصفح Chrome والمتصفحات المستندة إلى Chromium، الإصدار 111 أو أحدث.
• التطبيقات التي بدأت قبل تثبيت الإضافة تحتاج إلى إعادة تحميل.
• يُفحص الإطار العلوي لعلامة التبويب فقط.
• تأتي قياسات الزمن من performance.now()، التي تقلّل المتصفحات دقتها إلى نحو 0.1 ms.