Route

عنصری که خروجی مسیریابی است. اگر آن را درون r-router بگذارید، هرگاه مسیر کنونی با الگوی path آن بخواند محتوای اسلاتش را نشان می‌دهد و در غیر این صورت پنهانش می‌کند.

کجا به کارش ببرید: وقتی خروجی‌ای می‌خواهید که محتوایش را تنها تا وقتی نشان دهد که مسیر کنونی با یک الگو می‌خواند (با پشتیبانی از :param و *). <r-route> را درون <r-router> بگذارید تا یک تعویض‌کنندهٔ نمای سمت کلاینت بسازید.

شروع سریع

استفادهٔ پایه

r-routeای که path آن / است با مسیر پیش‌فرض می‌خواند، پس محتوایش به‌تنهایی هم رندر می‌شود:

وقتی مسیر کنونی بخواند، این محتوا نمایش می‌یابد.

<r-route path="/">
  <p>وقتی مسیر کنونی بخواند، این محتوا نمایش می‌یابد.</p>
</r-route>

درون یک مسیریاب

وقتی درون r-router به کار می‌روند، چند مسیر مثل یک کلید عمل می‌کنند: مسیریاب در هر جابه‌جایی همهٔ فرزندان r-route را همگام می‌کند، آن‌هایی را که pathشان می‌خواند نشان می‌دهد و بقیه را پنهان می‌کند:

<r-router>
  <r-route path="/" exact><h2>Home</h2></r-route>
  <r-route path="/about"><h2>About</h2></r-route>
  <r-route path="/users/:id"><h2>User profile</h2></r-route>
</r-router>

نگه‌دارندهٔ r-router و API جاوااسکریپتی createRouter / RouterCore (جابه‌جایی، نگهبان‌ها، گذارهای نما) در صفحهٔ Router مستند شده‌اند.

مرجع API

خصیصه‌ها

خصیصه	نوع	پیش‌فرض	توضیح
path	string	'/'	الگویی که با مسیر کنونی سنجیده می‌شود. از :param و * پشتیبانی می‌کند
exact	boolean	false	فقط‌خواندنی. اگر ویژگی exact باشد، تطابق کامل لازم است
params	Record<string, string>	{}	فقط‌خواندنی. پارامترهای گرفته‌شده از تطابق کنونی
sheet	string	''	CSS تزریق‌شده به shadow DOM کامپوننت

تطابق مسیر path

path روی / تکه می‌شود و بخش‌به‌بخش به یک عبارت باقاعده کامپایل می‌شود:

• بخشی که با : آغاز شود، یک پارامتر نام‌دار می‌گیرد (با یک بخش از مسیر می‌خواند)
• بخش * با تمام باقی‌ماندهٔ مسیر می‌خواند
• هر بخش دیگری عیناً می‌خواند

بدون exact، الگو با مسیر به‌عنوان پیشوند می‌خواند (بخش‌های بعدی مجازند). با exact تنها تطابق کامل پذیرفته می‌شود.

/users            با /users، /users/42، /users/42/profile می‌خواند
/users (exact)    فقط با /users می‌خواند
/users/:id        مقدار :id را می‌گیرد → params.id
/*                با همه‌چیز می‌خواند

پارامترهای گرفته‌شده را از خصیصهٔ فقط‌خواندنی params بخوانید (هر مقدار با decodeURIComponent رمزگشایی می‌شود):

const route = document.createElement('r-route');
route.path = '/users/:id';
router.append(route);
route.params; // به‌محض تطابق مسیریاب با این مسیر، مثلاً { id: '42' }

تطابق کامل exact

ویژگی بولی. وقتی باشد، این خروجی تنها با مسیر کامل می‌خواند (تطابق پیشوندی ندارد): path="/users" exact با /users می‌خواند اما با /users/42 نه.

<r-route path="/" exact><h2>Home</h2></r-route>

CSS بیرونی sheet

کد CSS که به shadow DOM کامپوننت تزریق می‌شود؛ همان قرارداد sheet که همهٔ کامپوننت‌های دیگر ranui هم دارند.

اسلات‌ها

اسلات پیش‌فرض (بی‌نام) محتوایی را نگه می‌دارد که تا وقتی مسیر فعال است نمایش می‌یابد. وقتی مسیر نخواند، روی میزبان hidden گذاشته می‌شود و محتوا دیده نمی‌شود.

<r-route path="/about">
  <!-- اسلات پیش‌فرض: تنها تا وقتی /about فعال است دیده می‌شود -->
  <h2>About</h2>
</r-route>

رویدادها

routematch

وقتی این خروجی فعال شود (یعنی path آن با مسیر کنونی بخواند) رخ می‌دهد و حباب می‌کند. event.detail برابر { path, params } است:

<r-route path="/users/:id"><h2>User profile</h2></r-route>

<script>
  // پیش از سوار کردن مسیری که به همین شکل ساخته شده، گوش بدهید
  const route = document.createElement('r-route');
  route.path = '/users/:id';
  route.addEventListener('routematch', (e) => {
    console.log(e.detail.path, e.detail.params); // '/users/42', { id: '42' }
  });
  router.append(route);
</script>

استایل

r-route نه دستگیرهٔ ()::part دارد و نه متغیرهای CSS اختصاصی --ran-route-*. میزبان عنصری ساده با display: block است که هنگام پنهان بودن به display: none جمع می‌شود. برای سفارشی‌سازی از ویژگی sheet استفاده کنید یا مستقیم به میزبان استایل بدهید.

آن را با import 'ranui' (که همهٔ کامپوننت‌ها را ثبت می‌کند) یا با import 'ranui/route'ِ مستقل بار کنید.

بهترین شیوه‌ها

• درون r-router سوارش کنید: r-route تنها وقتی با جابه‌جایی عوض می‌شود که جدّی از جنس r-router داشته باشد که همگامش کند.
• برای ریشه exact بگذارید: به path="/" ویژگی exact بدهید تا به‌شکل پیشوندی با هر مسیر دیگری نخواند.
• از خاص به عام مرتب کنید: مسیر همه‌گیر path="/*" را آخر بگذارید، چون مسیرِ بدون exact با پیشوند خودش می‌خواند.
• params را بخوانید، نشانی را تجزیه نکنید: بخش‌های پویا را با :param بگیرید و از خصیصهٔ params بخوانید.
• با routematch به فعال‌شدن واکنش نشان دهید: از رویداد حباب‌کنندهٔ routematch برای آغاز بارگذاری داده هنگام فعال‌شدن یک مسیر استفاده کنید.