nsh

nsh 是核心模組,包含:響應式 API(signal、computed、effect、context)、mount、token、宿主元素 View、Text、Scroll 和 Overlay、可選取的視圖、安全區域與鍵盤、動畫、裝置及其環境、PanResponder、剪貼簿、相片選取器、語音辨識、儲存、宿主通道、鍵盤快速鍵、原生元件與模組、無障礙功能,以及元素、樣式和事件的 TypeScript 型別。響應式圖本身在 Rust 中原生運行;讀取 signal 是對執行環境發出的一次呼叫,只需數奈秒,只有你自己的閉包才會在 JavaScript 直譯器中運行。

import { batch, cleanup, computed, context, effect, ErrorBoundary, mount, Overlay, Scroll, signal, split, Text, token, untracked, View } from "nsh";
import { Input } from "nsh/base";

NSH 的響應式機制與 SolidJS 採用相同的模型:元件函式只會執行一次,UI 中讀取了 signal 的部分會在這些 signal 改變時就地更新。元件不會重新渲染,也沒有虛擬 DOM。指南請參閱響應式。

#signal

function signal<T>(value: T, options?: SignalOptions<T>): Signal<T>;
function signal<T = undefined>(): Signal<T | undefined>;

interface Signal<T> {
  (): T;                              // read (tracked)
  set(value: T): void;                // write
  update(fn: (value: T) => T): void;  // write from the current value
}

interface SignalOptions<T> {
  /** When a new value counts as a change (default `===`); `false`: always. */
  equals?: false | ((previous: T, next: T) => boolean);
}

signal 保存一個值。呼叫它即可讀取該值,而在追蹤範圍內(JSX 表達式、computed、effect)讀取時,會讓該範圍訂閱它。set 和 update 會寫入新值,所有讀取過它的地方都會隨之更新。

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

function Counter() {
  const count = signal(0);
  return (
    <View style={{ padding: 24, gap: 12 }}>
      <Text>Count: {count()}</Text>
      <Text onPress={() => count.update((n) => n + 1)}>Add one</Text>
    </View>
  );
}

mount(Counter);

預設情況下,寫入與目前值 === 的值時不會有任何作用。傳入 equals: false 可使每次寫入都發出通知(適用於就地修改物件後再次設定同一個物件的情況),也可以傳入你自己的比較函式:

const items = signal<string[]>([], { equals: false });
const point = signal({ x: 0, y: 0 }, { equals: (a, b) => a.x === b.x && a.y === b.y });

#computed

function computed<T>(fn: (previous: T | undefined) => T, options?: SignalOptions<T>): Accessor<T>;

interface Accessor<T> {
  (): T;
}

由 signal 衍生出來的值。當 fn 讀取過的 signal 改變時,它會再次執行;computed 值的讀取者只有在其結果改變時才會更新(以 equals 比較,預設為 ===)。fn 會接收上一次的結果。

const first = signal("Ada");
const last = signal("Lovelace");
const full = computed(() => `${first()} ${last()}`);
full(); // "Ada Lovelace"

當衍生計算開銷較大,或需要在多處讀取時,請使用 computed。對於簡單的表達式,使用普通函式(const full = () => first() + " " + last())同樣具有響應性。

#effect

function effect(fn: () => void): void;

在渲染後執行 fn,之後每當它讀取過的 signal 改變時再次執行。effect 用於處理副作用:記錄日誌、計時器、與原生模組通訊。effect 屬於建立它的元件(或 effect),並會隨之一併被銷毀。

const query = signal("");
effect(() => {
  console.log("query is now", query());
});

若要在 effect 再次執行之前(或其元件移除時)還原某些操作,請在 effect 內呼叫 cleanup。

#batch

function batch<T>(fn: () => T): T;

執行 fn,並在結束時一次過套用其中所有寫入,讓讀取者只更新一次,而不是每次寫入都更新。回傳 fn 的回傳值。

batch(() => {
  first.set("Grace");
  last.set("Hopper");
}); // `full` recomputes once

#untracked

function untracked<T>(fn: () => T): T;

執行 fn,但不會讓目前範圍訂閱其中讀取的內容。當你想在 effect 或 JSX 表達式內讀取某個 signal 而不依賴它時,請使用此函式。

effect(() => {
  // Runs again when `query` changes, not when `page` changes.
  search(query(), untracked(() => page()));
});

#cleanup

function cleanup(fn: () => void): void;

註冊 fn,使其在目前的 effect 再次執行之前,或目前的元件或 effect 移除時執行。

function Clock() {
  const now = signal(new Date());
  const timer = setInterval(() => now.set(new Date()), 1000);
  cleanup(() => clearInterval(timer));
  return <Text>{now().toLocaleTimeString()}</Text>;
}

#context

function context<T>(defaultValue: T): Context<T>;

interface Context<T> extends Accessor<T> {
  Provider: (props: { value: T; children?: JSX.Element }) => JSX.Element;
}

元件向其渲染的所有內容提供的值,無論層級多深。呼叫 context(Theme())會讀取最近的提供者所提供的值;若沒有提供者,則得到 defaultValue。

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

const Theme = context<"light" | "dark">("light");

function Label(props: { text: string }) {
  return <Text style={{ color: Theme() === "dark" ? "#fff" : "#000" }}>{props.text}</Text>;
}

function App() {
  const dark = signal(false);
  return (
    <Theme.Provider value={dark() ? "dark" : "light"}>
      <View style={{ flex: 1, padding: 24, backgroundColor: dark() ? "#000" : "#fff" }}>
        <Label text="Hello" />
        <Text onPress={() => dark.update((d) => !d)}>Toggle</Text>
      </View>
    </Theme.Provider>
  );
}

mount(App);

#mount

function mount<P extends object>(app: Component<P>, props?: P): () => void;

將 app 渲染到畫面(視窗,或應用程式所嵌入的 NshAppView / NshView),並回傳一個用來移除它的函式。每個應用程式的入口檔案都以 mount(App) 結尾。

mount(App);

#split

function split<T extends object, K extends readonly (keyof T)[]>(
  props: T,
  keys: K,
): [Pick<T, K[number]>, Omit<T, K[number]>];

將 props 物件拆分為 keys 中列出的 props 和其餘 props。兩部分都保持響應性:值會改變的 props 是 getter,而 split 會將它們保留為 getter。當元件自行處理部分 props 並把其餘的傳遞下去時,請使用它。若解構 props(const { label } = props),只會讀取一次,並會失去後續的更新。

import { split, Text, View } from "nsh";
import { Input, type InputProps } from "nsh/base";

function LabeledInput(props: InputProps & { label: string }) {
  const [own, rest] = split(props, ["label"]);
  return (
    <View style={{ gap: 4 }}>
      <Text>{own.label}</Text>
      <Input {...rest} />
    </View>
  );
}

#ErrorBoundary

function ErrorBoundary(props: {
  fallback: JSX.Element | ((error: unknown, reset: () => void) => JSX.Element);
  children?: JSX.Element;
}): JSX.Element;

渲染其子元素;當其下任何內容拋出錯誤(元件主體、綁定、effect 或事件處理函式)時,則渲染 fallback。失敗的部分會被移除,並由 fallback 取代顯示。函式 fallback 會以 fallback(error, reset) 的形式被呼叫,傳入拋出的值和 reset(用於再次渲染子元素),無論它宣告了哪些參數;fallback 元素則按原樣顯示。錯誤會交給其上最近的 boundary 處理,而 fallback 中的錯誤則交給再上一層的 boundary。Rust 元件使用 catch_error(錯誤邊界)。

import { ErrorBoundary, Text, View } from "nsh";

function Feed() {
  return (
    <ErrorBoundary
      fallback={(error, reset) => (
        <View>
          <Text>{error instanceof Error ? error.message : String(error)}</Text>
          <Text onPress={reset}>Try again</Text>
        </View>
      )}
    >
      <Posts />
    </ErrorBoundary>
  );
}

#token

function token<K extends keyof Tokens>(name: K): Tokens[K];

取得應用程式主題(在 nsh.json 中為 "theme",基於 shadcn/ui 的 token)的設計 token name,並依目前顯示的外觀返回對應值: 顏色以 #rrggbbaa 表示,長度以點數表示,字型則以其字體系列名稱表示。名稱即主題的 CSS 變數, 不含 --(primary、muted-foreground、radius、font-mono,以及應用程式自訂的,例如 up)。讀取 token 具有 響應性:讀取了 token 的元件、memo 或 effect,會在主題或外觀改變時再次執行。 Tokens 會列出應用程式的 token 及其型別;NSH 會根據主題將它寫入 .nsh/types/nsh/tokens.d.ts。至於 class,請直接寫出 token 名稱(bg-primary、rounded-(--radius)):主題 token。

import { effect, token } from "nsh";

effect(() => console.log("primary is", token("primary"), "radius", token("radius")));

#View, Text, Scroll, Overlay

function View(props: ViewProps): JSX.Element;
function Text(props: TextProps): JSX.Element;
function Scroll(props: ScrollProps): JSX.Element;
function Overlay(props: OverlayProps): JSX.Element;

nsh 匯出的宿主元素,以標籤形式書寫:<View>、<Text>、<Scroll>、<Overlay>(將其 子元素顯示在視窗最上層,並相對於錨點定位:Overlay)。對於透過 import 指向其中之一的標籤(別名亦然),編譯器會 就地建立原生視圖,因此匯入它們在執行時不會產生 任何開銷。它們與其他元件一樣都是元件,因此也可以被傳遞(const Tag = inline ? Text : View)。 nsh 以相同方式匯出其他基本元件:List、Image、 Canvas、WebView和 Video,各自有專屬的參考 頁面。它們的 props 記載於元素之下。文字輸入框 Input 來自 nsh/base。

#安全區域與鍵盤

CSS 的環境變數可讓內容避開系統 UI,可用於任何視圖的 padding 和 margin (padding、paddingTop 等,即相同的 margin 鍵;Tailwind 的 p* / m* 任意值;Rust 中的 Styled 方法 .p_safe_area()、.pt_safe_area_plus(..)、.pb_keyboard() 等)。它們的值是 EnvValue: env(name)、env(name, <length>)、calc(env(name) + <length>) 和 calc(<length> + env(name))。

<View style={{ flex: 1, paddingTop: "env(safe-area-inset-top)", paddingBottom: "env(keyboard-inset-height)" }}>…</View>

#safeArea 與 safeAreaInsets

safeArea() 是畫面的安全區域(Rust 中為 safe_area());safeAreaInsets() 是元件所在位置的內縮距離 (Rust 中為 cx.insets()),即 safe-area-inset-* 變數的值。兩者都是具響應性的 Edges ({ top, right, bottom, left },單位為點)。請參閱 safeArea 與 safeAreaInsets。

#Keyboard 與 keyboardFrame

Keyboard.dismiss() 會隱藏軟鍵盤(Rust 中為 dismiss_keyboard()),keyboardFrame() 則告訴你鍵盤遮蓋了 多少畫面(Rust 中為 keyboard_height() 和 keyboard_duration())。請參閱 隱藏鍵盤和 鍵盤的高度。

#可選取的視圖

<View selectable>(Rust 中為 view().selectable(true))會讓其內的文字可以一同被選取,就像網頁一樣: 一次選取可橫跨多個視圖、Text 元素和 TextView,並依閱讀順序排列。請參閱 文字選取。

#動畫

動畫 API 在 UI 執行緒上播放動畫。你建立一個動畫值,將它(或由它衍生的值)綁定到樣式屬性,然後啟動動畫;此後每一幀都在原生層計算, 無需執行應用程式的程式碼。即使引擎或 JS 執行緒繁忙,也不會令動畫卡頓,而且動畫不會為應用程式帶來每幀的運算負擔。Rust 程式碼使用 nsh_core::prelude 中的 animated_value()、motion()、Animation、Spring、Timing、KeyframeTiming、MotionPreset 和 Easing,並透過元素的 .bind_* 方法綁定值;TSX 則從 nsh 匯入它們。

use nsh_core::{element::LayoutAnimation, prelude::*}; // animated_value, motion, Animation, Spring, Timing, Keyframe, KeyframeTiming, MotionPreset, MotionSpec, Easing, animate_layout

import { Animated, createAnimatedValue, createMotion, motions, Easing, LayoutAnimation, AnimatedNode, AnimatedValue } from "nsh";

指南請參閱動畫。

#動畫值可以驅動什麼

其他樣式屬性只接受普通值;若要為版面本身(尺寸、在流中的位置)加入動畫,請使用 LayoutAnimation。

#createAnimatedValue

function createAnimatedValue(value?: number): AnimatedValue;

建立一個動畫值,起始值為 value(預設為 0)。Rust:animated_value(value),即由建立它的元件持有的 Copy 控制代碼。

use nsh_core::prelude::*;

#[component]
pub fn App() -> impl IntoElement {
    let x = animated_value(0.0);
    let right = stored(false);
    let toggle = move || {
        let to_right = !right.get();
        right.replace(to_right);
        let _ = x.spring(if to_right { 200.0 } else { 0.0 }, Spring::default());
    };
    view()
        .flex_1()
        .p_6()
        .pt_12()
        .gap_4()
        .child(view().size(px(60.0)).rounded(px(12.0)).bg(rgb(0x6366f1)).bind_translate_x(&x))
        .child(text("Move").on_press(toggle))
}

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

function App() {
  const x = createAnimatedValue(0);
  let right = false;
  const toggle = () => {
    right = !right;
    x.spring(right ? 200 : 0);
  };
  return (
    <View style={{ flex: 1, padding: 24, paddingTop: 48, gap: 16 }}>
      <View style={{ width: 60, height: 60, borderRadius: 12, backgroundColor: "#6366f1", transform: [{ translateX: x }] }} />
      <Text onPress={toggle}>Move</Text>
    </View>
  );
}

mount(App);

#AnimatedValue

class AnimatedValue extends AnimatedNode {
  constructor(value: number);
  set(value: number): void;
  stop(): Promise<{ value: number }>;
  getValue(): Promise<number>;
  setOffset(offset: number): void;
  flattenOffset(): void;
  extractOffset(): void;
  timing(to: number, options?: { duration?: number; easing?: Easing; delay?: number }): Promise<{ finished: boolean }>;
  spring(to: number, options?: { stiffness?: number; damping?: number; mass?: number; velocity?: number }): Promise<{ finished: boolean }>;
  decay(options?: { velocity?: number; deceleration?: number; clamp?: [number, number]; bounce?: number }): Promise<{ finished: boolean }>;
  keyframes(keyframes: KeyframeValue[], options?: KeyframeTiming): Promise<{ finished: boolean }>;
}

每個動畫方法都會回傳一個 promise,以 { finished } 解析:動畫完成時為 true,被停止時(由 stop、set 或同一個值的另一個動畫停止)為 false。在 Rust 中它回傳 AnimationEnd,任務可 await 它以取得相同的 bool。

let opacity = animated_value(1.0);
spawn(async move {
    if opacity.timing(0.0, 200.0, Easing::EaseInOut).await {
        visible.set(false);
    }
});

const opacity = createAnimatedValue(1);
const { finished } = await opacity.timing(0, { duration: 200 });
if (finished) visible.set(false);

#AnimatedNode

class AnimatedNode {
  interpolate(config: {
    inputRange: number[];
    outputRange: number[] | string[];
    extrapolate?: Extrapolation;
    extrapolateLeft?: Extrapolation;
    extrapolateRight?: Extrapolation;
    easing?: Easing;
  }): AnimatedNode;
  diffClamp(min: number, max: number, options?: { snap?: boolean }): AnimatedNode;
  add(b: AnimatedNode | number): AnimatedNode;
  sub(b: AnimatedNode | number): AnimatedNode;
  mul(b: AnimatedNode | number): AnimatedNode;
  div(b: AnimatedNode | number): AnimatedNode;
  mod(b: AnimatedNode | number): AnimatedNode;
}

type Extrapolation = "extend" | "clamp" | "identity";

原生動畫圖中的一個節點:可以是 AnimatedValue,也可以是由其他節點衍生出來的值。衍生節點會在其輸入改變時於 UI 執行緒上求值。

let scroll_y = animated_value(0.0);
let header = scroll_y.diff_clamp(0.0, 44.0);

view()
    .flex_1()
    .child(scroll().scroll_value(&scroll_y).flex_1() /* rows */)
    .child(view().h(px(44.0)).bind_translate_y(&header.mul(-1.0)))

const scroll = createAnimatedValue(0);
const header = scroll.diffClamp(0, 44);

<Scroll scrollValue={scroll} style={{ flex: 1 }}>{/* rows */}</Scroll>
<View style={{ height: 44, transform: [{ translateY: header.mul(-1) }] }} />

let progress = animated_value(0.0);
let rotate = progress.interpolate(&[0.0, 1.0], &[0.0, 360.0]); // degrees, for bind_rotate
let color = progress.interpolate_colors(&[0.0, 0.5, 1.0], &[rgb(0x22c55e), rgb(0xeab308), rgb(0xef4444)]);

const progress = createAnimatedValue(0);
const rotate = progress.interpolate({ inputRange: [0, 1], outputRange: ["0deg", "360deg"] });
const color = progress.interpolate({ inputRange: [0, 0.5, 1], outputRange: ["#22c55e", "#eab308", "#ef4444"] });

#Keyframes

interface Keyframe {
  offset?: number;          // 0..1 of an iteration; missing offsets spread evenly
  value: number | string;   // a number, or an angle ("45deg", "0.5turn") in degrees
  easing?: Easing;          // the segment that starts here
}
type KeyframeValue = number | string | Keyframe;

interface KeyframeTiming {
  duration?: number;        // one iteration, ms (300)
  delay?: number;           // before the first iteration, ms (0)
  easing?: Easing;          // segments without their own (CSS "ease")
  iterations?: number | "infinite";   // 1
  direction?: "normal" | "reverse" | "alternate" | "alternate-reverse";
}

value.keyframes(frames, options) 透過關鍵影格播放一個值，並以 { finished } 完成，表示是否播放完畢；Animated.keyframes(value, { keyframes, ...options }) 等同組合動畫中的一個步驟。Rust：value.keyframes(frames, KeyframeTiming) 和 Animation::keyframes(&value, frames, KeyframeTiming)，附有 Keyframe::new(value)（平均分佈）、Keyframe::at(offset, value) 和 .ease(easing)，以及 KeyframeTiming::new(ms)，附有 .delay(ms)、.easing(e)、.iterations(Some(n))、.infinite() 和 .direction(PlaybackDirection::…)。

它們的播放方式與 CSS 關鍵影格相同：每條緩動只作用於一個區段（關鍵影格的緩動作用於由它開始的區段，其餘區段則使用時序的緩動）；關鍵影格中缺少的偏移量會平均分佈，第一個位於 0，最後一個位於 1；每次迭代都先跳到其第一個關鍵影格，若沒有位於 0 的關鍵影格，數值則由當前位置開始；在 delay 期間，數值維持在第一個關鍵影格（CSS animation-fill-mode: backwards）；反向迭代會倒序播放各區段，並將其曲線反轉；數值停留在最後一次迭代結束的位置。

let y = animated_value(0.0);
y.keyframes(
    [Keyframe::new(0.0), Keyframe::at(0.3, -20.0).ease(Easing::EaseIn), Keyframe::new(0.0)],
    KeyframeTiming::new(600.0).iterations(Some(3)),
);

const y = createAnimatedValue(0);
y.keyframes([0, { offset: 0.3, value: -20, easing: "easeIn" }, 0], { duration: 600, iterations: 3 });

#createMotion

function createMotion(options?: MotionOptions): Motion;

interface MotionOptions extends MotionPlayOptions {
  initial?: { [C in MotionChannel]?: number };   // where channels start (the others at rest)
  enter?: MotionName | MotionSpec;   // start where it starts and play it at once
}

interface MotionPlayOptions extends KeyframeTiming {
  ignoreReduceMotion?: boolean;      // play even when the user asks for less motion
}

interface Motion {
  readonly opacity: AnimatedValue;
  readonly translateX: AnimatedValue;
  readonly translateY: AnimatedValue;
  readonly rotate: AnimatedValue;    // degrees
  readonly rotateX: AnimatedValue;
  readonly rotateY: AnimatedValue;
  readonly scale: AnimatedValue;
  readonly scaleX: AnimatedValue;
  readonly scaleY: AnimatedValue;
  readonly style: { opacity: AnimatedValue; transform: MotionTransform };
  readonly transform: MotionTransform;
  play(motion: MotionName | MotionSpec, options?: MotionPlayOptions): Promise<{ finished: boolean }>;
  animation(motion: MotionName | MotionSpec, options?: MotionPlayOptions): CompositeAnimation;
  stop(): void;
  reset(): void;
}

建立一個 motion：為視圖的不透明度和變換的每個通道各建立一個動畫值，初始處於靜止狀態（不透明度和縮放為 1，其餘為 0），並提供可在這些通道上以原生方式播放的 motion。使用 style={motion.style} 綁定，或將 motion.style 或 motion.transform 展開到樣式中；變換會先套用平移，再套用旋轉，最後套用縮放，其中 scale 會併入 scaleX 和 scaleY：這佔用了視圖 8 個變換步驟中的 7 個，餘下一個留給你自己使用（[{ perspective: 600 }, ...motion.transform] 用於 3D 翻轉）。initial 設定各通道的起始位置（{ opacity: 0 }；其餘通道由靜止狀態開始）。使用 enter 時，它所移動的通道會由該 motion 的起點開始（經過 initial），並立即播放，其餘選項則作為它的時序（delay、duration 等）。motion 只會移動不透明度和變換：展開 motion.style 會設定視圖的 opacity，因此若要保留自己設定的不透明度，請只綁定 motion.transform；顏色則應使用動畫值和 interpolate 來移動。Rust：motion()，這是由建立它的元件保管的 Copy 控制代碼，以 .bind_motion(&m) 綁定；motion().entering(spec) 負責進場。

當使用者要求減少動態效果（reduceMotion()）時，play、animation 和 enter 會立即跳到 motion 的終點，不產生移動，除非已設定 ignoreReduceMotion（在選項或 motion 上設定）。

let card = motion().entering(MotionPreset::FadeInUp.spec().timing(|t| t.delay(80.0)));
view().size(px(120.0)).rounded(px(16.0)).bg(rgb(0x0969da)).bind_motion(&card).on_press(move || {
    card.play(MotionPreset::Pulse);
})

const card = createMotion({ enter: "fadeInUp", delay: 80 });
<View onPress={() => card.play("pulse")} style={{ width: 120, height: 120, borderRadius: 16, backgroundColor: "#0969da", ...card.style }} />

#motions

const motions: Readonly<Record<MotionName, MotionPreset>>;

type MotionChannel = "opacity" | "translateX" | "translateY" | "rotate" | "rotateX" | "rotateY" | "scale" | "scaleX" | "scaleY";

interface MotionSpec extends KeyframeTiming {
  keyframes: { [C in MotionChannel]?: KeyframeValue[] } | MotionFrame[];
  ignoreReduceMotion?: boolean;
}
type MotionFrame = { [C in MotionChannel]?: number | string } & { offset?: number; easing?: Easing };

interface MotionPreset extends MotionSpec {
  kind: "enter" | "exit" | "attention" | "loop";
}

以資料形式提供的現成 motion：motion.play("shake") 會播放 motions.shake。MotionName 是以下其中之一：fadeIn、fadeInUp、fadeInDown、fadeInLeft、fadeInRight、zoomIn、popIn、bounceIn、slideInUp、slideInDown、flipInX、flipInY（進場）；fadeOut、fadeOutUp、fadeOutDown、fadeOutLeft、fadeOutRight、zoomOut、popOut、slideOutDown、slideOutUp（退場）；shake、headShake、wiggle、swing、pulse、heartbeat、rubberBand、jello、tada、jump、flash（引起注意）；spin、float、breathe、sway、bob、glow（循環）。Animation 說明每一個 motion。展開預設即可修改它：motion.play({ ...motions.fadeInUp, duration: 600 })。

MotionSpec 是你自訂的 motion：可以是每個通道的關鍵影格（{ opacity: [0, 1], translateY: [24, 0] }），也可以是如 Web Animations API 所寫的影格清單（[{ opacity: 0, translateY: 24 }, { opacity: 1, translateY: 0 }]，沒有偏移量的影格會按其在清單中的位置決定位置），並附上關鍵影格時序。Rust：MotionSpec::new(KeyframeTiming)，附有 .values(channel, values)（平均分佈）、.track(channel, keyframes) 和 .timing(|t| …)；MotionPreset::FadeInUp（或 .spec()）是預設，MotionChannel 則為各通道命名。

let rise = MotionSpec::new(KeyframeTiming::new(400.0))
    .values(MotionChannel::Opacity, [0.0, 1.0])
    .track(MotionChannel::TranslateY, [Keyframe::at(0.0, 24.0).ease(Easing::EaseOut), Keyframe::at(1.0, 0.0)]);
card.play(rise);

card.play({ duration: 400, keyframes: [{ opacity: 0, translateY: 24, easing: "easeOut" }, { opacity: 1, translateY: 0 }] });

#Animated

const Animated: {
  timing(value: AnimatedValue, config: { toValue: number; duration?: number; easing?: Easing; delay?: number }): CompositeAnimation;
  spring(value: AnimatedValue, config: { toValue: number; stiffness?: number; damping?: number; mass?: number; velocity?: number }): CompositeAnimation;
  decay(value: AnimatedValue, config?: { velocity?: number; deceleration?: number; clamp?: [number, number]; bounce?: number }): CompositeAnimation;
  sequence(list: CompositeAnimation[]): CompositeAnimation;
  parallel(list: CompositeAnimation[], config?: { stopTogether?: boolean }): CompositeAnimation;
  stagger(ms: number, list: CompositeAnimation[], config?: { from?: "first" | "last" | "center" | number }): CompositeAnimation;
  delay(ms: number): CompositeAnimation;
  loop(animation: CompositeAnimation, config?: { iterations?: number; resetBeforeIteration?: boolean }): CompositeAnimation;
  keyframes(value: AnimatedValue, config: KeyframeTiming & { keyframes: KeyframeValue[] }): CompositeAnimation;
  add(a: AnimatedNode, b: AnimatedNode | number): AnimatedNode;
  subtract(a: AnimatedNode, b: AnimatedNode | number): AnimatedNode;
  multiply(a: AnimatedNode, b: AnimatedNode | number): AnimatedNode;
  divide(a: AnimatedNode, b: AnimatedNode | number): AnimatedNode;
  modulo(a: AnimatedNode, b: AnimatedNode | number): AnimatedNode;
  diffClamp(a: AnimatedNode, min: number, max: number, options?: { snap?: boolean }): AnimatedNode;
  sampleSpring(config: SpringConfig & { from?: number }, fps?: number): number[];
  sampleDecay(config: DecayConfig & { from?: number }, fps?: number): number[];
};

interface CompositeAnimation {
  start(callback?: (result: { finished: boolean }) => void): Promise<{ finished: boolean }>;
  stop(): void;
  reset(): void;
}

Animated 以多個步驟（timing、spring、decay、sequence、parallel 等）組成動畫。在呼叫 start() 之前不會執行任何動作；呼叫後，整個樹會以原生方式執行，每個步驟都會在上一個步驟結束的一刻於 UI 執行緒上開始（沒有影格間隙，步驟之間也不需要回到應用程式的程式碼）。Rust 以 Animation 建立相同的樹。

CompositeAnimation：

let ys: Vec<AnimatedValue> = (0..4).map(|_| animated_value(0.0)).collect();
let hop = Animation::stagger(
    80.0,
    ys.iter().map(|y| {
        Animation::sequence([
            Animation::timing(y, -36.0, Timing::new(220.0, Easing::Curve(Curve::Quad, EaseMode::Out))),
            Animation::spring(y, 0.0, Spring { stiffness: 300.0, damping: 12.0, ..Spring::default() }),
        ])
    }),
);
let run = hop.start();
spawn(async move { log::info!("{}", if run.await { "done" } else { "stopped" }) });

const ys = [0, 1, 2, 3].map(() => createAnimatedValue(0));
const hop = Animated.stagger(
  80,
  ys.map((y) =>
    Animated.sequence([
      Animated.timing(y, { toValue: -36, duration: 220, easing: Easing.out(Easing.quad) }),
      Animated.spring(y, { toValue: 0, stiffness: 300, damping: 12 }),
    ]),
  ),
);
hop.start(({ finished }) => console.log(finished ? "done" : "stopped"));

#Easing

type Easing =
  | "linear" | "ease" | "easeIn" | "easeOut" | "easeInOut"
  | [number, number, number, number]   // cubic Bézier x1, y1, x2, y2
  | EasingCurve
  | EasingSteps;                     // Easing.steps(…)

const Easing: {
  linear: Easing;
  ease: Easing;
  bezier(x1: number, y1: number, x2: number, y2: number): Easing;
  steps(count: number, position?: "jump-start" | "jump-end" | "jump-none" | "jump-both" | "start" | "end"): EasingSteps;
  in(e: Easing): Easing;
  out(e: Easing): Easing;
  inOut(e: Easing): Easing;
  sample(easing: Easing, count: number): number[];
  quad: EasingCurve;
  cubic: EasingCurve;
  poly(n?: number): EasingCurve;
  sin: EasingCurve;
  circle: EasingCurve;
  exp: EasingCurve;
  elastic(bounciness?: number): EasingCurve;
  back(s?: number): EasingCurve;
  bounce: EasingCurve;
};

緩動是資料，而不是應用程式的函式：執行階段會以原生方式計算它。在 Rust 中，它是列舉 Easing：Linear、EaseIn、EaseOut、EaseInOut、Bezier(x1, y1, x2, y2)、Steps(count, StepPosition) 和 Curve(curve, mode)，另有 Curve（Quad、Cubic、Poly(n)、Sin、Circle、Exp、Elastic(bounciness)、Back(s)、Bounce）和 EaseMode（In、Out、InOut）。若要繪製緩動曲線，Easing.sample(easing, count)（Rust：nsh_core::element::sample_easing）會給出由 0 至 1 之間 count 個等距點上的數值；Animated.sampleSpring 和 Animated.sampleDecay（sample_spring、sample_decay）會給出彈簧或衰減動畫每影格一個的數值（按 fps，預設為 60），由 from（0）起直至結束。這三者都來自動畫所執行的原生程式碼。在 TSX 中凡接受 Easing 的地方，你都可以傳入名稱（"easeOut"）、以四個數字表示的三次貝茲曲線，或 Easing 物件中的曲線。

Easing.steps(count, position) 即 CSS 的 steps()：數值會在 count 個層級之間跳躍，而不是連續移動（例如逐格播放的精靈圖、滴答轉動的指針）。position 指定跳躍發生的位置："jump-end"（預設，亦可寫作 "end"）、"jump-start"（"start"）、"jump-none" 或 "jump-both"；Rust：Easing::Steps(count, StepPosition::JumpEnd)、JumpStart、JumpNone、JumpBoth。

這些曲線都是「in」形式（起步較慢）。Easing.out(curve) 會將曲線反轉，Easing.inOut(curve) 會令曲線對稱，Easing.in(curve) 則保持原樣；在 Rust 中，這是 Easing::Curve 的 EaseMode。

let _ = value.timing(1.0, 600.0, Easing::Curve(Curve::Back(1.70158), EaseMode::Out));
let _ = value.timing_with(1.0, Timing { easing: Easing::Bezier(0.2, 0.0, 0.0, 1.0), ..Timing::default() });
let _ = value.timing_with(1.0, Timing { easing: Easing::EaseOut, ..Timing::default() });

value.timing(1, { duration: 600, easing: Easing.out(Easing.back()) });
value.timing(1, { easing: Easing.bezier(0.2, 0, 0, 1) });
value.timing(1, { easing: "easeOut" });

#LayoutAnimation

const LayoutAnimation: {
  configureNext(config: LayoutAnimationConfig, onEnd?: () => void): void;
  create(duration: number, type?: LayoutAnimationType, property?: LayoutAnimationProperty): LayoutAnimationConfig;
  Types: { easeInEaseOut; spring; linear; easeIn; easeOut; keyboard };
  Properties: { opacity; scaleXY };
  Presets: { easeInEaseOut: LayoutAnimationConfig; linear: LayoutAnimationConfig; spring: LayoutAnimationConfig };
  easeInEaseOut(onEnd?: () => void): void;
  linear(onEnd?: () => void): void;
  spring(onEnd?: () => void): void;
};

interface LayoutAnimationConfig {
  duration: number;                // ms
  create?: LayoutAnimationAnimation;    // views inserted
  update?: LayoutAnimationAnimation;    // views moved or resized
  delete?: LayoutAnimationAnimation;    // views removed
}

interface LayoutAnimationAnimation {
  type?: "easeInEaseOut" | "spring" | "linear" | "easeIn" | "easeOut" | "keyboard";
  property?: "opacity" | "scaleXY" | "scale";
  duration?: number;
  delay?: number;
  springDamping?: number;          // 0..1, default 0.7
}

LayoutAnimation.configureNext(config) 會以原生方式為下一次提交中的版面變更加上動畫：移動或改變大小的視圖會平滑過渡到新的框架，新視圖會出現（按 property 淡入或縮放進場），被移除的視圖則會消失。請在改變版面的狀態變更之前立即呼叫它。Rust：animate_layout(LayoutAnimation)，可使用 nsh_core::element::LayoutAnimation 的預設，或其 create、update 和 delete 轉場。

let open = signal(false);
let toggle = move || {
    animate_layout(LayoutAnimation::SPRING);
    open.update(|o| *o = !*o);
};

view()
    .child(text("Details").on_press(toggle))
    .child(when(move || open.get(), || text("Shown with a spring.")))

const open = signal(false);
const toggle = () => {
  LayoutAnimation.configureNext(LayoutAnimation.Presets.spring);
  open.update((o) => !o);
};

<View>
  <Text onPress={toggle}>Details</Text>
  <If when={open()}>
    <Text>Shown with a spring.</Text>
  </If>
</View>

#Device

Device API 讓應用程式得知裝置及其環境的資訊。Rust 程式碼呼叫 nsh_core::prelude 的函式（window()、dark()、font_scale()、locale()、lifecycle()、os()、idiom()、pixel_ratio()、set_color_scheme() 等）；TSX 則從 nsh 匯入。視窗大小、色彩配置、字體縮放、像素比例、語言地區和應用程式狀態都是響應式的：在綁定（Rust 中傳給元素的閉包，TSX 中的 JSX）、computed 或 effect 中讀取它們，當平台通報變更（旋轉、調整視窗大小、切換到深色模式、更改文字大小或語言、移到另一種密度的螢幕、離開應用程式後再返回）時，讀取它們的內容就會隨之更新。

use nsh_core::{
    platform::{Appearance, Idiom, Lifecycle, Os},
    prelude::*, // window, dark, font_scale, locale, lifecycle, os, idiom, pixel_ratio, set_color_scheme, ...
};

import { colorScheme, fontScale, lifecycle, locale, openUrl, pixelRatio, platform, setColorScheme, windowSize } from "nsh";

指南請參閱裝置與環境。

#windowSize

const windowSize: Accessor<Size>;

介面的大小，以點（point）為單位：即視窗，或嵌入的 NshAppView / NshView。響應式。Rust：window() -> Size<Points>。

let wide = move || window().width >= px(600.0);

view().style_when(wide, |s| s.flex_row())

const wide = () => windowSize().width >= 600;

<View style={{ flexDirection: wide() ? "row" : "column" }}>{/* ... */}</View>

#colorScheme

const colorScheme: Accessor<"light" | "dark">;

所顯示的外觀：除非應用程式自行設定（nsh.json "appearance"、setColorScheme），否則為系統的外觀。響應式。Rust：dark() -> bool；主題顏色（AdaptiveColor）和 .dark(…) 樣式變體無需讀取它也會跟隨。Tailwind 的 dark: 變體也會跟隨它（見 Tailwind）。

view().flex_1().bg(move || if dark() { black() } else { white() })

const dark = () => colorScheme() === "dark";

<View style={{ flex: 1, backgroundColor: dark() ? "#000" : "#fff" }} />

#fontScale

const fontScale: Accessor<number>;

使用者偏好的文字大小相對於預設值的比例（1 為預設大小；iOS 上為 Dynamic Type，Android 上為字體大小），或由嵌入的應用程式改為設定的文字大小。響應式。Rust：font_scale() -> f32。文字已會隨之縮放，除非設定了 allowFontScaling={false}；當其他尺寸也應跟隨時（例如文字旁的圖示），請讀取它。

#locale

const locale: Accessor<string>;

使用者的語言地區，以 BCP 47 標籤表示（"en-US"、"zh-Hans-CN"），或由嵌入的應用程式改為設定的語言地區。響應式。Rust：locale() -> Locale（locale().as_str() 為標籤）。Intl 預設會按它格式化；請讀取它來選擇你自己翻譯的字串（裝置與環境）。

#lifecycle

const lifecycle: Accessor<"active" | "inactive" | "background">;

應用程式是否正在使用，以 React Native 的 AppState 術語表示："active" 表示位於前景並接受輸入，"inactive" 表示可見但沒有焦點（其他應用程式或視窗取得了焦點，或系統在其上方顯示內容，例如應用程式切換器或來電），"background" 表示不可見（在背景、已最小化、隱藏的瀏覽器分頁）。顯示在原生應用程式內的應用程式，會跟隨該原生應用程式的狀態。響應式。Rust：lifecycle() -> Lifecycle（Lifecycle::Active、Inactive、Background）。

在 effect 中讀取它，即可暫停無人看見的工作，並在應用程式返回時恢復：

effect(move || {
    if lifecycle() == Lifecycle::Background {
        feed.pause();
    } else {
        feed.resume();
    }
});

effect(() => {
  if (lifecycle() === "background") feed.pause();
  else feed.resume();
});

#setColorScheme

function setColorScheme(scheme: "light" | "dark" | "system"): void;

無論系統的外觀為何，立即以 scheme 顯示應用程式：colorScheme()、dark: 類別、元件的主題和平台的控制項（警示、狀態列的預設樣式）都會跟隨它；"system" 則會再次跟隨系統。nsh.json "appearance" 會在一開始就設定它。Rust：set_color_scheme(Appearance::Dark)（Appearance::Light、Appearance::System）。

#platform

const platform: Platform;

interface Platform {
  readonly os: "ios" | "android" | "macos" | "windows" | "linux" | "web";
  readonly version: string;
  readonly idiom: "phone" | "pad" | "mac" | "tv" | "desktop";
  readonly desktop: boolean;
  readonly catalyst: boolean;
  select<T>(spec: PlatformSelectSpec<T>): T | undefined;
}

應用程式執行所在的平台,執行期間保持不變。

let columns = if is_desktop() { 3 } else { 1 };

const columns = platform.desktop ? 3 : 1;

#platform.select

interface PlatformSelectSpec<T> {
  ios?: T;
  android?: T;
  macos?: T;
  windows?: T;
  linux?: T;
  web?: T;
  mobile?: T;   // platform.desktop false: iOS (Mac Catalyst included), Android, phone and tablet browsers
  desktop?: T;  // platform.desktop true: macOS, Windows, Linux, desktop browsers
  native?: T;   // every platform but the web
  default?: T;
}

傳回目前作業系統(ios、android、web 等)對應的值,否則依 platform.desktop 傳回 desktop 或 mobile,再否則傳回 native(除網頁外的所有平台),再否則傳回 default,最後傳回 undefined。Rust 程式碼則對 os() 進行比對(對 mobile / desktop 則使用 is_desktop())。

use nsh_core::platform::Os;

let card = view().p_4();
let card = match os() {
    Os::Ios => card.shadow([BoxShadow {
        offset_y: px(2.0),
        blur: px(8.0),
        color: rgba(0x00000026).into(),
        ..BoxShadow::default()
    }]),
    Os::Android => card.elevation(px(4.0)),
    _ => card,
};

const shadow = platform.select({
  ios: { boxShadow: "0px 2px 8px rgb(0 0 0 / 0.15)" },
  android: { elevation: 4 },
});

#pixelRatio

const pixelRatio: Accessor<number>;

每個點(point)對應的裝置像素數(例如大多數 iPhone 為 3)。具反應性:當視窗移到另一個密度不同的螢幕(在 Mac Catalyst、桌面平台或外接顯示器上),以及 Android 的顯示大小設定改變密度時,它都會隨之改變。Rust:pixel_ratio() -> f32,以及用於以整數裝置像素表示長度的 round_to_nearest_pixel(points);在 TSX 中該長度為 Math.round(x * pixelRatio()) / pixelRatio()。

let hairline = move || px(1.0 / pixel_ratio());

const hairline = () => 1 / pixelRatio();

#openUrl

function openUrl(url: string): Promise<OpenUrlResult>;

interface OpenUrlResult {
  opened: boolean;
}

在應用程式以外開啟 url:網頁會在瀏覽器開啟,mailto: 連結會在郵件應用程式開啟,tel: 連結會在電話應用程式開啟,其他應用程式登記的任何 scheme 也一樣(maps:、宿主應用程式自己的 lb:// 連結)。它會以 { opened } resolve,表示是否有東西開啟了它:當沒有應用程式處理該 scheme 時為 false。Rust:nsh_core::prelude 的 open_url(url),即在 task 中 await(或直接丟棄)的結果,同樣是 bool。

button()
    .child(text("Contact us"))
    .on_press(|| {
        spawn(async {
            if !open_url("mailto:help@example.com").await {
                log::warn!("no mail app");
            }
        });
    })

<Button
  onPress={async () => {
    const { opened } = await openUrl("mailto:help@example.com");
    if (!opened) {
      console.warn("no mail app");
    }
  }}
>
  <Text>Contact us</Text>
</Button>

• URL 必須是絕對 URL(帶有 scheme)。會執行程式碼或存取應用程式自身資料的 URL,即 javascript:、data:、blob:、file:、about: 和 asset:,以及相對位址,都會令 promise 以 TypeError reject。openUrl 從不丟出例外:所有失敗都會 reject。
• 聲明了 capabilities 的應用程式需要 openUrl:"openUrl": true 表示所有 scheme,"openUrl": { "schemes": ["https", "mailto"] } 表示所列出的 scheme;其他 URL 會以 Error reject,其 code 為 "ERR_ACCESS_DENIED",permission 為 "openUrl",resource 為該 URL(見沙盒與 capabilities)。在 Rust 中,open_url 會對這些 URL 回應 false 並記錄原因。
• 嵌入式應用程式會先看到該 URL,並可改為透過自己的 router 處理(Swift NshAppView.onOpenURL、Java NshView.setOpenUrlHandler、Rust AppView::host().handle_open_url;見 iOS 和 Android)。此時 opened 為 true。
• 各平台使用自己的開啟方式:iOS 使用 UIApplication.open(嵌入時使用宿主應用程式的 application),Android 使用 ACTION_VIEW intent,macOS 使用 NSWorkspace,Windows 使用 ShellExecuteW,Linux 使用 GtkUriLauncher,GPUI 使用 open_url,網頁則開啟新分頁。nsh test 只會記錄 URL 而不會開啟。
• TextView 以 links="open" 用這種方式開啟其連結。

#版面方向

版面方向跟隨使用者的語言:使用從右至左的語言(阿拉伯語、希伯來語等)時,應用程式會由右至左排版,列(row)從右邊開始排列,而 left / right 樣式屬性(marginLeft、paddingRight 等)則表示起始和結束。變更會立即生效,無需重新啟動。

檢視的 direction 樣式("ltr"、"rtl" 或預設的 "inherit")設定其自身子樹的方向;在 Rust 中為 .direction(LayoutDirection::..)。

view().direction(LayoutDirection::Rtl).flex_row().gap_2().child(text("First")).child(text("Second"))

<View style={{ direction: "rtl", flexDirection: "row", gap: 8 }}>
  <Text>First</Text>
  <Text>Second</Text>
</View>

#相關內容

• 安全區域 insets(Rust safe_area();TSX safeArea()、safeAreaInsets())和軟鍵盤(Rust keyboard_height();TSX keyboardFrame())請見安全區域與鍵盤。
• 螢幕閱讀器和減少動態效果的設定請見無障礙。

#PanResponder

Pan responder 是建基於 gesture responder 系統的拖曳手勢:元素會認領一個手勢的觸控,然後獨自接收這些觸控及手勢狀態,手勢狀態會為你追蹤觸控點的質心、移動距離和速度。Rust 程式碼以 .claim_touches(TouchClaim::…) 認領觸控,並以 .on_responder_* 監聽器接收,其 ResponderEvent 帶有 PanGesture,全部位於 nsh_core::prelude;TSX 則從 nsh 匯入 PanResponder,其 onPanResponder… 回呼會接收觸控事件和手勢狀態。

use nsh_core::prelude::*; // TouchClaim, ClaimRequest, ResponderEvent, PanGesture

import { PanResponder, type PanResponderGestureState } from "nsh";

#PanResponder.create

const PanResponder: { create(config: PanResponderCallbacks): PanResponderInstance };

interface PanResponderInstance {
  panHandlers: TouchProps;
}

建立一個 pan responder。把它的 panHandlers 展開到應接收手勢的檢視上。在 Rust 中,由檢視自行認領觸控並監聽:

use nsh_core::prelude::*;

#[component]
pub fn App() -> impl IntoElement {
    let pos = signal((0.0_f32, 0.0_f32));
    let start = stored((0.0_f32, 0.0_f32));
    view().flex_1().child(
        view()
            .size(px(64.0))
            .rounded(px(32.0))
            .bg(rgb(0x6366f1))
            .style_with(move |s| {
                let (x, y) = pos.get();
                s.translate_x(px(x)).translate_y(px(y))
            })
            .claim_touches(TouchClaim::on_start())
            .on_responder_grant(move |_: &ResponderEvent| {
                start.replace(pos.get_untracked());
            })
            .on_responder_move(move |e: &ResponderEvent| {
                let (x, y) = start.get();
                pos.set((x + e.gesture.delta.x.0, y + e.gesture.delta.y.0));
            })
            .on_responder_release(move |e: &ResponderEvent| {
                log::info!("released at {:.0} pt/s", e.gesture.vx);
            }),
    )
}

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

function App() {
  const pos = signal({ x: 0, y: 0 });
  let start = { x: 0, y: 0 };
  const pan = PanResponder.create({
    onStartShouldSetPanResponder: () => true,
    onPanResponderGrant: () => (start = pos()),
    onPanResponderMove: (_, g) => pos.set({ x: start.x + g.dx, y: start.y + g.dy }),
    onPanResponderRelease: (_, g) => console.log(`released at ${g.vx.toFixed(0)} pt/s`),
  });
  return (
    <View style={{ flex: 1 }}>
      <View
        {...pan.panHandlers}
        style={{
          width: 64,
          height: 64,
          borderRadius: 32,
          backgroundColor: "#6366f1",
          transform: [{ translateX: pos().x }, { translateY: pos().y }],
        }}
      />
    </View>
  );
}

mount(App);

#回呼

每個回呼都會接收觸控事件(GestureResponderEvent,來自 nsh)和手勢狀態。在 Rust 中,認領以 .ask(|request: &ClaimRequest| …) 作決定,呼叫 request.claim() 以取得觸控(沒有 ask 時則一律取得),而每個監聽器都會收到一個 ResponderEvent,其 gesture 就是該狀態。

type PanHandler<R = void> = (e: GestureResponderEvent, gestureState: PanResponderGestureState) => R;

#PanResponderGestureState

interface PanResponderGestureState {
  stateID: number;
  moveX: number;               // latest centroid of the touches (surface points)
  moveY: number;
  x0: number;                  // the centroid when the responder was granted
  y0: number;
  dx: number;                  // distance moved since the grant
  dy: number;
  vx: number;                  // velocity, points per second
  vy: number;
  numberActiveTouches: number;
}

Rust:PanGesture,座標點為 Point<Points>。

#在捲動檢視內

當 pan responder 是 responder 時,其周圍的原生捲動檢視不會捲動(onShouldBlockNativeResponder 預設為 true)。若要讓水平滑動與垂直捲動並存,請只在水平移動時才成為 responder:

view()
    .claim_touches(TouchClaim::on_move().ask(|request: &ClaimRequest| {
        let d = request.event.gesture.delta;
        if d.x.0.abs() > 10.0 && d.x.0.abs() > d.y.0.abs() {
            request.claim();
        }
    }))
    .on_responder_move(move |e: &ResponderEvent| offset.set(e.gesture.delta.x.0))
    .on_responder_release(move |e: &ResponderEvent| {
        if e.gesture.delta.x.0.abs() > 120.0 { remove() } else { offset.set(0.0) }
    })
    .on_responder_terminate(move |_: &ResponderEvent| offset.set(0.0))

const swipe = PanResponder.create({
  onMoveShouldSetPanResponder: (_, g) => Math.abs(g.dx) > 10 && Math.abs(g.dx) > Math.abs(g.dy),
  onPanResponderMove: (_, g) => offset.set(g.dx),
  onPanResponderRelease: (_, g) => (Math.abs(g.dx) > 120 ? remove() : offset.set(0)),
  onPanResponderTerminate: () => offset.set(0),
});

對於平台本身可識別的拖曳,TouchClaim::on_pan(PanActivation::horizontal(10.0, 10.0)) 會在手指移動時於主執行緒上作決定。底層的 responder props(onStartShouldSetResponder、onResponderGrant、onTouchStart 等)也可以直接用在任何元素上;請見元素。

#Clipboard

Clipboard API 可讀寫系統剪貼簿:所有平台均支援文字(iOS 為 UIPasteboard,Android 為 ClipboardManager,桌面平台為 NSPasteboard、GDK 和 Win32 剪貼簿,網頁為 navigator.clipboard);iOS、桌面平台和網頁支援圖片;桌面平台和 Mac Catalyst 則支援在檔案管理器中複製的檔案。Rust 程式碼呼叫 nsh_core::prelude 的函式(set_clipboard、clipboard_string 等);TSX 則從 nsh 匯入 Clipboard。

use nsh_core::prelude::*; // set_clipboard, clipboard_string, clipboard_image, ...
use nsh_core::element::ClipboardImage;

import { Clipboard } from "nsh";

const Clipboard: {
  writeText(text: string): Promise<void>;
  readText(): Promise<string>;
  hasText(): Promise<boolean>;
  writeImage(src: string): Promise<void>;
  readImage(): Promise<ClipboardImage | null>;
  hasImage(): Promise<boolean>;
  readFiles(): Promise<string[]>;
};

interface ClipboardImage {
  url: string; // a URL that Image shows and fetch reads
  size: PixelSize; // in pixels
}

Rust 的讀取函式會傳回要在 task 中 await 的結果(spawn,或 async 模組函式);ClipboardImage 為 nsh_core::element::ClipboardImage,包含 url 和 size(一個 Size<DevicePixels>)。

iOS、桌面平台和網頁可透過剪貼簿處理圖片。在 Android 上,剪貼簿只承載文字:writeImage 和 readImage 會以 Error reject,其 code 為 "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM",而 hasImage 會 resolve false。在 Rust 中,set_clipboard_image 會令該處的剪貼簿維持原樣,而 clipboard_image 會回應 None。

使用者也可以自行從可選取文字複製;Clipboard API 則用於從程式碼進行複製,例如「複製」按鈕。

#Clipboard.writeText

writeText(text: string): Promise<void>;

把 text 放到剪貼簿,取代原有內容。Rust:set_clipboard(text)。

use nsh_core::prelude::*;

fn copy_button(code: Signal<String>) -> impl IntoElement {
    let copied = signal(false);
    view()
        .role(AccessibilityRole::Button)
        .on_press(move || {
            set_clipboard(code.get());
            copied.set(true);
        })
        .child(text(move || if copied.get() { "Copied" } else { "Copy" }))
}

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

const copied = signal(false);

<View
  onPress={async () => {
    await Clipboard.writeText(code());
    copied.set(true);
  }}
>
  <Text>{copied() ? "Copied" : "Copy"}</Text>
</View>;

#Clipboard.readText

readText(): Promise<string>;

以剪貼簿的文字 resolve,如果剪貼簿沒有文字則為 ""。Rust:clipboard_string()。在 iOS 上,讀取剪貼簿可能會顯示系統的貼上通知(「App pasted from …」),而在 Android 10 及更新版本上,只有位於前景的應用程式才能讀取。請在使用者要求貼上時才讀取,不要在每個畫面都讀取。

spawn(async move {
    let pasted = clipboard_string().await;
    if !pasted.is_empty() {
        code.set(pasted.trim().to_string());
    }
});

const pasted = await Clipboard.readText();
if (pasted) code.set(pasted.trim());

#Clipboard.hasText

hasText(): Promise<boolean>;

以剪貼簿是否有文字 resolve,而不會讀取內容:在 iOS 上不會出現貼上通知。Rust:clipboard_has_string()。可用它來決定是否顯示「貼上」按鈕。在網頁上,瀏覽器只能透過讀取來判斷,因此可能會向使用者要求權限。

let can_paste = signal(false);
spawn(async move { can_paste.set(clipboard_has_string().await) });

const canPaste = signal(false);
Clipboard.hasText().then((has) => canPaste.set(has));

#Clipboard.readImage

readImage(): Promise<ClipboardImage | null>;

以剪貼簿的圖片 resolve,如果剪貼簿沒有圖片則為 null:例如貼上的螢幕截圖,或在瀏覽器或圖片編輯器中複製的圖片。Rust:clipboard_image(),沒有圖片時為 None。url 是該圖片的 URL(PNG,或剪貼簿本身的 JPEG、GIF、WebP 或 BMP),可由 Image 以其 src 顯示,亦可由 fetch 讀取:fetch(url) 會提供其位元組,用於上傳。size(width 和 height)是解碼後以像素為單位的尺寸。與 readText 一樣,請在使用者要求貼上時才讀取。最大 48 MB(編碼後)的圖片會被讀取,以確保圖片能放進應用程式的記憶體;更大的圖片會以 Error reject,其 code 為 "ERR_NSH_QUOTA_EXCEEDED"(其訊息會說明圖片大小和上限),而 hasImage 會 resolve true。Rust:clipboard_image() 會對此回應 None。

use base64::Engine as _;
use nsh_core::{element::ClipboardImage, prelude::*};

fn attachments() -> impl IntoElement {
    let attachments = signal(Vec::<ClipboardImage>::new());
    let paste = move || {
        spawn(async move {
            if let Some(image) = clipboard_image().await {
                attachments.update(|list| list.push(image));
            }
        });
    };
    view()
        .flex_row()
        .gap_2()
        .child(text("Paste").on_press(paste))
        .child(each(
            attachments,
            |shot: &ClipboardImage| shot.url.clone(),
            |shot, _| image(move || shot.with(|s| s.url.clone())).size(px(64.0)).rounded(px(8.0)),
        ))
}

async fn upload(image: &ClipboardImage) -> Result<HttpResponse, String> {
    let (_, data) = image.url.split_once(',').ok_or("not a data: URL")?;
    let bytes = base64::engine::general_purpose::STANDARD
        .decode(data)
        .map_err(|e| e.to_string())?;
    let request = HttpRequest::post("https://example.com/upload", bytes).header("Content-Type", "image/png");
    fetch(request).await
}

import { Image, signal, View } from "nsh";
import { Clipboard, type ClipboardImage } from "nsh";

const attachments = signal<ClipboardImage[]>([]);

async function paste() {
  const image = await Clipboard.readImage();
  if (image) attachments.set([...attachments(), image]);
}

async function upload(image: ClipboardImage) {
  const body = new FormData();
  body.append("file", await (await fetch(image.url)).blob(), "screenshot.png");
  await fetch("https://example.com/upload", { method: "POST", body });
}

<View class="flex-row gap-2">
  <Each of={attachments()}>
    {(image) => <Image src={image().url} style={{ width: 64, height: 64, borderRadius: 8 }} />}
  </Each>
</View>;

在聊天類應用程式中,使用者會把螢幕截圖貼到輸入框,這類應用程式會在輸入框取得焦點時綁定貼上快速鍵,並在有圖片時取用:

use nsh_core::keymap::When;

on_key_with("mod+v", KeyOptions { when: When::Always, ..KeyOptions::default() }, move |_| {
    spawn(async move {
        if clipboard_has_image().await {
            paste().await;
        } else {
            insert_text(&clipboard_string().await);
        }
    });
});

import { keymap } from "nsh";

keymap.bind("mod+v", async () => {
  if (await Clipboard.hasImage()) return paste();
  insertText(await Clipboard.readText());
}, { when: "always" });

#Clipboard.hasImage

hasImage(): Promise<boolean>;

以剪貼簿是否有圖片 resolve,而不會讀取內容:在 iOS 上不會出現貼上通知。Rust: clipboard_has_image()。在 Android 上會 resolve false。

#Clipboard.writeImage

writeImage(src: string): Promise<void>;

把 src 所指的圖片放到剪貼簿,取代原有內容;可以是 base64 data: URL,或 readImage 提供的 url。 Rust:set_clipboard_image(src)。在 Windows 上它接受 PNG,即瀏覽器、Office 和「剪取工具」讀取的格式。在 Android 上會以 "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM" reject。

set_clipboard_image(image.url.clone());

await Clipboard.writeImage(image.url);

#Clipboard.readFiles

readFiles(): Promise<string[]>;

以在檔案管理器(Finder、Explorer、Files)中複製的檔案和資料夾的 file: URL resolve,按其 順序排列,或為 []:與檔案拖放提供的 URL 相同。Rust:clipboard_files()。 解析 URL 即可取得其路徑。

let paths: Vec<std::path::PathBuf> = clipboard_files()
    .await
    .iter()
    .filter_map(|file| url::Url::parse(file).ok()?.to_file_path().ok())
    .collect();

const files = await Clipboard.readFiles();
const names = files.map((url) => decodeURIComponent(new URL(url).pathname.split("/").pop()!));

#Picker

Picker API 會顯示系統的相片選擇器，並把使用者所選的圖片交給應用程式：iOS 上是 Photos picker（PHPickerViewController），Android 上是 Photo Picker，桌面平台上是開啟面板或檔案對話框，瀏覽器中則是 file input。在 iOS 和 Android 上，選擇器在應用程式以外運行，只交出使用者所選的內容，因此不需要相片庫權限。每張選取的圖片會以 File（TSX）或 PickedFile（Rust）的形式送達，其位元組保留在原生端：以 URL.createObjectURL(file) 在 Image 中顯示，以 fetch 和 FormData 上傳。Rust 程式碼呼叫 pick_images（位於 nsh_core::prelude）；TSX 從 nsh 匯入 Picker。

use nsh_core::picker::{PickRequest, PickedFile};
use nsh_core::prelude::*; // pick_images

import { Picker, type PickedImage } from "nsh";

const Picker: {
  pickImages(options?: PickImagesOptions): Promise<PickedImage[]>;
};

interface PickImagesOptions {
  multiple?: boolean; // let the user pick several (false: one)
  limit?: number; // at most this many when multiple (up to 100)
  maxDimension?: number; // scale images whose longer side is longer, in pixels
  quality?: number; // JPEG quality from 0 to 1 (0.9)
  format?: "compatible" | "current"; // "compatible": HEIC and the like as JPEG
}

interface PickedImage {
  file: File; // name, type, size in bytes and the bytes
  size: PixelSize; // upright
}

#Picker.pickImages

pickImages(options?: PickImagesOptions): Promise<PickedImage[]>;

顯示選擇器，並在使用者選取後，按選取順序以所選圖片 resolve；若使用者取消，則以 [] resolve。Rust：pick_images(request)，是在任務中 await 的結果（spawn，或 async 模組函式）。pickImages 永不拋出例外：超出範圍的選項（limit: 0，即不在 0 至 1 之間的 quality）會以 RangeError reject promise，而應用程式的 capabilities 未授權的選取會以 ERR_ACCESS_DENIED reject（見下文）。取消是使用者的回應，並非失敗：會以 [] resolve。

圖片送達時已可直接傳送：

• 所有瀏覽器和伺服器都支援的格式。 JPEG、PNG、GIF 和 WebP 會保持原樣；以其他格式儲存的相片（iPhone 上的 HEIC、HEIF、TIFF）會轉為 JPEG。format: "current" 則保留儲存時的格式。
• 在原生端縮小。 使用 maxDimension 時，較長邊超出該值的圖片會縮小至符合該值、轉正方向，然後重新編碼：PNG 仍為 PNG，其餘轉為品質 quality 的 JPEG。手機相片有 12 至 48 百萬像素；上傳前縮小至 2048 像素，可使檔案只有數百 KB。quality 同樣會重新編碼 JPEG。
• 顯示的內容。 size 是圖片顯示時的像素尺寸，已套用相機方向。NSH 重新編碼的圖片不帶任何中繼資料（包括位置）；保持原樣的圖片則保留其自身的中繼資料。

在 Windows、Linux 和 GPUI 視窗中，對話框會提供請求所接受的格式（使用 "compatible" 時：JPEG、PNG、GIF 和 WebP），檔案以其儲存時的原樣和原始尺寸送達。

聊天輸入框附加相片、在撰寫訊息期間顯示相片，並在訊息送出時上傳：

use nsh_core::geometry::{DevicePixels, Percentage};
use nsh_core::picker::{PickRequest, PickedFile};
use nsh_core::prelude::*;

fn attach_button(attached: Signal<Option<PickedFile>>) -> impl IntoElement {
    view()
        .role(AccessibilityRole::Button)
        .accessibility_label("Choose a photo")
        .on_press(move || {
            let mut request = PickRequest::new(false, 1);
            request.max_dimension = Some(DevicePixels(2048));
            request.quality = Some(Percentage(0.85));
            let picked = pick_images(request);
            spawn(async move {
                if let Some(file) = picked.await.into_iter().next() {
                    attached.set(Some(file));
                }
            });
        })
        .child(text("Photo"))
}

async fn upload(file: &PickedFile) -> Result<HttpResponse, String> {
    let request = HttpRequest::post("https://example.com/upload", file.data.to_vec())
        .header("Content-Type", file.mime.as_str());
    fetch(request).await
}

import { Image, signal, Text, View } from "nsh";
import { Picker } from "nsh";

const attached = signal<{ file: File; src: string } | null>(null);

async function choosePhoto() {
  const [picked] = await Picker.pickImages({ maxDimension: 2048, quality: 0.85 });
  if (picked) attached.set({ file: picked.file, src: URL.createObjectURL(picked.file) });
}

async function send(text: string) {
  const body = new FormData();
  body.append("text", text);
  if (attached()) body.append("photo", attached()!.file);
  await fetch("https://example.com/messages", { method: "POST", body });
  if (attached()) URL.revokeObjectURL(attached()!.src);
  attached.set(null);
}

<View class="flex-row items-center gap-2">
  <View role="button" accessibilityLabel="Choose a photo" onPress={choosePhoto}>
    <Text>Photo</Text>
  </View>
  <If when={attached()}>
    <Image src={attached()!.src} style={{ width: 48, height: 48, borderRadius: 8 }} />
  </If>
</View>;