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

الفئة: التواصل
الرموز: comp.skeleton
المستوى: أساسي

نظرة عامة

Web: tanrei-skeleton; schedule
SwiftUI: TanreiSkeleton; radio_button_unchecked
Jetpack Compose: TanreiSkeleton; radio_button_unchecked
Flutter: TanreiSkeleton; radio_button_unchecked
React Native: Skeleton; radio_button_unchecked

مولَّد من docs/status/status.json, specs/skeleton.spec.json

بيانات شخص وبطاقة، في أثناء تحميلهما

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

يتألف الهيكل من منطقة ومن عناصرها النائبة (placeholders). تُقال المنطقة للتقنيات المساعدة مرة واحدة، «جارٍ تحميل المشاريع» وهي مشغولة، والعناصر النائبة لا تقول شيئًا بنفسها. وينتظر الهيكل لحظة قبل أن يُعرض، فيعرض الانتظار القصير مكانًا فارغًا بالحجم الصحيح بدل أشكال تومض.

على الويب هو <tanrei-skeleton> حول عناصرك أنت التي تحمل class="tanrei-skeleton-placeholder". والمنصات الأخرى لم تنفّذه بعد.

هيكل التحميل ومؤشر التحميل ومؤشر التقدم والحالة الفارغة

أربعة مكوّنات تجيب عن «لا شيء هنا بعد». ويحدّد أيَّها تستخدم ما يُعرف عن الانتظار وعمّا سيأتي.

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

الاستخدام

ضع الهيكل حيث سيكون المحتوى حين يبدأ الانتظار، وضع المحتوى مكانه حين ينتهي الانتظار. أعطِه قيمة label تقول ما الذي يُحمَّل. والعنصر النائب عنصر فارغ من عندك يحمل الصنف (class): عنصر <span> في أي مكان، أو <div> حيث يكون ابنًا لكتلة، مثل <div> آخر. وداخل عنوان أو فقرة يكون <span>.

<link rel="stylesheet" href="@tanrei/web/skeleton.css" />

<!-- العناصر النائبة التي هي أبناء الهيكل المباشرون تُرصّ واحدًا تحت الآخر، وبينها فجوة. -->
<tanrei-skeleton label="جارٍ تحميل المشروع">
  <span class="tanrei-skeleton-placeholder" data-shape="block" style="block-size: 160px"></span>
  <span class="tanrei-skeleton-placeholder" style="inline-size: 12.5rem"></span>
  <span class="tanrei-skeleton-placeholder" data-lines="3"></span>
</tanrei-skeleton>

<!-- كل ما زاد على ذلك تخطيطك أنت، وفيه العناصر النائبة، حيث سيكون المحتوى. -->
<tanrei-skeleton label="جارٍ تحميل بيانات الكاتب">
  <div class="byline">
    <span class="tanrei-skeleton-placeholder" data-shape="circle" style="block-size: 40px"></span>
    <div>
      <h3><span class="tanrei-skeleton-placeholder" style="inline-size: 10rem"></span></h3>
      <p><span class="tanrei-skeleton-placeholder" data-lines="2"></span></p>
    </div>
  </div>
</tanrei-skeleton>

<!-- جزء من الظهور الأول للصفحة، يكتبه الخادم: يُعرض فورًا، ويكون صحيحًا قبل أي سكربت. -->
<tanrei-skeleton show-delay="0" role="progressbar" aria-busy="true" aria-label="جارٍ تحميل لوحة المعلومات">
  …
</tanrei-skeleton>
<noscript>تحتاج لوحة المعلومات إلى JavaScript.</noscript>

<script type="module">
  import '@tanrei/web/components/skeleton';
</script>

import { Skeleton } from '@tanrei/react';
import '@tanrei/web/skeleton.css';

{project ? (
  <ProjectCard project={project} />
) : (
  <Skeleton label="جارٍ تحميل المشروع">
    <span className="tanrei-skeleton-placeholder" data-shape="block" style={{ blockSize: 160 }} />
    <span className="tanrei-skeleton-placeholder" style={{ inlineSize: '12.5rem' }} />
    <span className="tanrei-skeleton-placeholder" data-lines={3} />
  </Skeleton>
)}

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

المواصفات

الأشكال الثلاثة: نص، وكتلة، ودائرة

العنصر النائب للنص يأخذ نمط النص في المكان الذي يقف فيه: في عنوان، وفي فقرة

البنية

الجزء	الوصف
1 `container`	The region that stands in the content's place: a block as wide as the place it stands in and as tall as what it holds, with no fill, no edge, no padding and no elevation. It is what assistive technology is told about, once, and it carries no state: a skeleton takes no input.
2 `placeholder`	A quiet filled shape in the place of one piece of the content: one or more lines of text, a block (a picture, a card, a control) or a circle (a person's picture, a round mark). It has the size the content will have and says nothing by itself.

الخصائص

الخاصية	النوع	القيمة الافتراضية	الوصف
`label`	`string`	`""`	What is loading, in the product's language ("Loading projects"): the name assistive technology is given for the whole skeleton, once. Never drawn. Left empty, it reads the product's words; Tanrei ships none of its own. Not read while decorative is true.
`decorative`	`boolean`	`false`	Whether something else already says this wait: a loading indicator beside it, a status text, a region the product itself exposes as busy and names. True keeps the whole skeleton from assistive technology, so that one wait is said once; it changes nothing that is drawn.
`showDelay`	`number`	`null`	How long, in milliseconds, this skeleton waits from the moment it is inserted before it is drawn and exposed to assistive technology; 0 shows it as it is inserted. Null takes comp.skeleton.motion.show-delay, the system's answer for every skeleton. Set it to 0 where the skeleton is part of the first presentation of a page or a view, which has nothing else to show; leave it where content is fetched in a view that is already there.

العناصر

أنواع العناصر التي يكررها المكوّن. يسرد كل نموذج اختبار عناصره بالترتيب، وتسمّي كل منصة كل نوع بأسلوبها.

`placeholder`

One shape in the place of one piece of the content: lines of text, a block or a circle.

الخاصية	النوع	القيمة الافتراضية	الوصف
`shape`	`text` \| `block` \| `circle`	`"text"`	What the placeholder stands for. Text is one or more lines of the text style in effect where it stands. Block is a box: a picture, a card, a control, a row. Circle is a round box: a person's picture, a round mark.
`lines`	`number`	`1`	For text: how many lines the text will take, a whole number of 1 or more. The placeholder is exactly that many line boxes high. Not read for a block or a circle.
`inlineSize`	`number`	`null`	The placeholder's size along the line, in points. Null leaves it to the layout: the whole inline size of its place for text and for a block, the side of the square for a circle. A size the product's own layout gives the placeholder (a share of a row, a track of a grid) is used as it is and needs no prop.
`blockSize`	`number`	`null`	The placeholder's size across the line, in points: the height of a block, and the side of a circle. Null is one line of the text style in effect, or the size the product's own layout gives. Not read for text, whose height is its lines.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
العنصر	`span`	`TanreiSkeletonPlaceholder`	`TanreiSkeletonPlaceholder`	`TanreiSkeletonPlaceholder`	`SkeletonPlaceholder`
`shape` · الخاصية	`data-shape`	`shape`	`shape`	`shape`	`shape`
`lines` · الخاصية	`data-lines`	`lines`	`lines`	`lines`	`lines`
`inlineSize` · الخاصية	`inline-size`	`width`	`width`	`width`	`width`
`blockSize` · الخاصية	`block-size`	`height`	`height`	`height`	`height`
ملاحظات	The product's own element with `class="tanrei-skeleton-placeholder"` — a `<span>`, or a `<div>` where it is a block's child — empty, so that it has nothing to expose. `data-shape` is `text` (the default, and what a missing or unknown value draws), `block` or `circle`; `data-lines` the number of lines. `inlineSize` and `blockSize` are the CSS properties `inline-size` and `block-size` on the element (in its `style`, or by a rule of the product's): a number of the spec is that many CSS pixels, and any other length, a percentage or an `aspect-ratio` the product writes there is a size its layout gives (SKL-4). The text style is the inherited `font`, so the placeholder goes where the text will be — inside the heading, the paragraph or the cell — and is `1lh` high a line.	`TanreiSkeletonPlaceholder(.text, lines: 3)`, `TanreiSkeletonPlaceholder(.circle, height: 40)`; a `.frame` or an `.aspectRatio` the product applies is a size its layout gives. The text style is the font of the environment (`.font(...)` on an ancestor), measured with the reader's text size.	`TanreiSkeletonPlaceholder(shape, lines, width, height, modifier)` inside the skeleton's scope; a size from `modifier` is a size the layout gives. The text style is `LocalTextStyle`, measured with the font scale.	`TanreiSkeletonPlaceholder.text(lines: 3)`, `.block(height: 160)`, `.circle(size: 40)`; inside an `Expanded`, a `SizedBox` or an `AspectRatio` it takes that size. The text style is `DefaultTextStyle`, with `MediaQuery.textScalerOf`.	`<SkeletonPlaceholder shape="text" lines={3} />`; `style` gives a size the layout gives (`flex`, a percentage, `aspectRatio`). React Native has no inherited text style, so the product passes one of Tanrei's text styles as `textStyle`, and the body style is used where it gives none (SKL-3).

الحالات

السلوك

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

المعرّف	المتطلب
`SKL-1`	THE skeleton SHALL lay itself out as a block that takes the whole inline size of the place it stands in and is as tall as what it holds: it SHALL lay out the placeholders that stand directly in it in one column, in the order given, each at its own size and at the start edge, comp.skeleton.container.gap apart, and SHALL leave placeholders that stand inside a layout of the product's own (a row, a grid, a card's own structure) to that layout, changing neither their place nor their size. THE skeleton SHALL draw no fill, no edge and no elevation, SHALL bring no padding and no outer space of its own, SHALL set no height of its own and SHALL NOT scroll or clip.
`SKL-2`	THE skeleton SHALL draw each placeholder as one box, or for text one box a line, filled with comp.skeleton.placeholder.color, with the corners of its shape (comp.skeleton.placeholder.shape.text for each line of text, comp.skeleton.placeholder.shape.block for a block, comp.skeleton.placeholder.shape.circle for a circle), never larger than half the box's smaller side, and with no edge, no elevation, no shadow and nothing inside it. THE skeleton SHALL draw nothing else: no glyph, no mark, no text, and never its label.
`SKL-3`	WHILE a placeholder's shape is text THE skeleton SHALL size it by the text style in effect where it stands — the style text placed there would be drawn in, and sys.typescale.body where the platform has no such style and the product gave none: the placeholder SHALL be exactly as tall as lines line boxes of that style, and in each line box THE skeleton SHALL draw one bar as tall as the style's font size, centred in the line box. Each bar SHALL be as long as the placeholder's inline size (inlineSize, else the whole inline size of its place), except that WHILE lines is 2 or more the last bar SHALL be comp.skeleton.placeholder.last-line-inline-size of that size, from the start edge. The placeholder SHALL NOT read blockSize.
`SKL-4`	WHILE a placeholder's shape is block THE skeleton SHALL draw one box whose inline size is inlineSize, else the size the product's layout gives it, else the whole inline size of its place, and whose block size is blockSize, else the size the product's layout gives it (a stretched cell, a ratio the product set), else one line box of the text style in effect where it stands (SKL-3). The block SHALL NOT read lines.
`SKL-5`	WHILE a placeholder's shape is circle THE skeleton SHALL draw one square box whose side is blockSize, else inlineSize, else the size the product's layout gives it, else one line box of the text style in effect where it stands (SKL-3), and SHALL draw it round. WHERE the place is narrower than the side THE skeleton SHALL make the square as large as the place allows and keep it square: a circle is never drawn as an oval. The circle SHALL NOT read lines.
`SKL-6`	THE skeleton SHALL keep the box of every placeholder, and so its own, unchanged from the moment it is inserted to the moment it is removed — while it waits to be shown (SKL-7), while it is shown and while it stirs (SKL-12) — and SHALL NOT guess what is coming: it draws the placeholders the product gave, in the sizes the product gave, and nothing of the content. That the content takes the box its placeholders held is the product's to arrange, by placing each placeholder where its content will be and as that content will be placed.
`SKL-7`	WHEN the skeleton is inserted into a view THE skeleton SHALL wait for its show delay (SKL-9) before it is shown, and WHILE it waits SHALL draw nothing, SHALL run no animation, SHALL be absent from the accessibility tree (no role, no name, no busy state), and SHALL still take the box it takes when shown (SKL-1 to SKL-5), so that nothing around it moves when it appears; a show delay of 0 SHALL show it as it is inserted.
`SKL-8`	WHEN its show delay ends THE skeleton SHALL be shown: it SHALL draw its placeholders at once, at their resting opacity and without an entrance of their own, expose itself as SKL-15 says without announcing itself (SKL-16), and start the animation of SKL-12 at the beginning of a pulse.
`SKL-9`	THE skeleton SHALL take its show delay from showDelay, a number of milliseconds used as given (the motion dial does not scale it). WHILE showDelay is null THE skeleton SHALL use comp.skeleton.motion.show-delay in its place; IF showDelay is negative or not a finite number THE skeleton SHALL use the token likewise and in debug builds report the value it ignored.
`SKL-10`	THE skeleton SHALL treat its show delay as a waiting time, not motion: WHERE motion is reduced it SHALL keep it, on every platform, including one whose reduced-motion setting removes every animation; and it SHALL keep counting it while the skeleton cannot be seen (scrolled out of view, in a hidden view), because the delay measures the wait, not what is seen.
`SKL-11`	WHEN the skeleton is removed before its show delay ends THE skeleton SHALL have drawn, exposed and announced nothing, and WHEN it is removed while shown it SHALL disappear at once, without a motion of its own: how the content enters is the content's. WHEN it is inserted again THE skeleton SHALL wait its whole show delay again; hiding it without removing it (a hidden ancestor, scrolling) SHALL neither restart nor pause the delay (SKL-10). WHEN showDelay changes while the delay is running THE skeleton SHALL finish the running delay as it started and use the new value from its next insertion.
`SKL-12`	WHILE the skeleton is shown THE skeleton SHALL stir as comp.skeleton.motion.animation names, without end. pulse SHALL ease the opacity of every placeholder's fill from its resting value to comp.skeleton.placeholder.dim-opacity of it over comp.skeleton.motion.dim-duration with comp.skeleton.motion.dim-easing and back over the same time on the same curve, every placeholder of the skeleton in step with the others. wave SHALL put each point of each placeholder through the same fall and return, each point later than the skeleton's start edge by a share of one whole pulse equal to its distance from that edge over the skeleton's inline size, so that one dimmer band travels from the start edge to the end edge through all the placeholders as through one surface. none SHALL leave the placeholders still at their resting opacity. In every manner THE skeleton SHALL change the fill's opacity only: no box moves, grows or changes shape, and nothing brighter than the resting fill is drawn.
`SKL-13`	WHERE reduced motion is requested THE skeleton SHALL NOT stir, whatever comp.skeleton.motion.animation names: it SHALL draw its placeholders still, at their resting opacity. The shapes, the label and the busy state still say that the place is waiting, and the show delay is kept (SKL-10).
`SKL-14`	WHILE the skeleton is not visible (scrolled out of view, in a hidden view, or in an app in the background) THE skeleton SHALL NOT run its animation, and SHALL resume it when it becomes visible.
`SKL-15`	WHILE the skeleton is shown and decorative is false THE skeleton SHALL expose itself to assistive technology as one element: the progressbar role with label as its name, no current value, and the platform's busy or indeterminate state. THE skeleton SHALL expose nothing of what it holds: no placeholder, no count of placeholders or of lines, and nothing of a layout the product placed in it.
`SKL-16`	THE skeleton SHALL NOT be focusable and SHALL NOT be a stop in the focus order, SHALL NOT announce itself when it is shown, when it changes or when it is removed, and SHALL NOT move keyboard or screen-reader focus. Saying that the content has arrived, where the product wants it said, is the product's, as it is beside a loading indicator.
`SKL-17`	WHILE decorative is true THE skeleton SHALL keep itself and everything it holds from assistive technology — no role, no name, no busy state — and SHALL draw, wait and stir as it otherwise would. A skeleton that stands inside another skeleton SHALL behave as decorative whatever its prop says: one wait is said once.
`SKL-18`	THE skeleton SHALL take its name from label, and WHILE label is empty from the product's words (the key loadingLabel); it has no words of its own in any language. WHILE both are empty and decorative is false THE skeleton SHALL still be drawn and still be exposed as SKL-15 says, without a name, and in debug builds report once that a skeleton has no label, naming the prop.
`SKL-19`	THE skeleton SHALL NOT take pointer, touch or keyboard input and SHALL NOT change anything it draws under a pointer, a press or focus: it has no hovered, focused, pressed, selected or disabled state and draws no state layer and no focus indicator. Whatever the product places in it besides placeholders SHALL be drawn as given, SHALL take no input and no focus, and SHALL NOT be exposed to assistive technology: a skeleton holds the shape of content, never content.
`SKL-20`	WHERE the platform draws with a person's own forced colors (the web's forced-colors mode, and a platform's equivalent where it has one) THE skeleton SHALL draw each placeholder, and each line of a text placeholder, as the outline of its shape, sys.border.hairline wide and inside its box, in the platform's text color, with no fill, and SHALL NOT stir: a fill is not drawn in that mode, and a placeholder that vanished would leave a blank place that says nothing.
`SKL-21`	WHILE the text size is enlarged THE skeleton SHALL grow its text placeholders with the text style they stand in, and every placeholder whose size is a line box with them, so that the skeleton still holds the box the enlarged content will take; it SHALL keep a size given as inlineSize or blockSize as given, SHALL never draw a placeholder wider than its place, SHALL keep its gap, and SHALL need no horizontal scrolling at a width of 320 points with text at 200 %.
`SKL-22`	WHERE the layout direction is right-to-left THE skeleton SHALL place its placeholders at the right edge, begin the shortened last bar of a text placeholder (SKL-3) and every placeholder narrower than its place at the right, and run a wave from the right edge to the left; a block and a circle are otherwise drawn as they are in a left-to-right layout.
`SKL-23`	THE skeleton 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 skeleton is shown THE skeleton SHALL draw itself for the new direction at once, without a motion of its own, keeping its place in its animation.
`SKL-24`	WHEN label, decorative or a placeholder's shape, lines, inlineSize or blockSize changes, or a placeholder is added or removed, while the skeleton waits or is shown THE skeleton SHALL draw and expose the new value at once, without a motion, without an announcement, and without restarting its show delay or its animation. THE skeleton SHALL neither show nor hide itself and SHALL NOT know when the content arrives: the product puts the skeleton in the content's place when the wait starts and takes it away when the wait ends, whatever the wait ends in.
`SKL-25`	WHEN a placeholder's shape names a value this spec does not have THE skeleton SHALL draw it as text; IF its lines is less than 1 or not a finite number THE skeleton SHALL use 1, and SHALL use the whole number below a lines that is not whole; IF its inlineSize or blockSize is negative or not a finite number THE skeleton SHALL treat it as null; WHEN comp.skeleton.motion.animation names a manner the skeleton does not know THE skeleton SHALL pulse. In each case it SHALL report the value it ignored in debug builds.
`SKL-26`	IF the skeleton holds no placeholder THE skeleton SHALL draw nothing, take no space and expose nothing, and in debug builds report that a skeleton holds no placeholder: a busy region with no shape in it is a blank place, and a wait whose shape is not known is a loading indicator's.

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

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

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
المكوّن	`tanrei-skeleton`	`TanreiSkeleton`	`TanreiSkeleton`	`TanreiSkeleton`	`Skeleton`
`label` · الخاصية	`label`	`label`	`label`	`label`	`label`
`decorative` · الخاصية	`decorative`	`isDecorative`	`decorative`	`decorative`	`decorative`
`showDelay` · الخاصية	`showDelay`	`showDelay`	`showDelay`	`showDelay`	`showDelay`
ملاحظات	Form: the light-DOM form a component around the product's own elements takes. `<tanrei-skeleton label="Loading projects">` is a custom element with no shadow root around the product's own layout and its placeholders, and one stylesheet, `@tanrei/web/skeleton.css`, draws everything — the column and its gap, the placeholders, the show delay, the animation, reduced motion and forced colors — with selectors that start at `tanrei-skeleton` and at the placeholder's class, wrapped in `:where()`. This is the point of the form: a skeleton is what a page shows before its script has run, so it must be whole before the element is defined and where script never runs; a shadow root would draw nothing until the module arrived, which is the wait the skeleton is for. The show delay without script is an animation with a delay (`animation: <appear> 0s linear var(--tanrei-comp-skeleton-motion-show-delay) both` from `visibility: hidden`), so the box is held and nothing is drawn or exposed until it ends (SKL-7); the `show-delay` attribute sets a custom property the stylesheet reads, and attribute selectors cover `show-delay="0"` before definition. pulse is an opacity animation of the placeholders with `animation-direction: alternate`; wave is one mask or background gradient sized to the host and positioned per placeholder (`background-attachment` does not serve here; the element measures the placeholders' offsets and writes them as custom properties once defined, and before definition a wave is drawn as a pulse — say so in the docs); `prefers-reduced-motion: reduce` removes the animation and keeps the delay (SKL-10, SKL-13); `forced-colors: active` replaces the fill with an outline in `CanvasText` (SKL-20). The choice of manner reaches the stylesheet as the custom property that carries its name, read by a style query or, where those are missing, by the element. A text placeholder of several lines is one element `calc(var(--lines) * 1lh)` high whose bars are drawn as backgrounds; whether the bars can have eased corners and a shortened last bar from CSS alone in three engines, or need the element to write one child a line once defined, is the build's to find out — the box must be the same either way. What the element adds once defined, and only then: `role="progressbar"`, `aria-busy="true"` and `aria-label` on the host when the delay ends, unless `decorative` or nested (then `aria-hidden="true"`); `inert` on the host, so that nothing inside takes focus or is read (SKL-19); pausing the animation while the host is not visible (SKL-14); the debug reports. A page that must be right before its script runs, or without it, writes `role`, `aria-busy` and `aria-label` on the element itself, and the element leaves what it finds; the placeholders are empty elements and expose nothing either way. The React wrapper renders the element around its children. Where script never runs the skeleton never ends unless the server replaces it: a product whose content arrives only by script gives the content, or a sentence, in `<noscript>`.	Proposed spelling, for the platform's agent to settle. `TanreiSkeleton("Loading projects", isDecorative:, showDelay:) { … }`, a view builder that holds placeholders directly (stacked, SKL-1) or inside the product's own stacks and grids. Not the platform's own redaction of a view, whose look is the platform's and which needs the real view to exist: the same idea drawn from Tanrei's tokens. Exposed as one accessibility element with the label, the progress trait's indeterminate form (`updatesFrequently` is not set) and its children ignored; `accessibilityHidden` while decorative or waiting. `accessibilityReduceMotion` stops the animation; the show delay is a task, not an animation. Not built on this platform yet: the stage color a fixture's surface names, which the text-lines-on-container-highest fixture draws on.	`TanreiSkeleton(label, decorative, showDelay) { … }`, a column scope. `clearAndSetSemantics { contentDescription = label; progressBarRangeInfo = ProgressBarRangeInfo.Indeterminate }` once shown, and `clearAndSetSemantics { }` with `invisibleToUser()` while decorative or waiting. The animation reads the system's animator duration scale: where it is 0 the placeholders are still, and the show delay is a coroutine delay that the scale does not shorten (SKL-10). Not built on this platform yet: the stage color a fixture's surface names, which the text-lines-on-container-highest fixture draws on.	`TanreiSkeleton(label: …, decorative:, showDelay:, children: […])`, or `child:` for a layout of the product's own. `Semantics(label: label, excludeSemantics: true)` with the progress indicator's indeterminate semantics once shown; `ExcludeSemantics` and `IgnorePointer` around everything it holds. `MediaQuery.disableAnimationsOf` stops the animation; the show delay is a `Timer`. Not built on this platform yet: the stage color a fixture's surface names, which the text-lines-on-container-highest fixture draws on.	`<Skeleton label="Loading projects">…</Skeleton>`. `accessible`, `accessibilityRole="progressbar"`, `accessibilityLabel` and `accessibilityState={{ busy: true }}` once shown; `importantForAccessibility="no-hide-descendants"` and `accessibilityElementsHidden` while decorative or waiting; `pointerEvents="none"`. `AccessibilityInfo.isReduceMotionEnabled` stops the animation. Follows the app's direction where an ancestor's is not known. Not built on this platform yet: the stage color a fixture's surface names, which the text-lines-on-container-highest fixture draws on.

الرموز

الرمز	يشير إلى	القيمة المحلولة (فاتح)
`--tanrei-comp-skeleton-container-gap`	`sys.space.space100`	8px
`--tanrei-comp-skeleton-motion-animation`	—	0
`--tanrei-comp-skeleton-motion-dim-duration`	`sys.motion.duration.extra-long4`	1000ms
`--tanrei-comp-skeleton-motion-dim-easing`	`sys.motion.easing.standard`	cubic-bezier(0.2, 0, 0, 1)
`--tanrei-comp-skeleton-motion-show-delay`	`sys.motion.role.show-delay`	300ms
`--tanrei-comp-skeleton-placeholder-color`	`sys.color.surface-variant`	#eeeeee
`--tanrei-comp-skeleton-placeholder-dim-opacity`	—	0.5
`--tanrei-comp-skeleton-placeholder-last-line-inline-size`	—	0.6
`--tanrei-comp-skeleton-placeholder-shape-block`	`sys.shape.corner.medium`	8px
`--tanrei-comp-skeleton-placeholder-shape-circle`	`sys.shape.corner.full`	9999px
`--tanrei-comp-skeleton-placeholder-shape-text`	`sys.shape.corner.extra-small`	3px

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

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

text

label: Loading the title showDelay: 0 items: 1

text-lines

label: Loading the article showDelay: 0 items: 1

text-lines-on-container-highest

label: Loading the article showDelay: 0 items: 1

text-short

label: Loading the name showDelay: 0 items: 1

block

label: Loading the picture showDelay: 0 items: 1

block-sized

label: Loading the action showDelay: 0 items: 1

block-line

label: Loading the row showDelay: 0 items: 1

circle

label: Loading the person showDelay: 0 items: 1

circle-line

label: Loading the mark showDelay: 0 items: 1

person

label: Loading the author showDelay: 0 items: 3

card

label: Loading the project showDelay: 0 items: 4

decorative

decorative: true showDelay: 0 items: 1

waiting

label: Loading the article items: 1

long-text

label: Loading the whole of the release notes f… showDelay: 0 items: 2

text-lines-rtl

label: جارٍ تحميل المقال showDelay: 0 direction: rtl items: 1

person-rtl

label: جارٍ تحميل الكاتب showDelay: 0 direction: rtl items: 3

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

الإرشادات

يحجز الصندوق

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

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

العنصر النائب للنص يوضع داخل العنوان أو الفقرة أو الخلية التي سيكون فيها النص. يأخذ نمط ذلك النص، وارتفاعه ارتفاع ذلك العدد من أسطره تمامًا، وكذلك حين يكبّر القارئ النص.
قل كم سطرًا سيأخذ النص بالخاصية data-lines. ستصيب بقدر ما يكون محتواك منتظمًا. والهيكل الذي ينقصه سطر واحد يحرّك الصفحة سطرًا واحدًا، وهذا يبقى أقل مما يحرّكها مكان فارغ.
أعطِ الكتلة حجم الصورة أو عنصر التحكم: رقمًا، أو نسبة، أو الحجم الذي يعطيها إياه تخطيطك. والدائرة تأخذ رقمًا واحدًا، هو ضلعها.

اضغط «تحميل»: يحجز الهيكل المكان ثانيتين ونصف الثانية، ثم يأخذ المحتوى صندوقه

تحميل

الرموز في ثلاثة مستويات

رموز المرجع تحمل القيم الخام. رموز النظام تسمّي الغرض من القيمة. رموز المكوّن تربط جزءًا واحدًا بأحدها.

هذا السطر يقع تحت المقالة، ولا يتحرك.

الأشكال

`data-shape`	ينوب عن	حجمه
`text` (الافتراضي)	سطر أو أكثر من النص.	صناديق أسطر عددها `data-lines` من نمط النص الذي يقف فيه. كل سطر شريط ارتفاعه حجم الخط. وآخر الأسطر، حين تتعدد، أقصر، فقلّما تنتهي فقرة عند الحافة. والخاصية `inline-size` تحدّد طول الأشرطة.
`block`	صورة، أو بطاقة، أو عنصر تحكم، أو صف.	الخاصيتان `inline-size` و `block-size`، أو الحجم الذي يعطيه إياه تخطيطك: خلية ممدودة، أو `aspect-ratio`. ومن دون حجم يكون بعرض مكانه وبارتفاع سطر واحد.
`circle`	صورة شخص، أو علامة مستديرة.	ضلع واحد: `block-size`، أو `inline-size`. ومن دون حجم يكون بارتفاع سطر واحد.

العناصر النائبة التي هي أبناء الهيكل المباشرون تُرصّ واحدًا تحت الآخر، وبينها فجوة مقدارها 8. وكل ما عدا ذلك، كدائرة بجانب سطرين أو شبكة من البطاقات، تخطيطك أنت داخل الهيكل. ليس هناك هيكل جاهز لبطاقة أو لقائمة: شاشاتك لك، ولا يعرفها أحد سواك.

في صف من عندك، يحتاج العنصر النائب للنص أو الكتلة إلى عرض من ذلك الصف، كما سيحتاج المحتوى: flex: 1، أو مسار في شبكة، أو قيمة inline-size.

انتظار واحد، إشارة واحدة

ضع كل العناصر النائبة لمنطقة واحدة في هيكل واحد، له قيمة label واحدة. والهيكل الذي داخل هيكل آخر صامت.

حيث يقول شيء آخر الانتظار نفسه أصلًا، كمؤشر تحميل في سطر حالة، أو نص حالة، أو منطقة تعلّمها أنت بأنها مشغولة وتسمّيها، عيِّن decorative. يُرسم الهيكل عندئذ كما هو ويُحجب عن التقنيات المساعدة، فلا يُقرأ الانتظار مرتين.

سطر حالة يقول الانتظار أصلًا، فالعناصر النائبة التي تحته زخرفية

جارٍ البحث…

ينتظر قبل أن يُعرض

من لحظة إدراجه، ينتظر الهيكل 300 ms قبل أن يُرسم ويُعرَض للتقنيات المساعدة، وصندوقه محجوز من البداية. والانتظار الذي ينتهي قبل ذلك يعرض مكانًا فارغًا كان بالحجم الصحيح من أوله.

أدرِج الهيكل حين يبدأ الانتظار وأزِله حين يصل المحتوى. تُحسب المهلة من الإدراج. وإخفاء الهيكل لا يبدؤها من جديد.
عيِّن show-delay="0" حيث يكون الهيكل جزءًا من الظهور الأول لصفحة أو لعرض، وليس فيهما حينئذ شيء آخر يُرى.
المهلة انتظار لا حركة: تبقى عند تقليل الحركة.

ينتهي دائمًا إلى شيء

ضع مكان الهيكل المحتوى، أو حالة فارغة حيث لم يأتِ شيء، أو تنويهًا بحالة الخطأ حيث أخفق التحميل. لا يتوقف من تلقاء نفسه بعد مدة أبدًا: أنت من يعرف متى يُكفّ عن الانتظار.

الهيكل لا يُعلِن أن المحتوى وصل. وحيث ينبغي أن يُسمع الوصول، كنتائج جاءت جوابًا عن بحث أو قائمة طُلبت، فقله عبر منطقتك الحيّة (live region) أو عبر نص الحالة في المكوّن الذي طلب. والعرض الذي يُفتح بمحتواه لا يحتاج إلى إعلان.

الحركة

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

يستطيع نظام التصميم أن يختار طريقة أخرى لكل هياكله بالرمز (token) comp.skeleton.motion.animation: القيمة pulse، أو wave (الخفوت نفسه، يعبر الهيكل كله من حافة بدايته إلى حافة نهايته شريطًا واحدًا)، أو none. وليس هناك إعداد لهيكل بعينه.

عند تقليل الحركة تسكن العناصر النائبة. الأشكال والتسمية وحالة الانشغال تقول أصلًا إن المكان ينتظر. وما دام الهيكل لا يُرى لا تجري حركته.

على الويب، قبل السكربت

هيكل التحميل هو ما تعرضه الصفحة قبل أن يعمل سكربتها، ولذلك يرسمه الملف @tanrei/web/skeleton.css كاملًا من دون العنصر. وأشياء قليلة تحتاج إلى العنصر، وتختلف إلى أن يُعرَّف أو حيث لا يعمل سكربت أبدًا:

الدور والاسم. الصفحة التي يجب أن تكون صحيحة قبل أن يعمل سكربتها تكتب role="progressbar" و aria-busy="true" و aria-label على العنصر نفسه، والعنصر يترك ما يجده.
قيمة للخاصية show-delay غير 0. ورقة الأنماط تنتظر مهلة نظام التصميم.
أكثر من 24 سطرًا في عنصر نائب واحد للنص.
الطريقة wave، وتُرسم نبضًا.
الهيكل الذي داخل عرض مخفي يبدأ انتظاره حين يظهر ذلك العرض.

حيث لا يعمل سكربت أبدًا، لا ينتهي الهيكل ما لم يضع الخادم شيئًا مكانه. والمحتوى الذي لا يصل إلا بسكربت يحتاج إلى عنصر <noscript> بجانب هيكله.

افعل

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

لا تفعل

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

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

الدور: progressbar
التسمية: label is the accessible name of the whole skeleton: what is loading. Once shown, the skeleton is one element — a progressbar with no value, in the platform's busy (indeterminate) state — and its placeholders are hidden; during its show delay, and while decorative is true, it is not exposed at all. It is exposed exactly as a loading indicator is, because it says the same thing: something is loading here.
الحد الأدنى للهدف: تستوفي مساحة اللمس الحد الأدنى لحجم الهدف حتى لو كان الحجم المرئي أصغر. minimum 32px · pointer 44px · spacing 8px · touch 48px

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

المفاتيح	الإجراء

ملاحظات

Not interactive: the skeleton takes no input and is never focusable (SKL-16, SKL-19), so there is no target of its own to size and minimumTarget holds trivially.
One wait, said once. Every placeholder of a region belongs to one skeleton with one label; a skeleton inside another is silent (SKL-17). Where the same wait is already said — a loading indicator in a status row, a status text, a region the product itself marks busy and names — set decorative, or the wait is read twice.
The skeleton does not announce that it appeared, and does not announce that the content arrived (SKL-16): it is removed with its busy state. Where arrival should be heard (results in answer to a search, a list that was asked for), the product says so through its own live region or the status text of the component that asked; a view that simply opens with its content needs no announcement.
A wait shorter than the show delay shows and exposes nothing (SKL-7): no shapes that flash for a sighted person, and no progressbar that appears and vanishes for a screen-reader user.
Nothing a person should read or use goes inside a skeleton: what it holds is kept from input and from assistive technology (SKL-19). A heading that is already known, a button that already works, stand outside it.
The fill is decoration, held to no contrast ratio: comp.skeleton.placeholder.color is a low-emphasis fill, and in the default system it has the tone of the highest container step, so a placeholder on a surface of that tone is hard to see. The wait is never said by the fill alone: the label says it to assistive technology, and forced colors draw every placeholder as an outline (SKL-20).
Motion: a pulse dims the fill by half and returns in 2 seconds in the default system, far below the three-per-second flash threshold; nothing moves and nothing brightens. Reduced motion stops it entirely (SKL-13): a large region that pulses is more than a small mark that does, and the shapes already say that the place is waiting.
A skeleton that never ends tells a lie. The product replaces it with the content, with an empty state where nothing came, or with a callout of the error status where loading failed, and sets its own limit on the wait; a task that takes many seconds, or whose progress can be measured, is a progress indicator's.
Text size, text spacing and reflow: SKL-21. A text placeholder follows the text style it stands in, so it grows with the reader's text size; a size given in points does not.

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

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

بعد أن يُعرض، يكون الهيكل عنصرًا واحدًا للتقنيات المساعدة: شريط تقدم (progress bar) بلا قيمة، مشغولًا، اسمه قيمة label. يُعرَض للتقنيات المساعدة كما يُعرَض مؤشر التحميل، لأنه يقول الشيء نفسه.
عناصره النائبة وعددها وأسطرها لا تُعرَض للتقنيات المساعدة، ولا يُعرَض تخطيط تضعه فيه.
ما دام ينتظر أن يُعرض لا يُعرَض للتقنيات المساعدة إطلاقًا. الانتظار الأقصر من المهلة لا يعرض شريط تقدم يظهر ثم يختفي.
مع decorative، أو داخل هيكل آخر، يُحجب عن التقنيات المساعدة.
لا يقبل التركيز وليس موضع توقف في ترتيب التركيز، ولا شيء بداخله كذلك. لا يُعلِن نفسه ولا ينقل التركيز أبدًا.
عند تقليل الحركة يسكن. وتبقى المهلة.
في الألوان المفروضة يُرسم كل عنصر نائب، وكل سطر نص، حدًّا لشكله بلون النص. التعبئة لا تُرسم في هذا الوضع، والعنصر النائب الذي يختفي كان سيترك مكانًا فارغًا.
مع النص المكبَّر يكبر العنصر النائب للنص مع نمط نصه، فيبقى الهيكل حاجزًا الصندوق الذي يأخذه المحتوى المكبَّر. والحجم المعطى رقمًا يبقى كما هو. لا شيء أعرض من مكانه؛ عند عرض 320 ونص مكبَّر إلى 200% لا يُمرَّر شيء أفقيًّا.
في التخطيط من اليمين إلى اليسار تقف العناصر النائبة في اليمين، ويبدأ السطر الأخير القصير من اليمين، وتجري الموجة من اليمين إلى اليسار.
يُبلَّغ في بنيات التنقيح عن شكل غير معروف، وعن عدد أسطر أو حجم لا يمكن استخدامه، وعن هيكل بلا عنصر نائب، وعن هيكل بلا تسمية.

ما عليك فعله

أعطِ قيمة label بلغة الصفحة تقول ما الذي يُحمَّل («جارٍ تحميل المشاريع»)، أو أعطِ الكلمة مرة واحدة لكل الهياكل بالاستدعاء setWords({ loadingLabel: … }). المكوّن لا يقدّم كلمات من عنده.
عيِّن decorative حيث يقول شيء آخر الانتظار أصلًا.
قل إن المحتوى وصل حيث يكون ذلك خبرًا.
لا تدع هيكلًا يقف إلى الأبد. ضع مكانه المحتوى، أو حالة فارغة، أو خطأ.
التعبئة زخرفة ولا تُلزَم بأي نسبة تباين. وهي صعبة الرؤية على سطح بأعلى درجات الحاوية. فلا تعتمد عليها وحدها لتقول إن مكانًا ينتظر. وحيث يقف على سطح كهذا، وجِّه comp.skeleton.placeholder.color إلى دور أقوى في طبقة.

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