nsh

nsh — основной модуль: реактивное API (сигналы, вычисляемые значения, эффекты, контекст), mount, token, хост-элементы View, Text, Scroll и Overlay, выделяемые представления, безопасная область и клавиатура, анимация, устройство и его окружение, PanResponder, буфер обмена, выбор фото, распознавание речи, хранилище, канал хоста, сочетания клавиш, нативные компоненты и модули, доступность, а также TypeScript-типы элементов, стилей и событий. Сам реактивный граф работает нативно на Rust; чтение сигнала — это вызов в рантайм, который стоит несколько наносекунд, и в интерпретаторе 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, которые читают сигналы, обновляются на месте при изменении этих сигналов. Повторного рендера компонента и виртуального DOM нет. Руководство см. в разделе Reactivity.

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

Сигнал хранит значение. Вызов сигнала читает значение и, внутри отслеживающей области (выражения 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;
}

Значение, производное от сигналов. fn запускается снова, когда меняется прочитанный им сигнал; читатели вычисляемого значения обновляются, только когда меняется его результат (по 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 после рендеринга и снова при каждом изменении прочитанного им сигнала. Используйте эффекты для побочных действий: логирования, таймеров, обращений к нативным модулям. Эффект принадлежит компоненту (или эффекту), в котором он создан, и удаляется вместе с ним.

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

Чтобы отменить что-либо перед повторным запуском эффекта (или когда его компонент исчезает), вызовите внутри него 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, не подписывая текущую область на то, что он читает. Используйте это, чтобы прочитать сигнал внутри эффекта или выражения JSX, не завися от него.

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

#cleanup

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

Регистрирует fn для запуска перед очередным запуском текущего эффекта или когда текущий компонент или эффект исчезает.

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

Значение, которое компонент предоставляет всему, что он рендерит, на любой глубине. Вызов контекста (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 на props, названные в keys, и остальные. Обе части остаются реактивными: props, значения которых меняются, являются геттерами, и split сохраняет их геттерами. Используйте это в компоненте, который часть 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;

Рендерит своих потомков или fallback, как только что-то под ними выбросит исключение: тело компонента, привязка, эффект или обработчик события. Часть, в которой произошёл сбой, удаляется, и на её месте показывается запасной вариант. Функция fallback вызывается как fallback(error, reset) с выброшенным значением и reset, который снова рендерит потомков, независимо от того, какие параметры она объявляет; элемент fallback показывается как есть. Сбой передаётся ближайшей границе выше него, а сбой в запасном варианте — границе выше той. Компоненты на Rust используют catch_error (Error boundaries).

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

Токен дизайна name темы приложения ("theme" в nsh.json, поверх токенов shadcn/ui) для отображаемого оформления: цвет — как #rrggbbaa, длина — как число пунктов, шрифт — как название семейства. Имена — это CSS-переменные темы без -- (primary, muted-foreground, radius, font-mono, а также собственные переменные приложения, например up). Чтение реактивно: компонент, memo или эффект, читающий токен, запускается снова при изменении темы или оформления. Tokens перечисляет токены приложения с их типами; NSH записывает его в .nsh/types/nsh/tokens.d.ts на основе темы. Для классов называйте токены напрямую (bg-primary, rounded-(--radius)): Theme tokens.

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). Компилятор создаёт нативное представление на месте для тега, который называет один из них через свой импорт (в том числе под псевдонимом), так что импорт ничего не стоит во время выполнения. Это такие же компоненты, как и любые другие, поэтому их можно и передавать (const Tag = inline ? Text : View). nsh точно так же экспортирует другие примитивы: List, Image, Canvas, WebView и Video, у каждого есть своя страница справочника. Их props описаны в разделе Elements. Текстовое поле ввода, Input, поставляется из nsh/base.

#Безопасная область и клавиатура

Переменные окружения CSS удерживают содержимое вне системного UI в padding и margin любого представления (padding, paddingTop, …, те же ключи margin; произвольные значения p* / m* в Tailwind; методы Styled .p_safe_area(), .pt_safe_area_plus(..), .pb_keyboard(), … в Rust). Их значения — 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() — безопасная область поверхности (safe_area() в Rust); safeAreaInsets() — отступы там, где рендерится компонент (cx.insets() в Rust), то есть значения переменных safe-area-inset-*. Оба являются реактивными Edges ({ top, right, bottom, left } в пунктах). См. safeArea and safeAreaInsets.

#Keyboard и keyboardFrame

Keyboard.dismiss() скрывает программную клавиатуру (dismiss_keyboard() в Rust), а keyboardFrame() сообщает, какую часть экрана она закрывает (keyboard_height() и keyboard_duration() в Rust). См. Hiding the keyboard и The keyboard’s height.

#Выделяемые представления

<View selectable> (view().selectable(true) в Rust) делает так, что тексты внутри него выделяются вместе, как на веб-странице: одно выделение проходит через представления, элементы Text и TextView в порядке чтения. См. Text selection.

#Анимация

API анимации выполняет анимацию в UI-потоке. Вы создаёте анимированное значение, привязываете его (или производные от него значения) к свойству стиля и запускаете анимацию; дальше каждый кадр вычисляется нативно, без запуска кода приложения. Занятый движок или JS-поток не может вызвать подтормаживание анимации, а сама анимация не требует от приложения никакой работы на каждом кадре. Код на Rust использует animated_value(), motion(), Animation, Spring, Timing, KeyframeTiming, MotionPreset и Easing из nsh_core::prelude и привязывает значения методами .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";

Руководство см. в разделе Animation.

#Что может управляться анимированным значением

Остальные свойства стиля принимают обычные значения; чтобы анимировать саму раскладку (размеры, позиции в потоке), используйте 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 }>;
}

Каждый метод анимации возвращает промис, который завершается с { finished }: true, когда анимация закончилась, false, когда она была остановлена (через stop, set или другой анимацией того же значения). В Rust он возвращает AnimationEnd, которого задача ожидает ради того же 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-кадры анимации: кривая плавности задаёт форму одного сегмента (у ключевого кадра — сегмент, который начинается с него, у timing — все остальные); отсутствующие у ключевых кадров 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;
}

Создаёт движение: анимированное значение для каждого канала непрозрачности и трансформации представления в состоянии покоя (непрозрачность и масштабы равны 1, остальные 0), а также движения, которые нативно проигрываются на них. Привяжите его через style={motion.style} или разверните motion.style либо motion.transform в стиль; трансформация применяет сначала сдвиги, затем повороты, затем масштабы, причём scale сворачивается в scaleX и scaleY: это 7 из 8 шагов трансформации представления, так что один остаётся для вашего ([{ perspective: 600 }, ...motion.transform] для 3D-переворотов). initial задаёт, откуда стартуют каналы ({ opacity: 0 }; остальные стартуют из состояния покоя). С enter каналы, которые оно двигает, стартуют там, где начинается это движение (по initial), и оно проигрывается сразу, а остальные опции служат его параметрами времени (delay, duration, …). Движение меняет только непрозрачность и трансформацию: разворачивание motion.style задаёт opacity представления, поэтому привязывайте только motion.transform, чтобы сохранить собственную непрозрачность, а цвета двигайте через анимированное значение и interpolate. Rust: motion() — дескриптор Copy, который хранит компонент, создавший его, привязывается через .bind_motion(&m); motion().entering(spec) выполняет вход.

Когда пользователь просит меньше движения (reduceMotion()), play, animation и enter сразу переходят в конечную точку движения, не двигаясь, если не задан ignoreReduceMotion (в опциях или у движения).

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.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 — это ваше собственное движение: ключевые кадры каждого канала ({ opacity: [0, 1], translateY: [24, 0] }) или список кадров в том виде, как их записывает Web Animations API ([{ opacity: 0, translateY: 24 }, { opacity: 1, translateY: 0 }]; кадр без offset размещается по его позиции в списке), с таймингом ключевых кадров. 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 это enum 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) выдаёт её значения в count равноотстоящих точках от 0 до 1; 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 это EaseMode у Easing::Curve.

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

API устройства сообщает приложению об устройстве и его окружении. Rust-код вызывает функции nsh_core::prelude (window(), dark(), font_scale(), locale(), lifecycle(), os(), idiom(), pixel_ratio(), set_color_scheme(), …); TSX импортирует их из nsh. Размер окна, цветовая схема, масштаб шрифта, плотность пикселей, локаль и состояние приложения реактивны: читайте их в привязке (замыкание, передаваемое элементу в Rust, JSX в TSX), 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";

См. руководство Device and environment.

#windowSize

const windowSize: Accessor<Size>;

Размер поверхности в пунктах: окна или встроенного 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(…) следуют за ним без его чтения. Вариант dark: из Tailwind тоже следует за ним (см. 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 — размер по умолчанию; Dynamic Type на iOS, размер шрифта на 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 по умолчанию форматирует под неё; читайте её, чтобы выбирать строки собственных переводов (Device and environment).

#lifecycle

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

Используется ли приложение, в терминах AppState из React Native: "active" — на переднем плане и принимает ввод, "inactive" — видно, но без фокуса (фокус у другого приложения или окна, либо система показывает что-то поверх, например переключатель приложений или входящий звонок), "background" — не видно (в фоне, свёрнуто, скрытая вкладка браузера). Приложение, показываемое внутри нативного приложения, следует состоянию этого приложения. Реактивно. Rust: lifecycle() -> Lifecycle (Lifecycle::Active, Inactive, Background).

Читайте его в эффекте, чтобы приостанавливать работу, которую никто не видит, и возобновлять её, когда приложение возвращается:

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, …), иначе desktop или mobile (по platform.desktop), иначе native (все платформы, кроме веба), иначе default, иначе undefined. Код на Rust использует match по os() (и is_desktop() для mobile / 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>;

Количество физических пикселей устройства на пункт (например, 3 на большинстве iPhone). Значение реактивное: оно меняется, когда окно переезжает на экран с другой плотностью (на 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: в приложении телефона и любую схему, зарегистрированную другим приложением (maps:, собственные ссылки lb:// хост-приложения). Промис завершается значением { opened } — открылось ли что-нибудь: 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 должен быть абсолютным (содержать схему). URL, которые выполнили бы код или обратились бы к данным самого приложения, — javascript:, data:, blob:, file:, about: и asset: — отклоняют промис с TypeError, как и относительные адреса. openUrl никогда не бросает исключение: любая ошибка приводит к отклонению промиса.
• Приложению, которое объявляет capabilities, нужно openUrl: "openUrl": true для любой схемы или "openUrl": { "schemes": ["https", "mailto"] } для перечисленных; остальные URL отклоняются с Error, у которой code равно "ERR_ACCESS_DENIED", permission "openUrl" и resource — URL (см. Песочница и capabilities). В Rust open_url отвечает false для них и пишет причину в лог.
• Сначала URL видит встраивающее приложение и может направить его в собственный роутер (Swift NshAppView.onOpenURL, Java NshView.setOpenUrlHandler, Rust AppView::host().handle_open_url; см. iOS и Android). Тогда opened равно true.
• Каждая платформа открывает URL собственным средством: UIApplication.open на iOS (приложение-хост при встраивании), intent ACTION_VIEW на Android, NSWorkspace на macOS, ShellExecuteW на Windows, GtkUriLauncher на Linux, open_url из GPUI, новая вкладка в вебе. nsh test записывает URL вместо того, чтобы открывать их.
• TextView открывает свои ссылки таким образом с помощью links="open".

#Направление раскладки

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

#См. также

• Safe area insets (Rust safe_area(); TSX safeArea(), safeAreaInsets()) и программная клавиатура (Rust keyboard_height(); TSX keyboardFrame()) описаны в разделе Safe area и клавиатура.
• Настройки screen reader и уменьшения анимации описаны в разделе Accessibility.

#PanResponder

Pan responders — это жесты перетаскивания поверх системы gesture responder: элемент захватывает касания жеста, а затем получает только их вместе с состоянием жеста, которое само отслеживает центроид касаний, пройденное расстояние и скорость. Код на Rust захватывает касания с помощью .claim_touches(TouchClaim::…) и получает их через слушатели .on_responder_*, чей ResponderEvent несёт PanGesture, всё это в nsh_core::prelude; TSX импортирует PanResponder из nsh, колбэки 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 через spread представлению, которое должно получать жест. В 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>.

#Внутри scroll view

Пока pan responder является responder, окружающие его нативные scroll view не прокручиваются (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),
});

Для pan, который платформа распознаёт сама, TouchClaim::on_pan(PanActivation::horizontal(10.0, 10.0)) принимает решение в главном потоке по мере движения пальцев. Базовые props responder (onStartShouldSetResponder, onResponderGrant, onTouchStart, …) также можно использовать напрямую на любом элементе; см. Элементы.

#Clipboard

API буфера обмена читает и записывает системный буфер обмена: текст — везде (UIPasteboard на iOS, ClipboardManager на Android, NSPasteboard, GDK и буфер обмена Win32 на десктопах, navigator.clipboard в вебе), изображения — на iOS, десктопах и в вебе, а файлы, скопированные в файловом менеджере, — на десктопах и Mac Catalyst. Код на Rust вызывает функции nsh_core::prelude (set_clipboard, clipboard_string, …); TSX импортирует Clipboard из nsh.

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.

Пользователь также может сам скопировать текст из выделяемого текста; 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 и новее читать его может только приложение на переднем плане. Читайте его, когда пользователь просит вставить, а не на каждом экране.

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

Приложение в стиле чата, где пользователи вставляют скриншоты в поле ввода сообщения, привязывает сочетание клавиш вставки, пока поле ввода в фокусе, и забирает изображение, если оно есть:

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 — URL data: в base64 или url, который дал readImage, — заменяя прежнее содержимое. 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[]>;

Завершается URL file: файлов и папок, скопированных в файловом менеджере (Finder, Explorer, Files), в их порядке, или []: теми же URL, которые даёт file drop. 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

API picker показывает системный выбор фотографий и передаёт приложению изображения, выбранные пользователем: Photos picker на iOS (PHPickerViewController), Photo Picker на Android, панель открытия или файловый диалог на десктопах и file input в браузере. На iOS и Android picker работает вне приложения и передаёт только то, что выбрал пользователь, поэтому разрешение на доступ к фототеке не требуется. Каждое выбранное изображение приходит как File (TSX) или PickedFile (Rust), байты которого остаются нативными: показывайте его с помощью URL.createObjectURL(file) в Image, загружайте с помощью fetch и FormData. Код на Rust вызывает pick_images из nsh_core::prelude; TSX импортирует Picker из nsh.

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

Показывает picker и завершается с изображениями, которые выбрал пользователь, в порядке выбора, или с [], если пользователь отменил выбор. Rust: pick_images(request) — ответ, которого нужно дождаться в задаче (spawn или функция модуля async). pickImages никогда не выбрасывает исключение: параметры вне допустимого диапазона (limit: 0, quality вне интервала от 0 до 1) отклоняют промис с RangeError, а выбор, который не разрешён возможностями (capabilities) приложения, отклоняется с ERR_ACCESS_DENIED (см. ниже). Отмена — это ответ пользователя, а не сбой: она завершается с [].

Изображения приходят готовыми к отправке:

• Форматы, которые принимают все браузеры и серверы. JPEG, PNG, GIF и WebP приходят как есть; фотография, сохранённая в другом формате (HEIC на iPhone, HEIF, TIFF), приходит как JPEG. format: "current" сохраняет исходный формат.
• Нативное уменьшение. С maxDimension изображение, у которого длинная сторона больше заданной, уменьшается до этого размера, поворачивается в правильную ориентацию и кодируется заново: PNG как PNG, всё остальное как JPEG с quality. Фотографии с телефона имеют от 12 до 48 мегапикселей; уменьшение до 2048 пикселей перед загрузкой делает их размером в несколько сотен килобайт. 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>;