Elements

Native Shell baut jeden Screen aus einer kleinen Menge von Elementen: Primitive wie View, Text und Image sowie Basiskomponenten wie Button, Dialog und NavStack. Jedes Primitive ist eine native View (eine UIView-Unterklasse auf iOS und Mac Catalyst, eine Android-View, eine AppKit-, GTK- oder Win32-View auf den Desktops), die von der NSH-Runtime erzeugt und angeordnet wird. Alles, was eine App anzeigt, besteht aus ihnen: Die Buttons, Cards, Zeilen und Screens einer App sind ihre eigenen Komponenten, die mit diesen Elementen gezeichnet und von der App gestaltet werden, sodass das Erscheinungsbild vollständig der App gehört.

Jedes Beispiel auf diesen Seiten gibt es in Rust und TSX: Wähle einen Tab, und alle Beispiele der Seite folgen.

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);

In Rust sind die Primitive Funktionen von nsh_core::prelude (view(), text(..), image(..)), und die Basiskomponenten stammen aus dem Crate nsh_base. Styles sind typisierte Methoden (.flex_1(), .gap_3(), .px(px(20.0)), .bg(..)), Zustandsstile nehmen eine Closure (.active(|s| s.opacity(0.6))), Listener sind Closures ihres Events (.on_press(move || ..), .on_change(move |text: &str| ..)), und .child(..) fügt Kinder hinzu. Ein Stück UI ist eine gewöhnliche Funktion, die impl IntoElement zurückgibt; sie läuft einmal, und Signals, die sie in Closures liest (text(move || ..), .bg(move || ..)), aktualisieren das, woran sie gebunden sind. Siehe Building with Rust.

In TSX ist jeder Tag in PascalCase geschrieben und benennt ein Binding im Gültigkeitsbereich: Die Primitive kommen aus nsh, die Basiskomponenten aus nsh/base. Nur <If> und <Each> sind Globals, die keinen Import brauchen. Ein Tag in Kleinbuchstaben wie <view> ist ein Build-Fehler, weil TypeScript ihn gegen einen globalen Typ pro Namen prüfen würde und generische Komponenten wie List und Each ihre Item-Typen nicht ableiten könnten. Der Compiler erkennt die Elemente anhand ihrer Imports und erzeugt die nativen Views an Ort und Stelle, sodass der Import zur Laufzeit nichts kostet. Siehe JSX and components.

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";

#Primitive

In TSX aus nsh importiert, in Rust aus nsh_core::prelude.

Padding und Margin halten Inhalte mit dem CSS-Wert env() von der System-UI fern: env(safe-area-inset-top) und die anderen Kanten (Safe area) sowie env(keyboard-inset-height) (Keyboard).

#Basis

In TSX aus nsh/base importiert, in Rust aus dem Crate nsh_base. Sie übernehmen Verhalten, Zustand, Fokus und Barrierefreiheit und beziehen ihr Aussehen von der App.

#Gemeinsame Props

Jedes Primitive akzeptiert die folgenden Props (der Typ CommonProps in TSX; die Traits Styled, Interactive und Accessible in Rust). Die Seiten der Elemente listen nur ihre eigenen Props auf. Die Rust-Spalte nennt die Builder-Methode.

#Styling

#Drücke und Feedback

Die Druckverarbeitung läuft nativ: Die Plattform erkennt den Druck und wendet die Press-Styles der App an, und der Code der App erfährt erst danach davon. Nur die innerste drückbare View reagiert; in Scroll-Views wartet ein Press-in etwa 130 ms, damit zuerst ein Scrollen beginnen kann.

PressEvent ist { position, pagePosition, modifiers, clickCount }: wo der Zeiger in der View und in ihrer Root-View war (Points), die beim Beginn des Drucks gehaltenen Modifier-Tasten und die aufeinanderfolgenden Klicks (2 bei einem Doppelklick). Wo die Plattform keinen Zeiger meldet, ist es der Ursprung der View ohne Tasten und mit einem Klick.

Der Style-Key pointerEvents (.pointer_events(PointerEvents::BoxNone) in Rust, die Klassen pointer-events-*) bestimmt, welche Touches die View und die Views in ihr erhalten: "none" keine von beiden (eine darin liegende View, die "auto" setzt, nimmt sie wieder entgegen), "box-none" nur die Views in ihr, "box-only" nur die View selbst (touch and gestures).

Das Press-Feedback gehört der App: activeStyle (oder active:-Klassen, .active(..) in Rust) gilt, solange die View gedrückt ist, nativ und ohne Round Trip zum Code der App (siehe unten).

#Zustandsstile

Styles, die gelten, solange die View in einem Zustand ist, über ihren eigenen Styles und nativ. Jeder ist die Objektform einer Tailwind-Variante. Spätere Zustände haben Vorrang (selected, checked und indeterminate, dann hover, focus, active); disabledStyle hat Vorrang vor allen, und die anderen gelten nicht, solange die View deaktiviert ist. Jeder nimmt den eigenen Style des Elements: einen TextStyle bei einem <Text>, einen InputStyle bei einem <Input>, einen ImageStyle bei einem <Image>, sonst einen 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

Die App bekommt mit, wenn die Maus über eine View fährt, sich darüber bewegt und sie wieder verlässt: unter macOS, Windows, Linux, im GPUI-Backend und in Desktop-Browsern, mit dem Zeiger eines iPads oder der Maus eines Macs unter iOS sowie mit Maus oder Stylus unter Android. Hover-Stile (hover:, .hover(..)) gestalten Views unter der Maus an denselben Stellen.

Wie CSS :hover und das mouseenter des DOM gilt eine View als gehovert, solange die Maus über ihr oder über etwas in ihr ist. Die Views um diejenige unter der Maus bekommen also ebenfalls onMouseEnter mit (von außen nach innen; onMouseLeave von innen nach außen). Die Events kommen im Nachhinein und nie bei Touches. Eine View, die unter der Maus entfernt wird, bekommt onMouseLeave mit, unter Linux und Windows bei der nächsten Mausbewegung.

MouseEvent gibt an, wo die Maus ist, wie GPUIs MouseMoveEvent: position in der View (ein Point in Punkten, ihre Transformationen rückgängig gemacht), pagePosition in der Root-View, in der sie liegt, wie Touches es liefern, die gehaltenen modifiers (control, alt, shift, platform: Command auf Apple-Plattformen, sonst die Windows-Taste) und pressedButton, die gedrückte Maustaste ("left", "right", "middle", "back" oder "forward", GPUIs MouseButton) oder null; in Rust position, page_position, modifiers und pressed_button. Auf Desktop und im Web ist ein Drag auch ein Touch (onTouchMove, der Responder), und seine Bewegungen erreichen onMouseMove mit gesetztem pressedButton: Feedback, das nur dem Hover folgt, überspringt diese; unter iOS und Android meldet der Hover den Zeiger ohne gedrückte Taste. Bewegungen kommen höchstens einmal pro Frame, die jeweils letzte, und immer vor dem onMouseLeave, das auf sie folgt, sodass ein Handler bei jeder Bewegung neu zeichnen kann:

// 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 gibt jedem Element einen Hinweis, der auf dem Desktop (macOS, Windows, Linux, dem GPUI-Backend und Desktop-Browsern) über dem Element erscheint, sobald der Zeiger eine halbe Sekunde darauf geruht hat, und bleibt, bis der Zeiger das Element verlässt oder drückt. Smartphones und Tablets zeigen keinen. Der Hinweis nimmt weder den Zeiger noch Drücke an, daher funktioniert das Element genau wie ohne ihn.

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>

Das Tooltip legt sein Aussehen, seine Platzierung, Verzögerung und Events selbst fest, so wie auch GPUIs .tooltip(..) eines annimmt. Eine App mit vielen Tooltips hält eine kleine eigene Komponente bereit, die einen Text in ihrem Tooltip einbettet.

#Kontextmenüs

onContextMenu teilt einer View mit, dass die sekundäre Taste über ihr gedrückt wurde: ein Rechtsklick, Control-Klick unter macOS, ein Zweifingerklick auf einem Touchpad, der sekundäre Klick des Zeigers eines iPads; in Browsern auch die Menütaste der Tastatur. Öffne dort das eigene Menü der App; in TSX zeigt Menu.popup das des Systems:

// 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 enthält position in der View, pagePosition in ihrer Root-View (wo Menu.popup ein Menü platziert: Menu.popup(items, e.pagePosition)) und die modifiers; in Rust position, page_position und modifiers. Die nächste View, die zuhört, von der unter dem Zeiger nach außen, bekommt es mit. Ein Texteingabefeld oder auswählbarer Text mit Bearbeitungsmenü (Windows, das GPUI-Backend, Browser), das näher liegt als diese View, zeigt stattdessen sein eigenes Menü. Die Plattform entscheidet das, während die Taste gedrückt wird, anhand dessen, was eingebunden ist; der Handler erfährt es also im Nachhinein, und nichts muss abgebrochen werden. Eine disabled View überlässt den Klick dem nächsten aktivierten Listener um sie herum. Auf Touchscreens öffnet ein langer Druck Menüs: Behandle onLongPress mit derselben Funktion.

#Tastaturfokus

Unter macOS und im Web bewegt Tab den Tastaturfokus zwischen seinen Stopps in Baumreihenfolge: den Eingabefeldern, den Views, die Drücke annehmen, und jeder focusable View. Fokus-Stile (focus:, .focus(..)) gestalten die fokussierte View, und Return oder Leertaste drückt sie, wenn sie Drücke annimmt. Ein Klick drückt eine View, ohne sie zu fokussieren, daher erscheinen Fokus-Stile nur beim Tastaturfokus.

Fokus und Drücke sind getrennt. Eine View, die Tasten annimmt, solange sie den Fokus hat (ein Diagramm, ein Slider, eine Liste, die ihre Auswahl mit den Pfeiltasten bewegt), setzt focusable und bindet ihre Tasten, solange sie fokussiert ist (onFocus / onBlur mit keymap); ein Drücken darauf erreicht weiterhin ein drückbares Element um sie herum, etwa eine Karte, die eine Seite öffnet.

Das focus() einer Ref verschiebt den Tastaturfokus auf einen Stopp, so wie Tab es tut (seine Fokus-Stile erscheinen und onFocus wird ausgelöst), etwa um ihn dem Auslöser eines geschlossenen Popups zurückzugeben, und blur() nimmt ihn weg.

Eine View um den Fokus gestaltet sich selbst mit focus-within: (focusWithinStyle, .focus_within(..)), solange der Fokus auf ihr oder auf einer View darin liegt: der Rahmen eines Feldes um das Eingabefeld, das bearbeitet, eine Toolbar, während einer ihrer Buttons den Fokus hat. Der Inhalt eines Overlay liegt in der View, in der das Overlay ist, wo auch immer es angezeigt wird, sodass ein Popup als Teil der View zählt, die seinen Auslöser enthält. In Rust bekommt eine Komponente mit dem on_focus_in(..) und on_focus_out(..) ihrer Ref mit, wie der Fokus in ein Element hineinkommt und es verlässt: Der Wechsel zwischen Views darin ist keines von beidem.

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 und Identität

#Gesten, die animierte Werte steuern

Diese Props binden eine Geste an native animierte Werte, die sich auf dem UI-Thread bewegen, ohne dass der Code der App pro Frame etwas tun muss. Siehe Touch und Gesten.

PanEvent ist { cancelled, translation, velocity, value? } (in Rust cancelled, translation, velocity_x, velocity_y, value_x, value_y): ob das System den Drag abgebrochen hat, die Verschiebung seit dem Start und die Geschwindigkeit in Punkten pro Sekunde (Points) sowie die gebundenen Werte in diesem Moment, { x?, y? } für die Achsen, die pan bindet (ein Drag kann einen Wert mitten in einer Animation greifen).

#Rohe Touches und das Responder-System

Für Gesten, die die obigen Props nicht abdecken, nimmt jedes Element die Touch- und Responder-Props an: onTouchStart, onTouchMove, onTouchEnd, onTouchCancel (und ihre …Capture-Formen), onStartShouldSetResponder, onMoveShouldSetResponder (und …Capture), onResponderGrant, onResponderReject, onResponderStart, onResponderMove, onResponderEnd, onResponderRelease, onResponderTerminate und onResponderTerminationRequest. Jeder Handler erhält ein GestureResponderEvent ({ identifier, locationX, locationY, pageX, pageY, target, timestamp, touches, changedTouches, nativeEvent, stopPropagation() }); the …ShouldSetResponder handlers also get a gestureState (dx, dy, vx, vy, …). Wenn onResponderGrant den Wert true zurückgibt, nehmen native Scroll-Views die Touches nicht an. panActivation ({ activeOffsetX, activeOffsetY, failOffsetX, failOffsetY }) macht die View erst dann zum Responder, wenn die Plattform ihren Pan aktiviert, sodass Drags in Scroll-Views die andere Achse ihnen überlassen (Touch und Gesten). PanResponder in PanResponder baut darauf auf. In Rust bekommt .on_touch(..) jeden Touch mit (TouchEvent), .claim_touches(..) entscheidet, wann die View sie annimmt, und .on_responder_grant(..), .on_responder_move(..), .on_responder_release(..) und die anderen folgen dem Responder.

#Barrierefreiheit

Siehe Barrierefreiheit.

#Plattformspezifische Props

Props, die nur auf einer Plattform existieren, stehen in TSX in einem nach ihr benannten Objekt, sodass die gemeinsamen Props überall gleich bleiben. Nur das Objekt der aktuellen Plattform wird gesendet; die anderen werden ignoriert. Rust-Builder nehmen sie als Methoden an, die auf ihrer Plattform wirken.

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>

Siehe plattformspezifischer Code.

#Ref-Methoden

In TSX erhält ref die Ref des Elements, deren Typ der eigene Typ des Elements ist: ViewRef (focus, blur, measure) für View, Text, Image, Canvas, Overlay und Shader, und ein Typ über ViewRef mit den Methoden des Elements für die übrigen: InputRef (Input), ScrollRef (Scroll), ListRef (List), WebViewRef (WebView), VideoRef (Video) und NativeComponentRef (native Komponenten). In Rust erzeugt element_ref() ein ElementRef-Handle, das .element_ref(&handle) anhängt. Ihre Methoden senden Befehle an die native View, und zwar in der Reihenfolge der Änderungen, die im selben Turn vor ihnen vorgenommen wurden. Die Seite des jeweiligen Elements gibt an, welche Methoden für es gelten. Typisiere eine Ref-Variable mit dem eigenen Typ ihres Elements (let field!: InputRef für ein <Input>): Eine Variable vom Typ ViewRef passt nicht zu einem Element, dessen Ref eigene Methoden hat.

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>;

#Warum Handler die UI nie blockieren

Der Main-Thread wartet nie auf den Code der App. Wenn das System sofort eine Antwort braucht (darf sich dieser Text ändern, darf der Zurück-Button die Seite entfernen, darf dieses Sheet geschlossen werden), beantwortet NSH das nativ anhand von Props, die vorher gesetzt wurden (maxLength, popOnBack, closeOnSwipe, …), und das Ereignis erreicht die App erst danach. Deshalb ist ein solches Verhalten eine Prop und kein Rückgabewert eines Handlers.