DirectSurface UIDirectSurface UI
开始使用
文档/布局系统

AdaptiveSidebarPanel 自适应侧栏

RenderAdaptiveSidebarPanel 用于“侧栏 + 主内容”页面。在宽度不足时，它自动把完整侧栏替换为紧凑侧栏；如果没有提供紧凑侧栏，则让主内容直接占满宽度。业务页面不需要监听 resize。

API 总览

import {  RenderAdaptiveSidebarPanel,  type AdaptiveSidebarDebugState,  type AdaptiveSidebarMode,  type AdaptiveSidebarResolvedMode,  type AdaptiveSidebarSide,} from 'ds-ui'

最小示例：

const fullNavigation = new RenderText('完整导航')const iconNavigation = new RenderText('紧凑导航')const editor = new RenderText('主内容') const page = new RenderAdaptiveSidebarPanel({  sidebar: fullNavigation,  collapsedSidebar: iconNavigation,  content: editor,  breakpoint: 720,  sidebarWidth: 240,  collapsedSidebarWidth: 56,})

当实际可用宽度小于 breakpoint 时，面板使用 collapsedSidebar；否则使用 sidebar。切换只改变当前参与布局和绘制的侧栏，不会重建 content。

模式切换后，失活侧栏不再参与 Tab 焦点顺序；如果焦点仍在失活侧栏中，面板会清除该焦点，并关闭由该侧栏子树拥有的 popup。框架不会擅自把焦点迁移到另一套侧栏，页面需要默认焦点时应显式设置。

构造参数

参数 类型 默认值 说明
sidebar RenderBox 必填 完整侧栏。
content RenderBox 必填 自动占用剩余空间的主内容。
collapsedSidebar RenderBox undefined 窄宽度使用的紧凑侧栏；省略时窄宽度隐藏侧栏。
mode 'auto' | 'expanded' | 'collapsed' 'auto' 自动或强制显示模式。
side 'left' | 'right' 'left' 侧栏方向。
breakpoint number 720 auto 模式的宽度分界。
sidebarWidth number 240 完整侧栏宽度。
collapsedSidebarWidth number 56 紧凑侧栏宽度。
gap number | undefined 主题间距 侧栏与主内容的间距。

这些参数都描述布局，不读取业务 model。mode 可以在特殊流程中手动指定，但普通响应式页面应保持默认的 auto。

宽度和断点会规整为非负有限值；NaN 或无穷值回退到表中的默认值。gap 为 undefined（包括无效数值回退）时继续使用主题间距，负数规整为 0。

调试状态

debugState() 返回最近一次布局结果：

const debugPanel = new RenderAdaptiveSidebarPanel({  sidebar: new RenderText('完整导航'),  content: new RenderText('主内容'),})const state = debugPanel.debugState() state.resolvedModestate.sidebarWidthstate.contentWidth

AdaptiveSidebarDebugState 只包含布局信息，不包含侧栏选择项或表单值，适合测试 320、480、768、1024、1440 等宽度。

推荐组合

AdaptiveSidebarPanel
  sidebar: 主记录列表
  collapsedSidebar: 紧凑入口
  content: DockPanel
    bottom: 保存/取消
    fill: 单一 vertical ScrollViewer
      FormPanel
  • 完整侧栏和紧凑侧栏负责同一组业务命令，但各自的点击回调仍由页面手动接线。
  • 主内容中的 FormPanel 继续根据剩余宽度计算列数和 label placement。
  • 主表格、树或编辑器如果已经管理滚动，不要再套同方向 ScrollViewer。

API 减法原则

该组件不提供 resize 回调、CSS 风格媒体查询、业务状态同步或内置侧栏选择模型。页面只提供两个侧栏视图和主内容，布局系统根据约束选择当前视图。