nsh

nsh 是核心模組：響應式 API（signal、computed 值、effect、context）、mount、token、host 元素 View、Text、Scroll 與 Overlay、可選取的檢視、安全區域與鍵盤、動畫、裝置及其環境、PanResponder、剪貼簿、照片選擇器、語音辨識、儲存空間、host channel、鍵盤快速鍵、原生元件與模組、無障礙，以及元素、樣式與事件的 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 衍生出的值。當它讀取過的 signal 變更時，fn 會再次執行；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 再次執行之前（或其元件消失時）復原某些操作，請在其中呼叫 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()）會讀取最近的 provider 的值；若沒有 provider，則為 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 渲染到 surface（視窗，或應用程式所嵌入的 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 往下傳遞的元件中。解構 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 元素則原樣顯示。失敗會交給其上最近的邊界處理，而 fallback 中的失敗則交給更上一層的邊界。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];

應用程式佈景主題的設計 token name（"theme" 位於 nsh.json，建立在 shadcn/ui 的 token 之上），以目前顯示的外觀呈現： 顏色為 #rrggbbaa，長度為以點為單位的數字，字型為其字型家族名稱。名稱為佈景主題的 CSS 變數， 去掉 --（primary、muted-foreground、radius、font-mono，以及應用程式自己的，例如 up）。讀取它具有響應性： 讀取 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 匯出的 host 元素，以標籤形式書寫：<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 and safeAreaInsets

safeArea() 是 surface 的安全區域（Rust 中為 safe_area()）；safeAreaInsets() 是元件 渲染處的內縮（Rust 中為 cx.insets()），即 safe-area-inset-* 變數的值。兩者都是具響應性的 Edges （{ top, right, bottom, left } 以點為單位）。請見 safeArea and safeAreaInsets。

#鍵盤與 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，被停止時為 false（被 stop、set 或同一個值的另一個動畫停止）。在 Rust 中它回傳 AnimationEnd，task 會等待它以取得相同的 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 } resolve，表示是否播放完成；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 keyframes 相同：easing 作用於單一區段（關鍵影格的 easing 作用於從它開始的區段，timing 的 easing 作用於其餘每個區段）；keyframes 中缺少的 offset 會平均分布，第一個為 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：為 view 的 opacity 與 transform 的每個通道各建立一個動畫值，初始處於靜止狀態（opacity 與 scale 為 1，其餘為 0），並提供可在這些通道上以原生方式播放的 motion。以 style={motion.style} 綁定，或將 motion.style 或 motion.transform 展開到 style 中；transform 依序套用平移、旋轉、縮放，其中 scale 會併入 scaleX 與 scaleY：佔用 view 8 個 transform 步驟中的 7 個，留下 1 個給你自己使用（[{ perspective: 600 }, ...motion.transform] 用於 3D 翻轉）。initial 設定各通道的起始位置（{ opacity: 0 }；其他通道從靜止狀態開始）。使用 enter 時，它所移動的通道會從該 motion 的起點開始（經過 initial），並立即播放，其餘選項則作為它的 timing（delay、duration、…）。motion 只會移動 opacity 與 transform：展開 motion.style 會設定 view 的 opacity，因此若要保留自己的 opacity，請只綁定 motion.transform，並以動畫值與 interpolate 來移動顏色。Rust：motion()，一個由建立它的元件持有的 Copy handle，以 .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.play({ ...motions.fadeInUp, duration: 600 })。

MotionSpec 是你自己的 motion：每個通道的關鍵影格（{ opacity: [0, 1], translateY: [24, 0] }），或以 Web Animations API 寫法的影格清單（[{ opacity: 0, translateY: 24 }, { opacity: 1, translateY: 0 }]，沒有 offset 的影格依其在清單中的位置決定），並搭配關鍵影格 timing。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 thread 上啟動（沒有影格間隙，步驟之間也不會回到 app 的程式碼）。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;
};

easing 是資料，而非 app 的函式：由 runtime 以原生方式計算。在 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）會給出 spring 或 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) 以原生方式為下一次 commit 的版面變化加上動畫：移動或改變大小的 view 會滑順過渡到新的 frame，新的 view 會出現（依 property 淡入或縮放進場），被移除的 view 會消失。請在改變版面的狀態變更之前呼叫它。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 讓 app 取得裝置及其環境的資訊。Rust 程式碼呼叫 nsh_core::prelude 的函式（window()、dark()、font_scale()、locale()、lifecycle()、os()、idiom()、pixel_ratio()、set_color_scheme()、…）；TSX 則從 nsh import。視窗大小、色彩配置、字型縮放、像素比例、locale 與 app 狀態皆為 reactive：在 binding（Rust 中傳給元素的 closure、TSX 中的 JSX）、computed 或 effect 中讀取它們，當平台回報變更時（旋轉、視窗調整大小、切換到深色模式、變更文字大小或語言、移到另一種密度的螢幕、離開 app 再回來），讀取它們的部分就會更新。

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

指南請見 Device and environment。

#windowSize

const windowSize: Accessor<Size>;

surface 的大小（以 point 為單位）：視窗，或嵌入的 NshAppView / NshView。Reactive。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">;

目前顯示的外觀：系統的外觀，除非 app 自行設定（nsh.json "appearance"、setColorScheme）。Reactive。Rust：dark() -> bool；主題顏色（AdaptiveColor）與 .dark(…) style variant 無須讀取它就會跟隨。Tailwind 的 dark: variant 同樣會跟隨（見 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 上為字型大小），或改由嵌入的 app 設定的文字大小。Reactive。Rust：font_scale() -> f32。除非 allowFontScaling={false}，否則文字已會隨之縮放；當其他尺寸也應跟隨時才需要讀取它，例如文字旁的圖示。

#locale

const locale: Accessor<string>;

使用者的 locale，以 BCP 47 標籤表示（"en-US"、"zh-Hans-CN"），或改由嵌入的 app 設定的 locale。Reactive。Rust：locale() -> Locale（locale().as_str() 為標籤）。Intl 預設會依它格式化；讀取它即可選擇你自己翻譯的字串（Device and environment）。

#lifecycle

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

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

在 effect 中讀取它，以暫停沒人看見的工作，並在 app 回來時恢復：

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 顯示 app，不論系統外觀為何：colorScheme()、dark: class、元件的主題與平台的控制項（alert、狀態列的預設樣式）都會跟隨；"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;
}

App 執行時所在的平台，執行期間保持不變。

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

每點的裝置像素數（例如大多數 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;
}

在 App 之外開啟 url：網頁在瀏覽器中開啟，mailto: 連結在郵件 App 中開啟，tel: 連結在電話 App 中開啟，以及其他 App 註冊的任何 scheme（maps:、宿主 App 自有的 lb:// 連結）。它會以 { opened } 完成，表示是否有東西開啟了它：當沒有 App 處理該 scheme 時為 false。Rust：open_url(url) 的 nsh_core::prelude，是可在任務中等待（或捨棄）的回應，同樣的 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 必須是絕對的（含有 scheme）。會執行程式碼或存取 App 自身資料的 URL，javascript:、data:、blob:、file:、about: 與 asset:，以及相對位址，都會以 TypeError 拒絕該 promise。openUrl 絕不會擲出例外：所有失敗都以拒絕表示。
• 宣告了 capabilities 的 App 需要 openUrl："openUrl": true 表示所有 scheme，"openUrl": { "schemes": ["https", "mailto"] } 表示所列出的 scheme；其他 URL 會以 Error 拒絕，其 code 為 "ERR_ACCESS_DENIED"，permission "openUrl"，而 resource 為該 URL（見沙盒與 capabilities）。在 Rust 中，open_url 對這些 URL 回應 false 並記錄原因。
• 嵌入的 App 會先看到該 URL，並可改由自己的路由器處理（Swift NshAppView.onOpenURL、Java NshView.setOpenUrlHandler、Rust AppView::host().handle_open_url；見 iOS 與 Android）。此時 opened 為 true。
• 各平台以自己的開啟器開啟：iOS 上為 UIApplication.open（嵌入時為宿主 App 的 application）、Android 上為 ACTION_VIEW intent、macOS 上為 NSWorkspace、Windows 上為 ShellExecuteW、Linux 上為 GtkUriLauncher、GPUI 的 open_url、網頁上為新分頁。nsh test 會記錄 URL 而不開啟。
• TextView 以 links="open" 用這種方式開啟其連結。

#版面方向

版面方向會依使用者的語言而定：在由右至左的語言（阿拉伯文、希伯來文等）中，App 會由右至左排版，列從右側開始排列，而 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>

#相關內容

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

#PanResponder

Pan 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 中，claim 以 .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 為回應者時，其周圍的原生捲動檢視不會捲動（onShouldBlockNativeResponder 預設為 true）。若要讓水平滑動與垂直捲動並存，只在水平移動時成為回應者：

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

對於平台能辨識的 pan，TouchClaim::on_pan(PanActivation::horizontal(10.0, 10.0)) 會在手指移動時於主執行緒上決定。底層的回應者屬性（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 的讀取函式會傳回可在任務中等待的回應（spawn，或 async 模組函式）；ClipboardImage 為 nsh_core::element::ClipboardImage，帶有 url 與 size（一個 Size<DevicePixels>）。

圖片可透過剪貼簿在 iOS、桌面平台與網頁上使用。Android 的剪貼簿只承載文字：writeImage 與 readImage 會以 Error 拒絕，其 code 為 "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM"，而 hasImage 會解析為 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>;

以剪貼簿的文字完成，若沒有文字則為 ""。Rust：clipboard_string()。在 iOS 上，讀取剪貼簿可能會顯示系統的貼上通知（「App pasted from …」），在 Android 10 以上則僅有位於前景的 App 可以讀取。請在使用者要求貼上時才讀取，而不是每個畫面都讀。

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

以剪貼簿是否含有文字完成，且不讀取內容：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>;

以剪貼簿中的圖片完成，若沒有圖片則為 null：貼上的螢幕截圖，或在瀏覽器 或圖片編輯器中複製的圖片。Rust：clipboard_image()，沒有圖片時為 None。url 是圖片的 URL（PNG，或 剪貼簿本身的 JPEG、GIF、WebP 或 BMP），Image 以其 src 顯示，fetch 也能讀取： fetch(url) 提供其位元組，可用於上傳。size（width 與 height）是解碼後以像素為單位的大小。與 readText 相同，請在使用者要求貼上時才讀取。最大 48 MB（編碼後）的圖片會被讀取，以確保圖片能放入 App 的記憶體；更大的圖片會以 Error 拒絕，其 code 為 "ERR_NSH_QUOTA_EXCEEDED"（訊息中會給出 圖片的大小與上限），而 hasImage 會解析為 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>;

聊天式 App 若讓使用者把螢幕截圖貼到輸入區，可在輸入欄位取得焦點時綁定貼上快速鍵， 並在有圖片時取用：

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

以剪貼簿是否含有圖片完成，且不讀取內容：iOS 上不會出現貼上通知。Rust： clipboard_has_image()。在 Android 上會解析為 false。

#Clipboard.writeImage

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

將 src 的圖片（base64 data: URL，或 readImage 提供的 url）放到剪貼簿，取代原有內容。 Rust：set_clipboard_image(src)。在 Windows 上它接受 PNG，這是瀏覽器、Office 與 Snipping Tool 所讀取的格式。在 Android 上會以 "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM" 拒絕。

set_clipboard_image(image.url.clone());

await Clipboard.writeImage(image.url);

#Clipboard.readFiles

readFiles(): Promise<string[]>;

以在檔案管理員（Finder、Explorer、Files）中複製的檔案與資料夾的 file: URL 完成，依其 順序排列，或為 []：與檔案拖放給出的 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 並回傳這些圖片;使用者取消時則回傳 []。Rust:pick_images(request),這是在 task 中 await 的結果(spawn,或 async 模組函式)。pickImages 不會 throw:超出範圍的選項(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>;