proscenium

خشبة المسرح - تطوير الواجهة الأمامية المتكاملة للقضبان

مقدمة · انظر · ني · أوم

اسم : خشبة المسرح

• جزء من المسرح أمام الستار.

يتعامل Proscenium مع كود الواجهة الأمامية والعميل الخاص بك كمواطنين من الدرجة الأولى في تطبيق Rails الخاص بك، ويفترض وجود إنترنت "سريع افتراضيًا". فهو يجمع ويصغر JavaScript (+ JSX)، وTypeScript (+TSX) وCSS في الوقت الفعلي، عند الطلب، وبدون أي تكوين.

أبرز النقاط:

• تجميع سريع وفي الوقت الفعلي، واهتزاز الأشجار، وتقسيم التعليمات البرمجية، وتصغير Javascript (.js،.jsx)، وTypescript (.ts،.tsx) وCSS (.css).
• لا حاجة إلى وقت تشغيل جافا سكريبت (مثل Node) - فقط المتصفح!
• لا توجد خطوة بناء أو تجميع مسبق.
• لا توجد عملية أو خادم إضافي - ما عليك سوى تشغيل rails s !
• يحول بناء جملة JavaScript وCSS الأحدث إلى بناء جملة أقدم للمتصفحات الأقدم.
• التكامل العميق مع القضبان.
• قم تلقائيًا بتحميل التخطيطات وطرق العرض والأجزاء الجزئية بشكل جانبي.
• الاستيراد من NPM وعناوين URL ومحليًا.
• دعم خريطة الاستيراد من جانب الخادم.
• وحدات CSS والخلطات.
• خرائط المصدر.

جدول المحتويات

• ابدء
• تثبيت
• رمز جانب العميل في أي مكان
• التحميل الجانبي
• استيراد
  • الواردات المحلية
• استيراد الخرائط
• خرائط المصدر
• SVG
• متغيرات البيئة
• i18n
• جافا سكريبت
  • اهتزاز الشجرة
  • تقسيم الكود
  • تحذيرات جافا سكريبت
• CSS
  • استيراد CSS من جافا سكريبت
  • وحدات CSS
  • ميكسينز CSS
  • تحذيرات CSS
• الآلة الكاتبة
  • تحذيرات الآلة الكاتبة
• JSX
• JSON
• دعم الفليكس
• عرض دعم المكونات
• خرق ذاكرة التخزين المؤقت
• لقد عاد آر جي إس!
• دقة
  • الأصول من محركات القضبان
• شكرًا
• تطوير

ابدء

من الواضح أن البدء يعتمد على ما إذا كنت تضيف Proscenium إلى تطبيق Rails موجود، أو تنشئ تطبيقًا جديدًا. لذا اختر الدليل المناسب أدناه:

• البدء باستخدام تطبيق Rails الجديد
• البدء باستخدام تطبيق Rails موجود
  • الهجرة من Sprockets
  • الترحيل من Propshaft [قريبًا]
  • الترحيل من Webpacker [قريبًا]
• تقديم مكون React باستخدام Proscenium

تثبيت

أضف هذا السطر إلى Gemfile الخاص بتطبيق Rails الخاص بك، وستكون جاهزًا للمضي قدمًا:

 gem 'proscenium'

يرجى ملاحظة أن Proscenium مصمم للاستخدام مع Rails فقط.

الآن، إذا قمت بتشغيل تطبيق Rails الخاص بك، فيمكنك فتح أي كود للواجهة الأمامية (JS، CSS، وما إلى ذلك). على سبيل المثال، يمكن الوصول إلى ملف على app/assets/stylesheets/application.css على https://localhost:3000/app/assets/stylesheets/application.css ، والذي سيتم تجميعه وتحويله وتصغيره [في الإنتاج] في الوقت الحقيقي.

رمز جانب العميل في أي مكان

تعتقد شركة Proscenium أن رمز الواجهة الأمامية الخاص بك لا يقل أهمية عن رمز الواجهة الخلفية الخاص بك، وليس فكرة لاحقة - يجب أن يكونوا مواطنين من الدرجة الأولى في تطبيق Rails الخاص بك. لذا بدلًا من الاضطرار إلى رمي كل ملفات JS وCSS الخاصة بك في دليل "app/assets"، ومن ثم طلب عملية منفصلة للتجميع أو التجميع، ما عليك سوى وضعها أينما تريد داخل تطبيقك، وتشغيل Rails فقط!

على سبيل المثال، إذا كان لديك بعض ملفات JS المطلوبة لعرض app/views/users/index.html.erb ، فما عليك سوى إنشاء ملف JS بجانبه في app/views/users/index.js . أو إذا كان لديك بعض ملفات CSS التي يستخدمها تطبيقك بالكامل، فضعها في app/views/layouts/application.css وقم بتحميلها بجانب تخطيطك. ربما لديك بعض وظائف JS المساعدة، لذا ضعها في lib/utils.js .

ما عليك سوى وضع JS(X) وCSS في أي مكان تريده، وسيتم تقديمهما بواسطة تطبيق Rails الخاص بك من الموقع الذي وضعتهما فيه.

باستخدام الأمثلة أعلاه...

• app/views/users/index.js => https://localhost:3000/app/views/users/index.js
• app/views/layouts/application.css => https://localhost:3000/app/views/layouts/application.css
• lib/utils.js => https://localhost:3000/lib/utils.js
• app/components/menu_component.jsx => https://localhost:3000/app/components/menu_component.jsx
• config/properties.css => https://localhost:3000/config/properties.css

التحميل الجانبي

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

المشكلة

باستخدام Rails، يمكنك عادةً تحميل أصول JavaScript وCSS بشكل تعريفي باستخدام المساعدين javascript_include_tag و stylesheet_link_tag .

على سبيل المثال، قد يكون لديك CSS "تطبيق" عالي المستوى موجود في ملف على /app/assets/stylesheets/application.css . وبالمثل، قد يكون لديك بعض جافا سكريبت العامة الموجودة في ملف في /app/javascript/application.js .

يمكنك يدويًا وبشكل معلن تضمين هذين الملفين في تخطيط التطبيق الخاص بك، شيء من هذا القبيل:

 <%# /app/views/layouts/application.html.erb %>

<!DOCTYPE html >
< html >
  < head >
    < title > Hello World </ title >
    <%= stylesheet_link_tag 'application' %> <!-- << Your app CSS -->
  </ head >
  < body >
    <%= yield %>
    <%= javascript_include_tag 'application' %> <!-- << Your app JS -->
  </ body >
</ html >

الآن، قد يكون لديك بعض CSS وJavaScript المطلوب فقط من خلال عرض محدد وجزئي، لذلك يمكنك تحميل ذلك في العرض (أو التخطيط)، شيء من هذا القبيل:

 <%# /app/views/users/index.html.erb %>

<%= stylesheet_link_tag 'users' %>
<%= javascript_include_tag 'users' %>

<%# needed by the `users/_user.html.erb` partial %>
<%= javascript_include_tag '_user' %>

<% render @users %> 

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

الحل

عند التحميل الجانبي لـ JavaScript وTypescript وCSS باستخدام Proscenium، يتم تضمينها تلقائيًا إلى جانب طرق العرض والأجزاء الجزئية والتخطيطات والمكونات، وذلك فقط عند الحاجة إليها.

يعمل التحميل الجانبي من خلال البحث عن ملف JS/TS/CSS بنفس اسم العرض أو الجزء أو التخطيط أو المكون. على سبيل المثال، إذا كان لديك عرض في app/views/users/index.html.erb ، فسيبحث Proscenium عن ملف JS/TS/CSS في app/views/users/index.js ، app/views/users/index.ts أو app/views/users/index.css . إذا عثر على واحدة، فسيتم تضمينها في HTML لهذا العرض.

JSX مدعوم أيضًا لـ JavaScript وTypescript. ما عليك سوى استخدام الامتداد .jsx أو .tsx بدلاً من .js أو .ts .

الاستخدام

ما عليك سوى إنشاء ملف JS و/أو CSS بنفس اسم أي عرض أو جزئي أو تخطيط.

دعونا نواصل مثال مشكلتنا أعلاه، حيث لدينا الأصول التالية

• /app/assets/application.css
• /app/assets/application.js
• /app/assets/users.css
• /app/assets/users.js
• /app/assets/user.js

تخطيط تطبيقك موجود في /app/views/layouts/application.hml.erb ، والعرض الذي يحتاج إلى أصول المستخدمين موجود في /app/views/users/index.html.erb ، لذا انقل أصولك JS وCSS بجانبها :

• /app/views/layouts/application.css
• /app/views/layouts/application.js
• /app/views/users/index.css
• /app/views/users/index.js
• /app/views/users/_user.js (جزئي)

الآن، في تخطيطك وعرضك، استبدل مساعدي javascript_include_tag و stylesheet_link_tag بالمساعد include_asset من Proscenium. شيء من هذا القبيل:

 <!DOCTYPE html >
< html >
  < head >
    < title > Hello World </ title >
    <%= include_assets # <-- %>
  </ head >
  < body >
    <%= yield %>
  </ body >
</ html >

في كل طلب صفحة، سيتحقق Proscenium مما إذا كان أي من طرق العرض والتخطيطات والأجزاء الجزئية الخاصة بك يحتوي على ملف JS/TS/CSS يحمل نفس الاسم، ثم يقوم بتضمينها أينما وضعت مساعد include_assets .

الآن لن تضطر أبدًا إلى تذكر تضمين الأصول الخاصة بك مرة أخرى. ما عليك سوى إنشائها جنبًا إلى جنب مع طرق العرض والجزئيات والتخطيطات الخاصة بك، وسيتولى Proscenium الباقي.

يتم تمكين التحميل الجانبي افتراضيًا، لكن يمكنك تعطيله عن طريق ضبط config.proscenium.side_load على false في /config/application.rb .

هناك أيضًا أدوات مساعدة include_stylesheets و include_javascripts للسماح لك بالتحكم في مكان تضمين أصول CSS وJS في HTML. يجب استخدام هؤلاء المساعدين بدلاً من include_assets إذا كنت تريد التحكم الدقيق في مكان تضمين الأصول.

التجميع

يعني تجميع ملف تضمين أي تبعيات مستوردة في الملف نفسه. هذه العملية متكررة لذا سيتم أيضًا تضمين تبعيات التبعيات (وما إلى ذلك).

سيتم تجميع Proscenium افتراضيًا وفي الوقت الفعلي. لذلك لا توجد خطوة بناء منفصلة أو تجميع مسبق.

يدعم Proscenium استيراد JS، وJSX، وTS، وTSX، وCSS، وSVG من NPM، عبر عنوان URL، وتطبيقك المحلي، وحتى من Ruby Gems الأخرى.

يتم دعم كل من عمليات الاستيراد الثابتة ( import ) والديناميكية ( import() ) لـ JavaScript وTypeScript، ويمكن استخدامها لاستيراد ملفات JS، وTS، وJSX، وTSX، وJSON، وCSS، وSVG.

قاعدة @import CSS مدعومة لـ CSS.

الواردات غير القابلة للتحليل

يتم تجميع مسارات الاستيراد حاليًا فقط إذا كانت عبارة عن سلسلة حرفية أو نمطًا كرويًا. لا يتم تجميع النماذج الأخرى لمسارات الاستيراد، وبدلاً من ذلك يتم الاحتفاظ بها حرفيًا في المخرجات التي تم إنشاؤها. وذلك لأن التجميع هو عملية وقت الترجمة وأن Proscenium لا يدعم جميع أشكال دقة مسار وقت التشغيل.

فيما يلي بعض الأمثلة:

 // Analyzable imports (will be bundled)
import "pkg" ;
import ( "pkg" ) ;
import ( `./locale- ${ foo } .json` ) ;

// Non-analyzable imports (will not be bundled)
import ( `pkg/ ${ foo } ` ) ;

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

الاستيراد من NPM ( node_modules )

عمليات الاستيراد العارية (عمليات الاستيراد التي لا تبدأ بـ ./ , / , https:// , http:// ) مدعومة بالكامل، وستستخدم مدير الحزم الذي تختاره (على سبيل المثال، NPM، Yarn، pnpm) عبر ملف package.json الموجود في جذر تطبيق Rails الخاص بك.

قم بتثبيت الحزمة التي تريد استيرادها باستخدام مدير الحزم الذي تختاره...

 npm install react

...ثم قم باستيرادها كما تفعل مع أي حزمة أخرى.

 import React from "react" ;

الواردات المحلية

وبالطبع يمكنك استيراد الكود الخاص بك، باستخدام المسارات النسبية أو المطلقة (امتداد الملف اختياري، والمسارات المطلقة تستخدم جذر Rails الخاص بك كقاعدة):

 import utils from "/lib/utils" ;
import constants from "./constants" ;
import Header from "/app/components/header" ; 

 @import "/lib/reset" ;

التفكيك

في بعض الأحيان لا ترغب في تجميع عملية الاستيراد. على سبيل المثال، تريد التأكد من تحميل نسخة واحدة فقط من React. في هذه الحالات، يمكنك استخدام البادئة unbundle

 import React from "unbundle:react" ;

هذا يعمل فقط على أي واردات عارية ومحلية.

يمكنك أيضًا استخدام بادئة unbundle الحزمة في خريطة الاستيراد الخاصة بك، والتي تضمن أن جميع عمليات استيراد مسار معين تكون دائمًا غير مجمعة:

{
  "imports" : {
    "react" : " unbundle:react "
  }
}

ثم قم بالاستيراد كالمعتاد:

 import React from "react" ; 

استيراد الخرائط

[قيد التنفيذ]

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

إذا لم تكن على دراية باستيراد الخرائط، فكر فيها كطريقة لتعريف الأسماء المستعارة.

ما عليك سوى إنشاء config/import_map.json وتحديد الواردات التي تريد استخدامها. على سبيل المثال:

{
  "imports" : {
    "react" : " https://esm.sh/[email protected] " ,
    "start" : " /lib/start.js " ,
    "common" : " /lib/common.css " ,
    "@radix-ui/colors/" : " https://esm.sh/@radix-ui/[email protected]/ "
  }
}

باستخدام خريطة الاستيراد أعلاه، يمكننا القيام...

 import { useCallback } from "react" ;
import startHere from "start" ;
import styles from "common" ;

و ل CSS...

 @import "common" ;
@import "@radix-ui/colors/blue.css" ;

يمكنك أيضًا كتابة خريطة الاستيراد الخاصة بك بلغة JavaScript بدلاً من JSON. لذا بدلًا من config/import_map.json ، أنشئ config/import_map.js وحدد دالة مجهولة. تقبل هذه الوظيفة وسيطة environment واحدة.

 ( env ) => ( {
  imports : {
    react :
      env === "development"
        ? "https://esm.sh/[email protected]?dev"
        : "https://esm.sh/[email protected]" ,
  } ,
} ) ; 

خرائط المصدر

يمكن أن تسهل خرائط المصدر تصحيح أخطاء التعليمات البرمجية الخاصة بك. يقومون بتشفير المعلومات اللازمة للترجمة من إزاحة السطر/العمود في ملف الإخراج الذي تم إنشاؤه إلى إزاحة السطر/العمود في ملف الإدخال الأصلي المقابل. يعد هذا مفيدًا إذا كان الكود الذي تم إنشاؤه مختلفًا بدرجة كافية عن الكود الأصلي (على سبيل المثال، الكود الأصلي هو TypeScript أو قمت بتمكين التصغير). يعد هذا مفيدًا أيضًا إذا كنت تفضل النظر إلى الملفات الفردية في أدوات مطور المتصفح الخاص بك بدلاً من ملف واحد كبير مجمع.

يتم دعم إخراج خريطة المصدر لكل من JavaScript وCSS. يتم إلحاق كل ملف برابط الخريطة المصدر. على سبيل المثال:

 //# sourceMappingURL=/app/views/layouts/application.js.map

يجب أن تقوم أدوات تطوير المتصفحات الخاصة بك باختيار هذا وتحميل خريطة المصدر تلقائيًا متى وأينما دعت الحاجة.

SVG

يمكنك استيراد SVG من JS(X)، والذي سيجمع كود مصدر SVG. بالإضافة إلى ذلك، في حالة الاستيراد من JSX أو TSX، سيتم عرض كود مصدر SVG كمكون JSX/TSX.

متغيرات البيئة

متوفر في >=0.10.0

يمكنك تحديد أي متغير بيئة والوصول إليه من JavaScript وTypescript ضمن مساحة الاسم proscenium.env .

لأسباب تتعلق بالأداء والأمان، يجب عليك الإعلان عن أسماء متغيرات البيئة التي ترغب في الكشف عنها في ملف config/application.rb الخاص بك.

 config . proscenium . env_vars = Set [ 'API_KEY' , 'SOME_SECRET_VARIABLE' ]
config . proscenium . env_vars << 'ANOTHER_API_KEY'

يفترض هذا أن متغير البيئة الذي يحمل نفس الاسم قد تم تعريفه بالفعل. إذا لم يكن الأمر كذلك، فستحتاج إلى تعريفه بنفسك إما في التعليمات البرمجية الخاصة بك باستخدام كائن Ruby's ENV ، أو في الصدفة الخاصة بك.

سيتم استبدال متغيرات البيئة المعلنة هذه بتعبيرات ثابتة، مما يسمح لك باستخدام هذا على النحو التالي:

 console . log ( proscenium . env . RAILS_ENV ) ; // console.log("development")
console . log ( proscenium . env . RAILS_ENV === "development" ) ; // console.log(true)

سيتم دائمًا الإعلان عن متغيرات البيئة RAILS_ENV و NODE_ENV لك تلقائيًا.

بالإضافة إلى ذلك، يوفر Proscenium أيضًا متغير process.env.NODE_ENV .env.NODE_ENV، والذي تم ضبطه على نفس قيمة proscenium.env.RAILS_ENV . يتم توفيره لدعم الأدوات الحالية للمجتمع، والتي غالبًا ما تعتمد على هذا المتغير.

تعد متغيرات البيئة قوية بشكل خاص في مساعدة اهتزاز الأشجار.

 function start ( ) {
  console . log ( "start" ) ;
}
function doSomethingDangerous ( ) {
  console . log ( "resetDatabase" ) ;
}

proscenium . env . RAILS_ENV === "development" && doSomethingDangerous ( ) ;

start ( ) ;

أثناء التطوير، سيتم تحويل الكود أعلاه إلى الكود التالي، مع تجاهل التعريف واستدعاء doSomethingDangerous() .

 function start ( ) {
  console . log ( "start" ) ;
}
start ( ) ;

يرجى ملاحظة أنه لأسباب أمنية، لا يتم استبدال متغيرات البيئة في عمليات استيراد عناوين URL.

سيتم استبدال متغير البيئة غير المحدد بـ undefined .

 console . log ( proscenium . env . UNKNOWN ) ; // console.log((void 0).UNKNOWN)

وهذا يعني أن التعليمات البرمجية التي تعتمد على هذا لن تهتز الشجرة. يمكنك حل هذه المشكلة باستخدام عامل التسلسل الاختياري:

 if ( typeof proscenium . env ?. UNKNOWN !== "undefined" ) {
  // do something if UNKNOWN is defined
} 

i18n

يتوفر الدعم الأساسي لاستيراد ملفات لغة Rails الخاصة بك من config/locales/*.yml وتصديرها بتنسيق JSON.

 import translations from "@proscenium/i18n" ;
// translations.en.* 

جافا سكريبت

افتراضيًا، سيستفيد مخرج Proscenium من جميع ميزات JS الحديثة من مواصفات ES2022 والإصدارات الأقدم. على سبيل المثال، a !== void 0 && a !== null ? a : b سوف يصبح a ?? b عند التصغير (يتم تمكينه افتراضيًا في الإنتاج)، والذي يستخدم بناء الجملة من إصدار ES2020 من JavaScript. سيتم تحويل أي ميزة بناء جملة غير مدعومة بواسطة ES2020 إلى بناء جملة JavaScript أقدم مدعوم على نطاق أوسع.

اهتزاز الشجرة

اهتزاز الشجرة هو المصطلح الذي يستخدمه مجتمع JavaScript لإزالة التعليمات البرمجية الميتة، وهو تحسين شائع للمترجم يزيل تلقائيًا التعليمات البرمجية التي لا يمكن الوصول إليها. يتم تمكين اهتزاز الشجرة افتراضيًا في Proscenium.

 function one ( ) {
  console . log ( "one" ) ;
}
function two ( ) {
  console . log ( "two" ) ;
}
one ( ) ;

سيتم تحويل الكود أعلاه إلى الكود التالي، مع تجاهل two() ، حيث لا يتم استدعاؤه أبدًا.

 function one ( ) {
  console . log ( "one" ) ;
}
one ( ) ;

تقسيم الكود

متوفر في >=0.10.0 .

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

كمثال:

 // /lib/son.js
import father from "./father" ;

father ( ) + " and Son" ; 

 // /lib/daughter.js
import father from "./father" ;

father ( ) + " and Daughter" ; 

 // /lib/father.js
export default ( ) => "Father" ;

يقوم كل من son.js و daughter.js باستيراد father.js ، لذا عادةً ما يشتمل كل من الابن والابنة على نسخة من الأب، مما يؤدي إلى تكرار التعليمات البرمجية وأحجام حزم أكبر.

إذا تم تحميل هذه الملفات من الجانب، فسيتم تقسيم father.js إلى ملف منفصل أو قطعة، ويتم تنزيلها مرة واحدة فقط.

• يتم تقسيم التعليمات البرمجية المشتركة بين نقاط الدخول المتعددة إلى ملف مشترك منفصل تستورده نقطتي الإدخال. وبهذه الطريقة، إذا قام المستخدم بالاستعراض أولاً إلى صفحة واحدة ثم إلى صفحة أخرى، فلن يحتاج إلى تنزيل كل JavaScript للصفحة الثانية من البداية إذا كان الجزء المشترك قد تم تنزيله وتخزينه مؤقتًا بواسطة المستعرض الخاص به بالفعل.

• سيتم تقسيم التعليمات البرمجية المشار إليها من خلال تعبير import() غير المتزامن إلى ملف منفصل ويتم تحميلها فقط عند تقييم هذا التعبير. يتيح لك هذا تحسين وقت التنزيل الأولي لتطبيقك عن طريق تنزيل الكود الذي تحتاجه عند بدء التشغيل فقط، ثم تنزيل كود إضافي بتكاسل إذا لزم الأمر لاحقًا.

• بدون تقسيم التعليمات البرمجية، يصبح تعبير import() هو Promise.resolve().then(() => require()) بدلاً من ذلك. لا يزال هذا يحافظ على الدلالات غير المتزامنة للتعبير، ولكنه يعني تضمين التعليمات البرمجية المستوردة في نفس الحزمة بدلاً من تقسيمها إلى ملف منفصل.

يتم تمكين تقسيم التعليمات البرمجية بشكل افتراضي. يمكنك تعطيله عن طريق ضبط خيار تكوين code_splitting على false في /config/application.rb الخاص بتطبيقك:

 config . proscenium . code_splitting = false

تحذيرات جافا سكريبت

هناك بعض التحذيرات المهمة فيما يتعلق بجافا سكريبت. هذه مفصلة على موقع esbuild.

CSS

يعد CSS أحد أنواع المحتوى من الدرجة الأولى في Proscenium، مما يعني أنه يمكنه تجميع ملفات CSS مباشرةً دون الحاجة إلى استيراد CSS الخاص بك من كود JavaScript. يمكنك @import ملفات CSS أخرى وملفات الصور والخطوط المرجعية باستخدام url() وسيقوم Proscenium بتجميع كل شيء معًا.

لاحظ أنه افتراضيًا، ستستفيد مخرجات Proscenium من جميع ميزات CSS الحديثة. على سبيل المثال، color: rgba(255, 0, 0, 0.4) سوف يصبح color: #f006 بعد تصغيره في الإنتاج، والذي يستفيد من بناء الجملة من وحدة ألوان CSS المستوى 4.

يتم دعم بناء جملة تداخل CSS الجديد، ويتم تحويله إلى CSS غير متداخل للمتصفحات الأقدم.

سيقوم Proscenium أيضًا بإدراج بادئات البائع تلقائيًا حتى يعمل CSS الخاص بك في المتصفحات القديمة.

استيراد CSS من جافا سكريبت

يمكنك أيضًا استيراد CSS من JavaScript. عند القيام بذلك، سيقوم Proscenium تلقائيًا بإلحاق كل ورقة أنماط برأس المستند كعنصر <link> .

 import "./button.css" ;

export let Button = ( { text } ) => {
  return < div className = "button" > { text } < / div > ;
} ;

وحدات CSS

ينفذ Proscenium مجموعة فرعية من وحدات CSS. وهو يدعم الكلمات الرئيسية :local و :global ، ولكن ليس خاصية composes . (من المستحسن استخدام mixins بدلاً من composes ، لأنها ستعمل في كل مكان، حتى في ملفات CSS العادية.)

امنح أي ملف CSS امتدادًا .module.css ، وسيعامله Proscenium كوحدة CSS، مما يؤدي إلى تحويل جميع أسماء الفئات بلاحقة فريدة للملف.

. title {
  font-size : 20 em ;
}

المدخلات أعلاه تنتج:

. title-5564cdbb {
  font-size : 20 em ;
}

لديك الآن اسم فئة فريد يمكنك استخدامه في أي مكان تقريبًا.

في مشاهداتك

يمكنك الرجوع إلى وحدات CSS من عروض Rails، والجزئيات، والتخطيطات باستخدام المساعد css_module ، الذي يقبل واحدًا أو أكثر من أسماء الفئات، وسيُرجع أسماء وحدات CSS المكافئة - اسم الفئة مع اللاحقة الفريدة الملحقة.

مع إعداد التحميل الجانبي، يمكنك استخدام المساعد css_module على النحو التالي.

 < div >
  < h1 class =" <%= css_module :hello_title %> " > Hello World </ h1 >
  < p class =" <%= css_module :body , paragraph : %> " >
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  </ p >
</ div >

يقبل css_module أسماء فئات متعددة، وسيُرجع سلسلة مفصولة بمسافات لأسماء وحدات CSS المحولة.

 css_module :my_module_name
# => "my_module_name-ABCD1234"

يمكنك أيضًا الإشارة إلى فئة من أي ملف CSS عن طريق تمرير مسار URL إلى الملف، كبادئة لاسم الفئة. سيؤدي القيام بذلك إلى تحميل ورقة الأنماط تلقائيًا.

 css_module '/app/components/button.css@big_button'
# => "big_button"

كما أنه يدعم حزم NPM (المثبتة بالفعل في /node_modules):

 css_module 'mypackage/button@big_button'
# => "big_button"

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

 css_module :my_module_name , path : Rails . root . join ( 'app/components/button.css' ) 

في جافا سكريبت الخاص بك

سيؤدي استيراد وحدة CSS من JS إلى إلحاق ورقة الأنماط تلقائيًا برأس المستند. وستكون نتيجة الاستيراد كائنًا من فئة CSS لأسماء الوحدات النمطية.

 import styles from "./styles.module.css" ;
// styles == { header: 'header-5564cdbb' }

من المهم ملاحظة أن الكائن المُصدَّر لأسماء وحدات CSS هو في الواقع كائن JavaScript Proxy. لذا فإن تدمير الكائن لن ينجح. بدلاً من ذلك، يجب عليك الوصول إلى الخصائص مباشرة.

كما أن استيراد وحدة CSS إلى وحدة CSS أخرى سيؤدي إلى نفس سلسلة الملخص لجميع الفئات.

ميكسينز CSS

يوفر Proscenium وظيفة تضمين أو "خلط" فئات CSS أو أكثر في فئة أخرى. يشبه هذا خاصية composes في وحدات CSS، ولكنه يعمل في كل مكان، ولا يقتصر على وحدات CSS.

يتم دعم مزيج CSS باستخدام قواعد @define-mixin و @mixin .

يتم تعريف mixin باستخدام @define-mixin في القاعدة. قم بتمرير اسم له، والذي يجب أن يلتزم بدلالات اسم الفصل، وأعلن القواعد الخاصة بك:

// /lib/mixins.css
@define-mixin bigText {
  font-size : 50 px ;
}

استخدم mixin باستخدام القاعدة @mixin . قم بتمرير اسم الميكسين الذي تريد استخدامه، وعنوان url الذي تم الإعلان عن الميكسين فيه. يتم استخدام عنوان url لحل المزيج، ويمكن أن يكون نسبيًا أو مطلقًا أو عنوان URL أو حتى من حزمة NPM.

// /app/views/layouts/application.css
p {
  @mixin bigText from url ( "/lib/mixins.css" );
  color : red;
}

ما ورد أعلاه ينتج هذا الإخراج:

 p {
  font-size : 50 px ;
  color : red;
}

يمكن الإعلان عن Mixins في أي ملف CSS. ولا يلزم الإعلان عنها في نفس الملف حيث يتم استخدامها. ومع ذلك، إذا قمت بالإعلان عن mixin واستخدمته في نفس الملف، فلن تحتاج إلى تحديد عنوان URL الخاص بمكان التصريح عن mixin.

 @define-mixin bigText {
  font-size : 50 px ;
}

p {
  @mixin bigText;
  color : red;
}

تعمل وحدات CSS وMixins معًا بشكل مثالي. يمكنك تضمين mixin في وحدة CSS.

تحذيرات CSS

هناك بعض التحذيرات المهمة فيما يتعلق بـ CSS. هذه مفصلة على موقع esbuild.

الآلة الكاتبة

يتم دعم Typescript وTSX بشكل تلقائي، كما أنهما يتمتعان بدعم مدمج لتحليل بناء جملة TypeScript وتجاهل التعليقات التوضيحية للنوع. ما عليك سوى إعادة تسمية ملفاتك إلى .ts أو .tsx وستكون جاهزًا للبدء.

يرجى ملاحظة أن Proscenium لا يقوم بأي فحص للنوع لذا ستظل بحاجة إلى تشغيل tsc -noEmit بالتوازي مع Proscenium للتحقق من الأنواع.

تحذيرات الآلة الكاتبة

هناك بعض التحذيرات المهمة فيما يتعلق بـ Typescript. هذه مفصلة على موقع esbuild.

JSX

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

 import * as React from "react" ;
render ( < div / > ) ;

وذلك لأن تحويل JSX يحول بناء جملة JSX إلى استدعاء React.createElement لكنه لا يستورد أي شيء بنفسه، لذلك لا يكون متغير React موجودًا تلقائيًا.

يقوم Proscenium بإنشاء بيانات الاستيراد هذه لك. ضع في اعتبارك أن هذا أيضًا يغير تمامًا كيفية عمل تحويل JSX، لذلك قد يؤدي إلى كسر التعليمات البرمجية الخاصة بك إذا كنت تستخدم مكتبة JSX غير React.

في المستقبل [ليس بعيدًا]، ستتمكن من ضبط Proscenium لاستخدام مكتبة JSX مختلفة، أو تعطيل هذا الاستيراد التلقائي تمامًا.

JSON

يؤدي استيراد ملفات .json إلى توزيع ملف JSON إلى كائن JavaScript، وتصدير الكائن باعتباره التصدير الافتراضي. استخدامه يبدو مثل هذا:

 import object from "./example.json" ;
console . log ( object ) ;

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

 import { version } from "./package.json" ;
console . log ( version ) ; 

دعم الفليكس

Phlex هو إطار عمل لبناء طرق عرض سريعة وقابلة لإعادة الاستخدام وقابلة للاختبار في روبي النقي. يعمل Proscenium بشكل مثالي مع Phlex، مع دعم التحميل الجانبي ووحدات CSS والمزيد. ما عليك سوى كتابة فئات Phlex الخاصة بك وترثها من Proscenium::Phlex .

 class MyView < Proscenium :: Phlex
  def view_template
    h1 { 'Hello World' }
  end
end

في تخطيطاتك، قم بتضمين Proscenium::Phlex::AssetInclusions ، واستدعاء مساعد include_assets .

 class ApplicationLayout < Proscenium :: Phlex
  include Proscenium :: Phlex :: AssetInclusions # <--

  def view_template ( & )
    doctype
    html do
      head do
        title { 'My Awesome App' }
        include_assets # <--
      end
      body ( & )
    end
  end
end

يمكنك على وجه التحديد تضمين أصول CCS وJS باستخدام مساعدي include_stylesheets و include_javascripts ، مما يسمح لك بالتحكم في مكان تضمينها في HTML.

التحميل الجانبي

أي فئة Phlex ترث Proscenium::Phlex سيتم تحميلها جانبيًا تلقائيًا.

وحدات CSS

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

ضمن فئات Phlex الخاصة بك، سيتم التعامل مع أي أسماء فئات تبدأ بـ @ كفئة وحدة CSS.

 # /app/views/users/show_view.rb
class Users :: ShowView < Proscenium :: Phlex
  def