导航¶

NavigationBar / NavigationView¶

主窗口的侧边导航，由窗口的 WindowType 决定紧凑/展开形态。window.addPage() 添加导航项。

页内独立使用¶

两者都是普通 Item，可以脱离窗口外壳直接放进页面（画廊 "Vertical navigation" 区就是这么展示的）。独立使用时有两件事必须知道：

① 选中项是单向绑定，必须由宿主回灌。 面板被点击时只发 itemClicked(index)，自己不修改 currentIndex —— 这是为了避免破坏"窗口 → 导航"的单向绑定：

NavigationView {
    model: [
        { key: "home", text: "Home", icon: ... },
        { key: "docs", text: "Documents", icon: ... }
    ]
    onItemClicked: (index) => currentIndex = index   // 页面里这段接线就是那个"宿主外壳"
}

ToggleNavigationBar 不继承该基类，它会自己更新 currentIndex，无需接线。

② titleBarHeight 默认等于窗口标题栏高度。 页内没有标题栏，不归零就会白白留出顶部空白（实测 48px，条目整体被压低）：

NavigationView {
    titleBarHeight: 0        // 页内无标题栏
    showReturnButton: false  // 页内也不需要返回按钮
}

面板显示模式¶

paneDisplayMode 让面板自己决定形态，不必再手工设 isExpanded：

模式	行为
`Enums.navigation.pane_unspecified`（默认）	不接管 `isExpanded`，行为与历史完全一致
`pane_auto`	面板宽度 ≥ `Enums.controlSize.navPanelExpandWidth` 时展开，否则紧凑
`pane_left`	始终展开侧边栏
`pane_left_compact`	始终紧凑图标栏
`pane_left_minimal`	折叠到只剩菜单按钮；`openPane()` / `togglePane()` 打开后就地展开为图标栏，点菜单按钮即开合

Fluent.NavigationView {
    paneDisplayMode: Enums.navigation.pane_auto
    // pane_left_minimal 时用 isPaneOpen / openPane() / closePane() / togglePane() 控制
}

设置任一模式后 isExpanded 由模式接管（"展开与否"正是模式要决定的事）；只有 pane_unspecified 例外，仍归调用方。

面板自带的菜单按钮在同一个实例上就能开合，不需要按模式克隆控件：

模式	菜单按钮的行为
`pane_left`	`toggle()`：展开侧边栏 ↔ 折叠成图标栏
`pane_left_compact`	`toggle()`：折叠态下点击即展开
`pane_left_minimal`	`togglePane()`：开关浮层面板（`isPaneOpen`）

pane_auto 只看面板自身宽度，所以做响应式时把宽度交给布局即可；图库里用一根滑杆演示了切换点。

顶栏（Top）形态不在 paneDisplayMode 范围内：那是窗口外壳的职责，WindowsBar 当前用 NavigationBar 承载。

SegmentedControl / Pivot 分段控件与透视导航¶

两者共用 items 模型（{ key, text, icon } 或纯字符串）与 currentIndex，默认横向排列：

Fluent.SegmentedControl { items: ["常规", "外观", "高级"] }
Fluent.Pivot { items: [{ key: "docs", text: "文档" }, { key: "img", text: "图片" }] }

orientation: Qt.Vertical 改为纵向堆叠，指示器从底部细条变成贴左边缘的竖条：

Fluent.SegmentedControl {
    orientation: Qt.Vertical
    items: ["General", "Appearance", "Advanced"]
}

纵向时单元按内容定宽（不会拉伸铺满），控件宽度取最宽单元。需要"整行铺满"的纵向导航请用 NavigationView 或 ToggleNavigationBar。

SelectorBar 选择条¶

无边框的选择条：条带直接铺在页面上，只有选中项带滑动胶囊。适合在一小组视图（2~5 个）之间切换，视觉重量比 SegmentedControl 更轻，比 TabBar 更扁平。

Fluent.SelectorBar {
    items: [
        { key: "overview", text: "总览" },
        { key: "activity", text: "活动", icon: "History" },
        { key: "about", text: "关于" }
    ]
    onItemClicked: (index, byUser) => view.push(pages[index])
}

成员	说明
`items: var`	`{ key, text, icon }` 或纯字符串
`currentIndex: int`	选中索引；越界时胶囊隐藏而不抛错
`orientation`	`Qt.Horizontal`（默认）/ `Qt.Vertical`，纵向按内容定宽堆叠
`itemFontSize / iconSize`	单元文字与图标尺寸
`pillAnimationEnabled`	是否动画滑动胶囊；时长与曲线同标签页切换（`Enums.duration.slow` + `OutCubic`）。首次就位不带动画，之后每次选中都滑动
`scrollDuration`	程序化平移时长，默认 `Enums.duration.scroll`（与 TabBar / 滚动区一致）
`scrollable / maxScrollOffset / scrollOffset`	只读：横向溢出与当前滚动位置
`itemClicked(index, byUser)`	用户点击（`byUser` 为 `true`）；编程式选中不发出
`currentItemChanged(key)`	选中键变化
`setCurrentIndex(idx) / setCurrentItem(key)`	编程式选中；越界或未知键被忽略
`addItem(key, text, icon) / getCurrentKey()`	追加项 / 取当前键
`revealCurrent()`	把选中项滚入可视区（选中变化时自动调用，按最小滚动量并优先对齐单元格边界）

横向条带在宽度不足时可横向滚动：选中项会自动滚入可视区（最小滚动量，并优先让前缘落在单元格边界上，因此不会留下半截标签），滚轮与拖拽平移条带。程序化位移（滚轮、自动滚入）复用仓库的平滑滚动引擎，是平滑滑行而非瞬跳；scrollDuration 可调。滚轮归属与 TabBar 一致 —— 溢出时条带自己消费滚轮；未溢出的条带不参与竞争，滚轮原样交给页面滚动区。纵向条带不滚动，按内容定高。

TabBar / TabWidget 标签页¶

import PrismQML as Fluent

Fluent.TabWidget {
    // 标签 + 内容
}

横向（默认）支持拖拽排序、滚动、关闭、添加按钮。TabBar 只渲染标签，页面内容由调用方或 TabWidget 承载。

orientation: Qt.Vertical 把标签列放到起始边（左），页面内容占据其余区域：

Fluent.TabWidget {
    orientation: Qt.Vertical
    width: 360
    height: 220
    tabs: [ { title: "标签1", content: page1 }, { title: "标签2", content: page2 } ]
}

纵向形态的行为：标签行占满列宽、行高取行高（tabWidth 若设置则作为行高）、标题过长省略、关闭按钮贴右、拖拽沿纵轴重排、添加按钮落在列尾、溢出沿 Y 轴滚动。列宽默认取 Enums.controlSize.tabBarVerticalWidth，可用公开属性 stripWidth 覆盖（横向的对应属性是 tabBarHeight，TabWidget 也代理了 stripWidth）。

CommandPalette 命令面板¶

Ctrl+K 风格的命令面板：模态浮层 + 搜索框 + 排名结果列表。过滤、模糊匹配、分组标题、命中高亮与 ↑↓ 导航复用库内搜索栈（SearchResultList），本组件只负责开合、遮罩、焦点与命令派发。

Fluent.CommandPalette {
    id: palette
    shortcut: "Ctrl+K"                        // 可选全局快捷键, 留空则关闭
    placeholderText: "输入命令..."
    hintText: "↑↓ 导航  Enter 执行  Esc 关闭"   // 留空则隐藏底部提示
    items: [
        { key: "open-file", title: "打开文件", subtitle: "Ctrl+O",
          section: "文件", icon: Enums.iconPath + "FolderOpen.svg" },
        { key: "toggle-theme", title: "切换主题", keywords: ["dark", "light"] }
    ]
    onCommandTriggered: (key, item) => runCommand(key)
}

打开：open() / toggle()，或 shortcut 指定的快捷键；每次打开都会清空查询并把键盘焦点收进搜索框。
关闭：Esc、点击遮罩、close()。执行命令时先关闭再发 onCommandTriggered(key, item)，宿主拿到的状态已经收敛。
数据：items 每项支持 key / title / subtitle / icon / section / keywords / enabled；section 非空且 sectionHeaders 为真时按分组显示。
文案：placeholderText / emptyText / hintText 由调用方注入本地化文本，组件内不硬编码。
键路由：面板打开期间 ↑ / ↓ / Enter / Esc 走窗口级快捷键——焦点在搜索框上，其内部文本输入会先吞掉方向键，事件冒泡不到面板。

层级路径导航。

PipsPager 分页指示器¶

Fluent.HorizontalPipsPager { count: 5; currentIndex: 0 }
Fluent.VerticalPipsPager { count: 4 }

支持翻页按钮、可见数量限制。

皮肤适配¶

新粗野下：导航选中项为橙实心块 + 黑边 + 白图标文字（替代 Fluent 的淡色高亮 + 滑动指示条）；TabWidget 选中标签白底粗黑边 + 硬阴影；分页点选中橙、未选黑。

导航¶