弹性布局 flex

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

示例

基础用法

一维排布容器：子项横着排，间距走档位，容器自己不给子项加任何样式

甲乙丙

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

const boxStyle =
  "padding: 8px 14px; border-radius: var(--xh-radius-md); background: var(--xh-bg-subtle); color: var(--xh-fg-default)";
</script>

<template>
  <XhFlex gap="sm">
    <span :style="boxStyle">甲</span>
    <span :style="boxStyle">乙</span>
    <span :style="boxStyle">丙</span>
  </XhFlex>
</template>

方向

direction 换主轴：row 横排（缺省），column 竖排

row（缺省）

甲乙丙

column

甲乙丙

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

const boxStyle =
  "padding: 8px 14px; border-radius: var(--xh-radius-md); background: var(--xh-bg-subtle); color: var(--xh-fg-default)";
const labelStyle = "font-size: 13px; color: var(--xh-fg-muted)";
</script>

<template>
  <XhFlex direction="column" gap="lg">
    <XhFlex direction="column" gap="xs">
      <span :style="labelStyle">row（缺省）</span>
      <XhFlex gap="sm">
        <span :style="boxStyle">甲</span>
        <span :style="boxStyle">乙</span>
        <span :style="boxStyle">丙</span>
      </XhFlex>
    </XhFlex>

    <XhFlex direction="column" gap="xs">
      <span :style="labelStyle">column</span>
      <XhFlex direction="column" gap="sm">
        <span :style="boxStyle">甲</span>
        <span :style="boxStyle">乙</span>
        <span :style="boxStyle">丙</span>
      </XhFlex>
    </XhFlex>
  </XhFlex>
</template>

对齐与分布

justify 管主轴怎么分，align 管交叉轴怎么对；两条轴互不相干

justify = start

甲乙丙

justify = center

甲乙丙

justify = end

甲乙丙

justify = between

甲乙丙

align = start

甲乙（更高）丙

align = center

甲乙（更高）丙

align = end

甲乙（更高）丙

align = stretch

甲乙（更高）丙

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

const trackStyle =
  "border: 1px solid var(--xh-border-default); border-radius: var(--xh-radius-md); padding: 8px; block-size: 72px";
const boxStyle =
  "padding: 8px 14px; border-radius: var(--xh-radius-md); background: var(--xh-bg-subtle); color: var(--xh-fg-default)";
const tallBoxStyle = `${boxStyle}; padding-block: 20px`;
const labelStyle = "font-size: 13px; color: var(--xh-fg-muted)";

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

<template>
  <XhFlex direction="column" gap="lg">
    <XhFlex v-for="j in justifies" :key="j" direction="column" gap="xs">
      <span :style="labelStyle">justify = {{ j }}</span>
      <!-- 轨道给了固定高度，主轴上才有多余空间可分 -->
      <XhFlex :justify="j" gap="sm" align="center" :style="trackStyle">
        <span :style="boxStyle">甲</span>
        <span :style="boxStyle">乙</span>
        <span :style="boxStyle">丙</span>
      </XhFlex>
    </XhFlex>

    <XhFlex v-for="a in aligns" :key="a" direction="column" gap="xs">
      <span :style="labelStyle">align = {{ a }}</span>
      <XhFlex :align="a" gap="sm" :style="trackStyle">
        <span :style="boxStyle">甲</span>
        <span :style="tallBoxStyle">乙（更高）</span>
        <span :style="boxStyle">丙</span>
      </XhFlex>
    </XhFlex>
  </XhFlex>
</template>

间距档位

gap 收的是档位名不是像素：xs / sm / md / lg / xl 逐档指向一个间距令牌

gap = xs

甲乙丙

gap = sm

甲乙丙

gap = md

甲乙丙

gap = lg

甲乙丙

gap = xl

甲乙丙

槽位覆盖

甲乙丙

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

const boxStyle =
  "padding: 6px 12px; border-radius: var(--xh-radius-md); background: var(--xh-bg-subtle); color: var(--xh-fg-default)";
const labelStyle = "font-size: 13px; color: var(--xh-fg-muted); inline-size: 96px";

const gaps = ["xs", "sm", "md", "lg", "xl"] as const;
</script>

<template>
  <XhFlex direction="column" gap="sm">
    <XhFlex v-for="g in gaps" :key="g" align="center" gap="md">
      <span :style="labelStyle">gap = {{ g }}</span>
      <XhFlex :gap="g">
        <span :style="boxStyle">甲</span>
        <span :style="boxStyle">乙</span>
        <span :style="boxStyle">丙</span>
      </XhFlex>
    </XhFlex>

    <!-- 档位不够用时，直接给使用者槽位写值，它排在所有档位之前 -->
    <XhFlex align="center" gap="md">
      <span :style="labelStyle">槽位覆盖</span>
      <XhFlex gap="xs" style="--xh-flex-gap: 40px">
        <span :style="boxStyle">甲</span>
        <span :style="boxStyle">乙</span>
        <span :style="boxStyle">丙</span>
      </XhFlex>
    </XhFlex>
  </XhFlex>
</template>

折行与行内

wrap 让放不下的子项换行、行与行之间同样吃 gap；inline 让容器缩到内容宽度、能跟文字排一行

不折行（缺省）：全部挤在一行里，宽度不够就被压窄

前端组件库无障碍设计令牌自定义元素键盘导航

wrap：换行摆，行间距同样是 gap

前端组件库无障碍设计令牌自定义元素键盘导航

inline：容器缩到内容宽度，跟前后文字排在同一行

当前筛选条件为

近 7 天已完成

，共 24 条。

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

const trackStyle =
  "border: 1px solid var(--xh-border-default); border-radius: var(--xh-radius-md); padding: 8px; max-inline-size: 320px";
const tagStyle =
  "padding: 4px 10px; border-radius: var(--xh-radius-full); background: var(--xh-bg-subtle); color: var(--xh-fg-default); font-size: 13px";
const labelStyle = "font-size: 13px; color: var(--xh-fg-muted)";

const tags = ["前端", "组件库", "无障碍", "设计令牌", "自定义元素", "键盘导航"];
</script>

<template>
  <XhFlex direction="column" gap="lg">
    <XhFlex direction="column" gap="xs">
      <span :style="labelStyle">不折行（缺省）：全部挤在一行里，宽度不够就被压窄</span>
      <XhFlex gap="sm" :style="trackStyle">
        <span v-for="t in tags" :key="t" :style="tagStyle">{{ t }}</span>
      </XhFlex>
    </XhFlex>

    <XhFlex direction="column" gap="xs">
      <span :style="labelStyle">wrap：换行摆，行间距同样是 gap</span>
      <XhFlex wrap gap="sm" :style="trackStyle">
        <span v-for="t in tags" :key="t" :style="tagStyle">{{ t }}</span>
      </XhFlex>
    </XhFlex>

    <XhFlex direction="column" gap="xs">
      <span :style="labelStyle">inline：容器缩到内容宽度，跟前后文字排在同一行</span>
      <!-- 外层留成普通块级容器：行内盒要和文字处在同一个行内格式化上下文里才看得出效果 -->
      <div style="line-height: 2">
        当前筛选条件为
        <XhFlex inline align="center" gap="xs">
          <span :style="tagStyle">近 7 天</span>
          <span :style="tagStyle">已完成</span>
        </XhFlex>
        ，共 24 条。
      </div>
    </XhFlex>
  </XhFlex>
</template>

产物

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

解剖

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

data-scope="flex"：root

Props

属性	类型	必填	说明
align	FlexAlign		交叉轴对齐：start / center / end / stretch / baseline，不写则由皮肤的缺省对齐决定。
direction	FlexDirection		主轴方向：row 横排、column 竖排，缺省 row。
gap	FlexGap		子项间距档位：xs / sm / md / lg / xl，不写则不留间距。档位换算成多少由皮肤定。
inline	boolean		容器按行内盒排版，宽度收到内容。
justify	FlexJustify		主轴分布：start / center / end / between / around / evenly，不写则子项从主轴起点排起。
wrap	boolean		一行放不下时折行。

connect API

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

成员	类型	说明
getRootProps	() => T['element']

键盘

规格出处：W3C APG

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