布局 layout

布局组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

头与脚各横贯一行，侧栏与内容并排占中间那一行；少写一段就少一行或少一列

控制台

导航

正文区。四段都可缺省，只摆头和内容也是一副合法的骨架。

版本 1.0.0

<script setup lang="ts">
import {
  XhLayoutContent,
  XhLayoutFooter,
  XhLayoutHeader,
  XhLayoutRoot,
  XhLayoutSider,
} from "@xihan-ui/vue";
</script>

<template>
  <XhLayoutRoot
    bordered
    style="block-size: 280px; border-radius: 8px; overflow: hidden"
  >
    <XhLayoutHeader>控制台</XhLayoutHeader>
    <XhLayoutSider>导航</XhLayoutSider>
    <XhLayoutContent>
      正文区。四段都可缺省，只摆头和内容也是一副合法的骨架。
    </XhLayoutContent>
    <XhLayoutFooter>版本 1.0.0</XhLayoutFooter>
  </XhLayoutRoot>
</template>

折叠侧栏

不传 sider-collapsed 即为非受控，把手按下去只改宽度，侧栏节点一直在

控制台

导航 · 收藏 · 回收站

折起来的是宽度不是高度，侧栏里的滚动位置与输入框都留着。

<script setup lang="ts">
import {
  XhLayoutContent,
  XhLayoutHeader,
  XhLayoutRoot,
  XhLayoutSider,
  XhLayoutSiderTrigger,
} from "@xihan-ui/vue";
</script>

<template>
  <XhLayoutRoot
    bordered
    style="block-size: 240px; border-radius: 8px; overflow: hidden"
  >
    <XhLayoutHeader>
      <XhLayoutSiderTrigger>切换</XhLayoutSiderTrigger>
      <span>控制台</span>
    </XhLayoutHeader>
    <XhLayoutSider>导航 · 收藏 · 回收站</XhLayoutSider>
    <XhLayoutContent>
      折起来的是宽度不是高度，侧栏里的滚动位置与输入框都留着。
    </XhLayoutContent>
  </XhLayoutRoot>
</template>

受控

传了 sider-collapsed 就由宿主说了算，组件不再自改，只发 sider-collapsed-change

当前：已展开

导航

把手与上面那个按钮改的是同一份状态。

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhLayoutContent,
  XhLayoutHeader,
  XhLayoutRoot,
  XhLayoutSider,
  XhLayoutSiderTrigger,
} from "@xihan-ui/vue";

const collapsed = ref(false);
</script>

<template>
  <div style="display: grid; gap: 12px">
    <XhButton size="sm" @click="collapsed = !collapsed">
      从外面{{ collapsed ? "展开" : "收起" }}
    </XhButton>

    <XhLayoutRoot
      v-model:sider-collapsed="collapsed"
      bordered
      style="block-size: 220px; border-radius: 8px; overflow: hidden"
    >
      <XhLayoutHeader>
        <XhLayoutSiderTrigger>切换</XhLayoutSiderTrigger>
        <span>当前：{{ collapsed ? "已折叠" : "已展开" }}</span>
      </XhLayoutHeader>
      <XhLayoutSider>导航</XhLayoutSider>
      <XhLayoutContent>
        把手与上面那个按钮改的是同一份状态。
      </XhLayoutContent>
    </XhLayoutRoot>
  </div>
</template>

侧栏位置

sider-placement 决定侧栏挂在行首还是行尾，分隔线也跟着换到挨内容的那一边

侧栏在行首

导航

正文

侧栏在行尾

属性面板

正文

<script setup lang="ts">
import {
  XhLayoutContent,
  XhLayoutHeader,
  XhLayoutRoot,
  XhLayoutSider,
} from "@xihan-ui/vue";
</script>

<template>
  <div style="display: grid; gap: 16px">
    <XhLayoutRoot
      sider-placement="start"
      bordered
      style="block-size: 160px; border-radius: 8px; overflow: hidden"
    >
      <XhLayoutHeader>侧栏在行首</XhLayoutHeader>
      <XhLayoutSider>导航</XhLayoutSider>
      <XhLayoutContent>正文</XhLayoutContent>
    </XhLayoutRoot>

    <XhLayoutRoot
      sider-placement="end"
      bordered
      style="block-size: 160px; border-radius: 8px; overflow: hidden"
    >
      <XhLayoutHeader>侧栏在行尾</XhLayoutHeader>
      <XhLayoutSider>属性面板</XhLayoutSider>
      <XhLayoutContent>正文</XhLayoutContent>
    </XhLayoutRoot>
  </div>
</template>

侧栏宽度

展开与折叠各一档宽度，两档都接受任意 CSS 长度，切换时按皮肤里的过渡走

220px ⇄ 56px

导航

只写其中一档时，另一档仍取皮肤里的缺省宽度。

<script setup lang="ts">
import {
  XhLayoutContent,
  XhLayoutHeader,
  XhLayoutRoot,
  XhLayoutSider,
  XhLayoutSiderTrigger,
} from "@xihan-ui/vue";
</script>

<template>
  <XhLayoutRoot
    sider-width="220px"
    sider-collapsed-width="56px"
    bordered
    style="block-size: 220px; border-radius: 8px; overflow: hidden"
  >
    <XhLayoutHeader>
      <XhLayoutSiderTrigger>切换</XhLayoutSiderTrigger>
      <span>220px ⇄ 56px</span>
    </XhLayoutHeader>
    <XhLayoutSider>导航</XhLayoutSider>
    <XhLayoutContent>
      只写其中一档时，另一档仍取皮肤里的缺省宽度。
    </XhLayoutContent>
  </XhLayoutRoot>
</template>

吸顶与固定

header-fixed 让头钉在滚动容器上沿，sider-fixed 让侧栏跟着钉住；两个一起用时侧栏自动让开头的高度

控制台

导航

第 1 段正文。向下滚：头钉在上沿，侧栏钉在头的下沿，只有正文在走。

第 2 段正文。向下滚：头钉在上沿，侧栏钉在头的下沿，只有正文在走。

第 3 段正文。向下滚：头钉在上沿，侧栏钉在头的下沿，只有正文在走。

第 4 段正文。向下滚：头钉在上沿，侧栏钉在头的下沿，只有正文在走。

第 5 段正文。向下滚：头钉在上沿，侧栏钉在头的下沿，只有正文在走。

第 6 段正文。向下滚：头钉在上沿，侧栏钉在头的下沿，只有正文在走。

第 7 段正文。向下滚：头钉在上沿，侧栏钉在头的下沿，只有正文在走。

第 8 段正文。向下滚：头钉在上沿，侧栏钉在头的下沿，只有正文在走。

第 9 段正文。向下滚：头钉在上沿，侧栏钉在头的下沿，只有正文在走。

第 10 段正文。向下滚：头钉在上沿，侧栏钉在头的下沿，只有正文在走。

第 11 段正文。向下滚：头钉在上沿，侧栏钉在头的下沿，只有正文在走。

第 12 段正文。向下滚：头钉在上沿，侧栏钉在头的下沿，只有正文在走。

第 13 段正文。向下滚：头钉在上沿，侧栏钉在头的下沿，只有正文在走。

第 14 段正文。向下滚：头钉在上沿，侧栏钉在头的下沿，只有正文在走。

版本 1.0.0

<script setup lang="ts">
import {
  XhLayoutContent,
  XhLayoutFooter,
  XhLayoutHeader,
  XhLayoutRoot,
  XhLayoutSider,
} from "@xihan-ui/vue";
</script>

<template>
  <!-- 滚动发生在骨架外面这一层：root 的高度跟着内容长，钉住的两段才有行程可走。
       overflow 写在这里而不是 root 上——写在 root 上，root 自己就成了一个永远滚不动的
       滚动容器，里面的吸附会静悄悄地不生效 -->
  <div
    style="
      block-size: 260px;
      overflow: auto;
      border: 1px solid var(--xh-border-default);
      border-radius: 8px;
    "
  >
    <!-- 滚动容器不是视口，把它的可视高度告诉侧栏，侧栏那道高度上限才算得准 -->
    <XhLayoutRoot
      header-fixed
      sider-fixed
      bordered
      style="--xh-layout-scrollport-h: 260px"
    >
      <XhLayoutHeader>控制台</XhLayoutHeader>
      <XhLayoutSider>导航</XhLayoutSider>
      <XhLayoutContent>
        <p v-for="i in 14" :key="i" style="margin-block-end: 12px">
          第 {{ i }} 段正文。向下滚：头钉在上沿，侧栏钉在头的下沿，只有正文在走。
        </p>
      </XhLayoutContent>
      <XhLayoutFooter>版本 1.0.0</XhLayoutFooter>
    </XhLayoutRoot>
  </div>
</template>

分别固定

两个开关各自独立：只写 header-fixed 时侧栏照常随内容滚走，只写 sider-fixed 时侧栏钉在滚动容器上沿、头照常滚走

只固定头

导航会滚走

第 1 段正文。

第 2 段正文。

第 3 段正文。

第 4 段正文。

第 5 段正文。

第 6 段正文。

第 7 段正文。

第 8 段正文。

第 9 段正文。

第 10 段正文。

头会滚走

只固定侧栏

第 1 段正文。

第 2 段正文。

第 3 段正文。

第 4 段正文。

第 5 段正文。

第 6 段正文。

第 7 段正文。

第 8 段正文。

第 9 段正文。

第 10 段正文。

<script setup lang="ts">
import {
  XhLayoutContent,
  XhLayoutHeader,
  XhLayoutRoot,
  XhLayoutSider,
} from "@xihan-ui/vue";
</script>

<template>
  <div style="display: grid; gap: 16px">
    <div
      style="
        block-size: 200px;
        overflow: auto;
        border: 1px solid var(--xh-border-default);
        border-radius: 8px;
      "
    >
      <XhLayoutRoot header-fixed bordered>
        <XhLayoutHeader>只固定头</XhLayoutHeader>
        <XhLayoutSider>导航会滚走</XhLayoutSider>
        <XhLayoutContent>
          <p v-for="i in 10" :key="i" style="margin-block-end: 12px">
            第 {{ i }} 段正文。
          </p>
        </XhLayoutContent>
      </XhLayoutRoot>
    </div>

    <div
      style="
        block-size: 200px;
        overflow: auto;
        border: 1px solid var(--xh-border-default);
        border-radius: 8px;
      "
    >
      <!-- 头没固定，侧栏就贴滚动容器的上沿，不必让开谁 -->
      <XhLayoutRoot
        sider-fixed
        bordered
        style="--xh-layout-scrollport-h: 200px"
      >
        <XhLayoutHeader>头会滚走</XhLayoutHeader>
        <XhLayoutSider>只固定侧栏</XhLayoutSider>
        <XhLayoutContent>
          <p v-for="i in 10" :key="i" style="margin-block-end: 12px">
            第 {{ i }} 段正文。
          </p>
        </XhLayoutContent>
      </XhLayoutRoot>
    </div>
  </div>
</template>

产物

层	值
自定义元素	<xh-layout>
Vue 组件	XhLayoutContent XhLayoutFooter XhLayoutHeader XhLayoutRoot XhLayoutSider XhLayoutSiderTrigger
组合式函数	useLayout
状态机	layoutMachine
皮肤	@xihan-ui/styles/layout.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="layout"：root · header · sider · content · footer · sider-trigger

Props

属性	类型	必填	说明
siderCollapsed	boolean		受控折叠态：给了值就由宿主说了算。
defaultSiderCollapsed	boolean		非受控初始折叠态。
siderWidth	string		展开时侧栏的宽度，任意 CSS 长度；不写则用皮肤里的档位。
siderCollapsedWidth	string		折叠时侧栏的宽度，任意 CSS 长度；不写则用皮肤里的档位。
siderPlacement	LayoutSiderPlacement		侧栏挂在行首还是行尾，缺省 start。
headerFixed	boolean		头吸顶：滚动时头钉在滚动容器的上沿。只落标记，钉住的实现归皮肤。
siderFixed	boolean		侧栏吸附：滚动时侧栏钉在滚动容器的上沿，头也吸顶时让开头那一条。只落标记，钉住的实现归皮肤。
bordered	boolean		在头、侧栏、脚与内容之间画分隔线。
onSiderCollapsedChange	(details: LayoutSiderCollapsedChangeDetails) => void		折叠态变化意图回调；受控时是唯一出口，非受控随内部转移一并通知。

状态机

状态：expanded · collapsed

事件：SIDER.COLLAPSE · SIDER.EXPAND · SIDER.TOGGLE · CONTROLLED.COLLAPSE · CONTROLLED.EXPAND

判据：isSiderCollapsedControlled

connect API

useLayout 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
siderCollapsed	boolean	侧栏当前是否折叠。
setSiderCollapsed	(next: boolean) => void
getRootProps	() => T['element']
getHeaderProps	() => T['element']
getSiderProps	() => T['element']
getContentProps	() => T['element']
getFooterProps	() => T['element']
getSiderTriggerProps	() => T['button']

键盘

规格出处：W3C APG

按键	生效条件	行为
Space / Enter	focus in sider-trigger	折叠/展开 sider