XiaoyeUI 源码专栏

面向要改这套源码的人的维护者原理手册：讲架构分层、模块边界、状态如何流动、改哪一行会炸。 它不重复 apps/docs 那 98 篇用法手册——那 98 篇回答"怎么用"，本专栏回答"为什么这样设计 + 源码怎么实现 + 改动要注意什么"。

落点状态：本目录被 .gitignore 显式排除（.gitignore:89），只存在于本地、不进版本控制。 因此别用 git status 自查本目录的产物（恒为空），用 ls docs/column/** 或直接读文件。

进度

已落盘 134 篇。每篇的达标判据由脚本机器校验：

node docs/column/tools/verify-refs.mjs --excerpt   # 每条 file:line 是否真存在、摘录是否与标注行吻合
node docs/column/tools/check-doc.mjs              # 骨架完整性 + 篇幅/引用密度 + 禁止项
node docs/column/tools/board.mjs                  # 全队列"落盘且达标"一览
node docs/column/tools/check-guide.mjs            # 15 篇深导览（选型表 + 坑索引 + 编号真实）

怎么读

1. 先读 01-architecture：包拓扑 → 生成物契约 → Token 派生 → 样式引擎 → 注入链 → 交互基座 → 消费侧集成。这一层是后面所有篇的词汇表。
2. 再读 02-infrastructure：某个基座的深读（vc-align 定位、vc-trigger 时序、table-core 状态机、虚拟化、motion…）。
3. 03-components 按需查：12 个类别，每类一篇 *-00-overview.md 横写（该类的共性抽象与近义组件选型），再逐组件一篇深读。
4. 每篇结构固定为七段（职责与边界 → 源码地图 → 架构与数据流 → 核心机制精读 → 对外契约 → 设计取舍 → 坑与改动指南）+ 附「三条可证伪检查点」。只想解决具体问题就直奔第七段；想建立心智模型就读第三、四段。
5. 每个目录另有一篇「深导览」（导览.md，全书入口是 总导览.md）：不讲机制，只做跨篇路由——近义组件选型表 + 全类坑索引（症状 → 哪一篇的坑 N）+ 改动前最小阅读集。第一次进某个类别先读它，能省掉在十几篇里翻的时间。

01-architecture（8 篇）

架构与工程总览，专栏的词汇表。

深导览（选型表 + 坑索引）：01-architecture/导览.md

• monorepo 拓扑与发布链路 — A01
• 组件目录契约与 gen:entries 生成物链路 — A02
• Design Token 四层体系 — A03
• cssinjs 样式引擎与 SSR 注水 — A04
• ConfigProvider 注入链与 Size/Disabled Context — A05
• Props 体系与类型工具 — A06
• 交互基础设施总览：一个浮层是怎么拼起来的 — A07
• 消费侧集成：自动导入与文档生成链 — A08

02-infrastructure（16 篇）

基座模块深读。

深导览（选型表 + 坑索引）：02-infrastructure/导览.md

• vc-align 定位求解与碰撞检测 — I01
• vc-trigger 弹出时序与事件穿透 — I02
• vc-util 工具层 — I03
• 输入基座：vc-input 与 BaseInput — I04
• vc-table 渲染架构 — I05
• table-core 状态机 — I06
• 日期计算内核 — I07
• 虚拟化双实现：vc-virtual-list 与 virtual-scroller — I08
• 动画与 motion 体系 — I09
• z-index 层级编排 — I10
• 多语言体系 — I11
• 校验适配层 resolvers — I12
• 响应式内核 hooks — I13
• 运行时约束与静态检查 — I14
• icons 包生成链与兼容层 — I15
• core / utils / metadata 三包的分工 — I16

03-components（110 篇：12 类横写 + 98 组件）

C01 通用基础（7 篇）

深导览（选型表 + 坑索引）：03-components/01-general/导览.md

• 类横写：button/icon/tag/chips/badge 的职责切分 — C01-00
• Button 按钮 — C01-01
• Icon 图标 — C01-02
• Tag 标签 — C01-03
• Chips 选项 Chips — C01-04
• Badge 徽标 — C01-05
• Empty 空状态 — C01-07

C02 布局与容器（14 篇）

深导览（选型表 + 坑索引）：03-components/02-layout/导览.md

• 类横写：栅格/flex/space 三代布局的取舍 — C02-00
• Grid 栅格 — C02-01
• Flex 弹性布局 — C02-02
• Layout 布局 — C02-03
• Space 间距 — C02-04
• Divider 分割线 — C02-05
• Splitter 分隔面板 — C02-06
• Card 卡片 — C02-07
• Panel 面板 — C02-08
• Collapse 折叠面板 — C02-09
• BlockUI 区块容器 — C02-10
• ScrollPanel 滚动面板 — C02-11
• Toolbar 工具栏 — C02-13
• Fieldset 字段集 — C02-14

C03 导航（14 篇）

深导览（选型表 + 坑索引）：03-components/03-navigation/导览.md

• 类横写：menu/tabs/steps/breadcrumb 的选中态模型 — C03-00
• Menu 导航菜单 — C03-01
• MegaMenu 大图菜单 — C03-02
• PanelMenu 面板菜单 — C03-03
• Breadcrumb 面包屑 — C03-04
• Tabs 标签页 — C03-05
• Steps 步骤条 — C03-06
• Pagination 分页 — C03-07
• Dropdown 下拉菜单 — C03-08
• ContextMenu 右键菜单 — C03-09
• Anchor 锚点 — C03-10
• Affix 固钉 — C03-11
• BackTop 返回顶部 — C03-12
• Tour 引导 — C03-13

C04 基础表单控件（10 篇）

深导览（选型表 + 坑索引）：03-components/04-form-controls/导览.md

• 类横写：受控/非受控与 useMergedState 的一致实现 — C04-00
• Input 输入框 — C04-01
• InputNumber 数字输入框 — C04-02
• Checkbox 多选框 — C04-03
• Radio 单选框 — C04-04
• Switch 开关 — C04-05
• Segmented 分段选择 — C04-06
• Slider 滑动条 — C04-07
• Rate 评分 — C04-08
• ColorPicker 颜色选择 — C04-10

C05 选择与日期（9 篇）

深导览（选型表 + 坑索引）：03-components/05-picker/导览.md

• 类横写：select/cascader/tree-select 共用的选项流水线 — C05-00
• Select 选择器 — C05-01
• AutoComplete 自动完成 — C05-02
• Cascader 级联选择 — C05-03
• TreeSelect 树选择 — C05-04
• Transfer 穿梭框 — C05-05
• DatePicker 日期选择 — C05-06
• TimePicker 时间选择 — C05-07
• Calendar 日历 — C05-08

C06 表单编排与编辑（9 篇）

深导览（选型表 + 坑索引）：03-components/06-form-editor/导览.md

• 类横写：Form 的字段注册、校验与上下文下发 — C06-00
• Form 表单 — C06-01
• FormList 列表表单 — C06-02
• Upload 上传 — C06-03
• Mentions 提及 — C06-04
• InlineEdit 行内编辑 — C06-05
• Inplace 原地编辑 — C06-06
• KeyFilter 关键词过滤 — C06-07
• SortableList 可排序列表 — C06-08

C07 反馈与浮层（10 篇）

深导览（选型表 + 坑索引）：03-components/07-feedback/导览.md

• 类横写：Modal/Drawer/Popover/Tooltip 的浮层生命周期归一 — C07-00
• Modal 对话框 — C07-01
• Drawer 抽屉 — C07-02
• Tooltip 文字提示 — C07-03
• Popover 气泡卡片 — C07-04
• Popconfirm 气泡确认 — C07-05
• Message 全局消息 — C07-06
• Notification 通知 — C07-07
• Alert 警告提示 — C07-08
• Result 结果 — C07-09

C08 表格与虚拟化（7 篇）

深导览（选型表 + 坑索引）：03-components/08-table/导览.md

• 类横写：table / data-table / tree-table 三代表格的分层与选型 — C08-00
• Table 表格 — C08-01
• DataTable 数据表格 — C08-02
• TreeTable 树表格 — C08-03
• List 列表 — C08-05
• VirtualList 虚拟列表 — C08-06
• VirtualScroller 虚拟滚动 — C08-07

C09 树与结构可视化（3 篇）

深导览（选型表 + 坑索引）：03-components/09-tree/导览.md

• 类横写：树数据的三种可视化形态 — C09-00
• Tree 树形控件 — C09-01
• DirectoryTree 目录树 — C09-02

C10 媒体与内容展示（9 篇）

深导览（选型表 + 坑索引）：03-components/10-media/导览.md

• 类横写：图片组的预览与对比关系 — C10-00
• Image 图片 — C10-01
• ImageCompare 图片对比 — C10-02
• Carousel 走马灯 — C10-04
• Avatar 头像 — C10-05
• Watermark 水印 — C10-06
• QRCode 二维码 — C10-07
• Chart 图表 — C10-08
• Comment 评论 — C10-09

C11 状态与信息呈现（9 篇）

深导览（选型表 + 坑索引）：03-components/11-status/导览.md

• 类横写：占位、进度与统计三类的更新频率取舍 — C11-00
• Spin 加载中 — C11-01
• Progress 进度 — C11-02
• Skeleton 骨架屏 — C11-03
• Statistic 统计数值 — C11-04
• MeterGroup 仪表组 — C11-05
• Timeline 时间轴 — C11-06
• Descriptions 描述列表 — C11-07
• Typography 排版 — C11-08

C12 全局与应用级（9 篇）

深导览（选型表 + 坑索引）：03-components/12-global/导览.md

• 类横写：应用级容器与全局能力（App/Portal/FocusTrap/Ripple） — C12-00
• App 应用容器 — C12-01
• ConfigProvider 全局配置 — C12-02
• DarkModeToggle 暗色切换 — C12-03
• FloatButton 浮动按钮 — C12-04
• Ripple 涟漪 — C12-05
• Portal 传送门 — C12-06
• FocusTrap 焦点陷阱 — C12-07
• SplitButton 分裂按钮 — C12-08

维护这份专栏

• 写作合同（红线、六步流程、七段骨架、硬指标、机器校验）：PROMPT.md
• 全书队列与主题边界（谁负责什么、避免两篇重复论证）：OUTLINE.md
• 导览写法合同（第 5 道门）：tools/GUIDE.md 与 node docs/column/tools/check-guide.mjs
• 派工与续写：node docs/column/tools/make-brief.mjs <编号> [slug] / --resume <编号>
• 队列状态回填：node docs/column/tools/set-status.mjs <编号>=已完成，--show 看分布

索引由 docs/column/tools/gen-index.mjs 生成，请勿手工编辑本文件。