Элементы

Native Shell строит каждый экран из небольшого набора элементов: примитивов, таких как View, Text и Image, и базовых компонентов, таких как Button, Dialog и NavStack. Каждый примитив — это нативное представление (подкласс UIView на iOS и Mac Catalyst, Android View, представление 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(..)), стили состояний принимают замыкание (.active(|s| s.opacity(0.6))), обработчики — это замыкания, получающие своё событие (.on_press(move || ..), .on_change(move |text: &str| ..)), а .child(..) добавляет дочерние элементы. Фрагмент UI — это обычная функция, возвращающая impl IntoElement; она выполняется один раз, а сигналы, которые она читает в замыканиях (text(move || ..), .bg(move || ..)), обновляют то, с чем связаны. См. Сборка на Rust.

В TSX каждый тег пишется в PascalCase и называет привязку в области видимости: примитивы приходят из nsh, базовые компоненты — из nsh/base. Только <If> и <Each> являются глобальными и не требуют импорта. Тег в нижнем регистре, например <view>, — это ошибка сборки, потому что TypeScript проверял бы его по одному глобальному типу на имя, а обобщённые компоненты, такие как 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 удерживают содержимое вне системного UI с помощью env() из CSS: env(safe-area-inset-top) и остальные края (Безопасная область) и env(keyboard-inset-height) (Клавиатура).

#Базовые компоненты

Импортируются из nsh/base в TSX, из крейта nsh_base в Rust. Они отвечают за поведение, состояние, фокус и доступность, а внешний вид берут из приложения.

#Общие свойства

Каждый примитив принимает перечисленные ниже свойства (тип CommonProps в TSX; трейты Styled, Interactive и Accessible в Rust). На страницах элементов перечислены только их собственные свойства. В столбце Rust указан метод построителя.

#Стилизация

#Нажатия и обратная связь

Обработка нажатий выполняется нативно: платформа распознаёт нажатие и применяет стили нажатия приложения, а код приложения узнаёт о нём только потом. Отвечает только самое внутреннее нажимаемое представление; внутри scroll view начало нажатия ждёт около 130 мс, чтобы сначала могла начаться прокрутка.

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) применяется, пока представление нажато, нативно, без обращения к коду приложения (см. ниже).

#Стили состояний

Стили, которые применяются, пока представление находится в некотором состоянии, поверх его собственных стилей, нативно. Каждый из них — объектная форма варианта 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 (наведение)

Приложение слышит, как мышь заходит на представление, движется над ним и уходит с него: на macOS, Windows, Linux, в бэкенде GPUI и в настольных браузерах, с указателем iPad или мышью Mac на iOS, а также с мышью или стилусом на Android. Стили наведения (hover:, .hover(..)) оформляют представления под курсором в тех же местах.

Как и CSS :hover и 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, responder), и его движения доходят до 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-щелчок на 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 (жесты, управляющие анимируемыми значениями)

Эти свойства привязывают жест к нативным анимируемым значениям, которые двигаются в UI-потоке, без работы кода приложения на каждый кадр. См. касания и жесты.

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 (сырые касания и система responder)

Для жестов, которые не покрывают свойства выше, каждый элемент принимает свойства касаний и responder: 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 не даёт нативным scroll-представлениям забрать касания. panActivation ({ activeOffsetX, activeOffsetY, failOffsetX, failOffsetY }) делает представление responder только после того, как платформа активирует его pan, поэтому перетаскивания внутри scroll-представлений оставляют другую ось им (Касания и жесты). PanResponder в PanResponder строится на них. В Rust .on_touch(..) слышит каждое касание (TouchEvent), .claim_touches(..) решает, когда представление их забирает, а .on_responder_grant(..), .on_responder_move(..), .on_responder_release(..) и остальные следуют за responder.

#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 (нативные компоненты). В Rust element_ref() создаёт дескриптор ElementRef, который подключает .element_ref(&handle). Методы дескриптора отправляют команды нативному представлению в том же порядке, что и изменения, сделанные до них в том же такте. На странице каждого элемента указано, какие методы к нему применимы. Типизируйте переменную 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>;

#Почему обработчики никогда не блокируют UI

Главный поток никогда не ждёт код приложения. Когда системе нужен ответ немедленно (можно ли изменить этот текст, можно ли кнопке «назад» убрать экран, можно ли закрыть этот лист), NSH отвечает на него нативно, исходя из заранее заданных свойств (maxLength, popOnBack, closeOnSwipe, …), а событие попадает в приложение уже после этого. Поэтому такое поведение задаётся свойством, а не возвращаемым значением обработчика.