解读 interior 的架构:headless hook + styled component 双导出,为什么能复制粘贴还能无限换肤
解读 interior 的架构:headless hook + styled component 双导出,为什么能复制粘贴还能无限换肤
interior 是一个专门做 React 微交互(micro-interactions) 的开源项目,口号是"为点击之后的半秒钟而生"。它没有任何 npm 包,每个组件就是 components/interior/ 目录下一个可复制粘贴的文件;每个文件同时导出 headless hook(纯行为逻辑)和 styled component(带样式的示例组件)两份产物。这种"双导出"架构,正是它能做到"拷走即用、还能无限换肤"的关键。本文带你拆解这套架构的设计思路。
🎯 一、interior 是什么:没有包管理的 React 微交互组件库
大多数 UI 库解决的是"组件长什么样",而 interior 关注的是点击之后那半秒里行为对不对:按钮标签变化时会不会跳动、列表加载时会不会闪、拖拽时标签页失焦会不会卡住。
它的几个关键特征:
| 特征 | 说明 |
|---|---|
| 无包管理 | 不提供 npm 包,源码即产品,直接复制进项目 |
| 组件数量 | 54 个组件,覆盖 10 大类 |
| 唯一依赖 | motion) |
| 文件形态 | 一个组件 = 一个自包含的 .tsx 文件 |
组件按场景分为 10 类,清单定义在 lib/registry.ts 中:
- Action Feedback:Copy Button、Loading Button、Hold to Confirm、Like Burst…
- Input:Floating Label、OTP Input、Password Strength…
- Async:Skeleton Swap、Streaming Text、Task Steps…
- Overlay / Navigation / Scroll / Data / Gesture / Content 等
每个条目一句话描述它解决的 UX 问题,例如 Lightbox 是"能回到出发点的缩放"。完整的设计语言(弹簧参数、阴影、颜色、动效守则)集中写在 DESIGN.md 里,它是整个仓库的"唯一事实来源"。
🧩 二、双导出架构:一个文件,两种身份
打开任意组件文件,比如 components/interior/copy-button.tsx,都会看到固定顺序的"文件文档":"use client" → imports → 动效常量(弹簧、缓动、INSTANT)→ 领域常量 → 纯函数 → 类型导出 → headless hook → 内联图标 → styled component。
以 Copy Button 为例,它对外导出两个主角:
// 行为:所有逻辑都在这里,零 class name
export function useCopyToClipboard({ timeout, onCopy, onError }) { ... }
// 示例皮肤:基于 hook 构建,可保留、可整段重写
export function CopyButton({ value, label, ... }) { ... }
对应源码位置:hook 在 copy-button.tsx,组件在 copy-button.tsx。
1️⃣ headless hook:行为归它,样式碰它不着
useX 系列 hook(useCopyToClipboard、useLightbox…)拥有全部行为:状态机、剪贴板回退、手势的中断面(pointercancel、窗口失焦、Escape……),但一个 class name 都不碰。它只返回数据(status、bind 等),界面完全由你决定怎么画。
2️⃣ styled component:拿来就用的示例皮肤
X 系列组件(CopyButton、Lightbox…)是构建在 hook 之上的官方示例,而不是必须使用的封装。官方文档原话是:"The hook is the product; the component is an example."(hook 是产品,组件是示例)。你既可以直接 <CopyButton value={...} /> 拿来就用,也可以丢掉它、只留 hook 自己写 JSX。
上图为文档站中 Lightbox 组件演示 实际使用的图片资源,组件源码见 components/interior/lightbox.tsx(700+ 行,从缩放、拖拽到键盘操作全部收进 useLightbox 钩子里)。
🔬 三、为什么"复制粘贴"就够:自包含文件设计
"复制粘贴"听着随意,其实背后有严格的自包含约束,规则写在 CLAUDE.md 的架构章节:
- 动效常量每个文件都复制一份。
EASE、弹簧参数等会出现在每个组件文件头部——因为复制走的文件不允许再 import 项目里的共享模块,否则拷走就编译报错。 - 图标全部内联绘制(Phosphor 几何路径),不引入图标包,保证整个文件只有一个依赖。
- 零注释。文件里不写代码注释,设计理由全部沉淀在 lib/registry.meta.ts 的
notes字段中,避免"文档与代码"漂移。 - 唯一依赖是
motion,拷进你的项目后只需安装这一个包。
这种设计让每个文件都像一张"独立图纸":不依赖上游仓库的任何路径,拷出来即可编译、即可运行。
🎨 四、为什么能"无限换肤":行为与渲染彻底解耦
换肤之所以"无限",是因为行为层和样式层之间没有一条耦合缝:
- hook 不引用任何 class、颜色、阴影,皮肤怎么改它都不感知;
- 示例组件刻意不用设计 token,而是写死字面量(
#4568FF主色、Tailwind stone 色阶、手写阴影)——因为它会被复制进没有你这套 token 的代码库; - 换肤成本 = 重写组件部分的 className,hook 一行不动。
上图为 Blur-up 模糊渐显图片演示 使用的素材,对应组件源码在 components/interior/blur-up-image.tsx。
除了样式解耦,interior 还有一组每个组件都必须满足的不变量(DESIGN.md §11):零布局位移(每个可能到达的状态都预先占好空间)、可中断的弹簧、prefers-reduced-motion 下"信息照发、只省旅途"、键盘是第二套完整实现而非兜底。这意味着你换的只是皮,骨架的"手感"标准始终不变。
🏭 五、文档站架构:注册表驱动的组件流水线
interior 仓库本身还包含一个 Next.js 文档站,它把"一个组件"拆成了标准的两文件一注册条目(见 CONTRIBUTING.md):
components/interior/<slug>.tsx 产品本体:hook + 示例组件
lib/demos/<slug>-demo.tsx 文档演示,在 lib/demos/index.tsx 注册
lib/registry.ts + lib/registry.meta.ts 注册表条目
这条流水线有三个巧妙之处:
- 状态由注册表决定:lib/registry.ts 中,一个 slug 只要出现在 registry.meta.ts 的人工维护映射里,状态就从
planned变成ready,文档站随之静态生成它的页面。 - 源码从磁盘读取:app/docs/[slug]/page.tsx 页面模板在构建时用
fs.readFile直接读取components/interior/<slug>.tsx的源文件做展示,页面上的代码永远不可能和真实文件漂移。 - 兼容 shadcn 生态:lib/shadcn-registry.ts 和路由 app/r/registry.json/route.ts 把每个组件包装成 shadcn 注册表格式,你可以用
bunx shadcn@latest add <站点>/r/<slug>.json让 CLI 帮你完成"复制粘贴"。
🚀 六、新手上手指南:3 步用起 interior
第 1 步:拿到组件文件
# 方式 A:clone 仓库后直接复制组件文件
git clone https://gitcode.com/gh_mirrors/inte/interior
cp interior/components/interior/copy-button.tsx your-project/components/
# 方式 B:让 shadcn CLI 代劳(效果等同复制)
bunx shadcn@latest add <文档站地址>/r/copy-button.json
第 2 步:安装唯一依赖
bun add motion
第 3 步:选择用法并换肤
- 想要现成皮肤:
import { CopyButton } from "@/components/copy-button"; - 想要自己的皮肤:
import { useCopyToClipboard } from "@/components/copy-button",拿到status和copy后自己渲染 JSX,样式随你的设计系统走——这就是"无限换肤"的由来。
📌 总结
- 双导出是核心:headless hook 承载 100% 行为且零样式,styled component 只是可丢弃的示例皮肤;
- 复制粘贴成立的前提是自包含:动效常量逐文件复制、图标内联、唯一依赖
motion; - 无限换肤成立的前提是行为/渲染彻底解耦,加上零布局位移、reduced-motion、完整键盘支持等硬性不变量;
- 文档站流水线(注册表 + 构建时读盘 + shadcn 兼容)保证了展示源码与真实文件永不漂移。
对新手而言,interior 最大的价值不只是 54 个开箱即用的微交互组件,更是提供了一个可学习的范本:把"行为"和"外观"拆成两份导出,组件就能既被复制、又被无限重绘。
📁 相关文件索引
- 组件源码目录:components/interior/
- 注册表与元数据:lib/registry.ts、lib/registry.meta.ts、lib/registry.generated.ts
- 演示用例:lib/demos/
- 设计语言:DESIGN.md、CONTRIBUTING.md、CLAUDE.md

