元素
SplitView
分栏视图把应用的导航分成几栏显示:侧边栏(分区或列表)、可选的内容栏(侧边栏所选内容中的条目)和详情栏。每一栏都是一个独立的 NavStack,因此每一栏保留自己的页面,各自推入和弹出。在 iOS、iPadOS 和 Mac Catalyst 上,这些栏属于 UISplitViewController:在 iPadOS 26 上侧边栏浮在内容之上,从边缘轻扫或按系统的侧边栏按钮即可呼出,窗口旋转和改变大小时由系统安排各栏。其他平台上各栏以固定宽度并排显示。空间紧凑时(手机、窄窗口)一次只显示一栏。显示哪些栏由 columnVisibility 决定,这个值由应用持有。
import { horizontalSizeClass, type JSX, mount, Scroll, signal, Text, View } from "nsh";
import { Button, type ColumnVisibility, createNavStack, NavPage, NavStack, SplitView } from "nsh/base";
import { desktop, focusRing, hoverFill, Log, Panel, Segmented, sectionSurface, Split, tint, ui, wide } from "./palette";
// `nsh/base`'s `SplitView`: three columns, each a `NavStack` of its own. The
// app owns which columns show (`columnVisibility`); on iOS the columns are a
// UISplitViewController's, here they stand side by side, and in a phone's
// width one shows at a time, the first the visibility shows.
/** One column shows where the window is horizontally compact. */
const compact = () => horizontalSizeClass() === "compact";
const folders = ["Inbox", "Drafts", "Archive"];
const notes: Record<string, string[]> = {
Inbox: ["Design review", "Release notes", "Lunch next week"],
Drafts: ["Quarterly update"],
Archive: ["Conference badges"],
};
const visibilities: ColumnVisibility[] = ["all", "doubleColumn", "detailOnly"];
function App() {
const visibility = signal<ColumnVisibility>("all");
const folder = signal(folders[0]);
const note = signal(notes.Inbox[0]);
const events = signal<string[]>([]);
const log = (line: string) => events.set([line, ...events()].slice(0, 4));
const sidebar = createNavStack(["folders"]);
const list = createNavStack(["notes"]);
const detail = createNavStack(["note"]);
/** A row of a column: its title, its selection in the theme's tint. */
const row = (title: string, selected: boolean, onPress: () => void) => (
<Button
onPress={onPress}
accessibilityState={{ selected }}
hoverStyle={selected ? undefined : { backgroundColor: hoverFill() }}
focusVisibleStyle={focusRing()}
style={{ paddingHorizontal: 12, paddingVertical: desktop ? 8 : 12, borderRadius: 6, backgroundColor: selected ? tint(ui().accent, 0.12) : "transparent" }}
>
<Text style={{ fontSize: 14, color: ui().text, fontWeight: selected ? "600" : "400" }}>{title}</Text>
</Button>
);
/** A column's page: its title over its rows, on its surface. */
const page = (title: string, surface: string, children: JSX.Element) => (
<NavPage title={title} header={<Text style={{ paddingHorizontal: 14, paddingVertical: 10, fontSize: 13, fontWeight: "600", color: ui().text }}>{title}</Text>}>
<View style={{ flex: 1, backgroundColor: surface, borderEndWidth: 1, borderEndColor: ui().line }}>{children}</View>
</NavPage>
);
return (
<View style={{ flex: 1, backgroundColor: ui().page, padding: 20, paddingTop: 24, gap: 14 }}>
<Text style={{ fontSize: 22, fontWeight: "700", color: ui().text }}>split view</Text>
<Text style={{ color: ui().muted }}>
{compact() ? "Pick a folder, then a note: each brings the next column in front" : "Choose which columns show; narrow the window to see one at a time"}
</Text>
<Split
grow
width={720}
inspector={
<>
<Panel title="columnVisibility">
<Segmented options={visibilities} value={visibility()} onChange={(next) => visibility.set(next)} />
</Panel>
<Log title="events" lines={events()} minHeight={96} />
</>
}
>
<View style={{ height: wide() ? 420 : 460, ...sectionSurface(), overflow: "hidden" }}>
<SplitView
style={{ flex: 1 }}
columnVisibility={visibility()}
onColumnVisibilityChange={({ columnVisibility }) => {
visibility.set(columnVisibility);
log(`onColumnVisibilityChange: ${columnVisibility}`);
}}
sidebar={
<NavStack state={sidebar}>
{() =>
page(
"Folders",
ui().inset.backgroundColor,
<Scroll style={{ flex: 1 }} contentStyle={{ padding: 6, gap: 2 }}>
{folders.map((f) =>
row(f, folder() === f, () => {
folder.set(f);
note.set(notes[f][0]);
if (compact()) visibility.set("doubleColumn");
}),
)}
</Scroll>,
)
}
</NavStack>
}
content={
<NavStack state={list}>
{() =>
page(
folder(),
ui().card.backgroundColor,
<Scroll style={{ flex: 1 }} contentStyle={{ padding: 6, gap: 2 }}>
{notes[folder()].map((n) =>
row(n, note() === n, () => {
note.set(n);
if (compact()) visibility.set("detailOnly");
}),
)}
</Scroll>,
)
}
</NavStack>
}
detail={
<NavStack state={detail}>
{() =>
page(
note(),
ui().card.backgroundColor,
<View style={{ flex: 1, padding: 16, gap: 10 }}>
<Text style={{ fontSize: 18, fontWeight: "600", color: ui().text }}>{note()}</Text>
<Text style={{ fontSize: 14, lineHeight: 20, color: ui().muted }}>{`In ${folder()}. Each column is a NavStack of its own, so its pages stay as the others change.`}</Text>
{compact() && row("Back to the notes", false, () => visibility.set("doubleColumn"))}
</View>,
)
}
</NavStack>
}
/>
</View>
</Split>
</View>
);
}
mount(App);use nsh_base::{ColumnVisibility, button, nav_page, nav_stack, split_view, theme};
use nsh_core::prelude::*;
const MESSAGES: [&str; 2] = ["Welcome", "Release notes"];
/// A message of the inbox: a press shows it in the detail.
fn row(
title: &'static str,
selected: Signal<&'static str>,
visibility: Signal<ColumnVisibility>,
) -> impl IntoElement {
button()
.on_press(move || {
selected.set(title);
// Where one column shows, the message comes in front.
if horizontal_size_class() == SizeClass::Compact {
visibility.set(ColumnVisibility::DetailOnly);
}
})
.px_4()
.py_3()
.child(text(title).text_color(move || theme().foreground()))
}
fn mail() -> impl IntoElement {
let visibility = signal(ColumnVisibility::Automatic);
let selected = signal(MESSAGES[0]);
split_view()
.flex_1()
.column_visibility(move || Some(visibility.get()))
.on_column_visibility_change(move |next: &ColumnVisibility| visibility.set(*next))
.sidebar(nav_stack().child(nav_page().title("Inbox").child(
view()
.flex_1()
.children(MESSAGES.map(|title| row(title, selected, visibility))),
)))
.detail(nav_stack().child(
nav_page()
.title(move || SharedString::from(selected.get()))
.child(text(move || format!("{} …", selected.get())).p_4()),
))
}import { horizontalSizeClass, mount, signal, Text, View } from "nsh";
import { Button, type ColumnVisibility, createNavStack, NavPage, NavStack, SplitView } from "nsh/base";
const messages = ["Welcome", "Release notes"];
const inbox = createNavStack(["inbox"]);
const message = createNavStack(["message"]);
function App() {
const visibility = signal<ColumnVisibility>("automatic");
const selected = signal(messages[0]);
const open = (title: string) => {
selected.set(title);
// Where one column shows, the message comes in front.
if (horizontalSizeClass() === "compact") visibility.set("detailOnly");
};
return (
<SplitView
class="flex-1"
columnVisibility={visibility()}
onColumnVisibilityChange={({ columnVisibility }) => visibility.set(columnVisibility)}
sidebar={
<NavStack state={inbox}>
{() => (
<NavPage title="Inbox">
<View class="flex-1">
{messages.map((title) => (
<Button onPress={() => open(title)} class="px-4 py-3">
<Text class="text-foreground">{title}</Text>
</Button>
))}
</View>
</NavPage>
)}
</NavStack>
}
detail={
<NavStack state={message}>
{() => (
<NavPage title={selected()}>
<Text class="p-4 text-foreground">{`${selected()} …`}</Text>
</NavPage>
)}
</NavStack>
}
/>
);
}
mount(App);SplitView 来自 nsh/base,在 Rust 中是 nsh_base::split_view(),以及 ColumnVisibility。在 Rust 中每一栏是一个接收它的栈的设置方法(.sidebar(..)、.content(..)、.detail(..));在 TSX 中每一栏是一个接收 <NavStack> 的属性。
#栏
sidebar:第一栏,应用的分区或列表。content:三栏中间的一栏,侧边栏所选内容中的条目(例如一个邮箱里的邮件)。没有它时视图只有两栏。detail:最后一栏,显示其他栏选中的内容。
每一栏都是一个 NavStack:它的页面、标题栏、返回按钮和状态都属于这个栈,在一栏中推入或弹出页面不会影响其他栏。各栏的宽度由平台决定:在 iOS 上由 UIKit 决定,并随窗口变化;其他平台上采用 iPadOS 的默认值,侧边栏和内容栏宽 320 点,详情栏占据其余空间。外观属于应用:各栏的内容和背景(包括栏之间的分隔线)都由页面绘制。
#显示哪些栏
columnVisibility |
空间充足时 | 空间紧凑时 |
|---|---|---|
"automatic"(默认) |
在 iPadOS 上由系统根据窗口大小和方向决定,并保留用户显示的栏;其他平台上显示所有栏 | 侧边栏 |
"all" |
所有栏 | 侧边栏 |
"doubleColumn" |
内容栏和详情栏;只有两栏时两栏都显示 | 内容栏;只有两栏时为侧边栏 |
"detailOnly" |
详情栏 | 详情栏 |
不设置 columnVisibility 时,视图自己保存这个值,初始为 "automatic"。设置后由应用持有这个值,并在 onColumnVisibilityChange({ columnVisibility }) 中更新它;这个事件报告用户或系统改为显示的栏:iPadOS 的侧边栏按钮、从边缘轻扫、在覆盖于详情栏之上的栏旁边按下、在手机上从一栏的第一页返回。应用保留另一个值时,视图会重新显示应用的值。在 "automatic" 下视图保留用户显示的栏;窗口旋转或改变大小时 iPadOS 自行做出的改变属于 "automatic" 本身,因此报告的是用户做出的改变。
#手机与窄窗口
窗口在水平方向紧凑时(horizontalSizeClass() 为 "compact",Rust 中为 horizontal_size_class())只显示一栏,即 columnVisibility 显示的第一栏。选中某项后要把详情栏显示到前面,就在这时设置 "detailOnly",就像上面的例子所做的那样。
- iOS、iPadOS 和 Mac Catalyst:窗口在水平方向紧凑时(iPhone、侧拉(Slide Over)中的 iPad,或窄的分屏(Split View)和台前调度(Stage Manager)窗口),分栏视图收起为一个由各栏页面组成的导航栈:先是侧边栏的页面,再按
columnVisibility依次是内容栏和详情栏的页面,栏之间使用系统的返回按钮和轻扫返回。在任何一栏推入的页面都会推入到这里。从一栏的第一页返回会显示前一栏,并通过onColumnVisibilityChange报告(三栏时"detailOnly"变为"doubleColumn",两栏时变为"all");离开的页面若不是所在栏的第一页,就像在普通的栈中一样被弹出。窗口重新变宽时,每一栏取回自己的页面。 - Android、桌面平台和 Web:窗口在水平方向紧凑时(窗口宽度小于 600 点),这一栏单独占满全部空间。返回前一栏的方式由应用提供:栏标题栏中的返回按钮,或 Android 上的
BackHandler。
在所有平台上,每一栏在两种呈现方式之间都保留自己的页面和状态。
#属性
| 属性 | Rust | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
sidebar |
.sidebar(..) |
JSX.Element |
无 | 第一栏:一个 NavStack。 |
content |
.content(..) |
JSX.Element |
无 | 三栏中间的一栏:一个 NavStack。没有它时视图只有两栏。 |
detail |
.detail(..) |
JSX.Element |
无 | 最后一栏:一个 NavStack。 |
columnVisibility |
.column_visibility(..) |
ColumnVisibility |
无 | 显示哪些栏(受控):"automatic"、"all"、"doubleColumn" 或 "detailOnly"。不设置时视图自己保存,初始为 "automatic"。 |
class、style |
样式方法 | string、StyleProp<ViewStyle> |
无 | 视图自身:它在父元素中的尺寸(如 flex-1)。它不会超出自己的边界,也不从各栏取得最小尺寸。 |
#事件
| 事件 | Rust | 说明 |
|---|---|---|
onColumnVisibilityChange |
.on_column_visibility_change(|v: &ColumnVisibility| ..) |
{ columnVisibility }:用户或系统改变了显示的栏,值为 "all"、"doubleColumn" 或 "detailOnly"。 |
#无障碍
- 每一栏的页面属于它的栈,按栏的顺序朗读,侧边栏在前。在 iOS 上,系统的侧边栏按钮和返回按钮对 VoiceOver 来说与任何
UISplitViewController中的一样。 - 只显示一栏时,屏幕阅读器只能读到这一栏。
标签、角色和播报的一般用法见无障碍。
#平台说明
- iOS、iPadOS 和 Mac Catalyst:两栏或三栏的
UISplitViewController,每一栏是对应NavStack的UINavigationController。iPadOS 26 以 Liquid Glass 让侧边栏浮在内容之上。从边缘轻扫和侧边栏按钮都由系统提供。 - Android、桌面平台和 Web:各栏以固定宽度并排显示。由用户调整大小和重新排列的工作区是
DockArea。