DisclosureRow

قابِ تک‌خطیِ [آغازین] عنوان · خلاصه که باز می‌شود و بدنه‌ای را نمایان می‌کند. همان سطری است که <r-reasoning> و <r-tool-card> با هم به کار می‌برند، تا رونوشتی که هر دو را دارد یک زبانِ باز و بسته شدن داشته باشد نه دو زبان.

کجا به کار می‌آید: وقتی خطی فشرده دارید که جای چیزی بزرگ‌تر می‌نشیند (یک فراخوانی ابزار، یک رشته استدلال، یک دسته لاگ) و جزئیاتش ارزش دارد تا وقتی خواسته نشده پنهان بماند.

شروع سریع

کاربرد پایه

تا وقتی سطر باز است بدنه دیده می‌شود.

<r-disclosure-row heading="خواندن فایل" summary="packages/ranui/index.ts" expandable>
  <div>تا وقتی سطر باز است بدنه دیده می‌شود.</div>
</r-disclosure-row>

heading نیمه آغازینِ با پهنای ثابت است و summary نیمه پایانی که سرریزش بریده می‌شود؛ پس ستونی از سطرها روی یک ستون فقرات هم‌تراز می‌ماند، هر قدر هم خلاصه‌ها بلند باشند. خلاصه خالی، جداکننده را هم با خود می‌برد.

تا وقتی کار در جریان است

busy نواری از درخشش را روی سطر می‌گذراند. یک چرخنده تنها می‌گوید جایی چیزی در جریان است؛ اما گذر درخشش روی سطر نشان می‌دهد کدام سطر هنوز کار می‌کند.

همراه یک نشانگر آغازین

اسلات leading و علامت زاویه یک خانه از شبکه را با هم شریک‌اند، پس جابه‌جایی میانشان هیچ هزینه چیدمانی ندارد و عنوان هرگز زیر نشانگر نمی‌لغزد.

اگر چیزی در leading نگذاشته باشید، علامت زاویه همیشه دیده می‌شود، چون تنها نشانه‌ای است که به خواننده می‌گوید این سطر باز می‌شود. با وجود محتوای آغازین، علامت زاویه هنگام هاور، هنگام فوکوس یا تا وقتی سطر باز است پیدا می‌شود و در بقیه اوقات نشانگر وضعیت دیده می‌شود.

باندل از سقف حجم گذشته است.

<r-disclosure-row heading="ساخت" summary="در ۴٫۲ ثانیه شکست خورد" tone="error" expandable>
  <r-state-dot slot="leading" state="error"></r-state-dot>
  <div>باندل از سقف حجم گذشته است.</div>
</r-disclosure-row>

مرجع API

ویژگی‌ها

ویژگی	اتریبیوت	نوع	پیش‌فرض	توضیح
heading	heading	string	''	نیمه آغازینِ سطر، با پهنای ثابت.
summary	summary	string	''	نیمه پایانی که بریده می‌شود. خالی که باشد جداکننده هم می‌رود.
open	open	boolean	false	اینکه بدنه نمایش یابد. بازتاب می‌یابد، پس :has([open]) کار می‌کند.
expandable	expandable	boolean	false	اینکه سطر بدنه‌ای دارد که ارزش باز کردن داشته باشد.
busy	busy	boolean	false	اینکه کاری که این سطر نمایندهٔ آن است هنوز در جریان باشد.
tone	tone	string	''	error خلاصه را رنگ می‌کند؛ هر مقدار دیگری همان لحن معمول است.
name	name	string	''	سطرها را گروه می‌کند تا باز شدن یکی، بقیه را ببندد.
sheet	sheet	string	''	CSSی که به shadow root تزریق می‌شود.

اتریبیوت heading است، نه title

title یک اتریبیوت بومی HTMLElement است که مرورگر آن را به‌شکل tooltip رسم می‌کند؛ پس کامپوننتی که آن را برای عنوان به کار ببرد، روی هر نمونه یک tooltip می‌رویاند که همان متنِ روی صفحه را تکرار می‌کند و پس از تنظیم، هیچ‌چیز خاموشش نمی‌کند. <r-card> و <r-modal> هم به همین دلیل همین تغییر نام را دارند.

رویدادها

رویداد	detail	انتشار	توضیح
disclosurebeforetoggle	{ open: boolean }	bubbles، composed، لغوپذیر	سطر در آستانه باز یا بسته شدن است.
disclosuretoggle	{ open: boolean }	bubbles، composed	سطر باز یا بسته شد.

رویداد disclosuretoggle است، نه toggle

toggle چیزی است که <details> می‌فرستد و ToggleEvent آن به‌جای detail مقادیر oldState / newState را دارد؛ شنونده‌ای که با نام پلتفرم تایپ شده باشد چیزی در آن نمی‌یابد. وضعیت را از خود عنصر بخوانید: row.open.

row.addEventListener('disclosuretoggle', () => {
  console.log(row.open ? 'opened' : 'closed');
});

disclosurebeforetoggle نخست فرستاده می‌شود و می‌توان ردش کرد؛ همین است که «بدنه را نخستین باری که باز شد بیاور» و «تا وقتی ویرایشی ذخیره نشده از بسته‌شدن سر باز بزن» را بیان‌پذیر می‌کند. پلتفرم معادلی برایش ندارد: <details> تنها toggleِ پس از رخداد را می‌فرستد و درخواستِ یک beforetoggle لغوپذیر روی آن هنوز باز است.

row.addEventListener('disclosurebeforetoggle', async (event) => {
  if (!event.detail.open || row.dataset.loaded) return;
  event.preventDefault(); // تا وقتی بدنه نرسیده بسته نگهش دار
  row.append(await fetchBody());
  row.dataset.loaded = 'true';
  row.open = true;
});

تنها فشردن آن را می‌فرستد. یک row.open = true برنامه‌نویسی‌شده یعنی خودِ برنامه نظرش را عوض کرده، و کسی نیست که از او بپرسد.

هر بار یک سطر

name سطرها را همان‌طور گروه می‌کند که name روی <details> این کار را می‌کند: باز کردن یکی بقیه را می‌بندد. دامنه گروه، کل سند است و لازم نیست سطرها هم‌نیا باشند.

<r-disclosure-row name="run" heading="Install" expandable>…</r-disclosure-row>
<r-disclosure-row name="run" heading="Build" expandable>…</r-disclosure-row>
<r-disclosure-row name="run" heading="Test" expandable>…</r-disclosure-row>

دسترس‌پذیری

سطر تنها وقتی یک کنترل است که چیزی برای باز کردن داشته باشد. با expandable، سطر role="button"، توقف Tab، aria-expanded و aria-controlsی دارد که به بدنه اشاره می‌کند؛ بدون آن، هیچ‌کدام را ندارد، چون اعلام یک خط متن به‌عنوان دکمه، به فشاری دعوت می‌کند که هیچ کاری نمی‌کند. busy مقدار aria-busy را می‌گذارد، پس گذر درخشش تنها نشانه‌ی در جریان بودن کار نیست.

بدنه بسته، به‌جای حذف، بریده می‌شود تا بتواند انیمیشن داشته باشد. همچنین inert می‌شود و محتوایش با content-visibility: hidden نادیده گرفته می‌شود، که تا وقتی بسته است آن را از ترتیب Tab و از مسیر رسم بیرون نگه می‌دارد.

بلندای سطر ۲۴ پیکسل است، دقیقاً کمینه WCAG 2.5.8، و سطرها بی‌فاصله روی هم می‌نشینند. با نشانگر درشت، بلندای پیش‌فرض به ۳۲ پیکسل می‌رود، چون ناحیه لمس را نمی‌شود فراتر از خودِ سطر بزرگ کرد بی‌آنکه با سطر بالایی هم‌پوشان شود؛ و این یعنی معاوضه یک هدف کوچک با یک هدف اشتباه. تنظیم --ran-disclosure-row-height بلندا را در هر نوع ورودی میخکوب می‌کند.

اسلات‌ها

اسلات	محتوا
default	بدنه، که تا وقتی open است نمایان می‌شود.
leading	نشانگری پیش از عنوان، معمولاً <r-state-dot>.
heading	مارک‌آپ نیمه آغازین، جایگزین متن سادهٔ اتریبیوت heading.
summary	مارک‌آپ نیمه پایانی، جایگزین متن سادهٔ اتریبیوت summary.

heading و summary به‌شکل اتریبیوت رشته ساده می‌گیرند، که معمولاً همان چیزی است که سطر یک فراخوانی ابزار لازم دارد. وقتی آن نیمه باید مارک‌آپ داشته باشد — کد، پیوند، یک کوته‌نوشت — به‌جایش در اسلات بگذارید. متن اتریبیوت پشتوانه اسلات است، پس محتوای اسلات صرفاً جایش را می‌گیرد:

<r-disclosure-row expandable>
  <code slot="heading">fetch()</code>
  <a slot="summary" href="https://example.com">https://example.com</a>
  <pre>…</pre>
</r-disclosure-row>

محتوای اسلات هم یک نیمه از خط به شمار می‌آید، پس جداکننده درست مثل حالت اتریبیوت‌ها پیدا و ناپدید می‌شود.

Partها

row · leading · title · separator · summary · disclosure · body

استایل‌دهی

<r-disclosure-row> ۱۵ ویژگی سفارشی CSS از آنِ خود دارد، به‌علاوه توکن‌های معنایی که از پوسته می‌خواند. هر جا که ارث برسد می‌توانید یکی را تعیین کنید: :root، یک دربرگیرنده، یا خود عنصر:

r-disclosure-row {
  --ran-disclosure-hover-background: var(--ran-color-bg-subtle);
}

Partها: body · disclosure · leading · row · separator · summary · title

فهرست کامل در توکن‌های استایل است؛ اینکه سراغ کدام توکن بروید کار سیستم طراحی است.

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

• یا به سطر بدنه بدهید، یا بازشدنی‌اش نکنید. علامت زاویه‌ای که به فضای خالی باز می‌شود به هیچ کار نمی‌آید؛ expandable را نگذارید و سطر همان یک خط می‌ماند.
• عنوان را در واژگانی ثابت نگه دارید (خواندن فایل، اجرای آزمون‌ها، جست‌وجو) و بخش متغیر را در خلاصه بگذارید. همین است که ستونی از سطرها را قابل مرور می‌کند.
• tone="error" را همیشه با واژه‌ها همراه کنید، نه تنها با رنگ: خلاصه باید بگوید چه چیزی شکست خورده است.