اللوحة السفلية — مكوّن واجهة مستخدم يراعي إمكانية الوصول

الفئة: الاحتواء
الرموز: comp.bottom-sheet
المستوى: مركّب
مبني من: Modal layer

نظرة عامة

Web: tanrei-bottom-sheet; schedule
SwiftUI: tanreiBottomSheet; schedule
Jetpack Compose: TanreiBottomSheet; schedule
Flutter: TanreiBottomSheet; schedule
React Native: BottomSheet; schedule

مولَّد من docs/status/status.json, specs/bottom-sheet.spec.json

لوحة نمطية: افتحها بالزر

حفظ الصورة

الاستخدام

اللوحة السفلية مُتحكَّم بها (controlled)، ولا تغلق نفسها أبدًا. تفتحها بضبط الخاصية open. وحين يطلب الشخص أن تذهب، تُصدر اللوحة الحدث close مع السبب، وأنت تعيد open إلى القيمة false. والاستثناء الوحيد هو SwiftUI: هناك open ربط (binding)، فتكتب اللوحة فيه false ثم تستدعي onClose. إن تركت open على true بقيت اللوحة، وبعد السحب تستقر من جديد عند أدنى ارتفاع لها. وعلى الويب يختلف هذا عن مربع الحوار: تلغي اللوحة الحدث الأصلي cancel وتُصدر close مكانه، فلا يغلقها المفتاح Escape إلى أن تغلقها أنت.

يحمل الحدث close أحد خمسة أسباب، بحالة الأحرف التي تتبعها المنصة:

السبب	ما فعله الشخص	أي هيئة
`close`	ضغط زر الإغلاق في اللوحة (`closable`)	القياسية والنمطية
`drag`	أفلت السحب تحت نصف أدنى ارتفاع للوحة، أو دفعها بسرعة إلى الأسفل من هناك	القياسية والنمطية
`scrim`	ضغط المنطقة المعتَّمة حول لوحة نمطية	النمطية
`escape`	ضغط المفتاح Escape	النمطية
`back`	استخدم الرجوع في المنصة: زر الرجوع أو إيماءته في Android، وإيماءة الخروج لإمكانية الوصول في iOS. وعلى الويب، طلب الإغلاق الذي يأتي بلا مفتاح، مثل إيماءة الرجوع في Android داخل المتصفح، هو `back`.	النمطية

لا تُصدر اللوحة الحدث close إلا ما دامت قيمة dismissible هي true، ومرة واحدة بالضبط لكل طلب. وما دامت القيمة false، فالحجاب (scrim) والمفتاح Escape والرجوع لا تفعل شيئًا، والسحب إلى الأسفل يستقر عند أدنى ارتفاع. والاستثناء زر الإغلاق: فهو يطلب الإغلاق بالسبب close أيًّا كانت قيمة dismissible، لأنه مخرج اخترتَ أن ترسمه.

للوحة هيئتان تحددهما الخاصية variant. النمطية (modal)، وهي الافتراضية، تراكب نمطي: تعتّم النافذة كلها، وتُبقي التركيز في داخلها، وتعيد التركيز حين تُغلق. القياسية (standard) منطقة تخطيط، لا تراكب: تغطي أسفل العنصر الأب الذي تضعها فيه، ولا ترسم حجابًا، وتدع الشخص يواصل العمل في المحتوى الذي فوقها.

ما يوضع في اللوحة شأنك. تزيح اللوحة محتواها عن الحواف إلى الداخل بمقدار حشوها (اضبط inset على false لقائمة تضع صفوفها حشوها بنفسها)، وتقصّه، وتعطيه لون محتوى، وتمرّره. وإن أعطيتها قيمة headline رسمت ترويسة فوق المحتوى: العنوان الرئيسي، وهو عنوان (heading) يسمّي اللوحة أيضًا حين تكون label فارغة، ومع تفعيل closable زر إغلاق تسمّيه الخاصية closeLabel، وهو زر صغير (small) من الطراز tonal في النظام الافتراضي، مثل كل أزرار الإغلاق في Tanrei. ويقوم تحت الترويسة فاصل بحسب dividerVisibility، وتبقى الترويسة مكانها حين يتمرّر المحتوى. وclosable معطَّل افتراضيًّا، لأن المقبض، والحجاب في اللوحة النمطية، هما مخرجا اللوحة؛ فعّله في اللوحة القياسية أو في لوحة بلا مقبض.

علِّم العنصر الذي ينبغي أن ينال التركيز عند فتح اللوحة بعلامة المنصة نفسها: autofocus على الويب، و .defaultFocus أو @AccessibilityFocusState على SwiftUI، و FocusRequester يُمرَّر في initialFocus على Compose، و autofocus: true على Flutter، و initialFocusRef على React Native. من دون علامة يذهب التركيز إلى اللوحة نفسها، فتُقرأ تسميتها أولًا.

<tanrei-button id="save" variant="outlined">حفظ الصورة</tanrei-button>

<!-- النمطية هي الافتراضية. closedby="none" هي dismissible مضبوطة على false. -->
<tanrei-bottom-sheet id="save-sheet" label="حفظ الصورة" handle-label="تغيير حجم اللوحة">
  <p>اختر أين تُحفظ الصورة.</p>
  <tanrei-button variant="text" autofocus>تم</tanrei-button>
</tanrei-bottom-sheet>

<!-- القياسية: تغطي أسفل الكتلة الحاوية لها. flush هي inset مضبوطة على false؛ و no-handle هي handle مضبوطة على false. -->
<div class="map" style="position: relative">
  <tanrei-bottom-sheet variant="standard" open label="أماكن قريبة" handle-label="تغيير حجم اللوحة" flush>
    <tanrei-list>…</tanrei-list>
  </tanrei-bottom-sheet>
</div>

<script type="module">
  import '@tanrei/web/components/bottom-sheet';
  const sheet = document.querySelector('#save-sheet');
  document.querySelector('#save').addEventListener('click', () => (sheet.open = true));
  sheet.querySelector('tanrei-button').addEventListener('click', () => (sheet.open = false));
  // اللوحة لا تغلق نفسها أبدًا. detail.reason هي drag أو scrim أو escape أو back.
  sheet.addEventListener('close', (e) => (sheet.open = false));
  // نقلها الشخص إلى ارتفاعها الآخر. اللوحة ضبطت detent من قبل.
  sheet.addEventListener('detentchange', (e) => console.log(e.detail.detent));
</script>

import { BottomSheet, Button } from '@tanrei/react';

<BottomSheet
  open={open}
  label="حفظ الصورة"
  handleLabel="تغيير حجم اللوحة"
  onClose={() => setOpen(false)}
  onDetentChange={(e) => setDetent(e.detail.detent)}
>
  <p>اختر أين تُحفظ الصورة.</p>
  <Button variant="text" onClick={() => setOpen(false)}>تم</Button>
</BottomSheet>

import Tanrei

// مُعدِّل على العرض الذي تغطيه اللوحة، مثل .sheet. الإغلاق يكتب false في الربط (binding)،
// ثم يستدعي onClose مع السبب. والارتفاع الذي يختاره الشخص يُكتب في detent.
PhotoView(photo)
    .tanreiBottomSheet(isPresented: $saving, detent: $detent,
                       handleLabel: "تغيير حجم اللوحة", label: "حفظ الصورة") {
        SaveTargets(photo)
        TanreiButton("تم", variant: .text) { saving = false }
    }

// القياسية: تراكب في أسفل العرض الذي تغطيه.
MapView()
    .tanreiBottomSheet(isPresented: $placesShown, variant: .standard,
                       handleLabel: "تغيير حجم اللوحة", label: "أماكن قريبة") {
        PlacesList()
    }

import io.github.chnotchy.tanrei.components.TanreiBottomSheet
import io.github.chnotchy.tanrei.components.TanreiButton
import io.github.chnotchy.tanrei.tokens.TanreiButtonVariant

// visible بدل استدعائها وهي مفتوحة فقط، لكي تعمل حركة الخروج.
// اضبطها على false من onClose، الذي يستقبل السبب.
TanreiBottomSheet(
    visible = saving,
    onClose = { saving = false },
    detent = detent,
    onDetentChange = { detent = it },
    handleLabel = "تغيير حجم اللوحة",
    contentDescription = "حفظ الصورة",
) {
    SaveTargets(photo)
    TanreiButton(text = "تم", onClick = { saving = false }, variant = TanreiButtonVariant.Text)
}

import 'package:tanrei/tanrei.dart';

// اللوحة النمطية هي الابن الأخير في Stack فوق الصفحة كلها. اضبط open على false من onClose.
Stack(
  children: <Widget>[
    const Positioned.fill(child: PhotoPage()),
    TanreiBottomSheet(
      open: saving,
      onClose: (TanreiSheetCloseReason reason) => setState(() => saving = false),
      detent: detent,
      onDetentChanged: (value) => setState(() => detent = value),
      handleSemanticLabel: 'تغيير حجم اللوحة',
      semanticLabel: 'حفظ الصورة',
      child: const SaveTargets(),
    ),
  ],
),

import { useRef, useState } from 'react';
import type { View } from 'react-native';
import { BottomSheet, Button } from '@tanrei/react-native';

const done = useRef<View>(null);
const [open, setOpen] = useState(false);

// مُتحكَّم بها: اضبط open على false من onClose، الذي يستقبل السبب ('drag' أو 'scrim' أو 'escape' أو 'back').
// اللوحة النمطية تُعرض في Modal شفاف. خاصية insets في اللوحة تحل محل الجوانب التي تسمّيها من insets في TanreiProvider.
<BottomSheet
  open={open}
  onClose={(reason) => setOpen(false)}
  detent={detent}
  onDetentChange={setDetent}
  handleLabel="تغيير حجم اللوحة"
  accessibilityLabel="حفظ الصورة"
  initialFocusRef={done}
>
  <SaveTargets />
  <Button ref={done} variant="text" onPress={() => setOpen(false)}>تم</Button>
</BottomSheet>

المواصفات

لوحة قياسية فوق أسفل عنصرها الأب: اسحبها إلى الأسفل لإغلاقها

الخريطة

عرض الأماكن القريبة

ثلاثة مقاهٍ ومخبز مفتوحة على بعد عشر دقائق مشيًا.

البنية

الجزء	الوصف
1 `scrim` · اختياري	The modal layer's scrim over everything behind a modal sheet (MDL-1). It blocks presses and, while the sheet is dismissible, a press on it asks the sheet to close. A standard sheet draws none.
2 `container`	The raised surface docked to the bottom edge of the area it covers, centred and no wider than its maximum width, its top corners rounded and its bottom corners square. Its color reaches under the bottom system inset.
3 `drag-handle` · اختياري	The control at the top of the sheet: a Handle without a value, always drawn, that carries hover, focus and press on its box, with the grip centred in it. Activating it moves the sheet between its two heights.
4 `drag-handle.grip` · اختياري	The Handle's line: the short rounded bar drawn in the handle's box that says the sheet can be dragged.
5 `header` · اختياري	The row below the drag handle's row (or at the top without one) that holds the headline and the close button. Drawn while headline is not empty or closable is true; it stays in place while the content scrolls.
6 `headline` · اختياري	What the sheet is about ("Share photo"), a heading. It names the sheet where label is empty.
7 `close-button` · اختياري	An icon-only Button of the small size showing the close glyph at the end of the header, in the variant comp.bottom-sheet.close-button.variant names (tonal in the default system), as every host's close button is. The sheet places it and chooses its variant; everything else it reads from Button's own tokens.
8 `divider` · اختياري	A hairline across the sheet below the header: drawn whenever the header is in the default system, or only while the content is scrolled away from its top under dividerVisibility scroll.
9 `content`	Whatever the product puts in the sheet: a list of choices, a form, details. The sheet insets it (unless inset is false), clips it, hands it a content color and scrolls it; it does not lay it out.
10 `focus-ring` · اختياري	Gap-then-ring indicator around the drag handle's box, shown for keyboard focus.

الخصائص

الخاصية	النوع	القيمة الافتراضية	الوصف
`variant`	`standard` \| `modal`	`"modal"`	Standard sits over the lower part of the content while the content above stays usable (a layout region); modal dims and blocks everything else and holds focus until it closes (a modal overlay). Both read the same container tokens: the scrim and the behaviour set them apart. Not a token axis.
`open`	`boolean`	`false`	Whether the sheet is shown. The product opens it, and closes it in answer to close (or from its own controls); on SwiftUI, where it is a binding, the sheet writes false itself.
`detent`	`partial` \| `full`	`"partial"`	The height the sheet rests at while its content is taller than it: partial takes comp.bottom-sheet.container.partial-fraction of the area; full reaches up to comp.bottom-sheet.container.margin-block-start below the area's top. A sheet whose content is shorter than its partial height has one height, and detent changes nothing. The person moves between the two by dragging or with the drag handle (detentChange).
`dismissible`	`boolean`	`true`	Whether a drag below the sheet's lowest height asks it to close and, for a modal sheet, whether Escape, the platform's back and a press on the scrim do too. Set it to false only when the person must finish the sheet's task with one of its own controls.
`handle`	`boolean`	`true`	Draws the drag handle at the top of the sheet. Without it the sheet can still be dragged by its padding and content (BSH-9), but a keyboard or switch user has no way to change its height, so leave it on for a sheet whose content can be taller than its partial height.
`handleLabel`	`string`	`""`	The drag handle's accessible name ("Resize sheet"); its expanded state is exposed with it. Required while the handle is interactive (BSH-11).
`inset`	`boolean`	`true`	Insets the content by comp.bottom-sheet.container.padding. Set it to false for content that pads itself or reaches the edges (a list whose rows carry their own padding).
`label`	`string`	`""`	Names the sheet for assistive technology ("Share photo"): the modal dialog, or the standard sheet's region. Required unless headline names it.
`headline`	`string`	`""`	What the sheet is about ("Share photo"), drawn in its header (BSH-28). While label is empty it is the sheet's accessible name.
`closable`	`boolean`	`false`	Draws the close button at the end of the header (BSH-29). False by default: the drag handle and, for a modal sheet, the scrim are the sheet's ways out. Set it where a person who cannot drag needs one they can see — a standard sheet, or a sheet without a handle.
`closeLabel`	`string`	`""`	The close button's accessible name ("Close sharing"). Required while closable is true.
`dividerVisibility`	`auto` \| `always` \| `scroll`	`"auto"`	When the divider below the header is drawn. always: whenever the header is drawn, at rest as well as while the content is scrolled. scroll: only while the content is scrolled away from its top. auto takes comp.bottom-sheet.divider.visibility, the design system's answer (always in the default system).

المنافذ

المنفذ	الوصف
`default`	The content. A fixture's content string is plain text, which takes sys.typescale.body in the content color (BSH-8).

الأحداث

الحدث	الوصف
`close`	The sheet asks to be closed: its close button (BSH-29), a released drag below its lowest height, or for a modal sheet a press on the scrim, Escape or the platform's back. Carries which of these it was, named close, drag, scrim, escape or back (in the platform's casing). The close button asks whatever dismissible says; the others only while dismissible is true.
`detentChange`	The person moved the sheet to its other height, by a drag or with the drag handle. Carries the new detent (partial or full). Not emitted when the product sets detent.

الحالات

السلوك

متطلبات بصيغة EARS. يُختبر تنفيذ كل منصة مقابل هذه المعرّفات. يُعرض نص المتطلبات كما ورد في ملف المواصفة، بالإنجليزية.

المعرّف	المتطلب
`BSH-1`	WHEN open becomes true THE bottom sheet SHALL slide its container up from below the bottom edge of the area it covers to its height (BSH-6) — WHILE variant is modal over the whole window on its modal layer, fading the layer's scrim in comp.bottom-sheet.scrim.color and comp.bottom-sheet.scrim.blur in behind it in step (MDL-1, MDL-7); WHILE variant is standard over the bottom of the parent the product placed it in, with no scrim — over comp.bottom-sheet.motion.enter-duration with comp.bottom-sheet.motion.enter-easing; WHEN open becomes false THE bottom sheet SHALL slide it down out of view from wherever it is and fade the scrim out, over comp.bottom-sheet.motion.exit-duration with comp.bottom-sheet.motion.exit-easing. WHERE motion is reduced it SHALL fade in and out in place without sliding, or appear and disappear at once on a platform whose reduced-motion setting removes every animation (Android's). A sheet that is mounted with open true SHALL appear in place without motion.
`BSH-2`	WHILE variant is modal and the sheet is open THE bottom sheet SHALL make everything outside it inert, keep the content behind it from scrolling and keep focus inside it, as its modal layer does (MDL-2, MDL-4): a modal overlay.
`BSH-3`	WHEN open changes from false to true THE bottom sheet SHALL move focus to the element in it that the product marked for initial focus (the platform's own mark, named in the platform notes) or, without one, to its container, so that assistive technology reads its label first; WHEN it closes while focus is inside it THE bottom sheet SHALL return focus to the element that had it when the sheet opened or, where that element no longer exists or cannot take focus, to the platform's default for a closed overlay. Focus SHALL move when the sheet opens or closes, not when its motion ends. This holds for both variants (a modal sheet moves and returns focus as its modal layer does, MDL-3, MDL-5); a standard sheet mounted with open true SHALL NOT move focus, and a modal sheet mounted with open true SHALL move focus in as if it had just opened, because it makes everything behind it unfocusable and focus must be somewhere it can reach.
`BSH-4`	WHILE variant is standard THE bottom sheet SHALL draw no scrim, SHALL NOT make anything inert, SHALL NOT keep focus inside it, SHALL let Tab and Shift+Tab move focus between it and the content it covers without closing it, and SHALL ignore Escape and the platform's back: a standard sheet is a layout region, not an overlay. The product places it over the content it covers, in a parent that holds both; the sheet SHALL dock to that parent's bottom edge, SHALL NOT resize or pad the content, and SHALL let presses on the part of the parent above it reach the content.
`BSH-5`	WHILE dismissible is true, WHEN the user presses the scrim, presses Escape or uses the platform's back WHILE variant is modal, as its modal layer answers them (MDL-6), or releases a drag that asks to close (BSH-9) in either variant, THE bottom sheet SHALL emit close exactly once with the reason scrim, escape, back or drag, and SHALL then be closed: through its binding where open is one (SwiftUI), and by the product setting open to false where open is a plain value (web, Compose, Flutter, React Native). WHILE dismissible is false THE bottom sheet SHALL ignore these inputs and emit nothing for them (its close button, BSH-29, still asks); a press on the scrim SHALL still reach nothing behind it.
`BSH-6`	THE bottom sheet SHALL be as tall as its drag handle's row, its header (BSH-28) and its content (with its insets), but no taller than its detent allows: WHILE detent is partial, comp.bottom-sheet.container.partial-fraction of the height of the area it covers; WHILE detent is full, that height less comp.bottom-sheet.container.margin-block-start. The area is the window below its top system inset for a modal sheet, and the parent the product placed it in for a standard sheet; WHILE the on-screen keyboard is shown the area SHALL end at the keyboard's top edge, so that the sheet sits on the keyboard and both heights are taken from the smaller area. The sheet has two heights only WHILE its content is taller than its partial height; otherwise it has one, and detent changes nothing.
`BSH-7`	THE bottom sheet SHALL draw its container at the bottom edge of the area, as wide as the area but no wider than comp.bottom-sheet.container.max-width and centred in it, filled with comp.bottom-sheet.container.color, raised by comp.bottom-sheet.container.elevation, with its top corners rounded by comp.bottom-sheet.container.shape and its bottom corners square; it SHALL extend its color under the bottom system inset and keep its content above that inset, and WHILE the on-screen keyboard is shown it SHALL sit on the keyboard (BSH-6) with its content above it.
`BSH-8`	THE bottom sheet SHALL lay out, top to bottom, the drag handle's row WHILE handle is true (BSH-12), the header WHILE there is one (BSH-28) and then its content. WHILE inset is true it SHALL inset the content by comp.bottom-sheet.container.padding from its start, end and bottom edges, and from its top edge WHILE handle is false and no header is drawn; WHILE inset is false the content SHALL reach the container's edges, below the handle's row and the header. It SHALL clip the content to the container's shape, SHALL hand it comp.bottom-sheet.content.color as the platform's inherited foreground (the web's inherited color, SwiftUI's foreground style, Compose's content color, Flutter's default text and icon style, React Native's Tanrei text context), and plain text given as content, where the platform must style it, SHALL take sys.typescale.body.
`BSH-9`	WHEN the user drags the sheet vertically — by its handle's row, by the padding around its content, or by its content where BSH-10 lets the drag reach the sheet — beyond the platform's touch slop THE bottom sheet SHALL follow the finger or pointer, never above its full height; WHEN the drag is released it SHALL settle at the next height in the direction of a fling, or else at the height nearest to where it was released, over comp.bottom-sheet.motion.enter-duration with comp.bottom-sheet.motion.enter-easing (at once where motion is reduced). A release below half of the sheet's lowest height, or a downward fling from its lowest height, SHALL ask to close WHILE dismissible is true (BSH-5, BSH-20); WHILE dismissible is false the sheet SHALL settle at its lowest height instead. A fling is a release faster than the platform's minimum fling velocity (Android's ViewConfiguration.getScaledMinimumFlingVelocity, Flutter's kMinFlingVelocity) or, where the platform names none (the web, SwiftUI, React Native), 0.5 points per millisecond; the touch slop is the platform's own (Android's ViewConfiguration.getScaledTouchSlop, Flutter's kTouchSlop) or, where the platform names none, 8 points. A release's velocity is the pointer's over its last moves: WHERE the pointer has not moved for longer than the time after which the platform's velocity tracker takes a pointer as stopped (40 milliseconds in Android's VelocityTracker, Jetpack Compose's VelocityTracker and Flutter's VelocityTracker) or, where the platform names none (the web, SwiftUI, React Native), 40 milliseconds before the release THE bottom sheet SHALL take the release as having no velocity, so that a drag that stops where it is wanted and is let go there is no fling, however fast it moved before it stopped. WHEN a drag ends at the height it did not start from THE bottom sheet SHALL set detent to it and emit detentChange exactly once with it.
`BSH-10`	WHILE the content is taller than the room the sheet gives it THE bottom sheet SHALL scroll the content inside the container, below the handle's row, and SHALL let assistive technology and keyboard focus scroll it at either height; a drag upward on the content SHALL first raise the sheet to its full height and then scroll the content, and a drag downward on the content SHALL first scroll the content to its top and then lower the sheet.
`BSH-11`	WHILE handle is true and the sheet has two heights THE bottom sheet SHALL make the drag handle one focus stop, a button named by handleLabel with the expanded state, true WHILE detent is full (its label and expanded, HDL-8), and WHEN the user activates it by pointer, touch, Enter or Space (its activate, HDL-7) THE bottom sheet SHALL move to its other height as BSH-9 settles and emit detentChange exactly once with the new detent; WHILE the sheet has one height the handle SHALL still be drawn at rest but SHALL NOT be focusable, pressable or exposed to assistive technology. WHILE the handle is interactive and handleLabel is empty it SHALL still render, and in debug builds report that the handle has no accessible name.
`BSH-12`	WHILE handle is true THE bottom sheet SHALL draw at its top a row holding the drag handle — a Handle of axis vertical and size medium, with no value and revealed — centred across the sheet with comp.bottom-sheet.handle.margin-block above and below it, and SHALL give that Handle its own tokens in place of the Handle's: the box comp.bottom-sheet.handle.container-width wide and comp.bottom-sheet.handle.container-height high with comp.bottom-sheet.handle.container-shape corners (HDL-3), the grip — the Handle's line — comp.bottom-sheet.handle.grip-width long and comp.bottom-sheet.handle.grip-height thick (HDL-1), and the container, line and state-layer colors of each state from the drag-handle control (comp.bottom-sheet.drag-handle.container.color, comp.bottom-sheet.drag-handle.grip.color, comp.bottom-sheet.drag-handle.state-layer.color, and so on for each state), its opacity in each state, and comp.bottom-sheet.motion.state-duration, comp.bottom-sheet.motion.state-easing and comp.bottom-sheet.motion.feedback-duration as its motion; in the default system each of them aliases the Handle's own. The row SHALL stay in place while the content scrolls.
`BSH-13`	WHILE the drag handle is hovered, keyboard-focused or pressed THE bottom sheet SHALL render the handle's box, grip and opacity from the component tokens of the highest-precedence active state, with precedence pressed over focused over hovered, and the grip at the Handle's length and thickness of a handle in use (HDL-4); focus gained by pointer or touch SHALL NOT select the focused state. A drag that starts on the handle SHALL keep it pressed while the sheet follows the drag, as a Handle is held for as long as a drag lasts (HDL-11).
`BSH-14`	WHEN the drag handle receives keyboard focus THE bottom sheet SHALL show the focus ring around the handle's box without animation; focus gained by pointer or touch SHALL NOT show it.
`BSH-15`	THE bottom sheet SHALL give the drag handle the Handle's hit area (HDL-5): at least sys.target.touch wide and high for touch input and sys.target.pointer for fine pointers, centred on its box, without changing its drawn size, and the Handle's vertical resize cursor; a platform that cannot tell the input type SHALL use sys.target.touch. A press on the rest of the handle's row drags the sheet as BSH-9 says.
`BSH-16`	WHEN the drag handle is pressed by pointer, touch, Enter or Space THE drag handle SHALL show the pressed state without delay and SHALL keep it visible for at least sys.motion.duration.press-hold, even when the press ends sooner (HDL-11).
`BSH-17`	WHILE pressed THE drag handle SHALL answer as sys.behavior.pressed-feedback names: overlay applies the pressed tokens to the whole container at once; ripple grows the pressed state layer from the point of contact (from the center for keyboard activation); dim applies the pressed opacity to the whole control and draws no state layer; none draws no answer to the press. Under ripple and dim only the container color stays with the state under the press; grip and opacity still come from the pressed tokens. Under none every part stays with the state under the press. The ripple grows over comp.bottom-sheet.motion.feedback-duration with comp.bottom-sheet.motion.state-easing, fades over comp.bottom-sheet.motion.state-duration with comp.bottom-sheet.motion.state-easing once the press has ended and press-hold has passed, and appears whole where motion is reduced.
`BSH-18`	THE bottom sheet SHALL ease its container's top corners and the drag handle's box corners by sys.shape.corner-smoothing (0 is a quarter circle, 0.6 the iOS continuous corner; a platform with only the OS curve draws it for any amount above 0) and show the handle's keyboard focus as sys.behavior.focus-style names (ring or glow); a platform that cannot draw a choice SHALL fall back to the first value and state that in its README.
`BSH-19`	WHEN the drag handle's colors, or its grip's length and thickness, change between states THE bottom sheet SHALL animate them over comp.bottom-sheet.motion.state-duration with comp.bottom-sheet.motion.state-easing, and SHALL change them at once where motion is reduced.
`BSH-20`	WHEN a released drag asks to close THE bottom sheet SHALL emit close (BSH-5), hold where the drag left it for one frame, and then slide out from there as BSH-1 says IF open has become false, or settle back at its lowest height as BSH-9 says IF open is still true (the product declined to close it).
`BSH-21`	WHEN the product changes detent while the sheet is open THE bottom sheet SHALL move to the new height over comp.bottom-sheet.motion.enter-duration with comp.bottom-sheet.motion.enter-easing (at once where motion is reduced) and SHALL NOT emit detentChange; where detent is a plain value (web, Compose, Flutter, React Native), a height the person chose (BSH-9, BSH-11) SHALL stay until the product sets detent again, and where it is a binding (SwiftUI) the sheet SHALL write the new detent to it.
`BSH-22`	THE bottom sheet SHALL expose its container, WHILE variant is modal, as a modal dialog named by label and, WHILE variant is standard, as a region named by label (a landmark on the web) — by the headline WHILE label is empty (BSH-28); WHILE label and headline are both empty it SHALL still render, and in debug builds report that it has no accessible name. The drag handle's grip, the Handle's line, SHALL be hidden from assistive technology; the handle itself is exposed only as BSH-11 says.
`BSH-23`	WHEN a dialog, a menu or another modal sheet opens from a modal bottom sheet THE bottom sheet SHALL stay below it, become inert with the rest of the window, and on the other overlay's closing receive back the focus that overlay returns, as its modal layer does (MDL-8, MDL-9); Escape SHALL dismiss only the topmost overlay.
`BSH-24`	WHILE the text size is enlarged THE bottom sheet SHALL grow with its content up to the height its detent allows and scroll the content beyond it (BSH-10), grow its header with a headline that wraps, and SHALL NOT scale the drag handle, nor the close button beyond what the Button itself does.
`BSH-25`	WHEN variant or detent names a value the bottom sheet does not define THE bottom sheet SHALL render with the default value, and in debug builds report the unknown value.
`BSH-26`	WHEN the layout direction is right-to-left THE bottom sheet SHALL keep its container and its drag handle centred, and its content SHALL follow the layout direction.
`BSH-27`	THE bottom sheet SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the bottom sheet is shown THE bottom sheet SHALL draw itself for the new direction at once, without a motion of its own, keeping its open state, its height and its focus.
`BSH-28`	WHILE headline is not empty or closable is true THE bottom sheet SHALL draw a header below the drag handle's row (or at the top of the container without one): a row at least comp.bottom-sheet.header.height high holding the headline from comp.bottom-sheet.container.padding after the start edge, in comp.bottom-sheet.headline.typescale and comp.bottom-sheet.headline.color, wrapping onto more lines rather than truncating and growing the row with it, exposed as a heading, and, WHILE closable is true, the close button ending comp.bottom-sheet.header.padding-inline-end before the end edge and comp.bottom-sheet.header.gap after the headline, both centred in the row; below it, a divider comp.bottom-sheet.divider.width thick in comp.bottom-sheet.divider.color across the sheet's full width WHILE dividerVisibility (or, for auto, comp.bottom-sheet.divider.visibility) is always, or is scroll and the content is scrolled away from its top, shown and hidden at once. The header SHALL NOT scroll with the content, and a drag on it SHALL move the sheet as a drag on the handle's row does (BSH-9). WHILE headline is not empty it SHALL name the sheet where label is empty. A dividerVisibility the sheet does not define SHALL be drawn as auto, and reported in debug builds.
`BSH-29`	WHILE closable is true THE bottom sheet SHALL draw its close button as an icon-only Button of the small size showing the glyph close of the system's icon set and named by closeLabel, in the variant comp.bottom-sheet.close-button.variant names, given through the channel a Button reads from the component that places it, and otherwise unrestyled: it reads Button's own tokens, answers hover, focus and press as any Button does and keeps its own minimum target (BTN-5); WHEN the user activates it THE bottom sheet SHALL emit close exactly once with the reason close, in either variant and whatever dismissible says, and SHALL then be closed as BSH-5 says. WHILE closable is true and closeLabel is empty it SHALL still draw the button, and in debug builds report that the button has no accessible name. THE bottom sheet SHALL draw no close mark of its own.
`BSH-30`	WHILE handle is false, dismissible is true and closable is false THE bottom sheet SHALL still render, and in debug builds report that it shows no way out a person can see: a drag, Escape and the scrim still close it, but nothing on screen says so to a person who cannot drag.
`BSH-31`	WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE bottom sheet SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on its container (BSH-22) — its dialog WHILE variant is modal, its region otherwise — an id reference by the elements it names in the host's tree or a tree around it, a description after its own. WHILE label or headline is not empty it is the container's name (BSH-22), over a name given so; WHILE both are empty, a name given so is the container's name and SHALL NOT be reported as having none in debug builds. WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE bottom sheet SHALL take it off that element.

مطابقة الأسماء بين المنصات

التكافؤ لا يعني واجهات برمجية متطابقة. تعبّر كل منصة عن العقد نفسه بأسلوبها.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
المكوّن	`tanrei-bottom-sheet`	`tanreiBottomSheet`	`TanreiBottomSheet`	`TanreiBottomSheet`	`BottomSheet`
`variant` · الخاصية	`variant`	`variant`	`variant`	`variant`	`variant`
`open` · الخاصية	`open`	`isPresented`	`visible`	`open`	`open`
`detent` · الخاصية	`detent`	`detent`	`detent`	`detent`	`detent`
`dismissible` · الخاصية	`closedby`	`dismissible`	`dismissible`	`dismissible`	`dismissible`
`handle` · الخاصية	`handle`	`handle`	`handle`	`showHandle`	`handle`
`handleLabel` · الخاصية	`handleLabel`	`handleLabel`	`handleLabel`	`handleSemanticLabel`	`handleLabel`
`inset` · الخاصية	`inset`	`inset`	`inset`	`inset`	`inset`
`label` · الخاصية	`label`	`label`	`contentDescription`	`semanticLabel`	`accessibilityLabel`
`headline` · الخاصية	`headline`	`headline`	`headline`	`headline`	`headline`
`closable` · الخاصية	`closable`	`closable`	`closable`	`showCloseButton`	`closable`
`closeLabel` · الخاصية	`closeLabel`	`closeLabel`	`closeLabel`	`closeButtonSemanticLabel`	`closeLabel`
`dividerVisibility` · الخاصية	`dividerVisibility`	`dividerVisibility`	`dividerVisibility`	`dividerVisibility`	`dividerVisibility`
`close` · الحدث	`close`	`onClose`	`onClose`	`onClose`	`onClose`
`detentChange` · الحدث	`detentchange`	`detent`	`onDetentChange`	`onDetentChanged`	`onDetentChange`
ملاحظات	`dismissible` is HTML's own `closedby` attribute, as on `<tanrei-dialog>`: `any` (the default) or `none`. `handle` and `inset` are boolean properties that default to true; their attributes are the inverses `no-handle` and `flush` (an HTML boolean attribute cannot default to true). `handleLabel` is the `handle-label` attribute, `closeLabel` the `close-label` attribute and `dividerVisibility` the `divider-visibility` attribute (`auto` reads `--tanrei-comp-bottom-sheet-divider-visibility` from the cascade with a style query, and where the browser has none the sheet writes the name it read on its header when it renders). The close button is a `<tanrei-button>` in the shadow root, icon-only (the close glyph in its `icon` slot, its `label` from `close-label`), whose variant comes from the resolved comp.bottom-sheet.close-button.variant through the internal channel a Button reads from its host; the headline is an `<h2>`. `close` is a CustomEvent whose `detail.reason` is `close`, `drag`, `scrim`, `escape` or `back` (`back` when a modal sheet's native `cancel` arrives without an Escape key, as Android's back gesture sends it), and `detentchange` one whose `detail.detent` is the new detent; the element sets `detent` itself before firing it. The product sets `open` to false from `close`. The content is the default slot. Drags use pointer events with `touch-action: none` on the handle's row and the top edge; the content scrolls natively and hands the drag over at its top (BSH-10). Fling 0.5 px/ms, slop 8 px. Insets are `env(safe-area-inset-bottom)`; the on-screen keyboard is read from `visualViewport`. Snapshot harness: a 400 × 720 viewport with a `surface` page; the sheet opened by `open`; the screenshot is the viewport, since a modal sheet and its backdrop are in the top layer. The drag handle is a `<tanrei-handle>` in the shadow root, its `container` and `line` exported as the parts `handle` and `grip`; the sheet sets the Handle's custom properties to its own tokens on it (BSH-12), answers its `activate`, and keeps it `inert` while the sheet has one height (BSH-11).	A view modifier on the view the sheet covers, as `.sheet` is: `.tanreiBottomSheet(isPresented: Binding<Bool>, variant:, detent: Binding<TanreiBottomSheetDetent>, dismissible:, handle:, handleLabel:, inset:, label:, onClose: ((TanreiSheetCloseReason) -> Void)?, content:)`. Closing writes false to `isPresented` and then calls `onClose` with the reason; a height the person chose is written to `detent` (detentChange). Modal: on iOS presented with `.fullScreenCover`, a clear presentation background and the system transition off, as `tanreiDialog` is (that presentation hides the rest of the app from VoiceOver); Tanrei draws the scrim, the sheet and the drag with a `DragGesture` (fling from its `velocity`, 0.5 pt/ms). Not the native `.sheet`: its dim cannot take the scrim token, and on iPad in a regular width it becomes a centred form, not a bottom sheet. macOS, which has no full-screen cover, draws the modal sheet as an overlay of the modified view with the modal trait. Standard: `.overlay(alignment: .bottom)` of the modified view. Initial focus is `.defaultFocus` or an `@AccessibilityFocusState` the product passes; Escape is `.onKeyPress(.escape)` and the escape gesture `.accessibilityAction(.escape)`. Snapshot harness: renders `TanreiBottomSheetSurface` (the sheet and, for a modal sheet, the scrim) in place in a 400 × 720 frame over a `surface` page, because a snapshot of the presenting view does not include a presented window. Not built on this platform yet: the header — headline, closable, closeLabel and dividerVisibility, the close reason close (BSH-28, BSH-29) — and the report of a sheet with no way out a person can see (BSH-30).	`TanreiBottomSheet(visible, onClose: (TanreiSheetCloseReason) -> Unit, variant, detent, onDetentChange, dismissible, handle, handleLabel, inset, contentDescription, initialFocus: FocusRequester?, content)`. `visible` rather than calling it only while open, so that the exit motion can run before the sheet goes; the caller sets `visible` to false from `onClose`. The sheet keeps a height the person chose until `detent` changes (BSH-21). Modal: drawn in a `Dialog` window of its own, as `TanreiDialog` and the modal drawer are, with `usePlatformDefaultWidth = false`, `decorFitsSystemWindows = false` and the window's own dim off (Tanrei draws the scrim); the window traps focus, answers back and hides the content behind from TalkBack; the sheet sets a pane title from `contentDescription`. Standard: fills its parent (a `Box` over the content) and draws the sheet at its bottom edge; the part above takes no touches. Drag with `Modifier.draggable` and nested scroll for BSH-10; fling and slop from `ViewConfiguration`. Snapshot harness: renders `TanreiBottomSheetContent` (the sheet and, for a modal sheet, the scrim) in place in a 400 × 720 dp box over a `surface` page; the window itself is covered by instrumented tests. Not built on this platform yet: the header — headline, closable, closeLabel and dividerVisibility, the close reason close (BSH-28, BSH-29) — and the report of a sheet with no way out a person can see (BSH-30).	`TanreiBottomSheet(variant:, open:, onClose: ValueChanged<TanreiSheetCloseReason>, detent:, onDetentChanged:, dismissible:, showHandle:, handleSemanticLabel:, inset:, semanticLabel:, child:)`, controlled: the caller sets `open` to false from `onClose`. The product places it in a `Stack` over what it covers — for a modal sheet, a `Stack` over the whole page, as the modal navigation drawer — not `showModalBottomSheet`, which needs Material. The modal form draws its scrim over the whole `Stack`, keeps focus in a `FocusScope`, blocks the page's semantics (`BlockSemantics`), names itself with `Semantics(scopesRoute: true, namesRoute: true)`, answers back through `PopScope` and Escape through `Shortcuts`/`Actions`. Initial focus is `autofocus: true` on a focusable widget. Drag with a vertical drag recogniser; fling `kMinFlingVelocity`, slop `kTouchSlop`. Snapshot harness: a golden of the whole 400 × 720 surface with the sheet in a `Stack` over a `surface` page. Not built on this platform yet: the header — headline, closable, closeLabel and dividerVisibility, the close reason close (BSH-28, BSH-29) — and the report of a sheet with no way out a person can see (BSH-30).	Controlled: `open`, `onClose(reason)`, `detent`, `onDetentChange`; the caller sets `open` to false from `onClose`. Modal: presented in a transparent `Modal` with `animationType="none"`, `statusBarTranslucent` and `navigationBarTranslucent` (Tanrei draws the scrim and the motion); `onRequestClose` (Android back, and Escape on a hardware keyboard) is close with the reason `back` or `escape`. Standard: a `View` positioned absolutely at the bottom of its parent. Drags with `PanResponder` (no gesture-handler dependency): slop 8 pt, fling 0.5 pt/ms. The on-screen keyboard is read from `Keyboard` events. Initial focus is an `initialFocusRef` the product passes, moved with `AccessibilityInfo.setAccessibilityFocus`. Insets come from the sheet's own `insets` prop, falling back to `TanreiProvider`'s `insets`; the package takes no safe-area dependency. Snapshot harness: renders `BottomSheetSurface` (the sheet and, for a modal sheet, the scrim) in place in a 400 × 720 view over a `surface` page, since a `Modal` is a native window the snapshot does not include. React Native cannot hand one gesture from the sheet to the content's native scroll view partway through, so BSH-10's hand-off takes two gestures there; the package takes no gesture-handler dependency (as it takes no safe-area one). Not built on this platform yet: the header — headline, closable, closeLabel and dividerVisibility, the close reason close (BSH-28, BSH-29) — and the report of a sheet with no way out a person can see (BSH-30).

الرموز

الرمز	يشير إلى	القيمة المحلولة (فاتح)
`--tanrei-comp-bottom-sheet-close-button-variant`	—	1
`--tanrei-comp-bottom-sheet-container-color`	`sys.color.surface-container-low`	#f9f9f9
`--tanrei-comp-bottom-sheet-container-elevation`	`sys.elevation.level2`	0px 0px 0px 1px rgb(0 0 0 / 0.08), 0px 1px 2px 0px rgb(0 0 0 / 0.04)
`--tanrei-comp-bottom-sheet-container-margin-block-start`	`sys.space.space600`	48px
`--tanrei-comp-bottom-sheet-container-max-width`	—	640px
`--tanrei-comp-bottom-sheet-container-padding`	`sys.space.space200`	16px
`--tanrei-comp-bottom-sheet-container-partial-fraction`	—	0.5
`--tanrei-comp-bottom-sheet-container-shape`	`sys.shape.corner.large`	12px
`--tanrei-comp-bottom-sheet-content-color`	`sys.color.on-surface`	#1b1b1b
`--tanrei-comp-bottom-sheet-divider-color`	`sys.color.outline-variant`	#000000 · 8%
`--tanrei-comp-bottom-sheet-divider-visibility`	`sys.behavior.divider-visibility`	0
`--tanrei-comp-bottom-sheet-divider-width`	`sys.border.hairline`	1px
`--tanrei-comp-bottom-sheet-drag-handle-container-color`	`comp.handle.standard.container.color`	#000000 · 0%
`--tanrei-comp-bottom-sheet-drag-handle-focused-container-color`	—	#848484 · 10%
`--tanrei-comp-bottom-sheet-drag-handle-focused-grip-color`	—	#848484
`--tanrei-comp-bottom-sheet-drag-handle-focused-state-layer-color`	—	#848484
`--tanrei-comp-bottom-sheet-drag-handle-grip-color`	`comp.handle.standard.line.color`	#848484
`--tanrei-comp-bottom-sheet-drag-handle-hovered-container-color`	—	#848484 · 8%
`--tanrei-comp-bottom-sheet-drag-handle-hovered-grip-color`	—	#4b4b4b
`--tanrei-comp-bottom-sheet-drag-handle-hovered-state-layer-color`	—	#848484
`--tanrei-comp-bottom-sheet-drag-handle-pressed-container-color`	—	#848484 · 10%
`--tanrei-comp-bottom-sheet-drag-handle-pressed-grip-color`	—	#4b4b4b
`--tanrei-comp-bottom-sheet-drag-handle-pressed-state-layer-color`	—	#848484
`--tanrei-comp-bottom-sheet-drag-handle-state-layer-color`	`comp.bottom-sheet.drag-handle.grip.color`	#848484
`--tanrei-comp-bottom-sheet-focused-opacity`	—	1
`--tanrei-comp-bottom-sheet-handle-container-height`	`comp.handle.container.breadth.medium`	24px
`--tanrei-comp-bottom-sheet-handle-container-shape`	`comp.handle.container.shape`	9999px
`--tanrei-comp-bottom-sheet-handle-container-width`	`comp.handle.container.length.medium`	48px
`--tanrei-comp-bottom-sheet-handle-grip-height`	`comp.handle.line.thickness.medium`	4px
`--tanrei-comp-bottom-sheet-handle-grip-width`	`comp.handle.line.length.medium`	32px
`--tanrei-comp-bottom-sheet-handle-margin-block`	`sys.space.space150`	12px
`--tanrei-comp-bottom-sheet-header-gap`	`sys.space.space100`	8px
`--tanrei-comp-bottom-sheet-header-height`	—	64px
`--tanrei-comp-bottom-sheet-header-padding-inline-end`	`sys.space.space150`	12px
`--tanrei-comp-bottom-sheet-headline-color`	`sys.color.on-surface`	#1b1b1b
`--tanrei-comp-bottom-sheet-hovered-opacity`	—	1
`--tanrei-comp-bottom-sheet-motion-enter-duration`	`sys.motion.role.appear.sheet.enter`	400ms
`--tanrei-comp-bottom-sheet-motion-enter-easing`	`sys.motion.easing.enter`	cubic-bezier(0.2, 0, 0, 1)
`--tanrei-comp-bottom-sheet-motion-exit-duration`	`sys.motion.role.appear.sheet.exit`	350ms
`--tanrei-comp-bottom-sheet-motion-exit-easing`	`sys.motion.easing.exit`	cubic-bezier(0.3, 0, 1, 1)
`--tanrei-comp-bottom-sheet-motion-feedback-duration`	`comp.handle.motion.feedback-duration`	450ms
`--tanrei-comp-bottom-sheet-motion-state-duration`	`comp.handle.motion.state-duration`	200ms
`--tanrei-comp-bottom-sheet-motion-state-easing`	`comp.handle.motion.state-easing`	cubic-bezier(0.2, 0, 0, 1)
`--tanrei-comp-bottom-sheet-pressed-opacity`	—	1
`--tanrei-comp-bottom-sheet-scrim-blur`	`comp.modal-layer.scrim.blur`	0px
`--tanrei-comp-bottom-sheet-scrim-color`	`comp.modal-layer.scrim.color`	#000000 · 40%
`--tanrei-comp-bottom-sheet-headline-typescale`	`sys.typescale.heading-5`	500 16px/1.5

نماذج الاختبار

عروض مرجعية. تلتقط كل المنصات لقطة لكل نموذج بالمعرّف نفسه حتى يمكن مقارنة النتائج.

modal

open: true handleLabel: Resize sheet label: Save photo مرسوم وحده في نافذة بحجم 400 × 720

modal-partial

open: true detent: partial handleLabel: Resize sheet label: Terms of service مرسوم وحده في نافذة بحجم 400 × 720

modal-full

open: true detent: full handleLabel: Resize sheet label: Terms of service مرسوم وحده في نافذة بحجم 400 × 720

no-handle

open: true handle: false label: Save photo مرسوم وحده في نافذة بحجم 400 × 720

standard

variant: standard open: true handleLabel: Resize sheet label: Nearby places مرسوم وحده في نافذة بحجم 400 × 720

modal-header

open: true handleLabel: Resize sheet headline: Save photo closable: true closeLabel: Close مرسوم وحده في نافذة بحجم 400 × 720

no-handle-header

open: true handle: false headline: Save photo closable: true closeLabel: Close مرسوم وحده في نافذة بحجم 400 × 720

standard-header

variant: standard open: true handleLabel: Resize sheet label: Cafés and bakeries nearby headline: Nearby places closable: true closeLabel: Close nearby places مرسوم وحده في نافذة بحجم 400 × 720

مولَّد من specs/bottom-sheet.spec.json, tokens/comp/bottom-sheet.tokens.json, design/tokens/

الإرشادات

متى يُستخدم

استخدم اللوحة السفلية في شاشة مضغوطة (Compact)، حيث لا حيّز بجانب المحتوى، لشيء ينتمي إلى الشاشة لكنه ليس موضوعها الرئيسي: الأماكن القريبة من نقطة على خريطة، طرق مشاركة صورة، اختيار قصير أو نموذج قصير. ترتفع اللوحة من الحافة الأقرب إلى الإبهام.

استخدم اللوحة الجانبية للنوع نفسه من المحتوى في نافذة عريضة، حيث تستطيع أن تقع بجانب المحتوى بدل أن تكون فوقه. استخدم مربع الحوار لقرار لا تستطيع المهمة أن تستمر من دونه. واستخدم درج التنقل لوجهات المنتج، لا لوحة سفلية.

عدة إجراءات من الإجراء الرئيسي. حين يأتي الإجراء الرئيسي للشاشة في بضع صور متقاربة (مستند جديد، أو مجلد، أو رفع ملف)، يفتح زر الإجراء الرئيسي لوحة سفلية نمطية تسردها. في نظام Tanrei يحل هذا محل قائمة FAB، التي لا يتضمنها النظام.

عدة إجراءات من الإجراء الرئيسي: افتح اللوحة بالزر

add

مستند

مجلد

رفع ملف

نمطية أم قياسية

الهيئة	ما هي	يُستخدم لـ
النمطية (الافتراضية)	تراكب نمطي. تنزلق اللوحة إلى الأعلى فوق حجاب يعتّم النافذة كلها. كل ما هو خارجها خامل (inert)، ويبقى التركيز في داخلها إلى أن تُغلق.	خطوة يُنهيها الشخص أو يغلقها قبل أن يعود: مشاركة، اختيار، نموذج قصير.
القياسية	منطقة تخطيط. تغطي اللوحة أسفل عنصرها الأب بلا حجاب، ويبقى المحتوى الذي فوقها قابلًا للاستخدام. المفتاح Tab ينتقل بين اللوحة والمحتوى، وخروج التركيز من اللوحة لا يغلقها أبدًا.	محتوى يستخدمه الشخص مع الشاشة معًا، مثل قائمة أماكن فوق خريطة.

تقرأ الهيئتان الرموز (tokens) نفسها: لا يفرّق بينهما إلا الحجاب والسلوك، فلا يعطيهما نظام تصميم مظهرين مختلفين.

مناطق التخطيط هي درج التنقل القياسي (ومنه هيئته المطوية)، وشريط التطبيق، واللوحة الجانبية القياسية، وكلها تقع بجانب المحتوى أو فوقه. أما اللوحة السفلية القياسية فتغطي جزءًا من عنصرها الأب، لكنها منطقة تخطيط هي الأخرى، لأن المعتبر هو السلوك: ليست نمطية، ولا ترسم حجابًا، ويبقى المحتوى قابلًا للاستخدام ما دامت مفتوحة. واللوحة التي تُغلق كلما غادرها التركيز لا يمكن استخدامها من لوحة المفاتيح إلى جانب الخريطة التي تصفها.

اللوحة القياسية لا تحرّك ما تغطيه ولا تضيف إليه حشوًا. إن وجب أن تبقى نهاية محتواك القابل للتمرير مرئية فوق اللوحة، فأضف إلى ذلك المحتوى حشوًا بمقدار الارتفاع الجزئي للوحة.

الارتفاعات

للخاصية detent قيمتان. عند partial تأخذ اللوحة حصة من المساحة التي تغطيها، وهي النصف بالرموز الافتراضية. وعند full تصل إلى هامش صغير تحت أعلى المساحة. والمساحة هي النافذة تحت هامشها العلوي (inset) للوحة النمطية، والعنصر الأب للوحة القياسية. وما دامت لوحة المفاتيح الظاهرة على الشاشة معروضة، تنتهي المساحة عند لوحة المفاتيح، فتستقر اللوحة فوقها.

لا يزيد ارتفاع اللوحة على ارتفاع محتواها. اللوحة التي يتسع محتواها ضمن الارتفاع الجزئي لها ارتفاع واحد، والخاصية detent لا تغيّر شيئًا. وما دام المحتوى أطول، فللوحة ارتفاعان، وينتقل الشخص بينهما بالسحب أو بمقبض السحب. كل انتقال كهذا يُصدر الحدث detentChange مع الارتفاع الجديد. على الويب و Compose و Flutter و React Native تحتفظ اللوحة بالارتفاع الذي اختاره الشخص إلى أن تضبط detent من جديد. وعلى SwiftUI تكتب الارتفاع في الربط detent. وضبطك detent بنفسك يحرّك اللوحة من دون إصدار أي حدث.

مقبض السحب والإيماءات

مقبض السحب هو الشريط القصير في أعلى اللوحة، في صف يبقى في مكانه حين يُمرَّر المحتوى. ومع تفعيل handle يُرسم على كل لوحة.

عنصر تحكم، حين يكون هناك مكان يُذهب إليه. ما دام للوحة ارتفاعان، فالمقبض زر اسمه قيمة handleLabel، وحالته موسَّعة (expanded) عند الارتفاع الكامل. الضغط أو المفتاح Enter أو Space ينقل اللوحة إلى ارتفاعها الآخر. وما دام للوحة ارتفاع واحد، يُرسم المقبض ساكنًا علامةً على أن اللوحة يمكن سحبها، لكن لا يمكن التركيز عليه ولا ضغطه ولا تراه التقنيات المساعدة.
هدفه. الصف كله على امتداد المقبض هو مساحة اللمس له، ولا تقل عن الحد الأدنى للهدف في كل اتجاه، وإن كان الشريط نفسه صغيرًا.
السحب. يستطيع الشخص أن يسحب اللوحة إلى الأعلى والأسفل من صف المقبض، أو من الحشو حول المحتوى، أو من المحتوى نفسه. تتبعه اللوحة حالما يتجاوز الإصبع أو المؤشر هامش اللمس (touch slop) في المنصة (8 نقاط حيث لا تسمّي المنصة قيمة)، ولا ترتفع أبدًا فوق ارتفاعها الكامل.
الإفلات. عند الإفلات، الدفعة السريعة (fling) تجعل اللوحة تستقر عند الارتفاع التالي في اتجاهها، والإفلات الأبطأ عند أقرب ارتفاع. والدفعة السريعة إفلات أسرع من الحد الأدنى لسرعة الدفع في المنصة، أو من 0.5 نقطة في الميلي ثانية حيث لا تسمّي المنصة قيمة.
السحب للإغلاق. الإفلات تحت نصف أدنى ارتفاع، أو دفعة سريعة إلى الأسفل من أدنى ارتفاع، يطلب من اللوحة أن تُغلق بالسبب drag، ما دامت قيمة dismissible هي true. تثبت اللوحة حيث تركها السحب مدة إطار واحد، ثم تنزلق خارجةً إن ضبطت open على false، أو تستقر من جديد إن لم تفعل. وما دامت قيمة dismissible هي false تستقر عند أدنى ارتفاع لها.
المحتوى الذي يُمرَّر. السحب إلى الأعلى على المحتوى يرفع اللوحة أولًا إلى الارتفاع الكامل، ثم يمرّر المحتوى. والسحب إلى الأسفل يعيد المحتوى أولًا بالتمرير إلى أعلاه، ثم يخفض اللوحة. وحيث لا تستطيع منصة أن تسلّم إيماءة واحدة من اللوحة إلى تمرير المحتوى، يحتاج الجزء الثاني إلى سحب ثانٍ (انظر الفجوات المعروفة في المنصات أدناه). ولوحة المفاتيح والتقنيات المساعدة تستطيع تمرير المحتوى عند أي من الارتفاعين.

السحب ليس الطريقة الوحيدة أبدًا. المقبض يغيّر الارتفاع بضغطة واحدة أو من لوحة المفاتيح، واللوحة النمطية تُغلق كذلك بالحجاب أو بالمفتاح Escape أو بالرجوع. أما اللوحة القياسية، والنمطية التي قيمة dismissible فيها false، فليس لها طريقة ثانية كهذه للإغلاق، فأعطها زرًّا يغلقها.

الفتح والتركيز والإغلاق

الفتح. تنزلق اللوحة إلى الأعلى من تحت الحافة السفلية. واللوحة النمطية تُظهر حجابها تدريجيًّا فوق النافذة كلها في الوقت نفسه. اللوحة التي تُعرض و open قيمتها true من الأصل تظهر في مكانها، بلا حركة. والقياسية حينئذ تترك التركيز حيث هو. أما النمطية فتنقل التركيز إلى داخلها كما لو كانت قد فُتحت للتو، لأن لا شيء خلفها يستطيع أن يأخذ التركيز بعد ذلك.
دخول التركيز. الفتح ينقل التركيز إلى العنصر الذي علّمته، أو إلى اللوحة نفسها، في الهيئتين. ينتقل التركيز حين تُفتح اللوحة، لا حين تنتهي حركتها.
حصر التركيز، في النمطية فقط. في اللوحة النمطية، المفتاح Tab من آخر عنصر يقبل التركيز يذهب إلى الأول، و Shift+Tab من الأول يذهب إلى الأخير. وتنقّل قارئ الشاشة يبقى في الداخل، والمحتوى الذي خلفها لا يُمرَّر. أما اللوحة القياسية فلا تحصر شيئًا: المفتاح Tab يمضي إلى المحتوى، وتبقى اللوحة مفتوحة.
الإغلاق. حين تُغلق اللوحة والتركيز في داخلها، يعود التركيز إلى العنصر الذي كان عليه حين فُتحت اللوحة.
التكدّس. مربع الحوار أو قائمة الخيارات أو لوحة نمطية أخرى تُفتح من لوحة نمطية تتكدّس فوقها. المفتاح Escape يغلق الأعلى فقط، وتستعيد اللوحة التركيز الذي يعيده ذلك التراكب.
الحركة. حيث تُقلَّل الحركة، تظهر اللوحة وتختفي تدريجيًّا في مكانها من دون انزلاق. وعلى Android، الذي يزيل إعدادُه كل حركة، تظهر وتختفي فورًا.

افعل

ضع مهمة اللوحة أمام العين: عنوان في أعلى المحتوى، وزر «تم» أو «إغلاق» حين لا تكون للوحة طريقة أخرى للإغلاق.
أوقف inset لقائمة تحمل صفوفها حشوها الخاص، لتصل الصفوف إلى الحواف.
اترك المقبض مفعَّلًا لكل لوحة قد يطول محتواها أكثر من ارتفاعها الجزئي، ليستطيع مستخدمو لوحة المفاتيح وأجهزة التبديل (switch) تغيير ارتفاعها.
استخدم الهيئة القياسية حين يحتاج الشخص إلى المحتوى الذي فوق اللوحة وهي مفتوحة.

لا تفعل

لا تضبط dismissible على false إلا إذا وجب على الشخص أن يُنهي مهمة اللوحة بأحد عناصر التحكم التي فيها.
لا تستخدم لوحة نمطية لقرار يجب أن يقاطع الشخص. استخدم مربع الحوار.
لا تضع تنقل المنتج في لوحة سفلية. استخدم درج التنقل أو شريط التنقل.
لا تكدّس لوحة فوق لوحة لمهمة ذات خطوات. غيّر محتوى لوحة واحدة بدل ذلك.

إمكانية الوصول

الدور: dialog
التسمية: The sheet is named by label, or by its headline where label is empty: a modal dialog while variant is modal, a region while it is standard. The headline is a heading; the close button is named by closeLabel; the divider is decorative. The drag handle, while the sheet has two heights, is a button named by handleLabel with the expanded state (true at full height); at one height it is hidden. The grip is decorative.
الحد الأدنى للهدف: تستوفي مساحة اللمس الحد الأدنى لحجم الهدف حتى لو كان الحجم المرئي أصغر. minimum 32px · pointer 44px · spacing 8px · touch 48px

لوحة المفاتيح

المفاتيح	الإجراء
`Tab / Shift+Tab`	Moves focus through the drag handle (while it is interactive), the close button (while closable is true) and the content's focusable elements, in that order. In an open modal sheet it wraps and never leaves the sheet; from a standard sheet it moves on to the content, and the sheet stays open.
`Enter` / `Space`	On the drag handle, moves the sheet to its other height (partial or full). On the close button, asks the sheet to close (close, reason close).
`Escape`	Asks an open modal sheet to close (close, reason escape) while dismissible is true; with stacked overlays, only the topmost. A standard sheet ignores it.

ملاحظات

Dragging is never the only way (WCAG 2.5.7): the drag handle changes the height with a single press or from the keyboard, and a modal sheet closes with Escape, back or a press on the scrim. A standard sheet, and a modal one whose dismissible is false, closes only by a drag, its close button or the product: set closable, or put a Close or Done button in its content.
The standard form is a layout region, although it covers the bottom of the content rather than pushing it aside: the person works in the content and in the sheet at once, so focus leaving it never closes it. The modal form is a modal overlay.
Web: the modal form is a native <dialog> opened with showModal() inside the shadow root, so the rest of the page is inert and the sheet is in the top layer; ::backdrop draws the scrim. Its cancel event (Escape) is cancelled and becomes close with the reason escape; the product then sets open to false. The standard form is a region (a <section> named by label) positioned at the bottom of its containing block. The `autofocus` attribute on a slotted element marks initial focus.
Where a platform presents the modal sheet in a window of its own (Compose's Dialog, React Native's Modal), the window's own dim and transition are switched off and Tanrei draws the scrim and the motion, so every platform draws the same color.
The sheet does not move or pad the content a standard sheet covers; a product whose content must stay visible above the sheet pads its scrolling content by the sheet's partial height.
How a state looks is a value decision of the active design system; components read the state's tokens and never compute the effect themselves.

مولَّد من specs/bottom-sheet.spec.json, tokens/sys/measure.tokens.json

ما يتكفل به المكوّن

تُعرَّف اللوحة النمطية للتقنيات المساعدة مربعَ حوار نمطيًّا اسمه قيمة label، أو قيمة headline حين تكون label فارغة. واللوحة القياسية منطقة (region) تُسمّى بالطريقة نفسها، وهي مَعلم (landmark) على الويب.
العنوان الرئيسي عنوان (heading). وزر الإغلاق زر Tanrei بأيقونة فقط تسمّيه الخاصية closeLabel، وله الهدف الأدنى وحلقة التركيز والحالات الخاصة بالزر نفسه؛ ويطلب من اللوحة أن تُغلق بالسبب close في الهيئتين، أيًّا كانت قيمة dismissible. والفاصل تحت الترويسة زخرفي.
ما دامت لوحة نمطية مفتوحة، فكل ما هو خارجها خامل ومخفي عن التقنيات المساعدة، ويبقى التركيز وتنقّل قارئ الشاشة في داخلها. واللوحة القياسية لا تجعل شيئًا خاملًا.
الفتح ينقل التركيز إلى العنصر الذي علّمته، أو إلى اللوحة. والإغلاق يعيد التركيز إلى العنصر الذي كان عليه حين فُتحت اللوحة. وهذا يصح في الهيئتين.
المفتاح Escape والرجوع في المنصة والضغط على الحجاب تطلب من اللوحة النمطية أن تُغلق، ما دامت قيمة dismissible هي true. واللوحة القياسية تتجاهل المفتاح Escape والرجوع.
مقبض السحب مقبضُ تغيير حجمٍ يُرسم دائمًا، برموز اللوحة الخاصة بها. وما دام للوحة ارتفاعان، فهو زر واحد يقبل التركيز اسمه قيمة handleLabel، وهو موسَّع عند الارتفاع الكامل. المفتاحان Enter و Space ينقلان اللوحة إلى ارتفاعها الآخر. وعند ارتفاع واحد يُخفى المقبض عن التقنيات المساعدة. أما الشريط المرسوم (grip) فمخفي دائمًا.
مساحة اللمس للمقبض لا تقل عن الحد الأدنى للهدف، وحلقة التركيز عليه تظهر لتركيز لوحة المفاتيح فقط.
يُمرَّر المحتوى داخل اللوحة، وتركيز لوحة المفاتيح والتقنيات المساعدة تستطيع تمريره عند أي من الارتفاعين.
النص الأكبر يجعل اللوحة تكبر مع محتواها، حتى الارتفاع الذي تسمح به قيمة detent، ويُمرَّر المحتوى فيما يتجاوز ذلك. والمقبض لا يتغير حجمه.
لون اللوحة يمتد تحت الهامش السفلي للنظام (inset)، ومحتواها يبقى فوق ذلك الهامش وفوق لوحة المفاتيح الظاهرة على الشاشة.
تبلّغ بنيات التنقيح (debug) عن لوحة بلا label ولا headline، وعن مقبض تفاعلي بلا handleLabel، وعن زر إغلاق بلا closeLabel، وعن لوحة بلا مقبض ولا زر إغلاق يمكن مع ذلك صرفها (ولا شيء على الشاشة يقول كيف)، وعن قيمة غير معروفة للخاصية variant أو detent أو dividerVisibility.

فجوات معروفة في المنصات:

السحب بالفأرة على المحتوى يحرّك اللوحة كما يفعل اللمس، فلا يمكن تحديد النص في لوحة بالسحب عليه إلى الأسفل ما دامت اللوحة تستطيع أن تتحرك.
لا ترسم SwiftUI و Compose و Flutter و React Native الترويسة بعد: الخصائص headline وclosable وcloseLabel وdividerVisibility، والسبب close، على الويب وحده حتى الآن.
الويب: مع اللمس، يقرر المتصفح من يأخذ الإيماءة عند بدايتها، فتسليم الإيماءة بين اللوحة وتمرير المحتوى يحتاج إلى إيماءة ثانية. أما الفأرة أو القلم فيسلّمان ضمن سحب واحد. والسحب باللمس لا يغطيه اختبار بعد. وفي Firefox تغادر اللوحة فورًا بدل أن تنزلق خارجةً، كما يفعل مربع الحوار.
ليس في SwiftUI دور لمربع الحوار ولا للمنطقة: اللوحة حاوية اسمها قيمة label، وتحمل الصفة النمطية (modal trait) ما دامت نمطية. وليس للمقبض حالة توسيع، فتقول قيمته «expanded» أو «collapsed»، بالإنجليزية فقط. ولا يستطيع SwiftUI أن ينقل التركيز إلى اللوحة نفسها حين لا يُعلَّم شيء، ولا يعيد تركيز لوحة المفاتيح إلى شيء حين تُغلق؛ وعلى iOS يعيد الغطاء النمطي تركيز VoiceOver. وعلى macOS تغطي اللوحة النمطية العرض الذي أُلحق به المُعدِّل فقط، فألحقه بجذر النافذة.
على SwiftUI في iOS: تحت الارتفاع الكامل، السحب على المحتوى يرفع اللوحة والسحب التالي يمرّر، ولا يُمرَّر المحتوى هناك، ولا حتى مع VoiceOver أو لوحة المفاتيح. والنص المجرّد في المحتوى يأخذ خط المتن من دون ارتفاع سطره، فيكون ارتفاع السطرين 40 نقطة حيث ترسم المنصات الأخرى 44.
على SwiftUI: الهامش السفلي ولوحة المفاتيح الظاهرة على الشاشة، ولوحة المفاتيح الفعلية، والمفتاح Escape وإيماءة الخروج في iOS لم تُشغَّل على جهاز ولم تُختبر بضغطها.
على Compose: تمرّر اللوحة محتواها بنفسها، فأعطها عمودًا عاديًّا، لا قائمة كسولة (lazy list). وحين تُغلق لوحة نمطية، تحتفظ نافذتها بالتركيز إلى أن تنتهي حركة الخروج. وعمليات السحب فيها متحقَّق منها تحت Robolectric فقط، لا على جهاز.
على Flutter: اللوحة القياسية حاوية مسمّاة، لا مَعلم منطقة، لأن Flutter 3.32 ليس فيه دور كهذا. واللوحة لم تُفحص بعد مع TalkBack و VoiceOver على جهاز.
لا يستطيع React Native أن يعرف أي عنصر كان عليه التركيز، فحين تُغلق اللوحة يذهب التركيز حيث تضعه المنصة، لا إلى العنصر الذي فتحها، كما في مربع الحوار ودرج التنقل. ومن دون initialFocusRef لا ينقل الفتح إلا قارئ الشاشة، إلى اللوحة.
لا يستطيع React Native أن يسلّم إيماءة واحدة من اللوحة إلى تمرير المحتوى في منتصفها، فيضيع باقي ذلك السحب والسحب التالي يمرّر. والمكوّن Modal والسحب وتفادي لوحة المفاتيح والهوامش متحقَّق منها في Jest فقط، لا على جهاز قط.
مع الإعداد cupertino، يُرسم الشريط (grip) بلون الحدّ الفاتح عند Apple، ويقيس تباينه مع اللوحة 1.8:1 في المخطط اللوني الفاتح و 2.2:1 في الداكن، دون النسبة 3:1 التي تحتاج إليها حدود عنصر التحكم. ومخططا التباين المتوسط والعالي يرفعانه إلى 4.5:1 أو أكثر. والنسبتان اللتان لا تبلغان 3:1 قياسان يُحفظان معلومةً فقط: معايير إمكانية الوصول في Tanrei لا تنطبق على إعداد جاهز يحاكي نظامًا آخر.
مع الإعداد m3-like، تحتفظ اللوحة عند الارتفاع الكامل بالهامش العلوي للنظام الافتراضي: قيمة Material تنتظر أن يغطي مرجع المطابقة اللوحة السفلية.

ما عليك فعله

أعطِ كل لوحة قيمة للخاصية label أو headline، مثل «حفظ الصورة». هي تسمّي مربع الحوار أو المنطقة.
أعطِ المقبض قيمة للخاصية handleLabel، مثل «تغيير حجم اللوحة»، بلغة منتجك.
أغلق اللوحة بنفسك: اضبط open على false استجابةً لطلب الإغلاق (الحدث close على الويب، و onClose على Compose و Flutter و React Native)، ومن زر «تم» أو «إغلاق» الخاص بك. وعلى SwiftUI تكتب اللوحة false في الربط عنك.
أعطِ اللوحة القياسية، واللوحة النمطية التي قيمة dismissible فيها false، زرًّا مرئيًّا يغلقها: زر إغلاقها (closable مع closeLabel) أو زرًّا من عندك. يجب ألا يكون السحب المخرج الوحيد.
علِّم التركيز الأولي حيث يفيد، مثل الحقل الأول في نموذج قصير.
على React Native، مرِّر initialFocusRef، وأعد التركيز بنفسك إلى العنصر الذي فتح اللوحة بعد أن تُغلق، ومرِّر هوامش النافذة (insets) إلى الخاصية insets في اللوحة أو إلى TanreiProvider.

الشيفرة المصدرية والمشكلات على GitHub