Carousel

يعرض الـ carousel الشرائح واحدة في كل مرة: صور المنتج، أو خطوات التعريف بالتطبيق، أو لافتة تنتقل من تلقاء نفسها، أو صفًا من البطاقات. يتولى Carousel السلوك: أي شريحة تظهر، والتمرير بين الشرائح، وعنصرا التحكم السابق والتالي، والترقيم (pagination)، ومفاتيح الأسهم، والانتقال الدائري عند الأطراف، وما يسمعه قارئو الشاشة. تجد أجزاؤه الـ carousel عبر السياق (context)، فيرتبها التطبيق بحرية في تخطيطه. أما المظهر فهو من شأن التطبيق: لا ألوان ولا أحجام ولا أسهم ولا نقاط ولا تسميات من الـ carousel نفسه.

import { mount, signal, Text, View } from "nsh";
import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPagination, CarouselPaginationItem, CarouselPrevious } from "nsh/base";
import { desktop, focusRing, hoverFill, Icon, Log, Split, tint, ui } from "./palette";

const places: { name: string; detail: string; from: string; to: string }[] = [
  { name: "Lisbon", detail: "Tiles, trams and the river light", from: "#3d5a73", to: "#8fb3c9" },
  { name: "Kyoto", detail: "Temples, moss gardens, quiet lanes", from: "#5a3d4a", to: "#c98fa6" },
  { name: "Oaxaca", detail: "Markets, mole and mezcal", from: "#6b4a2f", to: "#d1a06b" },
  { name: "Tromsø", detail: "Fjords under the northern lights", from: "#2f4a4f", to: "#6bb3a8" },
  { name: "Marrakesh", detail: "Riads, souks and courtyards", from: "#73402f", to: "#d9875b" },
];

function App() {
  const shown = signal(0);
  const events = signal<string[]>([]);
  const log = (line: string) => events.set([line, ...events()].slice(0, 3));
  const arrow = {
    style: { width: desktop ? 28 : 34, height: desktop ? 28 : 34, borderRadius: 999, alignItems: "center", justifyContent: "center", ...ui().raised } as const,
    class: "transition-opacity active:opacity-70 disabled:opacity-30 motion-reduce:transition-none",
    hoverStyle: hoverFill(),
    focusStyle: focusRing(2),
  };
  return (
    <View style={{ flex: 1, backgroundColor: ui().page, padding: 20, paddingTop: 24, gap: 14 }}>
      <Text style={{ fontSize: 22, fontWeight: "700", color: ui().text }}>carousel</Text>
      <Text style={{ color: ui().muted }}>
        {desktop
          ? "Scroll with the touchpad, click the arrows or a dot, or focus it and press ← →; after the last place comes the first"
          : "Swipe the cards, or tap the arrows or a dot; after the last place comes the first"}
      </Text>

      <Split gap={14} inspector={<Log title={`onChange · ${places[shown()].name}`} lines={events()} minHeight={76} />}>
        {/* Five cards at 85% span more than the view and a card: the loop is seamless. */}
        <Carousel
          looping
          accessibilityLabel="Places to visit"
          onChange={({ index }) => {
            shown.set(index);
            log(`index: ${index} (${places[index].name})`);
          }}
          style={{ gap: 12, borderRadius: 14 }}
          focusStyle={focusRing(4)}
        >
          {/* Each card is 85% of the view: the next one peeks in. */}
          <CarouselContent style={{ height: desktop ? 150 : 170, gap: 10 }}>
            <Each of={places}>
              {(p, i) => (
                <CarouselItem
                  accessibilityLabel={`${i() + 1} of ${places.length}: ${p().name}`}
                  style={{
                    width: "85%",
                    height: "100%",
                    padding: 16,
                    justifyContent: "flex-end",
                    gap: 2,
                    borderRadius: 14,
                    borderCurve: "continuous",
                    backgroundColor: p().from,
                    backgroundImage: `linear-gradient(135deg, ${p().from} 0%, ${p().to} 100%)`,
                  }}
                >
                  <Text style={{ fontSize: 20, fontWeight: "700", color: "#ffffff" }}>{p().name}</Text>
                  <Text style={{ fontSize: 13, color: tint("#ffffff", 0.82) }}>{p().detail}</Text>
                </CarouselItem>
              )}
            </Each>
          </CarouselContent>

          <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
            <CarouselPrevious accessibilityLabel="Previous place" {...arrow}>
              <Icon name="back" size={14} tint={ui().text} />
            </CarouselPrevious>
            {/* The dots: a pill springs to the one of the card shown. */}
            <CarouselPagination
              accessibilityLabel="Choose a place"
              style={{ flex: 1, flexDirection: "row", justifyContent: "center", alignItems: "center" }}
              indicatorStyle={{ top: 7, bottom: 7, marginHorizontal: 2, borderRadius: 4, backgroundColor: ui().accent }}
            >
              <Each of={places}>
                {(p, i) => (
                  <CarouselPaginationItem
                    index={i()}
                    accessibilityLabel={p().name}
                    class="group"
                    style={{ width: 20, height: 20, alignItems: "center", justifyContent: "center", borderRadius: 10 }}
                    focusStyle={focusRing()}
                  >
                    <View
                      class="opacity-60 group-hover:opacity-100 group-selected:opacity-0 transition-opacity motion-reduce:transition-none"
                      style={{ width: 6, height: 6, borderRadius: 3, backgroundColor: tint(ui().text, 0.4) }}
                    />
                  </CarouselPaginationItem>
                )}
              </Each>
            </CarouselPagination>
            <CarouselNext accessibilityLabel="Next place" {...arrow}>
              <Icon name="chevron" size={14} tint={ui().text} />
            </CarouselNext>
          </View>
        </Carousel>
      </Split>
    </View>
  );
}

mount(App);

المحتوى عبارة عن native scroll view. يحرّك الإصبع وعجلة الفأرة ولوحة اللمس الشرائح على الخيط الرئيسي للمنصة، في الإطار نفسه الذي يتحرك فيه المؤشر، وعند الإفلات يستقر المحتوى على أقرب شريحة، بشريحة واحدة لكل swipe سريع. وعندما يستقر المحتوى يبلّغ الـ carousel عن الشريحة عبر onChange. أما عناصر التحكم والترقيم والمفاتيح وindex الخاص بالتطبيق فتمرّر المحتوى أصليًا إلى الشريحة، بحركة متحركة.

use nsh_base::{
    carousel, carousel_content, carousel_item, carousel_next, carousel_pagination,
    carousel_pagination_item, carousel_previous, theme,
};
use nsh_core::prelude::*;

fn photos() -> impl IntoElement {
    let index = signal(0u32);
    let names = ["Harbor", "Dunes", "Glacier"];
    carousel()
        .index(move || Some(index.get()))
        .on_change(move |i: &u32| index.set(*i))
        .accessibility_label("Photos")
        .gap_3()
        .child(
            carousel_content().w_full().h(px(180.0)).gap_3().child(
                names
                    .iter()
                    .enumerate()
                    .map(|(i, name)| {
                        carousel_item()
                            .accessibility_label(format!("{} of 3: {name}", i + 1))
                            .w_full()
                            .rounded(move || theme().radius)
                            .bg(move || theme().muted)
                            .items_center()
                            .justify_center()
                            .child(text(*name))
                    })
                    .collect::<Vec<_>>(),
            ),
        )
        .child(
            view()
                .flex_row()
                .items_center()
                .gap_2()
                .child(carousel_previous().accessibility_label("Previous photo").child(text("‹")))
                .child(
                    carousel_pagination()
                        .flex_row()
                        .gap_1()
                        .child(
                            (0..3)
                                .map(|i| {
                                    carousel_pagination_item()
                                        .index(i)
                                        .accessibility_label(format!("Photo {}", i + 1))
                                        .size_2()
                                        .rounded_full()
                                        .bg(move || theme().border)
                                        .selected_style(|s| s.bg(move || theme().primary))
                                })
                                .collect::<Vec<_>>(),
                        ),
                )
                .child(carousel_next().accessibility_label("Next photo").child(text("›"))),
        )
}

import { mount, signal, Text, View } from "nsh";
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPagination,
  CarouselPaginationItem,
  CarouselPrevious,
} from "nsh/base";

const NAMES = ["Harbor", "Dunes", "Glacier"];

function App() {
  const index = signal(0);
  return (
    <Carousel index={index()} onChange={({ index: next }) => index.set(next)} accessibilityLabel="Photos" class="gap-3">
      <CarouselContent class="h-[180px] w-full gap-3">
        {NAMES.map((name, i) => (
          <CarouselItem
            accessibilityLabel={`${i + 1} of ${NAMES.length}: ${name}`}
            class="w-full items-center justify-center rounded-(--radius) bg-muted"
          >
            <Text>{name}</Text>
          </CarouselItem>
        ))}
      </CarouselContent>
      <View class="flex-row items-center gap-2">
        <CarouselPrevious accessibilityLabel="Previous photo" class="disabled:opacity-40">
          <Text>‹</Text>
        </CarouselPrevious>
        <CarouselPagination class="flex-row gap-1">
          {NAMES.map((_, i) => (
            <CarouselPaginationItem
              index={i}
              accessibilityLabel={`Photo ${i + 1}`}
              class="size-2 rounded-full bg-border selected:bg-primary"
            />
          ))}
        </CarouselPagination>
        <CarouselNext accessibilityLabel="Next photo" class="disabled:opacity-40">
          <Text>›</Text>
        </CarouselNext>
      </View>
    </Carousel>
  );
}

mount(App);

يأتي Carousel وأجزاؤه من nsh/base، وهي nsh-base crate في Rust. الشريحة المعروضة هي index الخاصة بالتطبيق: يبلّغ التمرير أو عنصر التحكم أو المفتاح عن الشريحة التالية عبر onChange، ويمرّر الـ carousel إلى index التي يعيدها التطبيق. تبقى الشريحة التي استقر عليها التمرير معروضة إلى أن يجيب التطبيق عن onChange الخاص بها: تبقى إذا أعادها التطبيق بوصفها index، ويرتد المحتوى إلى شريحة التطبيق بحركة متحركة إذا أبقى التطبيق على index التي كانت لديه. وعند غياب index يحتفظ الـ carousel بقيمته الخاصة، انطلاقًا من defaultIndex. في Rust تنشئ carousel() وcarousel_content() وcarousel_item() وcarousel_previous() وcarousel_next() وcarousel_pagination() وcarousel_pagination_item() الأجزاء، مع setter لكل خاصية (.index(..))، وlistener لكل حدث (.on_change(..))، وطرق الأنماط typed، و.child(..) لمحتواها.

#الخصائص

#Carousel

#CarouselContent

#CarouselItem

#CarouselPrevious, CarouselNext

#CarouselPagination

#CarouselPaginationItem

#الأحداث

#الأجزاء

#عدة شرائح في كل عرض

عرض الشريحة يحدده صنفها (class) الخاص، لذا فصف من البطاقات هو عدة شرائح داخل منطقة العرض. كل شريحة نقطة التقاط (snap point) عند بدايتها: يستقر المحتوى بحيث تكون تلك الشريحة حيث تستقر الأولى، فتُحفظ الحشوة التي قبل الأولى قبل كل شريحة. وعند نهاية المدى تستقر الشرائح التي لا تبلغ ذلك الموضع مع الأخيرة، ويتوقف التالي هناك. يسمّي index الشريحة في الموضع الأول؛ أما الشرائح التي تستقر مع الأخيرة فتُظهر الموضع نفسه، ويُبلَّغ عند التمرير هناك عن أولاها:

<Carousel accessibilityLabel="Collections">
  <CarouselContent class="w-full gap-4 px-4">
    <Each of={collections()}>
      {(c) => (
        <CarouselItem class="basis-1/3">
          <Card collection={c()} />
        </CarouselItem>
      )}
    </Each>
  </CarouselContent>
</Carousel>

يُظهر basis-1/2 بعرض هاتف، أو basis-[85%]، جزءًا من البطاقة التالية. أما الـ carousel العمودي (axis="vertical") فيحدد أحجام شرائحه بحسب ارتفاعها.

#التكرار الدائري

مع looping تدور الشرائح بسلاسة: بعد الأخيرة تأتي الأولى، سواء بالتمرير أو بالانتقال بالتالي أو بالمفاتيح، أو بضبط index الخاص بالتطبيق، دون إرجاع للشرائح التي بينهما. يحتفظ المحتوى بمساحة دورة كاملة من الشرائح قبلها وبعدها، ويرسم كل شريحة حيث تكون أقرب إلى منتصف العرض؛ وتجري الحركة ذلك على إطارات المنصة نفسها، مع التمرير. كل شريحة موجودة مرة واحدة فقط: يراها قارئو الشاشة والترقيم مرة واحدة.

يكون التكرار سلسًا ما دامت الشرائح تغطي منطقة العرض وشريحة إضافية (ثلاث شرائح بعرض كامل، أو خمس بعرض ثلث). ومع عدد أقل، يبقى السابق والتالي والمفاتيح تدور، لكن بالتمرير راجعًا عبر الشرائح.

#شرائح تنتقل من تلقاء نفسها

اللافتة التي تتحرك تلقائيًا من شأن التطبيق: مؤقّت يضبط index. يبلّغ الـ carousel بوقت تفاعل المستخدم معه، فينتظر المؤقت حينها، كما يطلب نمط carousel في WAI-ARIA: onDragStart / onDragEnd حول السحب، وonFocus / onBlur ما دام تركيز لوحة المفاتيح داخل الـ carousel (عليه، أو على عناصر التحكم فيه، أو الترقيم، أو محتوى الشرائح)، ومؤشر الفأرة فوق view يحيط به. أوقفه عند تفعيل تقليل الحركة، وامنح المستخدمين زرًّا يوقفه (عنصر التحكم في التدوير):

import { cleanup, effect, reduceMotion, signal, Text, View } from "nsh";
import { Button, Carousel, CarouselContent } from "nsh/base";

const index = signal(0);
const playing = signal(true);
const held = signal(0);
const hold = (on: boolean) => held.set(held() + (on ? 1 : -1));

effect(() => {
  index();
  if (!playing() || held() > 0 || reduceMotion()) return;
  const timer = setInterval(() => index.set((index() + 1) % SLIDES.length), 4000);
  cleanup(() => clearInterval(timer));
});

<View onMouseEnter={() => hold(true)} onMouseLeave={() => hold(false)}>
  <Carousel
    looping
    index={index()}
    onChange={({ index: next }) => index.set(next)}
    onDragStart={() => hold(true)}
    onDragEnd={() => hold(false)}
    onFocus={() => hold(true)}
    onBlur={() => hold(false)}
    accessibilityLabel="Highlights"
  >
    <CarouselContent class="w-full">{/* the slides */}</CarouselContent>
    <Button onPress={() => playing.set(!playing())} class="self-start px-3 py-1">
      <Text>{playing() ? "Pause slides" : "Play slides"}</Text>
    </Button>
  </Carousel>
</View>

قراءة index() داخل الـ effect تبدأ فترة كاملة من جديد بعد كل تغيير، بما فيه تغيير المستخدم. ومع looping، يتحرك الانتقال من الشريحة الأخيرة إلى الأولى إلى الأمام عبر الوصلة.

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

• الـ carousel منطقة (region) تسمّيها accessibilityLabel؛ وكل شريحة مجموعة (group) تسمّيها تسميتها الخاصة (موضعها بين الشرائح الأخرى وما تعرضه).
• السابق والتالي زرّان (buttons)، يُعطَّلان عند الطرفين ما لم يكن الـ carousel دائريًا؛ وكل عنصر ترقيم زر، يكون محددًا (selected) ما دامت شريحته معروضة.
• كل تسمية من التطبيق، وبلغة التطبيق.
• كل شريحة في الـ carousel الدائري موجودة مرة واحدة، أينما رُسمت.

راجع إمكانية الوصول للاطلاع على التسميات والأدوار والإعلانات بوجه عام.

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

على macOS والويب، حيث يصل Tab إلى الـ views التي تستقبل الضغطات، يكون الـ carousel نقطة توقف لتركيز لوحة المفاتيح، وكذلك عناصر التحكم فيه وعناصر الترقيم. وما دام أحدها يملك التركيز:

في التخطيط من اليمين إلى اليسار تتتابع شرائح الـ carousel الأفقي من اليمين، فينقل Left إلى الشريحة التالية وRight إلى السابقة؛ أما الـ carousel العمودي فيحتفظ بـ Up وDown. وعنصر التحكم الذي يصبح معطّلًا وهو يملك التركيز (التالي في الشريحة الأخيرة) يسلّم التركيز إلى الـ carousel، فتستمر المفاتيح في العمل هناك. أما الـ views القابلة للتركيز التي يضعها التطبيق داخل الشرائح فتحتفظ بمفاتيحها: أسهم حقل الإدخال تحرك مؤشر الكتابة فيه.

#الحركة

• يحرّك التمرير والعجلة ولوحة اللمس الشرائح مع المؤشر، في الإطار نفسه: المنصة هي التي تمرّرها.
• عند الإفلات ينساب المحتوى إلى أقرب شريحة، بشريحة واحدة لكل swipe سريع، كما تلتقط المنصة.
• السابق والتالي وعنصر الترقيم والمفتاح وindex الخاص بالتطبيق تمرّر المحتوى إلى الشريحة بحركة متحركة؛ ومع تقليل الحركة، فورًا.
• يقفز مؤشر الترقيم إلى عنصر الشريحة المعروضة؛ ومع تقليل الحركة ينتقل فورًا.
• looping ينتقل من الشريحة الأخيرة إلى الأولى بخطوة إلى الأمام عبر الوصلة؛ وحين يستقر المحتوى يرجع بدورة كاملة دون حركة، وهذا لا يغيّر شيئًا على الشاشة.

#ملاحظات المنصات

• iOS وAndroid وMac Catalyst: يمرّر الإصبع الشرائح؛ والنقرة تضغط عنصر تحكم.
• أنظمة سطح المكتب (macOS وWindows وLinux وGPUI) والويب: تمرّر العجلة ولوحة اللمس الشرائح، والنقر يضغط عنصر تحكم. أما سحب الفأرة فوق المحتوى فمن شأن التطبيق، كما في كل scroll view هناك.
• ترسم كل منصة ما ينسّقه التطبيق: الشرائح وعناصر التحكم والترقيم ومؤشره.