元素

SplitView

分栏视图把应用的导航分成几栏显示:侧边栏(分区或列表)、可选的内容栏(侧边栏所选内容中的条目)和详情栏。每一栏都是一个独立的 NavStack,因此每一栏保留自己的页面,各自推入和弹出。在 iOS、iPadOS 和 Mac Catalyst 上,这些栏属于 UISplitViewController:在 iPadOS 26 上侧边栏浮在内容之上,从边缘轻扫或按系统的侧边栏按钮即可呼出,窗口旋转和改变大小时由系统安排各栏。其他平台上各栏以固定宽度并排显示。空间紧凑时(手机、窄窗口)一次只显示一栏。显示哪些栏由 columnVisibility 决定,这个值由应用持有。

el-split-view.tsx
el-split-view.tsx运行中
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()),
        ))
}

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。