العناصر

يبني Native Shell كل شاشة من مجموعة صغيرة من العناصر: عناصر أولية (primitives) مثل View وText وImage، ومكوّنات أساسية (base components) مثل Button وDialog وNavStack. كل عنصر أولي هو عرض أصلي (native view): صنف فرعي من UIView على iOS وMac Catalyst، أو View على Android، أو عرض AppKit أو GTK أو Win32 على أنظمة سطح المكتب، وينشئه بيئة تشغيل NSH ويتولى تخطيطه. كل ما يعرضه التطبيق مصنوع منها: أزرار التطبيق وبطاقاته وصفوفه وشاشاته هي مكوّنات خاصة به، تُرسم بهذه العناصر ويُنسّقها التطبيق، فيكون مظهره من صنعه بالكامل.

كل مثال في هذه الصفحات متاح بلغتي Rust وTSX: اختر تبويبًا، وستتبعه جميع الأمثلة في الصفحة.

use nsh_core::prelude::*;

fn app() -> impl IntoElement {
    let count = signal(0_u32);
    view()
        .flex_1()
        .items_center()
        .justify_center()
        .gap_3()
        .child(text(move || format!("Tapped {} times", count.get())).text_2xl())
        .child(
            view()
                .rounded_lg()
                .bg(rgb(0x2563eb))
                .px_4()
                .py_2()
                .active(|s| s.opacity(0.6))
                .on_press(move || count.update(|n| *n += 1))
                .child(text("Tap").text_color(white())),
        )
}

import { mount, signal, Text, View } from "nsh";

function App() {
  const count = signal(0);
  return (
    <View style={{ flex: 1, alignItems: "center", justifyContent: "center", gap: 12 }}>
      <Text style={{ fontSize: 24 }}>Tapped {count()} times</Text>
      <View onPress={() => count.update((n) => n + 1)} class="rounded-lg bg-blue-600 px-4 py-2 active:opacity-60">
        <Text class="text-white">Tap</Text>
      </View>
    </View>
  );
}

mount(App);

في Rust، العناصر الأولية هي دوال من nsh_core::prelude (view() وtext(..) وimage(..))، وتأتي المكوّنات الأساسية من الحزمة nsh_base. الأنماط هي دوال مكتوبة الأنواع (.flex_1() و.gap_3() و.px(px(20.0)) و.bg(..))، وأنماط الحالات تأخذ closure ‏(.active(|s| s.opacity(0.6)))، والمستمعات هي closures تستقبل حدثها (.on_press(move || ..) و.on_change(move |text: &str| ..))، وتضيف .child(..) العناصر الأبناء. قطعة الواجهة هي دالة عادية تعيد impl IntoElement؛ تُنفَّذ مرة واحدة، وتحدّث الإشارات (signals) التي تقرؤها داخل closures ‏(text(move || ..) و.bg(move || ..)) ما ترتبط به. راجع البناء باستخدام Rust.

في TSX، كل وسم مكتوب بنمط PascalCase ويسمّي ارتباطًا (binding) موجودًا في النطاق: تأتي العناصر الأولية من nsh والمكوّنات الأساسية من nsh/base. <If> و<Each> فقط عنصران عامّان لا يحتاجان إلى استيراد. الوسم بأحرف صغيرة مثل <view> يسبب خطأ في البناء، لأن TypeScript كان سيفحصه مقابل نوع عام واحد لكل اسم، ولن تتمكن المكوّنات العامة (generic) مثل List وEach من استنتاج أنواع عناصرها. يتعرف المترجم على العناصر من خلال عمليات الاستيراد وينشئ العروض الأصلية في موضعها، لذلك لا يكلّف استيرادها شيئًا وقت التشغيل. راجع JSX والمكوّنات.

import { Canvas, Image, List, Overlay, Scroll, Shader, Text, Video, View, WebView } from "nsh";
import { Button, Dialog, Menu, NavPage, NavStack, Popover, Sheet, Tooltip, Input } from "nsh/base";

#العناصر الأولية

تُستورد من nsh في TSX، ومن nsh_core::prelude في Rust.

يُبقي الحشو (padding) والهامش (margin) المحتوى بعيدًا عن واجهة النظام باستخدام env() من CSS: env(safe-area-inset-top) وبقية الحواف (المنطقة الآمنة) وenv(keyboard-inset-height) (لوحة المفاتيح).

#الأساسية

تُستورد من nsh/base في TSX، ومن الحزمة nsh_base في Rust. تمتلك هذه المكوّنات السلوك والحالة والتركيز وإمكانية الوصول، ويأتي مظهرها من التطبيق.

#الخصائص المشتركة

يقبل كل عنصر أولي الخصائص التالية (النوع CommonProps في TSX؛ والسمات Styled وInteractive وAccessible في Rust). تسرد صفحات العناصر خصائصها الخاصة فقط. يذكر عمود Rust اسم دالة البناء.

#التنسيق

#الضغطات والاستجابة

تجري معالجة الضغط أصليًا: تتعرف المنصة على الضغطة وتطبّق أنماط الضغط الخاصة بالتطبيق، ولا تعلم شيفرة التطبيق بها إلا بعد ذلك. لا يستجيب إلا أعمق عرض قابل للضغط؛ وداخل عروض التمرير ينتظر بدء الضغط (press-in) نحو 130 ms ليتمكن التمرير من البدء أولًا.

PressEvent هو { position, pagePosition, modifiers, clickCount }: موضع المؤشر داخل العرض وداخل عرضه الجذر (Point)، ومفاتيح التعديل المضغوطة عند بدء الضغطة، وعدد النقرات المتتابعة (2 للنقر المزدوج). وعندما لا تُبلغ المنصة عن مؤشر، فهو نقطة أصل العرض دون مفاتيح ونقرة واحدة.

مفتاح النمط pointerEvents (.pointer_events(PointerEvents::BoxNone) في Rust، والأصناف pointer-events-*) يحدد أي اللمسات يستقبلها العرض والعروض الموجودة بداخله: "none" لا هذا ولا تلك (ويستعيدها أي عرض بداخله يضبط "auto")، "box-none" العروض الموجودة بداخله فقط، "box-only" العرض نفسه فقط (اللمس والإيماءات).

استجابة الضغط من شأن التطبيق: يُطبَّق activeStyle (أو أصناف active:، أو .active(..) في Rust) أصليًا ما دام العرض مضغوطًا، دون أي ذهاب وإياب إلى شيفرة التطبيق (انظر أدناه).

#أنماط الحالات

أنماط تُطبَّق ما دام العرض في حالة معينة، فوق أنماطه الخاصة، وتتم أصليًا. كل منها هو الصيغة الكائنية لمتغيّر (variant) في Tailwind. الحالات اللاحقة لها الأولوية (selected وchecked وindeterminate، ثم hover وfocus وactive)؛ ولـ disabledStyle الأولوية على الجميع، ولا تُطبَّق الحالات الأخرى ما دام العرض معطّلًا. يأخذ كل منها نمط العنصر نفسه: TextStyle على <Text>، وInputStyle على <Input>، وImageStyle على <Image>، وViewStyle في غير ذلك.

view()
    .rounded_lg()
    .bg(rgb(0x2563eb))
    .px_4()
    .py_2()
    .active(|s| s.opacity(0.6))
    .hover(|s| s.bg(rgb(0x1d4ed8)))
    .on_press(save)
    .child(text("Save").text_color(white()))

<View onPress={save} activeStyle={{ opacity: 0.6 }} hoverStyle={{ backgroundColor: "#1d4ed8" }} class="rounded-lg bg-blue-600 px-4 py-2">
  <Text class="text-white">Save</Text>
</View>

#التحويم (Hover)

يسمع التطبيق دخول الفأرة إلى عنصر عرض (view) وحركتها فوقه ومغادرتها له: على macOS وWindows وLinux وواجهة GPUI الخلفية ومتصفحات سطح المكتب، وبمؤشر iPad أو فأرة Mac على iOS، وبفأرة أو قلم على Android. أنماط التحويم (hover:، .hover(..)) تنسّق العناصر المحوَّم فوقها في الأماكن نفسها.

مثل :hover في CSS وmouseenter في DOM، يُعدّ العنصر محوَّمًا فوقه ما دامت الفأرة فوقه أو فوق أي شيء بداخله، لذا تسمع العناصر المحيطة بالعنصر الذي تحت الفأرة onMouseEnter أيضًا (من الخارج إلى الداخل؛ onMouseLeave من الداخل إلى الخارج). تصل الأحداث بعد وقوع الفعل ولا تصل أبدًا عند اللمس. العنصر الذي يُزال من تحت الفأرة يسمع onMouseLeave، وذلك على Linux وWindows عند حركة الفأرة التالية.

يبيّن MouseEvent موضع الفأرة، كما يفعل MouseMoveEvent في GPUI: position داخل العنصر (Point بالنقاط، مع التراجع عن تحويلاته)، وpagePosition داخل العنصر الجذر الذي يوجد فيه، كما تعطيه اللمسات، وmodifiers المضغوطة (control، alt، shift، platform: Command على منصات Apple، ومفتاح Windows في غيرها)، وpressedButton، الزر المضغوط ("left"، "right"، "middle"، "back" أو "forward"، وهو MouseButton في GPUI) أو null؛ وفي Rust position، page_position، modifiers وpressed_button. على أنظمة سطح المكتب والويب يُعدّ السحب لمسة أيضًا (onTouchMove، المستجيب)، وتصل حركاته إلى onMouseMove مع ضبط pressedButton: التغذية الراجعة التي تتبع التحويم فقط تتجاهلها؛ وعلى iOS وAndroid يبلّغ التحويم عن المؤشر دون زر مضغوط. تصل الحركات مرة واحدة في الإطار كحد أقصى، وهي الأحدث، وتصل دائمًا قبل onMouseLeave الذي يليها، لذا يمكن للمعالج إعادة الرسم عند كل حركة:

// A crosshair over a chart.
let at = signal(None::<Points>);

view()
    .h(px(200.0))
    .on_mouse_move(move |e: &MouseEvent| at.set(Some(e.position.x)))
    .on_mouse_leave(move |_: &MouseEvent| at.set(None))
    .child(when(move || at.get().is_some(), move || {
        view()
            .absolute()
            .left(move || at.get().unwrap_or_default())
            .top_0()
            .bottom_0()
            .w(px(1.0))
            .bg(rgb(0x888888))
    }))

// A crosshair over a chart.
const at = signal<number | null>(null);

<View onMouseMove={(e) => at.set(e.position.x)} onMouseLeave={() => at.set(null)} style={{ height: 200 }}>
  <If when={at() !== null}>
    <View style={{ position: "absolute", left: at()!, top: 0, bottom: 0, width: 1, backgroundColor: "#888" }} />
  </If>
</View>

#التلميحات (Tooltips)

يمنح tooltip أي عنصر تلميحًا، يظهر فوقه على أنظمة سطح المكتب (macOS وWindows وLinux وواجهة GPUI الخلفية ومتصفحات سطح المكتب) بعد أن يستقر المؤشر عليه نصف ثانية، ويبقى حتى يغادره المؤشر أو يضغطه. لا تعرض الهواتف واللوحيات أي تلميح. لا يلتقط التلميح المؤشر ولا الضغطات أبدًا، فيعمل العنصر تمامًا كما يعمل بدونه.

view()
    .on_press(save)
    .tooltip(
        tooltip()
            .rounded_md()
            .bg(rgb(0x111827))
            .px_2()
            .py_1()
            .child(text("Save the document").text_color(white())),
    )
    .child(text("💾"))

<View
  onPress={save}
  tooltip={
    <Tooltip class="rounded-md bg-gray-900 px-2 py-1">
      <Text class="text-white">Save the document</Text>
    </Tooltip>
  }
>
  <Text>💾</Text>
</View>

يحدد Tooltip مظهره وموضعه وتأخيره وأحداثه بنفسه، كما يفعل .tooltip(..) في GPUI. التطبيق الذي فيه تلميحات كثيرة يحتفظ بمكوّن صغير خاص به يلفّ نصًا في Tooltip.

#قوائم السياق (Context menus)

يخبر onContextMenu العنصر بأن الزر الثانوي ضُغط فوقه: نقرة يمين، أو Control-click على macOS، أو نقرة بإصبعين على لوحة اللمس، أو النقرة الثانوية لمؤشر iPad؛ وفي المتصفحات مفتاح القائمة في لوحة المفاتيح أيضًا. افتح قائمة التطبيق الخاصة هناك؛ وفي TSX يعرض Menu.popup قائمة النظام:

// The app's own menu, placed where the click was.
let menu_at = signal(None::<Point<Points>>);

view()
    .on_context_menu(move |e: &ContextMenuEvent| menu_at.set(Some(e.page_position)))
    .child(text(row.name.clone()))

import { Menu } from "nsh/desktop";

<View onContextMenu={(e) => Menu.popup(rowMenu(row), e.pagePosition)}>…</View>

يحتوي ContextMenuEvent على position داخل العنصر، وpagePosition داخل عنصره الجذر (حيث يضع Menu.popup قائمة: Menu.popup(items, e.pagePosition)) وmodifiers؛ وفي Rust position وpage_position وmodifiers. أقرب عنصر يستمع، بدءًا من العنصر الذي تحت المؤشر ثم نحو الخارج، هو الذي يسمعه. حقل إدخال نصي، أو نص قابل للتحديد له قائمة تحرير (Windows وواجهة GPUI الخلفية والمتصفحات)، إذا كان أقرب من ذلك العنصر فإنه يعرض قائمته الخاصة بدلًا منه. تقرر المنصة ذلك لحظة نزول الزر، بناءً على ما هو مركّب، فيُبلَّغ المعالج بعد وقوع الفعل ولا حاجة إلى إلغاء أي شيء. العنصر disabled يترك النقرة لأقرب مستمع مفعّل حوله. على الشاشات اللمسية يفتح الضغط المطوّل القوائم: عالج onLongPress بالدالة نفسها.

#تركيز لوحة المفاتيح (Keyboard focus)

على macOS والويب، ينقل Tab تركيز لوحة المفاتيح بين نقاط توقفه بترتيب الشجرة: حقول الإدخال، والعناصر التي تقبل الضغط، وكل عنصر focusable. أنماط التركيز (focus:، .focus(..)) تنسّق العنصر المركَّز، ويضغطه Return أو Space إذا كان يقبل الضغط. النقرة تضغط العنصر دون تركيزه، لذا تظهر أنماط التركيز لتركيز لوحة المفاتيح فقط.

التركيز والضغط منفصلان. العنصر الذي يستقبل المفاتيح وهو مركَّز (مخطط، أو منزلق، أو قائمة تحرّك تحديدها بمفاتيح الأسهم) يضبط focusable ويربط مفاتيحه أثناء التركيز (onFocus / onBlur مع keymap)؛ وتظل الضغطة عليه تصل إلى عنصر قابل للضغط حوله، مثل بطاقة تفتح صفحة.

يحرّك focus() الخاص بـ ref تركيز لوحة المفاتيح إلى نقطة توقف كما يفعل Tab (تظهر أنماط تركيزها ويُطلَق onFocus)، مثلًا لإعادته إلى مشغّل نافذة منبثقة أُغلقت، ويزيله blur().

يُنسّق العنصر المحيط بالتركيز نفسه بـ focus-within: (focusWithinStyle، .focus_within(..)) ما دام التركيز عليه أو على أي عنصر بداخله: إطار حقل حول الإدخال الذي يحرّر، أو شريط أدوات بينما أحد أزراره عليه التركيز. محتوى Overlay داخل العنصر الذي يوجد فيه التراكب، أينما ظهر، لذا تُعدّ النافذة المنبثقة جزءًا من العنصر الذي يحمل مشغّلها. في Rust يسمع المكوّن دخول التركيز إلى عنصر وخروجه منه عبر on_focus_in(..) وon_focus_out(..) الخاصين بـ ref: والتنقل بين العناصر داخله ليس دخولًا ولا خروجًا.

view()
    .rounded_lg()
    .p_3()
    .focus(|s| s.bg(rgb(0xe0f2fe)))
    .on_press(open)
    .child(text("Open"))

// An overlay's backdrop: a click closes it, Tab goes past it to the content.
view().absolute().inset_0().focusable(false).on_press(close)

// A chart in a card: Tab stops at the chart, a click opens the card's page.
view().on_press(open_page).child(
    view()
        .h(px(160.0))
        .focusable(true)
        .focus(|s| s.bg(rgb(0xe0f2fe)))
        .on_focus(move || focused.set(true))
        .on_blur(move || focused.set(false)),
)

<View class="rounded-lg p-3 focus:bg-sky-100" onPress={open}>
  <Text>Open</Text>
</View>

{/* An overlay's backdrop: a click closes it, Tab goes past it to the content. */}
<View class="absolute inset-0" focusable={false} onPress={close} />

{/* A chart in a card: Tab stops at the chart, a click opens the card's page. */}
<View onPress={openPage}>
  <View
    class="h-40 focus:bg-sky-100"
    focusable
    onFocus={() => focused.set(true)}
    onBlur={() => focused.set(false)}
  />
</View>

#التخطيط والهوية (Layout and identity)

#الإيماءات التي تقود القيم المتحركة (Gestures driving animated values)

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

PanEvent هو { cancelled, translation, velocity, value? } (وفي Rust cancelled، translation، velocity_x، velocity_y، value_x، value_y): هل ألغى النظام السحب، والإزاحة منذ البداية، والسرعة بالنقاط في الثانية (قيم Point)، والقيم المرتبطة في تلك اللحظة، { x?, y? } للمحاور التي يربطها pan (يمكن للسحب أن يمسك قيمة أثناء حركتها).

#اللمسات الخام ونظام المستجيب (Raw touches and the responder system)

للإيماءات التي لا تغطيها الخصائص أعلاه، يقبل كل عنصر خصائص اللمس والمستجيب: onTouchStart، onTouchMove، onTouchEnd، onTouchCancel (وصيغ …Capture الخاصة بها)، onStartShouldSetResponder، onMoveShouldSetResponder (و…Capture)، onResponderGrant، onResponderReject، onResponderStart، onResponderMove، onResponderEnd، onResponderRelease، onResponderTerminate وonResponderTerminationRequest. يستقبل كل معالج GestureResponderEvent ({ identifier, locationX, locationY, pageX, pageY, target, timestamp, touches, changedTouches, nativeEvent, stopPropagation() }); the …ShouldSetResponder handlers also get a gestureState (dx, dy, vx, vy, …). إرجاع true من onResponderGrant يمنع عروض التمرير الأصلية من أخذ اللمسات. panActivation ({ activeOffsetX, activeOffsetY, failOffsetX, failOffsetY }) يجعل العنصر مستجيبًا فقط بعد أن تفعّل المنصة حركة السحب الخاصة بها، فتترك عمليات السحب داخل عروض التمرير المحور الآخر لها (اللمس والإيماءات). يعتمد PanResponder في PanResponder عليها. في Rust يسمع .on_touch(..) كل لمسة (TouchEvent)، ويقرر .claim_touches(..) متى يأخذها العنصر، وتتبع .on_responder_grant(..) و.on_responder_move(..) و.on_responder_release(..) وغيرها المستجيب.

#إمكانية الوصول (Accessibility)

انظر إمكانية الوصول.

#الخصائص الخاصة بمنصة واحدة (Platform-only props)

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

use nsh_core::Ripple;

view()
    .rounded_lg()
    .bg(white())
    .p_4()
    .elevation(px(2.0))
    .ripple(Ripple { color: Some(rgba(0x00000022).into()), ..Ripple::default() })
    .on_press(save)
    .child(text("Save"))

<View onPress={save} android={{ ripple: { color: "#00000022" }, elevation: 2 }} class="rounded-lg bg-white p-4">
  <Text>Save</Text>
</View>

انظر الشيفرة الخاصة بكل منصة.

#طرق الـ Ref

في TSX، يستقبل ref الـ ref الخاص بالعنصر، ونوعه هو نوع العنصر نفسه: ViewRef (focus، blur، measure) للعناصر View وText وImage وCanvas وOverlay وShader، ونوع مبني على ViewRef مع طرق العنصر بالنسبة إلى البقية: InputRef (Input)، ScrollRef (Scroll)، ListRef (List)، WebViewRef (WebView)، VideoRef (Video) وNativeComponentRef (المكوّنات الأصلية native components). في Rust، ينشئ element_ref() مقبضًا من النوع ElementRef يقوم .element_ref(&handle) بربطه. ترسل طرقه أوامر إلى الـ view الأصلي، بالترتيب نفسه مع التغييرات التي أُجريت قبلها في الدورة نفسها. توضح صفحة كل عنصر الطرق التي تنطبق عليه. اكتب نوع متغير الـ ref بنوع عنصره نفسه (let field!: InputRef للعنصر <Input>): فالمتغير المكتوب بالنوع ViewRef لا يناسب عنصرًا يحتوي الـ ref الخاص به على طرق خاصة به.

let field = element_ref();

view()
    .on_press(move || field.focus())
    .child(input().element_ref(&field).placeholder("Tap the row to type"))

import { type InputRef, View } from "nsh";
import { Input } from "nsh/base";

let input!: InputRef;
<View onPress={() => input.focus()}>
  <Input ref={input} placeholder="Tap the row to type" />
</View>;

#لماذا لا تحجب المعالجات واجهة المستخدم أبدًا

لا ينتظر الخيط الرئيسي (main thread) شيفرة التطبيق أبدًا. فعندما يحتاج النظام إلى إجابة فورية (هل يجوز تغيير هذا النص، وهل يجوز للزر الرجوع أن يُخرج الصفحة من المكدس، وهل يجوز إغلاق هذه الورقة السفلية)، يجيب NSH عنها محليًا اعتمادًا على props جرى ضبطها مسبقًا (maxLength، popOnBack، closeOnSwipe، …)، ثم يصل الحدث إلى التطبيق بعد ذلك. ولهذا السبب يكون هذا السلوك prop وليس قيمة مُعادة من معالج.