Layout 布局
页面或应用的骨架用 Layout:页头、放导航的侧边栏、内容区和页脚,可以整页一起滚动,也可以各区域各自滚动。在内容区里排几个元素,请用 Flex 或 Grid;临时盖在页面上的面板,请用 Drawer。
LayoutSider只有放在带hasSider的Layout里,才会排在内容旁边;放在别处会像页头一样纵向堆叠,并给出警告。position="absolute"时,布局会填满最近的定位父元素,所以这个父元素必须有高度:整个应用就是窗口,否则是一个设定了高度的盒子。
Layout 是页面的骨架:LayoutHeader、LayoutContent 和 LayoutFooter 纵向排列,加上 hasSider 后 LayoutSider 放在内容旁边。每个部件默认渲染对应的地标元素(header、aside、main、footer),可以用 as 换掉。
滚动有两种方式:
- 整页滚动(
position="static",默认)。布局随内容变高、从不裁剪,所以position="sticky"的页头和侧边栏会粘在窗口上。适合文档和文档站。 - 各区域各自滚动(
position="absolute")。布局填满最近的定位父元素,内容区、每个侧边栏和嵌套的布局各自滚动。适合应用外壳。
#演示
#基础用法
页头、内容和页脚纵向排列;hasSider 把侧边栏放到旁边。bordered 在朝向内容的一侧画一条分隔线。
#应用外壳
position="absolute" 填满最近的定位父元素。给这个父元素一个高度(这里是 360px 的盒子;整个应用就是窗口)。页头和页脚保持自身高度,中间的区域各自滚动。
Message 1. The header and footer stay put; the sider and this pane scroll on their own.
Message 2. The header and footer stay put; the sider and this pane scroll on their own.
Message 3. The header and footer stay put; the sider and this pane scroll on their own.
Message 4. The header and footer stay put; the sider and this pane scroll on their own.
Message 5. The header and footer stay put; the sider and this pane scroll on their own.
Message 6. The header and footer stay put; the sider and this pane scroll on their own.
Message 7. The header and footer stay put; the sider and this pane scroll on their own.
Message 8. The header and footer stay put; the sider and this pane scroll on their own.
Message 9. The header and footer stay put; the sider and this pane scroll on their own.
Message 10. The header and footer stay put; the sider and this pane scroll on their own.
Message 11. The header and footer stay put; the sider and this pane scroll on their own.
Message 12. The header and footer stay put; the sider and this pane scroll on their own.
Message 13. The header and footer stay put; the sider and this pane scroll on their own.
Message 14. The header and footer stay put; the sider and this pane scroll on their own.
Message 15. The header and footer stay put; the sider and this pane scroll on their own.
Message 16. The header and footer stay put; the sider and this pane scroll on their own.
#滚动条
侧边栏和 absolute 布局的内容区在 ScrollArea 里滚动。用 scrollAreaProps 给它传属性,这里用 trigger: "none" 让滚动条一直显示;内边距写在它的 contentClassName 上,才会跟着一起滚动。nativeScrollbar 改用浏览器自己的滚动条。
Message 1. With trigger="none" the scrollbars show without hovering.
Message 2. With trigger="none" the scrollbars show without hovering.
Message 3. With trigger="none" the scrollbars show without hovering.
Message 4. With trigger="none" the scrollbars show without hovering.
Message 5. With trigger="none" the scrollbars show without hovering.
Message 6. With trigger="none" the scrollbars show without hovering.
Message 7. With trigger="none" the scrollbars show without hovering.
Message 8. With trigger="none" the scrollbars show without hovering.
Message 9. With trigger="none" the scrollbars show without hovering.
Message 10. With trigger="none" the scrollbars show without hovering.
Message 11. With trigger="none" the scrollbars show without hovering.
Message 12. With trigger="none" the scrollbars show without hovering.
Message 13. With trigger="none" the scrollbars show without hovering.
Message 14. With trigger="none" the scrollbars show without hovering.
Message 15. With trigger="none" the scrollbars show without hovering.
Message 16. With trigger="none" the scrollbars show without hovering.
#收起
showTrigger 在侧边栏边缘加一个切换按钮。collapseMode="width" 把内容收窄到 collapsedWidth;默认的 transform 保持内容宽度,把它滑到边缘下面。
Press the button on the sider's edge. With collapseMode="width" the content narrows to collapsedWidth, so only the icons stay.
#右侧边栏,受控
放在内容后面、placement="right" 的侧边栏在左侧画分隔线和切换按钮。showTrigger="bar" 在旁边画一根拉杆。用 collapsed 和 onUpdateCollapsed 控制;collapsedWidth={0} 加 showCollapsedContent={false} 会把它完全藏起来。
#文档站
整页滚动(外框代替窗口)。页头吸顶;两个侧边栏吸在页头下方 48px 处,高度是窗口减去这个偏移,链接放不下时各自滚动。hideBelow 在窗口窄于某个 Grid 断点时隐藏侧边栏:页面列表在 m 以下隐藏,大纲在 l 以下隐藏。
When to use
The page scrolls as a whole. The header sticks to the top and both siders stick below it, each as tall as the window that is left.
Below 1024px the pages sider hides, and below 1280px the outline does.
Demos
The page scrolls as a whole. The header sticks to the top and both siders stick below it, each as tall as the window that is left.
Below 1024px the pages sider hides, and below 1280px the outline does.
Scrolling
The page scrolls as a whole. The header sticks to the top and both siders stick below it, each as tall as the window that is left.
Below 1024px the pages sider hides, and below 1280px the outline does.
Accessibility
The page scrolls as a whole. The header sticks to the top and both siders stick below it, each as tall as the window that is left.
Below 1024px the pages sider hides, and below 1280px the outline does.
API
The page scrolls as a whole. The header sticks to the top and both siders stick below it, each as tall as the window that is left.
Below 1024px the pages sider hides, and below 1280px the outline does.
#Layout Props
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
as | div | header | footer | aside | main | nav | section | article | div | 渲染的元素。 | 未发布 |
hasSider | boolean | false | 子元素横向排列。里面有 LayoutSider 时要设置。 | 未发布 |
position | static | absolute | static | static 随页面流动;absolute 填满定位父元素,各区域各自滚动。嵌套的布局继承 absolute 的滚动方式。 | 未发布 |
#LayoutHeader、LayoutFooter Props
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
as | LayoutElement | header / footer | 渲染的元素。 | 未发布 |
bordered | boolean | false | 在朝向内容的一侧画分隔线。 | 未发布 |
position | static | sticky | static | sticky 在页面滚动时把它留在顶部(页头)或底部(页脚)。 | 未发布 |
stickyOffset | number | string | 0 | 粘住时离边缘的距离,数字单位是 px。 | 未发布 |
#LayoutContent Props
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
as | LayoutElement | main | 渲染的元素。 | 未发布 |
nativeScrollbar | boolean | false | 用浏览器自己的滚动条,而不是 ScrollArea。 | 未发布 |
onScroll | (event) => void | undefined | 滚动元素滚动时调用。 | 未发布 |
scrollAreaProps | LayoutScrollAreaProps | undefined | 传给 ScrollArea 的属性。 | 未发布 |
scrollRef | Ref<HTMLElement> | undefined | 滚动的元素(内容区本身或它的 ScrollArea),用于 scrollTo。 | 未发布 |
#LayoutSider Props
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
as | LayoutElement | aside | 渲染的元素。 | 未发布 |
bordered | boolean | false | 在朝向内容的一侧画分隔线。 | 未发布 |
collapsed | boolean | undefined | 是否收起(受控)。 | 未发布 |
collapsedWidth | number | string | 48 | 收起时的宽度,数字单位是 px。 | 未发布 |
collapseMode | width | transform | transform | width 收窄内容;transform 保持内容宽度并把它滑出去。 | 未发布 |
contentClassName | string | undefined | 包住子元素的元素的类名。 | 未发布 |
contentStyle | CSSProperties | undefined | 包住子元素的元素的样式。 | 未发布 |
defaultCollapsed | boolean | false | 初始是否收起(非受控)。 | 未发布 |
hideBelow | s | m | l | xl | undefined | 窗口窄于该断点(640、1024、1280、1536px)时隐藏侧边栏。 | 未发布 |
nativeScrollbar | boolean | false | 用浏览器自己的滚动条,而不是 ScrollArea。 | 未发布 |
onScroll | (event) => void | undefined | 滚动元素滚动时调用。 | 未发布 |
onUpdateCollapsed | (collapsed: boolean) => void | undefined | 按下切换按钮时以新状态调用。 | 未发布 |
placement | left | right | left | 在内容的哪一侧;分隔线和切换按钮朝向内容。右侧边栏要放在内容后面。 | 未发布 |
position | static | sticky | static | sticky 在页面滚动时把它留在视野里。在 absolute 布局里忽略,那里它本来就各自滚动。 | 未发布 |
scrollAreaProps | LayoutScrollAreaProps | undefined | 传给 ScrollArea 的属性。 | 未发布 |
scrollRef | Ref<HTMLElement> | undefined | 滚动的元素,用于 scrollTo。 | 未发布 |
showCollapsedContent | boolean | true | 收起时是否仍显示内容。 | 未发布 |
showTrigger | boolean | button | bar | false | 显示收起开关:边缘上的按钮(true、button)或旁边的拉杆。 | 未发布 |
stickyOffset | number | string | 0 | 粘住时离顶部的距离,数字单位是 px。 | 未发布 |
triggerLabel | string | 语言包的“切换侧边栏” | 切换按钮的无障碍名称。 | 未发布 |
width | number | string | 272 | 展开时的宽度,数字单位是 px。 | 未发布 |
每个部件都把原生属性和 ref 转发到根元素。
#说明
- 页头、页脚和侧边栏从不使用
position: absolute。应用外壳里它们是 flex 项,由各区域滚动;页面里它们可以sticky。 Layout本身不滚动:滚动的是内容区或侧边栏,用scrollRef/onScroll拿到它。absolute布局里的嵌套Layout在自己的子元素溢出时仍然原生滚动。- 侧边栏在哪一侧由
LayoutSider的placement决定,所以一个布局两侧可以各有一个侧边栏。 - 颜色由主题决定。需要在侧边栏展开或收起结束时做事,在侧边栏上监听
transitionend。