LobeHub 前端布局实战：@lobehub/ui 的 Flexbox 与 Center 组件完全指南

本篇基于 LobeHub 仓库内 React 技能规范文档 .agents/skills/react/references/layout-kit.md 编写，系统讲解 @lobehub/ui 提供的 Flexbox 与 Center 两个布局组件的 Props 语义、经典布局范例与最佳实践，并结合仓库中真实业务组件（404 页面、分享视图、验证列表等）的源码实现，说明这些布局约定在 LobeHub 多应用 Monorepo 中的落地方式。读完本文，你可以在 LobeHub 项目中按官方约定编写可滚动、可伸缩、主题自适应的 Flex 布局，而不必手搓 CSS。

1. 布局组件在 LobeHub 组件体系中的位置

在讲解具体用法之前，先明确 Flexbox / Center 在 LobeHub 组件选型规范中的定位。仓库的 React 技能文档 SKILL.md 定义了组件优先级：

1. src/components — 项目内可复用组件；
2. @lobehub/ui/base-ui — headless 原语；
3. @lobehub/ui 根导出 — 更高层 / antd 封装组件，其中 Layout 分类明确包含 Center、DraggablePanel、Flexbox、Grid、Header、MaskShadow；
4. antd 本身 — 仅在前两者都无提供时使用。

SKILL.md 在 Layout 一节直接指向本文档：「Use Flexbox and Center from @lobehub/ui. See references/layout-kit.md for full props and examples.」也就是说，Flexbox 和 Center 是 LobeHub 前端布局的官方默认选择。依赖版本上，根目录 package.json 中声明了 "@lobehub/ui": "^5.38.0"，同时项目使用 antd 6.3.5 与 antd-style 4.1.0 作为样式基础设施——Flexbox 正是构建在这套 antd 主题 token 体系之上的布局封装。

2. Flexbox 组件：基本用法

Flexbox 是最常用的布局组件，语义等价于 CSS 的 display: flex，默认是纵向排列：

import { Flexbox } from '@lobehub/ui';

// 默认纵向布局
<Flexbox>
  <div>Child 1</div>
  <div>Child 2</div>
</Flexbox>

// 横向布局
<Flexbox horizontal>
  <div>Left</div>
  <div>Right</div>
</Flexbox>

关键认知：默认方向是 vertical，横向必须显式加 horizontal。这一约定贯穿整个代码库，例如 src 下有 15+ 个业务文件直接以 <Flexbox horizontal …> 方式写横排布局（见 package.json 依赖声明的同一套组件）。

2.1 常用 Props 速查

Prop	类型	说明
horizontal	boolean	设为 true 时切换为横向（row）布局，默认纵向（column）
flex	number | string	控制 flex 属性，flex={1} 表示填满剩余空间，flex={'none'} 表示不参与伸缩
gap	number	子元素间距（优先于 margin 使用）
align	string	交叉轴对齐，如 'center'、'flex-start'
justify	string	主轴对齐，如 'space-between'、'center'
padding	number	内边距
paddingInline	number	水平方向内边距
paddingBlock	number	垂直方向内边距
width / height	number | string	尺寸，通常传 '100%' 或具体像素值，数字即 px
style	CSSProperties	自定义样式对象，用于边框、溢出等 Props 未覆盖的场景

2.2 真实用例：404 页面

LobeHub 的 404 组件 src/components/404/index.tsx 展示了 align + justify + style 三者配合的最小范式：

<Flexbox align={'center'} justify={'center'} style={{ minHeight: '100%', width: '100%' }}>
  <FluentEmoji emoji={'👀'} size={64} />
  <h2 style={{ fontWeight: 'bold', marginTop: '1em', textAlign: 'center' }}>
    {title || t('notFound.title')}
  </h2>
  …
</Flexbox>

这里没有使用 Center，而是用 align='center' justify='center' 手动居中——两者能力等价，Center 的价值在于把这一组合固化为语义化组件。另注意 minHeight: '100%' 这类取值需要放在 style 中，因为 Props 里只有 height。

3. 经典三栏布局范例

原文档给出的三栏布局是 LobeHub 类应用（侧边栏 + 主内容 + 页脚）的标准骨架，务必完整掌握：

// 经典三栏布局
<Flexbox horizontal height={'100%'} width={'100%'}>
  {/* 左侧边栏 */}
  <Flexbox
    width={260}
    style={{
      borderRight: `1px solid ${theme.colorBorderSecondary}`,
      height: '100%',
      overflowY: 'auto',
    }}
  >
    <SidebarContent />
  </Flexbox>

  {/* 中间内容区 */}
  <Flexbox flex={1} style={{ height: '100%' }}>
    <Flexbox flex={1} padding={24} style={{ overflowY: 'auto' }}>
      <MainContent />
    </Flexbox>

    {/* 页脚 */}
    <Flexbox
      style={{
        borderTop: `1px solid ${theme.colorBorderSecondary}`,
        padding: '16px 24px',
      }}
    >
      <Footer />
    </Flexbox>
  </Flexbox>
</Flexbox>

逐层拆解这个结构的布局原理：

• 最外层 horizontal height={'100%'} width={'100%'}：撑满整个视口并切分为左右两列；
• 侧边栏固定 width={260}，overflowY: 'auto' 让侧栏内容独立滚动，不与主内容争抢滚动条；
• 中间列 flex={1} 吃掉剩余全部宽度，内部再纵向嵌套两层：flex={1} 的内容区独占高度并 overflowY: 'auto' 实现内容区独立滚动，页脚则被自然推到底部——这是「滚动区 + 固定页脚」模式的核心技巧；
• 分隔线使用 theme.colorBorderSecondary，即通过 useTheme hook 读取 antd 主题 token，保证深浅色主题下边框颜色自动适配。这正是原文档 Best Practices 中「Combine with useTheme hook for theme-responsive layouts」的落地形态：不要写死边框色，一律取主题变量。

4. Center 组件：语义化居中

Center 是对 Flexbox 的进一步封装，固定为水平 + 垂直双轴居中。适用于占位符、图标容器、空状态等场景：

import { Center } from '@lobehub/ui';

<Center width={'100%'} height={'100%'}>
  <Content />
</Center>

// 图标居中
<Center className={styles.icon} flex={'none'} height={40} width={40}>
  <Icon icon={icon} size={24} />
</Center>

第二个示例值得注意两个细节：flex={'none'} 使容器不随父级 Flex 伸缩（固定 40×40），className 说明 Center 也支持 antd-style 生成的类名，可与 createStaticStyles 组合使用。

仓库中 Center 的真实用法印证了这一点：

• apps/share/src/features/artifact/SharedArtifactView.tsx 使用 <Center height={'100dvh'}> 让分享页内容在整个动态视口高度内居中，SharedPageView.tsx 同样使用 height={'100vh'}；
• apps/workbench/src/features/verify/VerifyList.tsx 用 <Center className={styles.emptyState} gap={12}> 构建带间距的空状态布局——Center 保留了 gap、className 等 Flexbox 全部能力；
• packages/builtin-tool-knowledge-base/src/client/Render/SearchKnowledgeBase/Item/index.tsx 用 <Center className={styles.badge}> 做小号徽章居中。

可以推断：凡是需要「单块内容在某容器内双轴居中」的场景，优先写 Center 而不是重复 align/justify 两个属性，既减少样板代码又统一了团队心智模型。

5. 最佳实践（原文档约定 + 仓库佐证）

原文档给出的六条 Best Practices 完整保留并补充依据：

1. 用 flex={1} 填满可用空间——三栏布局中间列的标准写法；
2. 用 gap 代替 margin 做子元素间距——避免 margin 塌陷与相邻元素间距失控，如 VerifyList.tsx 的 gap={12}；
3. 复杂布局嵌套 Flexbox——「外层横向切列、内层纵向切行」的组合是主内容区 + 页脚模式的通用解法；
4. 可滚动内容设置 overflow: 'auto'——放在具体滚动容器上（overflowY: 'auto'），而不是外层容器，让滚动局部化；
5. 横向布局显式写 horizontal（默认是纵向）；
6. 结合 useTheme hook 做主题自适应布局——边框色、分隔线一律取 theme.colorBorder* 系列 token。

结合 SKILL.md 的样式优先级约定（首选 createStaticStyles + cssVar.*，单次性样式可用 inline style），布局层面的推荐组合是：结构用 Flexbox/Center Props，一次性视觉细节用 style 或 className 静态样式，主题相关颜色用 useTheme。

6. 选型小结

场景	推荐写法
通用 Flex 容器	<Flexbox horizontal?> + gap / align / justify / flex
内容双轴居中（空状态、图标、占位）	<Center>
撑满剩余空间	子项 flex={1}，父项保证 height: '100%'
独立滚动区	滚动容器 style={{ overflowY: 'auto' }}，配合固定页脚
主题化分隔线	useTheme 取 colorBorderSecondary 写入 style

以上约定在 LobeHub 的 src/components、apps/share、apps/workbench 及 packages/builtin-tool-* 系列内置工具 UI 中一致执行。掌握 Flexbox 与 Center 这两个组件及其 Props 语义，就覆盖了 LobeHub 前端绝大部分静态布局需求；更复杂的拖拽面板可再看 @lobehub/ui 根导出的 DraggablePanel 与 Grid。