ranui

کتابخانه‌ای از رابط کاربری که روی custom elements بومی ساخته شده است. هر کامپوننت یک تگ <r-*> است، پس در React، Vue، Svelte، Solid، Astro یا حتی یک فایل ساده‌ی HTML به یک شکل کار می‌کند. نه آداپتوری در کار است و نه نسخه‌ای از فریم‌ورک که باید با آن جور دربیاید. تایپ‌های TypeScript، پوستهٔ روشن و تیره بر پایهٔ design token، کپسوله‌سازی با Shadow DOM و رندر سمت سرور از همان ابتدا هستند.

v0.5.0-alpha.7MITesm · cjs · iifepackages/ranui

ranui در مرحلهٔ alpha است: نسخه‌ها تغییرات ناسازگار دارند. نسخهٔ دقیق را قفل کنید و پیش از ارتقا فهرست تغییرات را بخوانید.

نصب

npm install ranui

<!-- یا از یک CDN، بدون هیچ مرحلهٔ ساخت -->
<script src="https://unpkg.com/ranui/dist/umd/index.umd.cjs"></script>

استفاده

import کردن، عناصر را ثبت می‌کند؛ از آن پس فقط تگ می‌نویسید.

import 'ranui'; // همهٔ کامپوننت‌ها
import 'ranui/button'; // یا فقط یکی

<r-button type="primary">استقرار پروژه</r-button>

تگ در همهٔ فریم‌ورک‌ها یکی است؛ تفاوت فقط در شیوهٔ پاس‌دادن مقدار و بستن رویداد است که راهنمای کدنویسی به‌تمامی پوشش می‌دهد:

<script src="https://unpkg.com/ranui/dist/umd/index.umd.cjs"></script>

<body>
  <r-button>Button</r-button>
</body>

import 'ranui';

export const App = () => <r-button type="primary">Deploy</r-button>;
// مقدارهای پیچیده و شنونده‌های رویداد از راه ref می‌روند — راهنمای کدنویسی را ببینید.

<template>
  <r-button type="primary" @click="deploy">Deploy</r-button>
</template>

<!-- در پیکربندی ساخت، `r-` را به compilerOptions.isCustomElement بیفزایید. -->

import 'ranui';

const button = document.createElement('r-button');
button.textContent = 'Deploy';
document.body.appendChild(button);

نقاط ورود

هر نقطهٔ ورود دقیقاً همان چیزی را ثبت می‌کند که نامش می‌گوید، پس صفحه‌ای که فقط پوسته می‌خواهد هرگز بهای کتابخانهٔ کامپوننت‌ها را نمی‌پردازد.

import	شامل
`ranui`	همهٔ کامپوننت‌ها
`ranui/<component>`	یک کامپوننت: `ranui/button`، `ranui/select`، …
`ranui/theme`	پوستهٔ روشن/تیره و بازنویسی توکن‌ها؛ بدون عنصر
`ranui/i18n`	موتور ترجمه؛ بدون عنصر
`ranui/fonts`	قلم‌های میزبانی‌شدهٔ Geist Sans و Geist Mono
`ranui/style`	شیوه‌نامه، اگر پیکربندی شما خودش برنمی‌داردش
`ranui/builder`	سازندهٔ روان DOM با واکنش‌پذیری ریزدانه
`ranui/ssr`، `ranui/ssr-stream`	رندر سمت سرور
`ranui/testing`	ابزارهایی برای رسیدن به shadow root بسته از دل یک آزمون
`ranui/typings`	تایپ‌های محیطی عناصر برای JSX / TS

کامپوننت‌ها

۴۰ عنصر. همهٔ آن‌ها همراه با ویژگی‌ها، خصیصه‌ها، رویدادها، اسلات‌ها و نام‌های ()::part در مرجع API عناصر آمده‌اند.

عمومی: Button · Icon · Loading

ورود داده: Input · CheckBox · Select · ColorPicker · Attachments · VoiceButton · Forms

نمایش داده: Card · Section · Tabs · Image · Progress · Radar · Player · Preview · Glass · Scratch · StateDot · DisclosureRow

رندر محتوا: Markdown · Math · Mermaid

هوش مصنوعی و گفت‌وگو: Conversation · Reasoning · ToolCard · TokenMeter

لایه‌ها و بازخورد: Modal · Popover · Dropdown · Message · Skeleton

ناوبری: Router · Route · Link

پایه‌ها: پوسته · ThemeSwitch · i18n

پنج عنصر صفحهٔ جداگانه ندارند، چون تنها درون عنصر دیگری وجود دارند: <r-option> (Select)، <r-tabs> (Tabs)، <r-img> (Image)، <r-dropdown-item> (Dropdown) و <r-content> (Popover). مثل بقیه در مرجع API آمده‌اند.

زنده

Primary

Warning

Text

Default

استایل

کامپوننت‌ها در یک shadow root بسته رندر می‌شوند: CSS صفحه به درون نشت نمی‌کند و گزینشگرها هم به درون نمی‌رسند. چهار راه ورود هست، به‌ترتیب ترجیح.

۱. توکن‌های طراحی (ویژگی‌های سفارشی CSS): از مرز ارث می‌رسند، پس تعیین آن‌ها روی :root، روی یک نگه‌دارنده، یا روی خود عنصر همگی کار می‌کنند:

<r-progress
  percent="0.7"
  type="drag"
  style="--ran-progress-track-background: linear-gradient(to right, #f00, #ff0, #0f0, #0ff, #00f)"
></r-progress>

۲. ()::part برای تنظیم‌های ساختاری که توکن‌ها پوشش نمی‌دهند · ۳. ویژگی sheet برای تزریق CSS به shadow root · ۴. محتوای اسلات، که در سند خودتان می‌ماند و CSS صفحهٔ شما را می‌گیرد.

نام توکن‌ها همان سیستم طراحی است؛ قاعدهٔ انتخاب میان آن‌ها راهنمای طراحی است؛ و سازوکارش در راهنمای کدنویسی آمده.

رویدادها

کامپوننت‌ها CustomEvent می‌فرستند و بار داده در detail است. شنونده را روی خود عنصر ببندید: اینکه رویدادی حباب می‌کند یا نه تصمیمی است در سطح هر کامپوننت، و مرجع API برای هرکدام آن را می‌گوید:

<r-select id="env"></r-select>

<script>
  document.getElementById('env').addEventListener('change', (event) => {
    console.log(event.detail.value);
  });
</script>

شکل ویژگی onchange="…" و شکل خصیصه el.onchange = … هم کار می‌کنند، چون این‌ها عناصر عادی DOM هستند؛ اما تنها یک هندلر می‌پذیرند و فاز capture ندارند، پس آنچه باید نخست سراغش بروید addEventListener است.

بعد کجا برویم

اگر می‌خواهید…	بخوانید
API دقیق یک عنصر را ببینید	API عناصر
بدانید کدام توکن و چرا	سیستم طراحی
صفحه‌ای بسازید که یکدست دیده شود	راهنمای طراحی
ranui را درست به یک برنامه وصل کنید	راهنمای کدنویسی
روشن/تیره اضافه کنید یا همه‌چیز را بازطراحی کنید	پوسته
رابط را ترجمه کنید	i18n
روی سرور رندر کنید	رندر سمت سرور
بدون فریم‌ورک نمای واکنشی بسازید	سازنده
پیش از ارتقا ببینید چه تغییر کرده	فهرست تغییرات