解读 interior 的架构:headless hook + styled component 双导出,为什么能复制粘贴还能无限换肤

原创2026-10-18 20:38:411,954 阅读

解读 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 图片灯箱组件演示用的 React 微交互素材:峡谷河流风景图

上图为文档站中 Lightbox 组件演示 实际使用的图片资源,组件源码见 components/interior/lightbox.tsx(700+ 行,从缩放、拖拽到键盘操作全部收进 useLightbox 钩子里)。

🔬 三、为什么"复制粘贴"就够:自包含文件设计

"复制粘贴"听着随意,其实背后有严格的自包含约束,规则写在 CLAUDE.md 的架构章节:

  1. 动效常量每个文件都复制一份。EASE、弹簧参数等会出现在每个组件文件头部——因为复制走的文件不允许再 import 项目里的共享模块,否则拷走就编译报错。
  2. 图标全部内联绘制(Phosphor 几何路径),不引入图标包,保证整个文件只有一个依赖。
  3. 零注释。文件里不写代码注释,设计理由全部沉淀在 lib/registry.meta.ts 的 notes 字段中,避免"文档与代码"漂移。
  4. 唯一依赖是 motion,拷进你的项目后只需安装这一个包。

这种设计让每个文件都像一张"独立图纸":不依赖上游仓库的任何路径,拷出来即可编译、即可运行。

🎨 四、为什么能"无限换肤":行为与渲染彻底解耦

换肤之所以"无限",是因为行为层和样式层之间没有一条耦合缝:

  • hook 不引用任何 class、颜色、阴影,皮肤怎么改它都不感知;
  • 示例组件刻意不用设计 token,而是写死字面量(#4568FF 主色、Tailwind stone 色阶、手写阴影)——因为它会被复制进没有你这套 token 的代码库;
  • 换肤成本 = 重写组件部分的 className,hook 一行不动。

Blur-up 模糊渐显图片组件演示用的 React 微交互素材:山坡上的城堡

上图为 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   注册表条目

这条流水线有三个巧妙之处:

  1. 状态由注册表决定:lib/registry.ts 中,一个 slug 只要出现在 registry.meta.ts 的人工维护映射里,状态就从 planned 变成 ready,文档站随之静态生成它的页面。
  2. 源码从磁盘读取:app/docs/[slug]/page.tsx 页面模板在构建时用 fs.readFile 直接读取 components/interior/<slug>.tsx 的源文件做展示,页面上的代码永远不可能和真实文件漂移。
  3. 兼容 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 个开箱即用的微交互组件,更是提供了一个可学习的范本:把"行为"和"外观"拆成两份导出,组件就能既被复制、又被无限重绘。

📁 相关文件索引

登录后查看全文
interior