元素

Native Shell 用一小组元素构建每个界面：View、Text、Image 等原语，以及 Button、Dialog、NavStack 等基础组件。每个原语都对应一个原生视图（iOS 和 Mac Catalyst 上是 UIView 子类，Android 上是 View，桌面上是 AppKit、GTK 或 Win32 视图），由 NSH 运行时创建并布局。应用显示的一切都由它们组成：应用的按钮、卡片、列表行和页面都是它自己的组件，用这些元素绘制、由应用设置样式，因此应用的外观完全由应用决定。

这些页面上的每个示例都同时给出 Rust 和 TSX：选择一个标签页，页面上的所有示例都会随之切换。

use nsh_core::ui::prelude::*;

fn app() -> impl IntoElement {
    let count = signal(0_u32);
    view()
        .flex_1()
        .items_center()
        .justify_center()
        .gap_3()
        .child(text(move || format!("已点击 {} 次", count.get())).text_2xl())
        .child(
            view()
                .rounded_lg()
                .bg(rgb(0x2563eb))
                .px_4()
                .py_2()
                .active(|s| s.opacity(0.6))
                .on_press(move || count.update(|n| *n += 1))
                .child(text("点我").text_color(white())),
        )
}

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

function App() {
  const count = signal(0);
  return (
    <View style={{ flex: 1, alignItems: "center", justifyContent: "center", gap: 12 }}>
      <Text style={{ fontSize: 24 }}>已点击 {count()} 次</Text>
      <View onPress={() => count.update((n) => n + 1)} class="rounded-lg bg-blue-600 px-4 py-2 active:opacity-60">
        <Text class="text-white">点我</Text>
      </View>
    </View>
  );
}

mount(App);

在 Rust 中，原语是 nsh_core::ui::prelude 中的函数（view()、text(..)、image(..)），基础组件来自 nsh_base crate。样式是有类型的方法（.flex_1()、.gap_3()、.px(px(20.0))、.bg(..)），状态样式接收一个闭包（.active(|s| s.opacity(0.6))），监听器是接收事件的闭包（.on_press(move || ..)、.on_change(move |text: &str| ..)），.child(..) 添加子元素。一段 UI 就是一个返回 impl IntoElement 的普通函数，只运行一次；它在闭包里读取的 signal（text(move || ..)、.bg(move || ..)）会更新所绑定的内容。参见用 Rust 构建。

在 TSX 中，每个标签都使用 PascalCase，并指向作用域中的绑定：原语从 nsh 导入，基础组件从 nsh/base 导入。只有 <If> 和 <Each> 是无需导入的全局组件。<view> 这样的小写标签会导致构建错误，因为 TypeScript 只能对照每个名称一个的全局类型来检查它，List、Each 这类泛型组件就无法推断条目类型。编译器通过导入识别这些元素并就地创建原生视图，所以导入它们在运行时没有任何开销。参见 JSX 与组件。

import { Canvas, Image, Input, List, Overlay, Scroll, Text, Video, View, WebView } from "nsh";
import { Button, Dialog, Menu, NavPage, NavStack, Popover, SafeAreaView, Sheet, Tooltip } from "nsh/base";

#原语

TSX 从 nsh 导入，Rust 从 nsh_core::ui::prelude 导入。

#Base

TSX 从 nsh/base 导入，Rust 从 nsh_base crate 导入。它们负责行为、状态、焦点和无障碍，外观由应用决定。

#通用属性

所有原语都接受下列属性（TSX 中为 CommonProps 类型；Rust 中为 Styled、Interactive 和 Accessible trait）。各元素页面只列出该元素自己的属性。Rust 一列给出对应的构建方法。

#样式

#按压与反馈

按压处理在原生侧完成：由平台识别按压并应用应用设定的按压样式，应用代码只在事后收到通知。只有最内层可按压的视图会响应；在滚动视图内，按下会等待约 130 ms，让滚动有机会先开始。

按压反馈由应用决定：视图被按下时，activeStyle（或 active: 类，Rust 中为 .active(..)）在原生侧生效，无需经过应用代码（见下文）。

#状态样式

视图处于某种状态时，在其自身样式之上、由原生侧应用的样式。每一个都是某个 Tailwind 变体的对象形式。后面的状态优先（selected、checked 与 indeterminate，然后是 hover、focus、active）；disabledStyle 优先于所有状态，视图被禁用时其他状态样式不生效。

view()
    .rounded_lg()
    .bg(rgb(0x2563eb))
    .px_4()
    .py_2()
    .active(|s| s.opacity(0.6))
    .hover(|s| s.bg(rgb(0x1d4ed8)))
    .on_press(save)
    .child(text("保存").text_color(white()))

<View onPress={save} activeStyle={{ opacity: 0.6 }} hoverStyle={{ backgroundColor: "#1d4ed8" }} class="rounded-lg bg-blue-600 px-4 py-2">
  <Text class="text-white">保存</Text>
</View>

#悬停

应用可以得知鼠标移到视图上、在视图上移动和离开视图：macOS、Windows、Linux、GPUI 后端和桌面浏览器都支持；iOS 上是 iPad 的指针或 Mac 的鼠标，Android 上是鼠标或手写笔。悬停样式（hover:、.hover(..)）在同样的地方为悬停的视图设置样式。

与 CSS 的 :hover 一样，鼠标在视图上或在其内部任何内容上时，视图都算作被悬停，因此鼠标下方视图外层的视图也会收到 onHoverIn（由外向内；onHoverOut 由内向外）。事件在发生之后才通知应用，触摸从不触发；按着按键移动属于触摸（onTouchMove、响应者系统）。从鼠标下方移除的视图会收到 onHoverOut，在 Linux 和 Windows 上要等到鼠标下一次移动。

HoverEvent 像 GPUI 的 MouseMoveEvent 一样给出鼠标的位置：position 是在视图中的位置（一个 Point，单位为点，已去掉视图的变换），pagePosition 是在视图所在根视图中的位置（与触摸相同），以及按住的 modifiers（control、alt、shift、platform：Apple 平台上是 Command，其他平台是 Windows 键）；Rust 中为 position、page_position 和 modifiers。移动事件每帧最多一次，总是最新的那次，并且一定在随后的 onHoverOut 之前到达，因此处理函数可以在每次移动时重绘：

// 图表上的十字线。
let at = signal(None::<Points>);

view()
    .h(px(200.0))
    .on_hover_move(move |e: &HoverEvent| at.set(Some(e.position.x)))
    .on_hover_out(move || at.set(None))
    .child(when(move || at.get().is_some(), move || {
        view()
            .absolute()
            .left(move || at.get().unwrap_or_default())
            .top_0()
            .bottom_0()
            .w(px(1.0))
            .bg(rgb(0x888888))
    }))

// 图表上的十字线。
const at = signal<number | null>(null);

<View onHoverMove={(e) => at.set(e.position.x)} onHoverOut={() => at.set(null)} style={{ height: 200 }}>
  <If when={at() !== null}>
    <View style={{ position: "absolute", left: at()!, top: 0, bottom: 0, width: 1, backgroundColor: "#888" }} />
  </If>
</View>

#工具提示

tooltip 为任意元素加上提示：在桌面平台（macOS、Windows、Linux、GPUI 后端和桌面浏览器）上，指针在元素上停留半秒后显示在它上方，指针离开或按下时隐藏。手机和平板不显示。提示从不接收指针或按压，所以元素的行为与没有它时完全一样。

view().on_press(save).tooltip("保存文档").child(text("💾"))

<View onPress={save} tooltip="保存文档">
  <Text>💾</Text>
</View>

需要自己的外观、位置、延迟或事件时，把 nsh/base 的 Tooltip 作为 tooltip 传入，与 GPUI 的 .tooltip(..) 相同。

#上下文菜单

onContextMenu 告诉视图：鼠标的辅助按钮在它上面按下了——右键单击、macOS 上的 Control 单击、触控板的双指单击、iPad 指针的辅助点按；在浏览器里还有键盘的菜单键。在这里打开应用自己的菜单；在 TSX 中，Menu.popup 显示系统菜单：

// 应用自己的菜单，放在点击的位置。
let menu_at = signal(None::<Point<Points>>);

view()
    .on_context_menu(move |e: &ContextMenuEvent| menu_at.set(Some(e.page_position)))
    .child(text(row.name.clone()))

import { Menu } from "nsh/desktop";

<View onContextMenu={(e) => Menu.popup(rowMenu(row), e.pagePosition)}>…</View>

ContextMenuEvent 包含视图中的 position、根视图中的 pagePosition（Menu.popup 放置菜单的位置：Menu.popup(items, e.pagePosition)）以及 modifiers；Rust 中为 position、page_position 和 modifiers。从指针下方的视图向外，最近的一个监听者收到事件。如果比它更近的是文本输入框，或带有编辑菜单的可选中文本（Windows、GPUI 后端、浏览器），则显示它们自己的菜单。平台在按钮按下时根据已挂载的内容做出决定，因此处理函数在事后得到通知，不需要取消任何东西。disabled 的视图把这次点击留给外层最近的、未停用的监听者。在触摸屏上用长按打开菜单：用同一个函数处理 onLongPress。

#键盘焦点

在 macOS 和 Web 上，Tab 在可按压的视图（以及输入框）之间移动键盘焦点，按 Return 或空格会按下获得焦点的视图，焦点样式（focus:、.focus(..)）为它设置样式。点击会按下视图但不让它获得焦点，所以焦点样式只在键盘聚焦时生效。

view()
    .rounded_lg()
    .p_3()
    .focus(|s| s.bg(rgb(0xe0f2fe)))
    .on_press(open)
    .child(text("打开"))

// 浮层的背景层：点击关闭浮层，Tab 直接越过它进入内容。
view().absolute().inset_0().focusable(false).on_press(close)

<View class="rounded-lg p-3 focus:bg-sky-100" onPress={open}>
  <Text>打开</Text>
</View>

{/* 浮层的背景层：点击关闭浮层，Tab 直接越过它进入内容。 */}
<View class="absolute inset-0" focusable={false} onPress={close} />

#布局与标识

#驱动动画值的手势

这些属性把手势绑定到原生动画值，值在 UI 线程上变化，每帧都不经过应用代码。参见触摸与手势。

PanEvent 为 { translationX, translationY, velocityX, velocityY, valueX?, valueY? }（Rust 中为 translation、velocity_x、velocity_y、value_x、value_y）：自开始以来的位移、以点每秒计的速度，以及此刻所绑定值的数值（拖动可能在动画中途抓住一个值）。

#原始触摸与响应者系统

对于上面属性覆盖不到的手势，每个元素都支持触摸与响应者属性： onTouchStart、onTouchMove、onTouchEnd、onTouchCancel（以及对应的 …Capture 形式）、 onStartShouldSetResponder、onMoveShouldSetResponder（以及 …Capture）、onResponderGrant、onResponderReject、 onResponderStart、onResponderMove、onResponderEnd、onResponderRelease、onResponderTerminate 和 onResponderTerminationRequest。每个处理函数都会收到一个 GestureResponderEvent （{ identifier, locationX, locationY, pageX, pageY, target, timestamp, touches, changedTouches, nativeEvent, stopPropagation() }）；…ShouldSetResponder 回调还会收到 gestureState（dx、dy、vx、vy 等）。 onResponderGrant 返回 true 可阻止原生滚动视图接管触摸。panActivation （{ activeOffsetX, activeOffsetY, failOffsetX, failOffsetY }）让视图只在平台激活它的拖动后才成为响应者， 滚动视图里的拖动因此把另一个轴留给滚动视图（触摸与手势）。 nsh/gesture 中的 PanResponder 就构建在它们之上。在 Rust 中，.on_touch(..) 接收每次触摸（TouchEvent），.claim_touches(..) 决定视图何时接管触摸，.on_responder_grant(..)、.on_responder_move(..)、.on_responder_release(..) 等跟随响应者状态。

#无障碍

参见无障碍。

#平台专属属性

在 TSX 中，只在某个平台上存在的属性放在以该平台命名的对象里，这样共享属性在各平台上保持一致。只有当前平台的对象会被发送，其他的会被忽略。Rust 的构建器以方法的形式提供它们，在各自的平台上生效。

use nsh_core::Ripple;

view()
    .rounded_lg()
    .bg(white())
    .p_4()
    .elevation(px(2.0))
    .ripple(Ripple { color: Some(rgba(0x00000022).into()), ..Ripple::default() })
    .on_press(save)
    .child(text("保存"))

<View onPress={save} android={{ ripple: { color: "#00000022" }, elevation: 2 }} class="rounded-lg bg-white p-4">
  <Text>保存</Text>
</View>

参见平台相关代码。

#ref 方法

在 TSX 中 ref 收到一个 YNode；在 Rust 中，element_ref() 创建一个 ElementRef 句柄，由 .element_ref(&handle) 附加到元素上。它们的方法向原生视图发送命令，与同一轮中先前的改动按顺序执行。各元素页面会说明哪些方法适用。

let field = element_ref();

view()
    .on_press(move || field.focus())
    .child(input().element_ref(&field).placeholder("点击这一行开始输入"))

import { Input, View, type YNode } from "nsh";

let input!: YNode;
<View onPress={() => input.focus()}>
  <Input ref={input} placeholder="点击这一行开始输入" />
</View>;

#为什么处理函数不会阻塞 UI

主线程从不等待应用代码。当系统需要立即得到答复时（这段文本能否修改、返回键能否返回上一页、这个 sheet 能否关闭），NSH 会根据事先设置好的属性（maxLength、popOnBack、closeOnSwipe、pointerEvents 等）在原生侧作答，事件随后才送达应用。正因如此，这类行为都是属性，而不是处理函数的返回值。