Link

لنگری آگاه از مسیریاب که یک <a> دور محتوای اسلات می‌کشد و جابه‌جایی درون برنامه را می‌رباید.

کجا به کارش ببرید: وقتی لنگری می‌خواهید که مسیرهای درونی را از مسیریاب ranui بگذراند و پیوندهای بیرونی را به مرورگر بسپارد. <r-link> جابه‌جایی درون برنامه را می‌رباید و push/replace را به‌جای شما انجام می‌دهد.

شروع سریع

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

شروع کنید

<r-link href="/getting-started">شروع کنید</r-link>

وقتی روی یک href درونی کلیک شود، پیوند مسیر را به مسیریاب فعال ranui می‌دهد (push، یا اگر ویژگی replace گذاشته شده باشد replace). پیوندهای بیرونی (https://، //، mailto:، tel:) و کلیک‌های همراه با کلید تغییردهنده (دکمهٔ وسط، Ctrl/Cmd/Shift/Alt) طبق معمول به مرورگر می‌رسند. اگر هیچ مسیریابی ثبت نشده باشد، به‌جای آن رویداد ran-navigate را ارسال می‌کند که حباب می‌کند و composed است.

مرجع API

خصیصه‌ها

خصیصه	نوع	پیش‌فرض	توضیح
href	string	''	مقصد جابه‌جایی. مسیرهای درونی درون برنامه حل می‌شوند و نشانی‌های بیرونی عادی می‌روند
replace	boolean	false	اگر باشد، جابه‌جایی درون برنامه مدخل کنونی تاریخچه را جایگزین می‌کند (فقط‌خواندنی)
sheet	string	''	CSS تزریق‌شده به shadow DOM پیوند

مقصد href

مسیرهای درونی درون برنامه حل می‌شوند؛ نشانی‌های مطلق و پیوندهای mailto: / tel: عادی می‌روند.

پیوند درونیپیوند بیرونی

<r-link href="/docs">پیوند درونی</r-link> <r-link href="https://example.com">پیوند بیرونی</r-link>

جایگزینی تاریخچه replace

ویژگی بولی. وقتی باشد، جابه‌جایی درون برنامه به‌جای افزودن مدخل تازه، مدخل کنونی تاریخچه را جایگزین می‌کند (router.replace).

جایگزینی مدخل

<r-link href="/settings" replace>جایگزینی مدخل</r-link>

استایل بیرونی sheet

کد CSS که به shadow DOM پیوند تزریق می‌شود و از همان قرارداد sheet پیروی می‌کند که همهٔ کامپوننت‌های دیگر ranui دارند. چون <a>ِ کلیک‌شدنی داخل shadow root است، اگر می‌خواهید میزبان مثل دکمه یا کارت دیده شود، مدل جعبه (display، padding، width) را با sheet بدهید.

پیوند با فاصلهٔ داخلی

<r-link href="/docs" sheet="a { display: inline-block; padding: 8px 16px; }">پیوند با فاصلهٔ داخلی</r-link>

اسلات‌ها

اسلات	توضیح
(پیش‌فرض)	محتوای پیوند، که در <a>ِ داخل shadow بازتاب می‌یابد (متن یا گره)

رویدادها

رویداد	detail	چه زمانی
ran-navigate	{ path: string, replace: boolean }	روی پیوند درونی کلیک شود و هیچ مسیریاب ranui فعال نباشد. حباب می‌کند و composed است.

<r-link href="/docs">Docs</r-link>

<script>
  const link = document.createElement('r-link');
  link.href = '/docs';
  link.textContent = 'Docs';
  link.addEventListener('ran-navigate', (e) => {
    console.log(e.detail.path, e.detail.replace);
  });
  nav.append(link);
</script>

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

• جابه‌جایی درونی: از href نسبت به ریشه استفاده کنید (مثلاً /docs) تا مسیریاب آن را درون برنامه انجام دهد.
• پیوندهای بیرونی: نشانی‌های مطلق و mailto: / tel: به مرورگر می‌رسند؛ پیکربندی اضافه‌ای لازم نیست.
• جایگزینی تاریخچه: به پیوندهایی که نباید مدخل «بازگشت» بسازند (تغییر مسیر، تعویض زبانه) replace بدهید.
• حالت فعال: میزبان به :host([active]) a استایل می‌دهد (پررنگ + زیرخط)، پس برای نشان‌دادن پیوند جاری ویژگی active را بگذارید.
• مثل دکمه یا کارت: سطح (زمینه، حاشیه، گردی گوشه) را روی میزبان بگذارید و مدل جعبهٔ <a> (display، padding، width) را با sheet تزریق کنید تا کل ناحیه کلیک‌شدنی شود.
• پوسته‌دهی: <a> توکن‌های سراسری --ran-color-link، --ran-color-primary (حلقهٔ فوکوس) و --ran-radius-sm را می‌خواند؛ به‌جای انتظار متغیرهای مخصوص کامپوننت --ran-link-* (که وجود ندارند)، همان توکن‌ها را بازنویسی کنید.