Progress

نوار پیشرفت برای نشان‌دادن پیشرفت کار، با دستگیرهٔ کشیدنی اختیاری.

کجا به کارش ببرید: وقتی نواری می‌خواهید که پیشرفت کاری را نشان دهد. برای پیشرفت فقط‌خواندنی <r-progress> را همان‌طور به کار ببرید و اگر کاربر باید مقدار را با دستگیرهٔ کشیدنی تعیین کند از type="drag" استفاده کنید.

شروع سریع

<r-progress percent="40%"></r-progress>

💡 نکته: r-progress عنصری بلوکی و بدون عرض ذاتی است. داخل یک ردیف flex ممکن است تا عرض صفر جمع شود؛ عرض صریح بدهید (مثلاً style="width:100%") یا آن را در بافتار بلوکی بگذارید.

مرجع API

خصیصه‌ها

خصیصه	نوع	پیش‌فرض	توضیح
`percent`	`string`	`'0'`	پیشرفت کنونی؛ عدد یا درصد می‌پذیرد. سقف آن `total` است.
`total`	`string`	`'100'`	کل پیشرفت؛ عدد یا درصد می‌پذیرد.
`type`	`string`	`'primary'`	نوع نوار: `primary` (ایستا) یا `drag` (کلیک‌شدنی / کشیدنی).
`dot`	`string`	`'true'`	اینکه دستگیرهٔ کشیدن نشان داده شود: `true` یا `false`.
`sheet`	`string`	`''`	CSS تزریق‌شده به shadow DOM کامپوننت.

مقدار پیشرفت `percent`

پیشرفت کنونی را تعیین می‌کند. عدد یا رشتهٔ درصد می‌پذیرد و نمی‌تواند از total بگذرد. اگر total تعیین نشده باشد پیش‌فرض آن 100 است، یعنی percent به‌عنوان درصدی از ۱۰۰ خوانده می‌شود.

<r-progress percent="30%"></r-progress>
<r-progress percent="70%"></r-progress>
<r-progress percent="100%"></r-progress>

کل پیشرفت `total`

مخرج percent را تعیین می‌کند. هم عدد و هم درصد مجاز است، پس percent="30" total="1000" نوار را ۳٪ پر می‌کند.

<r-progress percent="30" total="1000"></r-progress>
<r-progress percent="70" total="100"></r-progress>
<r-progress percent="10%" total="100%"></r-progress>

نوع نوار `type`

primary: نوار پیشرفت ایستا. وقتی type تعیین نشده باشد همین پیش‌فرض است.
drag: نوار کلیک‌شدنی و کشیدنی. کلیک روی ریل یا کشیدن دستگیره percent را به‌روز می‌کند و رویداد change می‌فرستد. کشیدن دستگیره به dot="true" نیاز دارد.

<r-progress type="drag" percent="30%"></r-progress> <r-progress type="primary" percent="40%"></r-progress>

دستگیرهٔ کشیدن `dot`

نمایش دستگیره را روشن و خاموش می‌کند. دستگیره تنها وقتی ترسیم می‌شود که dot="true" و type="drag" باشد؛ روی نوار ایستای primary عمداً حذف می‌شود، پس آنجا dot اثر دیدنی ندارد.

<r-progress type="drag" percent="30%" dot="true"></r-progress>
<r-progress type="drag" percent="30%" dot="false"></r-progress>

رویدادها

`change`

در نوع drag، هر بار که کاربر روی ریل کلیک کند یا دستگیره را بکشد و percent عوض شود ارسال می‌شود. شیء detail این‌ها را حمل می‌کند:

فیلد	نوع	توضیح
`value`	`string`	پیشرفت کنونی
`percent`	`string`	پیشرفت کنونی
`total`	`string`	کل پیشرفت

<r-progress type="drag" percent="30%"></r-progress>

<script>
  const progress = document.createElement('r-progress');
  progress.type = 'drag';
  progress.percent = '30%';
  progress.addEventListener('change', (e) => {
    console.log(e.detail.value, e.detail.percent, e.detail.total);
  });
  container.append(progress);
</script>

Part‌های CSS

Part	توضیح
`track`	ریل پیشرفت (زمینه).
`fill`	بخش پرشدهٔ ریل.
`dot`	دستگیرهٔ کشیدن.

r-progress::part(fill) {
  background: var(--ran-color-primary);
}

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

نوارهای ایستا: برای نمایش پیشرفت فقط‌خواندنی از پیش‌فرض type="primary" استفاده کنید.
نوارهای تعاملی: اگر کاربر باید مقدار را تعیین کند از type="drag" استفاده کنید و به رویداد change گوش بدهید.
درصد یا عدد: percent و total را آزادانه ترکیب کنید؛ وقتی به یک کل مشخص نگاشت می‌شوند عدد خام بدهید و برای مهار مستقیم، درصد.
عرض در چیدمان: نوار را در نگه‌دارنده‌ای بلوکی بپیچید یا عرض صریح بدهید تا در چیدمان‌های flex جمع نشود.