VS Code
پیش‌نمایش زندهٔ فریم کنسول کنار کد شما، ساختار اولیهٔ App Router، قطعه‌کدها و پیوندهای خطای TX.
افزونهٔ 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 کنسول مرورگر شما ترسیم می‌کند.
پیش‌نمایش فریم‌های خود را از یکی از دو منبع می‌گیرد. نشان موجود در نوار ابزار مشخص می‌کند کدام منبع فعال است:
| منبع | زمان استفاده | آنچه می‌بینید |
|---|---|---|
| زنده | دستور text dev در حال اجرا است و برنامه در یک زبانهٔ مرورگر باز است | برنامهٔ واقعی، با وضعیت، داده‌ها و اندازهٔ شبکهٔ آن |
| بدون رابط | سرور توسعه‌ای وجود ندارد، یا هیچ زبانه‌ای باز نیست | فایل باز که افزونه آن را به اندازهٔ پنل رندر می‌کند |
حالت 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 را با چیدمان‌های آن در مسیر فایل باز و با استفاده از تاریخچه‌ای در حافظه نصب می‌کند:
| فایل | پیش‌نمایش |
|---|---|
app/page.tsx | / |
app/(shop)/items/[id]/page.tsx | /items/id (بخش‌های پویا از نام خود استفاده می‌کنند) |
app/blog/[[...slug]]/layout.tsx | /blog |
components/Card.tsx | خروجی پیش‌فرض، یا نخستین خروجی PascalCase، بدون props |
فراخوانی‌های هم‌مبدأ fetch("/api/...") کنترل‌گرهای route.ts شما را مانند دستور text run در همان فرایند اجرا می‌کنند. شبکه از اندازهٔ پنل پیروی می‌کند و ذخیرهٔ هر فایلی در برنامه باعث رندر دوبارهٔ آن می‌شود. خطاها همراه با پیوند به صفحات TX### خود در بالای فریم نمایش داده می‌شوند.
فرمان‌ها
| فرمان | توضیح |
|---|---|
| Text.js: Start Dev Server | اسکریپت dev شما (یا دستور text dev) را در ترمینال اجرا می‌کند |
| Text.js: Stop Dev Server | سرور توسعه‌ای را که از VS Code راه‌اندازی شده متوقف می‌کند |
| Text.js: Open Preview | پیش‌نمایش زنده را برای فایل فعال باز می‌کند |
| Text.js: Open in Browser Console | مسیر فعلی را روی سرور توسعه باز می‌کند. سپس کنسول مرورگر را باز کنید |
| Text.js: New Page | app/<route>/page.tsx با فراداده و params نوع‌دار |
| Text.js: New Layout | app/<route>/layout.tsx |
| Text.js: New Route Handler | app/<route>/route.ts با GET و POST |
| Text.js: New Loading UI / Error Boundary / Not Found Page | loading.tsx، error.tsx، not-found.tsx |
فرمان‌های ایجاد ساختار اولیه در منوی زمینهٔ پوشه‌ها در Explorer هم قرار دارند. این فرمان‌ها بخش‌های App Router مانند settings، blog/[slug]، docs/[...path] و (marketing)/about را می‌پذیرند و اجازه نمی‌دهند یک page و یک route.ts در یک بخش قرار بگیرند. پروژه‌های JavaScript (بدون tsconfig.json) فایل‌های .jsx و .js دریافت می‌کنند.
قطعه‌کدها
| پیشوند | محتوای درج‌شده |
|---|---|
txpage، txlayout، txloading، txerror | فایل‌های مسیر، با نام پوشهٔ خود |
txc | کامپوننت کنسول با نام فایل |
txroute، txroutep | کنترل‌گرهای مسیر، با یا بدون پارامتر |
box، boxb، text، scrollbox، link، spinner | کامپوننت‌ها |
input، select، tabs | کامپوننت‌های تعاملی |
useInput، useKeymap، useFocus، useTheme، useViewport، useRouter، useInterval | هوک‌ها |
metadata، txconfig | فرادادهٔ مسیر و text.config.ts |
کدهای خطا
نشانگر را در هر جایی روی یک کد TX### نگه دارید: در کد منبع، گزارش‌ها، پنل «خروجی» یا رد پشتهٔ جای‌گذاری‌شده. کادر شناور عنوان، پیام و بستهٔ آن را همراه با پیوند به صفحه‌اش در textjs.org نشان می‌دهد. هر کد یک پیوند هم هست (کلیک همراه با ⌘).
نوار وضعیت
گزینهٔ ▼ وضعیت سرور توسعه و اندازهٔ شبکهٔ کنسول را نشان می‌دهد، برای مثال ▼ :3000 120×36. زبانه‌ها هر زمان اندازه‌شان تغییر کند آن را به سرور توسعه گزارش می‌دهند، حتی اگر پیش‌نمایشی باز نباشد. برای دسترسی به فرمان‌های اصلی روی این گزینه کلیک کنید.
تنظیمات
| تنظیم | پیش‌فرض | توضیح |
|---|---|---|
textjs.preview.mode | auto | auto، live یا headless |
textjs.preview.followEditor | false | حالت زنده: دنبال کردن مسیر در حال ویرایش |
textjs.preview.fontSize | 12 | اندازهٔ قلم سلول (DevTools از 12 استفاده می‌کند) |
textjs.preview.runtime | فایل باینری Node.js برای پیش‌نمایش‌های بدون رابط (پیش‌فرض: نسخهٔ همراه VS Code) | |
textjs.devServer.url | نشانی سرور توسعه (پیش‌فرض: کشف روی درگاه‌های 3000–3010). فقط نشانی‌های loopback با http:// استفاده می‌شوند | |
textjs.devServer.command | فرمان برای Start Dev Server |
اعتماد به فضای کاری
پیش‌نمایش و سرور توسعه کد پروژهٔ شما را اجرا می‌کنند (پیکربندی Vite، فایل text.config.* و کامپوننت‌های آن). در حالت محدود، افزونه فقط قطعه‌کدها، ایجاد ساختار اولیه و پیوندهای خطا را ارائه می‌کند و تنظیمات textjs.preview.runtime، textjs.devServer.command و textjs.devServer.url فضای کاری را نادیده می‌گیرد. برای روشن کردن پیش‌نمایش، به فضای کاری اعتماد کنید. فایل‌های خارج از پوشه‌های فضای کاری شما هرگز پیش‌نمایش داده نمی‌شوند.
نحوهٔ کار
دستور text dev سه نقطهٔ پایانی برای ویرایشگرها ارائه می‌کند. این نقاط فقط به اتصال‌های loopback خطاب به میزبان loopback (localhost، 127.0.0.1، [::1]) و فقط به درخواست‌های بدون Origin یا با مبدأ خود سرور توسعه پاسخ می‌دهند. درخواست‌های بین‌سایتی و no-cors مرورگرها رد می‌شوند:
| نقطهٔ پایانی | |
|---|---|
GET /__textjs/status | ریشهٔ پروژه، زبانه‌های متصل، اندازهٔ شبکه و مسیر فعلی |
GET /__textjs/frames | رویدادهای ارسالی سرور: یک رویداد frame به‌ازای هر تغییر، کدگذاری‌شده به‌شکل تفاوت ردیف‌ها |
POST /__textjs/input | یک کلید، جای‌گذاری، متن IME یا کلید مرده (text)، چرخ ماوس یا ناوبری برای زبانه. به JSON و سرآیند x-textjs-mirror: 1 نیاز دارد، بنابراین سایت‌های دیگر نمی‌توانند فشردن کلیدها را ارسال کنند |
زبانه‌ها فریم‌ها را از طریق سوکت HMR در Vite به سرور توسعه ارسال می‌کنند که به توکنی مخصوص هر سرور نیاز دارد. اگر می‌خواهید نمایشگر خود را بسازید، قالب انتقال از @textjs/app/frame-protocol صادر می‌شود (FrameEncoder، FrameDecoder، parseInputMessage). هیچ‌یک از این‌ها در خروجی دستور text build وجود ندارد.