⁦VS Code⁩

تعرض إضافة Text.js في ⁦VS Code⁩ إطار وحدة التحكم بجانب الشيفرة. وتعكس التطبيق الذي يعمل باستخدام text dev، أو تعرض الملف المفتوح نفسه عندما لا يكون أي تطبيق قيد التشغيل. وتضيف أيضًا إنشاء الهياكل الأولية لمسارات ⁦App Router⁩، ومقتطفات شيفرة وروابط لرموز الأخطاء TX###.

#التثبيت

ثبّت Text.js من ⁦Visual Studio Marketplace⁩. في ⁦VS Code⁩، افتح عرض الإضافات (⌘⇧X) وابحث عن textjs.vscode-textjs، أو شغّل:

code --install-extension textjs.vscode-textjs

تنشط الإضافة في أي مجلد يحتوي على تطبيق Text.js: ملف text.config.ts، أو حزمة تعتمد على @textjs/app وتحتوي على دليل app/. وتعمل أيضًا في المستودعات الموحدة التي تضم عدة تطبيقات.

#المعاينة المباشرة

افتح ملف page.tsx أو layout.tsx أو مكوّنًا، وشغّل Text.js: ⁦Open Preview⁩ (⌘K V)، أو انقر زر المعاينة في شريط عنوان المحرر. ترسم اللوحة الإطار بواجهة DevTools نفسها وخلايا خط Menlo نفسها المستخدمة في وحدة التحكم في المتصفح.

تحصل المعاينة على إطاراتها من أحد مصدرين. وتوضح الشارة في شريط الأدوات المصدر النشط:

يستخدم auto (الإعداد الافتراضي) المصدر المباشر عند توفره، والمصدر بلا واجهة في غير ذلك. ثبّت أحدهما من الشارة أو باستخدام textjs.preview.mode.

#لوحة المفاتيح

انقر وحدة التحكم لإرسال ضغطات المفاتيح إلى التطبيق: تعمل الأسهم وTab والاختصارات والكتابة واللصق كما في المتصفح. انقر خارج وحدة التحكم للتوقف. تظل اختصارات المحرر مثل ⌘P و⌘⇧P موجهة إلى ⁦VS Code⁩. ويرسل التمرير فوق وحدة التحكم أحداث عجلة التمرير.

يمكن كتابة مسار في حقل العنوان، مثل /deployments/dpl_a1، للتنقل في أي من المصدرين.

#الوضع المباشر

عند فتح معاينة، يطلب خادم التطوير من علامات التبويب المتصلة بث إطاراتها. ترسل علامات التبويب الصفوف التي تغيرت فقط، وتتوقف عن الإرسال عند إغلاق المعاينة، فلا يتحمل التطبيق أي تكلفة إذا لم تكن له معاينة مفتوحة. يمر حفظ الملف عبر ⁦Fast Refresh⁩، وتتحدث المعاينة مع علامة التبويب.

فعّل المتابعة (textjs.preview.followEditor) لنقل علامة تبويب المتصفح إلى مسار ملف page.tsx الذي تحرره.

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

#الوضع بلا واجهة

تبدأ الإضافة مشغّلًا صغيرًا داخل المشروع. يحمّل ملفات المسارات باستخدام Vite و@textjs/app الخاصين بالمشروع، فتعمل الأسماء البديلة و TypeScript و JSX كما في text dev. ويركّب ⁦App Router⁩ عند مسار الملف المفتوح مع تخطيطاته، باستخدام سجل محفوظ في الذاكرة:

تشغّل استدعاءات fetch("/api/...") من المصدر نفسه معالجات route.ts داخل العملية، كما في text run. تتبع الشبكة حجم اللوحة، ويؤدي حفظ أي ملف في التطبيق إلى عرضه مجددًا. تظهر الأخطاء فوق الإطار، مع روابط إلى صفحات TX### الخاصة بها.

#الأوامر

تتوفر أوامر إنشاء الهياكل الأولية أيضًا في قائمة سياق المجلدات في المستكشف. تقبل مقاطع ⁦App Router⁩ مثل settings وblog/[slug] وdocs/[...path] و(marketing)/about، وترفض وضع page وroute.ts في المقطع نفسه. تحصل مشاريع JavaScript (التي لا تحتوي على tsconfig.json) على ملفات .jsx و.js.

#مقتطفات الشيفرة

#رموز الأخطاء

مرّر المؤشر فوق رمز TX### في أي موضع: في الشيفرة المصدرية أو السجلات أو لوحة الإخراج أو تتبع مكدس ملصق. تعرض نافذة التمرير عنوانه ورسالته وحزمته، مع رابط إلى صفحته على textjs.org. وكل رمز هو أيضًا رابط (انقر مع الضغط على ⌘).

#شريط الحالة

يعرض العنصر ▼ حالة خادم التطوير وحجم شبكة وحدة التحكم، مثل ▼ :3000 120×36. ترسل علامات التبويب حجمها إلى خادم التطوير كلما تغير، حتى دون وجود معاينة مفتوحة. انقر العنصر للوصول إلى الأوامر الرئيسية.

#الإعدادات

#الثقة بمساحة العمل

تشغّل المعاينة وخادم التطوير شيفرة المشروع (إعدادات Vite وtext.config.* والمكوّنات). في الوضع المقيّد، لا توفر الإضافة إلا مقتطفات الشيفرة وإنشاء الهياكل الأولية وروابط الأخطاء، وتتجاهل textjs.preview.runtime وtextjs.devServer.command وtextjs.devServer.url من إعدادات مساحة العمل. امنح الثقة لمساحة العمل لتفعيل المعاينة. لا تُعرض أبدًا معاينات للملفات خارج مجلدات مساحة العمل.

#آلية العمل

يوفر text dev ثلاث نقاط نهاية للمحررات. لا تستجيب إلا لاتصالات الاسترجاع المحلي الموجهة إلى مضيف استرجاع محلي (localhost، 127.0.0.1، [::1])، وللطلبات التي لا تحتوي على Origin أو التي تحمل مصدر خادم التطوير نفسه. تُرفض طلبات المتصفحات العابرة للمواقع وطلبات no-cors:

ترسل علامات التبويب الإطارات إلى خادم التطوير عبر مقبس HMR في Vite، الذي يتطلب رمزًا مميزًا خاصًا بكل خادم. يُصدّر تنسيق النقل من @textjs/app/frame-protocol (FrameEncoder، FrameDecoder، parseInputMessage) إذا أردت بناء عارض خاص بك. لا يوجد أي من ذلك في مخرجات text build.