元素

Native Shell 以一小組元素構建每個畫面:View、Text 和 Image 等基本元素,以及 Button、Dialog 和 NavStack 等基礎元件。每個基本元素都是原生視圖(在 iOS 和 Mac Catalyst 上是 UIView 子類別,在 Android 上是 View,在桌面平台上是 AppKit、GTK 或 Win32 視圖),由 NSH runtime 建立並排版。應用程式顯示的一切都由它們組成:應用程式的按鈕、卡片、列和畫面都是它自己的元件,以這些元素繪製並由應用程式設定樣式,所以應用程式的外觀完全由自己決定。

這些頁面上的每個範例都提供 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 crate。樣式是有型別的方法(.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 || ..))中讀取的 signal 會更新它們所綁定的內容。參閱以 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";

#基本元素

TSX 中從 nsh 匯入,Rust 中從 nsh_core::prelude 匯入。

內距(padding)和外距(margin)可使用 CSS 的 env() 讓內容避開系統 UI:env(safe-area-inset-top) 及其他邊緣(安全區域)和 env(keyboard-inset-height)(鍵盤)。

#基礎元件

TSX 中從 nsh/base 匯入,Rust 中來自 nsh_base crate。它們負責行為、狀態、焦點和無障礙功能,外觀則由應用程式決定。

#通用屬性

每個基本元素都接受以下屬性(TSX 中為 CommonProps 型別;Rust 中為 Styled、Interactive 和 Accessible trait)。各元素頁面只列出其專屬屬性。Rust 欄列出對應的建構方法。

#樣式

#按壓與回饋

按壓處理在原生層執行:平台負責識別按壓並套用應用程式的按壓樣式,應用程式的程式碼事後才會得知。只有最內層的可按壓視圖會作出回應;在捲動視圖內,按下(press-in)會等待約 130 毫秒,讓捲動可以先開始。

PressEvent 是 { position, pagePosition, modifiers, clickCount }:指標在視圖內及其根視圖內的位置(Point),按壓開始時按住的修飾鍵,以及連續點擊次數(雙擊為 2)。若平台沒有回報指標,則為視圖的原點、沒有按鍵,點擊次數為一。

樣式鍵 pointerEvents(Rust 中為 .pointer_events(PointerEvents::BoxNone),class 為 pointer-events-*)決定視圖本身及其內部視圖接收哪些觸控:"none" 兩者皆不接收(內部設定 "auto" 的視圖會重新接收),"box-none" 只有其內部的視圖接收,"box-only" 只有視圖本身接收(觸控與手勢)。

按壓回饋由應用程式決定:activeStyle(或 active: class,Rust 中為 .active(..))在視圖被按壓期間以原生方式套用,無需與應用程式的程式碼往返溝通(見下文)。

#狀態樣式

當視圖處於某個狀態時套用的樣式,以原生方式疊加在其自有樣式之上。每一項都是 Tailwind variant 的物件形式。後面的狀態優先(selected、checked 和 indeterminate,其次是 hover、focus、active);disabledStyle 優先於全部,而在視圖停用時,其他狀態都不會套用。每一項都接受該元素自己的樣式:<Text> 上為 TextStyle,<Input> 上為 InputStyle,<Image> 上為 ImageStyle,其他元素為 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>

#懸停

App 可以偵測滑鼠移入視圖、在其上移動及移出：支援 macOS、Windows、Linux、GPUI 後端和桌面瀏覽器；在 iOS 上支援 iPad 的指標或 Mac 的滑鼠；在 Android 上支援滑鼠或觸控筆。懸停樣式（hover:、.hover(..)）會在相同的平台上為被懸停的視圖設定樣式。

與 CSS 的 :hover 和 DOM 的 mouseenter 一樣，只要滑鼠在視圖上，或在其內任何內容上，該視圖即算被懸停，因此滑鼠下方那個視圖的外層視圖同樣會收到 onMouseEnter（由外至內；onMouseLeave 則由內至外）。這些事件在事後才觸發，觸控時永不觸發。若滑鼠下方的視圖被移除，該視圖會收到 onMouseLeave，在 Linux 和 Windows 上要待下次滑鼠移動時才收到。

MouseEvent 說明滑鼠的位置，與 GPUI 的 MouseMoveEvent 相同：position 是在該視圖內的位置（以點為單位的 Point，已還原其變換）；pagePosition 是在其所屬根視圖內的位置，與觸控事件提供的一致；modifiers 是按住的修飾鍵（control、alt、shift、platform：在 Apple 平台上是 Command，在其他平台上是 Windows 鍵）；pressedButton 是按住的按鈕（"left"、"right"、"middle"、"back" 或 "forward"，即 GPUI 的 MouseButton），或 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>

#工具提示

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 自行設定外觀、位置、延遲和事件，就像 GPUI 的 .tooltip(..) 所接受的那樣。工具提示很多的 app，會自備一個小元件，把文字包在它的 Tooltip 中。

#情境選單

onContextMenu 會告知視圖，其上按下了次要按鈕：右鍵按一下、macOS 上的 Control-按一下、觸控板上的雙指按一下、iPad 指標的次要按一下；在瀏覽器中還包括鍵盤的選單鍵。在此打開 app 自己的選單；在 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。

#鍵盤焦點

在 macOS 和網頁上，Tab 鍵會按樹狀順序在各個停駐點之間移動鍵盤焦點：輸入框、接受按下操作的視圖，以及每個 focusable 視圖。焦點樣式（focus:、.focus(..)）會為取得焦點的視圖設定樣式；若視圖接受按下操作，按 Return 或空白鍵即可按下它。點按會按下視圖但不會令它取得焦點，因此焦點樣式只會在鍵盤焦點下顯示。

焦點和按下操作是分開的。在取得焦點時接收按鍵的視圖（圖表、滑桿、以方向鍵移動選擇項的列表）會設定 focusable，並在取得焦點時綁定其按鍵（onFocus / onBlur，配合 keymap）；按下它時，操作仍會傳到其外層可按下的視圖，例如會打開頁面的卡片。

ref 的 focus() 會像 Tab 鍵一樣把鍵盤焦點移到某個停駐點（其焦點樣式會顯示，onFocus 也會觸發），例如在彈出視窗關閉後把焦點交還給觸發它的元素；blur() 則會移除焦點。

外層視圖可在焦點位於自身或其內任何視圖時，用 focus-within:（focusWithinStyle、.focus_within(..)）設定自己的樣式：例如包住正在編輯的輸入框的欄位外框，或其中一個按鈕取得焦點時的工具列。Overlay 的內容算作該疊加層所在視圖之內，不論它顯示在何處，因此彈出視窗算是包含其觸發元素的視圖的一部分。在 Rust 中，元件可透過其 ref 的 on_focus_in(..) 和 on_focus_out(..) 得知焦點進入和離開某個元素：在元素內部的視圖之間移動則兩者皆不算。

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>

#版面配置與識別

#以手勢驅動動畫值

這些屬性把手勢綁定到原生動畫值，動畫值在 UI 執行緒上移動，app 的程式碼無需逐幀處理。參閱觸控與手勢。

PanEvent 是 { cancelled, translation, velocity, value? }（在 Rust 中為 cancelled、translation、velocity_x、velocity_y、value_x、value_y）：包括系統是否取消了拖曳、自開始以來的位移、以每秒點數計的速度（各個 Point），以及當下已綁定的值，即 { x?, y? }，對應 pan 所綁定的軸（拖曳可以在動畫進行中抓住某個值）。

#原始觸控與 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, …）。 在 onResponderGrant 中回傳 true 可防止原生捲動視圖接管觸控。panActivation （{ activeOffsetX, activeOffsetY, failOffsetX, failOffsetY }）會令視圖只在平台啟動其平移手勢之後才成為 responder，因此捲動視圖內的拖曳會把另一個軸留給捲動視圖 （觸控與手勢）。 PanResponder 中的 PanResponder 建基於這些屬性。在 Rust 中，.on_touch(..) 會接收每一次觸控 （TouchEvent），.claim_touches(..) 決定視圖何時接管觸控，.on_responder_grant(..)、 .on_responder_move(..)、.on_responder_release(..) 及其他則跟隨 responder。

#無障礙功能

參閱無障礙功能。

#平台專屬屬性

只存在於單一平台的屬性，在 TSX 中放在以該平台命名的物件內，因此共用屬性在各處都保持一致。只有當前平台的物件會被傳送，其餘的會被忽略。Rust builder 則以方法接受這些屬性，並只在相應平台上生效。

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

主執行緒從不等待應用程式的程式碼。當系統需要即時得到答覆時（是否允許此文字變更、返回按鈕是否可以彈出、此 sheet 是否可以關閉），NSH 會根據事先設定的 prop（maxLength、popOnBack、closeOnSwipe……）在原生層直接回應，事件其後才會傳到應用程式。這就是此類行為屬於 prop，而不是處理函式回傳值的原因。