栅格 grid

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

示例

基础用法

二维排布容器：cols 定分几列，gap 走间距档位，每一格按文档序依次落格

甲

乙

丙

丁

戊

己

<script setup lang="ts">
import { XhGridItem, XhGridRoot } from "@xihan-ui/vue";

const cellStyle =
  "padding: 12px; border-radius: var(--xh-radius-md); background: var(--xh-bg-subtle); color: var(--xh-fg-default)";

const cells = ["甲", "乙", "丙", "丁", "戊", "己"];
</script>

<template>
  <XhGridRoot :cols="3" gap="md">
    <XhGridItem v-for="c in cells" :key="c" :style="cellStyle">{{ c }}</XhGridItem>
  </XhGridRoot>
</template>

列数

cols 收 1 到 12 的整数；各列等宽，放不下的格子自动换到下一行

cols = 2

甲

乙

丙

丁

cols = 3

甲

乙

丙

丁

戊

己

cols = 4

甲

乙

丙

丁

戊

己

庚

辛

cols = 6

甲

乙

丙

丁

戊

己

庚

辛

壬

癸

子

丑

槽位覆盖：侧栏定宽、正文吃掉剩下的宽度

侧栏

正文

<script setup lang="ts">
import { XhGridItem, XhGridRoot } from "@xihan-ui/vue";

const cellStyle =
  "padding: 10px; border-radius: var(--xh-radius-md); background: var(--xh-bg-subtle); color: var(--xh-fg-default); text-align: center";
const labelStyle = "font-size: 13px; color: var(--xh-fg-muted)";

const columns = [2, 3, 4, 6];
const cells = ["甲", "乙", "丙", "丁", "戊", "己", "庚", "辛", "壬", "癸", "子", "丑"];
</script>

<template>
  <XhGridRoot gap="lg">
    <XhGridItem v-for="n in columns" :key="n">
      <div :style="labelStyle">cols = {{ n }}</div>
      <XhGridRoot :cols="n" gap="sm" style="margin-block-start: 6px">
        <XhGridItem v-for="c in cells.slice(0, n * 2)" :key="c" :style="cellStyle">{{ c }}</XhGridItem>
      </XhGridRoot>
    </XhGridItem>

    <!-- 各列等宽不够用时，直接给使用者槽位写一份轨道表，它排在所有列数档之前 -->
    <XhGridItem>
      <div :style="labelStyle">槽位覆盖：侧栏定宽、正文吃掉剩下的宽度</div>
      <XhGridRoot gap="sm" style="--xh-grid-columns: 160px 1fr; margin-block-start: 6px">
        <XhGridItem :style="cellStyle">侧栏</XhGridItem>
        <XhGridItem :style="cellStyle">正文</XhGridItem>
      </XhGridRoot>
    </XhGridItem>
  </XhGridRoot>
</template>

间距档位

gap 收的是档位名不是像素：xs / sm / md / lg / xl 逐档指向一个间距令牌，行距与列距同吃这一份

gap = xs

甲

乙

丙

丁

戊

己

gap = sm

甲

乙

丙

丁

戊

己

gap = md

甲

乙

丙

丁

戊

己

gap = lg

甲

乙

丙

丁

戊

己

gap = xl

甲

乙

丙

丁

戊

己

槽位覆盖

甲

乙

丙

丁

戊

己

<script setup lang="ts">
import { XhGridItem, XhGridRoot } from "@xihan-ui/vue";

const cellStyle =
  "padding: 8px; border-radius: var(--xh-radius-md); background: var(--xh-bg-subtle); color: var(--xh-fg-default); text-align: center";
const labelStyle = "font-size: 13px; color: var(--xh-fg-muted)";

const gaps = ["xs", "sm", "md", "lg", "xl"] as const;
const cells = ["甲", "乙", "丙", "丁", "戊", "己"];
</script>

<template>
  <XhGridRoot gap="lg">
    <XhGridItem v-for="g in gaps" :key="g">
      <div :style="labelStyle">gap = {{ g }}</div>
      <XhGridRoot :cols="3" :gap="g" style="margin-block-start: 6px">
        <XhGridItem v-for="c in cells" :key="c" :style="cellStyle">{{ c }}</XhGridItem>
      </XhGridRoot>
    </XhGridItem>

    <!-- 档位不够用时，直接给使用者槽位写值，它排在所有档位之前 -->
    <XhGridItem>
      <div :style="labelStyle">槽位覆盖</div>
      <XhGridRoot :cols="3" gap="xs" style="--xh-grid-gap: 32px; margin-block-start: 6px">
        <XhGridItem v-for="c in cells" :key="c" :style="cellStyle">{{ c }}</XhGridItem>
      </XhGridRoot>
    </XhGridItem>
  </XhGridRoot>
</template>

跨列与错列

span 让一格横跨几列；offset 让一格改从第 offset + 1 条列线起排，把它前面那几列空出来

span：横跨几列就占几格宽，放不下的自动挤到下一行

span = 4

span = 2

甲

乙

offset：起排的列线往后挪，前面那几列空着

offset = 1

offset = 2

offset = 3

两者同写：从第三条列线起排，横跨两列

offset = 2，span = 2

<script setup lang="ts">
import { XhGridItem, XhGridRoot } from "@xihan-ui/vue";

const cellStyle =
  "padding: 10px; border-radius: var(--xh-radius-md); background: var(--xh-bg-subtle); color: var(--xh-fg-default); text-align: center";
const markStyle =
  "padding: 10px; border-radius: var(--xh-radius-md); background: var(--xh-bg-brand-subtle); color: var(--xh-fg-brand-strong); text-align: center";
const labelStyle = "font-size: 13px; color: var(--xh-fg-muted)";

const offsets = [1, 2, 3];
</script>

<template>
  <XhGridRoot gap="lg">
    <XhGridItem>
      <div :style="labelStyle">span：横跨几列就占几格宽，放不下的自动挤到下一行</div>
      <XhGridRoot :cols="4" gap="sm" style="margin-block-start: 6px">
        <XhGridItem :span="4" :style="markStyle">span = 4</XhGridItem>
        <XhGridItem :span="2" :style="markStyle">span = 2</XhGridItem>
        <XhGridItem :style="cellStyle">甲</XhGridItem>
        <XhGridItem :style="cellStyle">乙</XhGridItem>
      </XhGridRoot>
    </XhGridItem>

    <XhGridItem>
      <div :style="labelStyle">offset：起排的列线往后挪，前面那几列空着</div>
      <!-- 每档单独一行来看：同一行里前面已经排了东西时，空出来的是那几条列线而不是紧挨着的几格 -->
      <XhGridRoot gap="sm" style="margin-block-start: 6px">
        <XhGridItem v-for="n in offsets" :key="n">
          <XhGridRoot :cols="4" gap="sm">
            <XhGridItem :offset="n" :span="4 - n" :style="markStyle">offset = {{ n }}</XhGridItem>
          </XhGridRoot>
        </XhGridItem>
      </XhGridRoot>
    </XhGridItem>

    <XhGridItem>
      <div :style="labelStyle">两者同写：从第三条列线起排，横跨两列</div>
      <XhGridRoot :cols="4" gap="sm" style="margin-block-start: 6px">
        <XhGridItem :offset="2" :span="2" :style="markStyle">offset = 2，span = 2</XhGridItem>
      </XhGridRoot>
    </XhGridItem>
  </XhGridRoot>
</template>

格内对齐

align 管每一项在自己那格里的块向落点，justify 管行内落点；两轴缺省都是铺满整格

align = start

这一格内容多
把整行撑高
共三行

乙

丙

align = center

这一格内容多
把整行撑高
共三行

乙

丙

align = end

这一格内容多
把整行撑高
共三行

乙

丙

align = stretch

这一格内容多
把整行撑高
共三行

乙

丙

justify = start

甲

乙

丙

justify = center

甲

乙

丙

justify = end

甲

乙

丙

justify = stretch

甲

乙

丙

<script setup lang="ts">
import { XhGridItem, XhGridRoot } from "@xihan-ui/vue";

const cellStyle =
  "padding: 8px 12px; border-radius: var(--xh-radius-md); background: var(--xh-bg-subtle); color: var(--xh-fg-default)";
const tallStyle = `${cellStyle}; background: var(--xh-bg-brand-subtle); color: var(--xh-fg-brand-strong)`;
const trackStyle =
  "border: 1px solid var(--xh-border-default); border-radius: var(--xh-radius-md); padding: 8px; margin-block-start: 6px";
const labelStyle = "font-size: 13px; color: var(--xh-fg-muted)";

const aligns = ["start", "center", "end", "stretch"] as const;
const justifies = ["start", "center", "end", "stretch"] as const;
</script>

<template>
  <XhGridRoot gap="lg">
    <!-- 第一格把整行撑高，另外两格才有块向落点可看 -->
    <XhGridItem v-for="a in aligns" :key="a">
      <div :style="labelStyle">align = {{ a }}</div>
      <XhGridRoot :cols="3" gap="sm" :align="a" :style="trackStyle">
        <XhGridItem :style="tallStyle">这一格内容多<br />把整行撑高<br />共三行</XhGridItem>
        <XhGridItem :style="cellStyle">乙</XhGridItem>
        <XhGridItem :style="cellStyle">丙</XhGridItem>
      </XhGridRoot>
    </XhGridItem>

    <!-- 内容比列窄，才看得出行内落点；stretch 下每一格铺满整列 -->
    <XhGridItem v-for="j in justifies" :key="j">
      <div :style="labelStyle">justify = {{ j }}</div>
      <XhGridRoot :cols="3" gap="sm" :justify="j" :style="trackStyle">
        <XhGridItem :style="cellStyle">甲</XhGridItem>
        <XhGridItem :style="cellStyle">乙</XhGridItem>
        <XhGridItem :style="cellStyle">丙</XhGridItem>
      </XhGridRoot>
    </XhGridItem>
  </XhGridRoot>
</template>

响应式列数

cols 除了整数也收断点对象，逐档写各自的列数：窄视口一列，越宽排得越密，拖动窗口即可看到换档

cols = { base: 1, sm: 2, lg: 4 }

甲

乙

丙

丁

戊

己

庚

辛

只写两档：cols = { base: 2, md: 3 }

甲

乙

丙

丁

戊

己

不写 base：cols = { lg: 3 }

甲

乙

丙

<script setup lang="ts">
import { XhGridItem, XhGridRoot } from "@xihan-ui/vue";

const cellStyle =
  "padding: 12px; border-radius: var(--xh-radius-md); background: var(--xh-bg-subtle); color: var(--xh-fg-default); text-align: center";
const labelStyle = "font-size: 13px; color: var(--xh-fg-muted)";

const cards = ["甲", "乙", "丙", "丁", "戊", "己", "庚", "辛"];
</script>

<template>
  <XhGridRoot gap="lg">
    <!-- 一面卡片墙：窄屏一列到底，宽屏一行摆四张 -->
    <XhGridItem>
      <div :style="labelStyle">cols = { base: 1, sm: 2, lg: 4 }</div>
      <XhGridRoot :cols="{ base: 1, sm: 2, lg: 4 }" gap="sm" style="margin-block-start: 6px">
        <XhGridItem v-for="c in cards" :key="c" :style="cellStyle">{{ c }}</XhGridItem>
      </XhGridRoot>
    </XhGridItem>

    <!-- 没写的档沿用比它窄的那一档：这里只在 md 换一次，md 往上都是三列 -->
    <XhGridItem>
      <div :style="labelStyle">只写两档：cols = { base: 2, md: 3 }</div>
      <XhGridRoot :cols="{ base: 2, md: 3 }" gap="sm" style="margin-block-start: 6px">
        <XhGridItem v-for="c in cards.slice(0, 6)" :key="c" :style="cellStyle">{{ c }}</XhGridItem>
      </XhGridRoot>
    </XhGridItem>

    <!-- 不写 base 就还是一列，从 lg 起才分栏 -->
    <XhGridItem>
      <div :style="labelStyle">不写 base：cols = { lg: 3 }</div>
      <XhGridRoot :cols="{ lg: 3 }" gap="sm" style="margin-block-start: 6px">
        <XhGridItem v-for="c in cards.slice(0, 3)" :key="c" :style="cellStyle">{{ c }}</XhGridItem>
      </XhGridRoot>
    </XhGridItem>
  </XhGridRoot>
</template>

断点档位一览

四档断点取自令牌：sm 640px、md 768px、lg 1024px、xl 1280px；自窄到宽依次接管，视口到哪一档就用哪一档的列数

档位与生效宽度

档位

生效宽度

base

0（起始档）

sm

≥ 640px

md

≥ 768px

lg

≥ 1024px

xl

≥ 1280px

五档写全：cols = { base: 1, sm: 2, md: 3, lg: 4, xl: 6 }

甲

乙

丙

丁

戊

己

庚

辛

壬

癸

子

丑

<script setup lang="ts">
import { XhGridItem, XhGridRoot } from "@xihan-ui/vue";

const cellStyle =
  "padding: 10px; border-radius: var(--xh-radius-md); background: var(--xh-bg-subtle); color: var(--xh-fg-default); text-align: center";
const headStyle = `${cellStyle}; background: var(--xh-bg-brand-subtle); color: var(--xh-fg-brand-strong)`;
const labelStyle = "font-size: 13px; color: var(--xh-fg-muted)";

// 档位名与生效宽度，与断点令牌逐字一致
const tiers = [
  { name: "base", width: "0（起始档）" },
  { name: "sm", width: "≥ 640px" },
  { name: "md", width: "≥ 768px" },
  { name: "lg", width: "≥ 1024px" },
  { name: "xl", width: "≥ 1280px" },
];

const cells = ["甲", "乙", "丙", "丁", "戊", "己", "庚", "辛", "壬", "癸", "子", "丑"];
</script>

<template>
  <XhGridRoot gap="lg">
    <!-- 一档一行：左边档位名，右边这一档从多宽起生效 -->
    <XhGridItem>
      <div :style="labelStyle">档位与生效宽度</div>
      <XhGridRoot :cols="2" gap="sm" style="margin-block-start: 6px">
        <XhGridItem :style="headStyle">档位</XhGridItem>
        <XhGridItem :style="headStyle">生效宽度</XhGridItem>
        <template v-for="tier in tiers" :key="tier.name">
          <XhGridItem :style="cellStyle">{{ tier.name }}</XhGridItem>
          <XhGridItem :style="cellStyle">{{ tier.width }}</XhGridItem>
        </template>
      </XhGridRoot>
    </XhGridItem>

    <!-- 五档写全：一路拉宽窗口，每过一道断点这片格子就少排一行 -->
    <XhGridItem>
      <div :style="labelStyle">五档写全：cols = { base: 1, sm: 2, md: 3, lg: 4, xl: 6 }</div>
      <XhGridRoot
        :cols="{ base: 1, sm: 2, md: 3, lg: 4, xl: 6 }"
        gap="sm"
        style="margin-block-start: 6px"
      >
        <XhGridItem v-for="c in cells" :key="c" :style="cellStyle">{{ c }}</XhGridItem>
      </XhGridRoot>
    </XhGridItem>
  </XhGridRoot>
</template>

产物

层	值
自定义元素	<xh-grid>
Vue 组件	XhGridItem XhGridRoot
状态机	无，connect 直接由 props 算属性
皮肤	@xihan-ui/styles/grid.css

解剖

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

data-scope="grid"：root · item

Props

属性	类型	必填	说明
align	GridAlign		每一项在自己那格里的块向对齐：start / center / end / stretch / baseline，不写则铺满格高。
cols	GridCols		列数：1 至 12 的整数，不写按一列排。各列等宽，且每列的下限是 0，长内容不会把自己那列撑宽。 也收断点对象 { base, sm, md, lg, xl }，逐档写各自的列数，没写的档沿用比它窄的那一档。
gap	GridGap		行列间距档位：xs / sm / md / lg / xl，不写则不留间距。档位换算成多少由皮肤定。
justify	GridJustify		每一项在自己那格里的行内对齐：start / center / end / stretch，不写则铺满格宽。

connect API

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

成员	类型	说明
getRootProps	() => T['element']
getItemProps	(props?: GridItemProps) => T['element']

键盘

规格出处：W3C APG

无键盘交互（不接收焦点，或焦点行为完全由原生元素提供）。