做前端开发时间久了会遇到一种很奇怪的项目状态功能都正常但没有人敢改代码。一个很简单的页面改一行 CSS可能把某个隐藏模块的布局带崩改一个按钮事件可能让另一个页面的逻辑失效。页面看起来结构清楚实际上已经是一盘互相牵连的线团。这种状态通常不是因为程序员不够细心而是 HTML 页面缺少一个真正意义上的“组件系统”。更准确地说缺少的不是组件而是分层的组件系统。标题里的 “layered” 比 “component” 更值得琢磨。它说的不是把代码放到不同文件夹而是让页面在纵向上分成若干可以独立观察、替换和维护的“层”。分层 HTML 组件系统的核心价值不是让代码更好看而是让复杂页面从“不可预测地牵连”变成“按边界地协作”。这篇文章我会从分层组件系统的必要性、四层结构、通信机制以及落地时的渐进路径和排查思路几个方面展开。它不是某个框架的教程而是无论你用手写 HTML、原生 Web Components还是组件化框架都能参考的一套设计思路。1. 单层组件的困局不是代码量问题是依赖方向问题1.1 拆了组件不等于有了分层先澄清一个容易混淆的点。很多人觉得把页面拆成头部、导航、卡片、弹窗各自做成组件这就是组件化了。组件化确实做了但系统仍然可能是单层的结构、样式、行为、内容全部耦合在一个组件里。举个例子。你封装了一个按钮组件文件里同时包含按钮的 HTML 结构、颜色、文字内容和点击逻辑。这个组件确实能在多个页面复用但它内部已经是一锅粥。当其中一个页面要求按钮在某种场景下变短、变灰、不响应点击时你只能在组件里加条件分支一个页面用一套判断另一个页面用另一套判断。时间一长这个组件内部会塞满 “如果在这个场景就渲染这个那个场景就渲染那个” 的逻辑。单层组件的核心问题不是代码量变大而是依赖方向不明确。组件内部什么都管就意味着改动任何一个局部需求时你要理解整段组件逻辑。每一条依赖都可能是双向的时间一长没有人能说清楚哪块逻辑可以安全替换。这就是为什么要把“组件化”再往前走一步变成“分层组件系统”。分层的价值不是减少代码量而是给依赖关系划定方向哪一层是稳定的哪一层是易变的哪一层依赖哪一层。方向一旦清楚替换成本、排查成本、甚至是交接成本都会大幅下降。1.2 一个反直觉判断分层不是拆分是合并另一个反直觉的地方是分层看起来是在做拆分实际上是在做合并。拆组件是把一个大的页面拆成多个小的块。分层则是把同类职责合并成“层”。比如所有组件里的颜色、间距、圆角、阴影这些都属于展示层它们被合并在展示层的变量体系里所有组件里的格式化逻辑、数据来源、状态流转属于内容层或数据层。合并的结果是同类问题只有一个地方需要改。所以一个真正的分层 HTML 组件系统通常包含两层含义纵向看每个组件内部由结构、展示、行为、内容四层构成。横向看全局的样式变量、脚本工具、数据规范分别属于各自的层。我实际接触过的项目里前端架构出问题的原因往往不是组件拆分得不够细而是“层”没有立起来。组件越拆越细依赖却越来越乱。真正需要补的不是更多组件而是把每一类职责放回它该在的那一层。2. 分层 HTML 组件系统的四层骨架2.1 结构层先定骨架不关心长相和动作结构层回答的是“这个组件由哪些部分组成”。对一个卡片组件来说结构就是 header、body、footer 三块对一个弹窗组件来说结构就是遮罩、容器、标题栏、内容区、操作区。结构层是组件最稳定的部分它决定了组件的语义和文档粒度。在 HTML 里结构层通常体现为一段模板片段。你可以用原生 HTML 片段、模板字符串、组件框架的 TSX 或 JSX也可以用 Web Components 的template标签。关键是结构层里不应该出现具体文字内容、不应该写入具体样式、不应该绑定业务交互逻辑。一个常见误区是为了省事把样式的 class 和结构写在一起比如classcard card--red card--large这会让结构层和展示层混在一起。分层之后结构层负责写清楚节点层次和角色命名比如card__header、card__body展示层再通过 class 或属性来应用视觉规则。下面是一个卡片组件结构层的示例!-- 结构层card.html 模板片段 -- article classcard>/* card.css —— 展示层示例 */ .card { --card-border-color: #e0e0e0; --card-radius: 8px; border: 1px solid var(--card-border-color); border-radius: var(--card-radius); padding: 16px; } .card__header { font-size: 1.25rem; margin-bottom: 8px; } .card__body { color: var(--card-body-color, #444); }使用变量的好处是展示层不需要感知业务场景它只提供默认值和主题入口。之后即使要支持暗色模式也可以在更上层的样式表里覆盖这批变量组件本身的 CSS 不需要改动。2.3 行为层交互逻辑要能“脱离页面”被测试行为层负责组件的交互和动态表现。比如点击按钮展开内容、关闭弹窗、下拉刷新、拖拽排序。行为层要和结构层有一个确定的连接方式通常是通过选择器、>// card.js —— 行为层示例 document.addEventListener(click, (event) { const toggle event.target.closest([data-card-actiontoggle]); if (!toggle) return; const card toggle.closest([data-componentcard]); if (!card) return; const isExpanded card.classList.toggle(card--expanded); toggle.textContent isExpanded ? 收起 : 展开; });这里使用事件委托好处是无论卡片是静态渲染还是动态插入行为层都能处理。这也是分层系统里行为层和结构层解耦的一个典型写法行为层只认节点属性不认具体的组件实例引用。2.4 内容层把变化最快的东西从代码里拿出去内容层是四层里最容易理解、也最容易做过头的一层。它指的是组件内部具体展示的数据、文案、图片、链接等内容。在真实项目里内容变化频率往往远高于结构和样式。分层组件系统希望做到的是改内容时不需要动结构、样式和行为。最常见的机制就是插槽、内容投影或组件子节点。以卡片组件为例使用者在页面上可以直接这样写!-- 页面使用卡片组件内容层由使用方决定 -- article classcard>// 行为层弹窗关闭时派发自定义事件 closeButton.addEventListener(click, () { dialog.close(); dialog.dispatchEvent(new CustomEvent(dialog-closed, { detail: { reason: button }, bubbles: true })); });使用自定义事件的好处是外层可以用事件解耦组件内部不需要感知上一层的存在。这跟分层系统的思想是一致的每一层只暴露标准接口具体实现可以由各层自由替换。3.3 常见的错误示范层之间互相“偷看”有些项目名义上做了分层实际却出现很多越层访问。比如 CSS 层通过 JS 注入样式JS 层去读取某个元素的颜色值再决定下一步逻辑或者结构层内部内联了一段样式和一个事件监听。这些做法在分层系统里属于“层间偷看”。短期能改得快长期会让层与层之间形成隐性依赖。我建议在代码评审时专门检查三个点HTML 里有没有写style属性有的话展示层没有完全立起来。JS 里有没有直接操作 style、classList 以外的样式逻辑有的话行为层在偷偷依赖展示层。CSS 选择器里有没有依赖 JS 生成的特定文本内容有的话展示层在依赖内容层。这三条检查规则虽然简单但真的能挡住很多后期维护的大麻烦。4. 什么时候该分层、什么时候不该分层4.1 不是所有 HTML 页面都需要分层如果只是写一个静态介绍页、一次性的活动页或者一个不超过 100 行的纯展示组件硬套分层会让代码变得抽象和啰嗦。分层是一种架构成本它应该用在会持续演进、会被多次复用、有多种展示形态的组件上。我在实际项目里的判断标准是三个问题这个组件会不会在三个以上地方被复用它是否会因为不同场景而出现样式、内容或行为上的差异它的改动频率是否高于它所在页面如果三个问题有两个“是”就值得做分层如果只有一个“是”可以做简化分层比如只把展示层单独出来如果三个都“否”直接写成普通 HTML 就好。4.2 过度分层的五个信号分层也不是越细越好。做过头时系统会显得非常“正式”但其实每一步都在增加无效工作。我总结了五个过度分层的信号信号一一个不到 50 行的组件被拆成了 4 个文件和 3 层目录。信号二内容层只放了一个字符串却已经走完整套插槽机制。信号三行为层和展示层之间为了“解耦”额外加了一个中间层。信号四写一个简单改动需要同时修改六个文件。信号五新人第一次看代码时找不到内容在哪里被渲染。出现这些信号时应该先把层合并回去直到改动一个局部需求时只需改一个文件。分层系统的收益是降低复杂系统的维护成本不是为了证明架构能力。4.3 渐进式分层先跑通、再拆分、最后固化我个人最推荐的方式不是一开始就设计一个完美的分层架构而是分三步走。第一步先用单体 HTML 把功能跑通。页面或组件的交互、内容、展示全部先完成目的是确认需求本身没有问题。第二步识别变化与不变。打开这个页面问自己未来半年里哪部分最可能被改是样式、内容还是交互这部分的变化频率决定了它应该独立成层。第三步再把稳定的结构、变化的样式、交互行为、易变内容分别拆出来最后用一套约定目录、命名、属性规范固化下来。注意渐进式分层的核心不是“以后可能会需要”而是“现在已经确定会变”。没有真实变化驱动时拆层大概率只会增加维护负担。渐进式分层的好处在于你是基于真实需求做拆分而不是凭经验预判。很多架构过度设计来自“我以后可能会需要”这个幻觉而渐进式分层把这个问题压到了最低。5. 落地一套分层 HTML 组件系统的通用方案5.1 最小目录与命名约定如果项目是纯原生 HTML/CSS/JS我一般建议这样一个目录结构components/ card/ card.css card.js card.html dialog/ dialog.css dialog.js dialog.html pages/ home.html detail.html styles/ tokens.css base.csscomponents/里每个组件一个目录结构、展示、行为三个文件分开。styles/tokens.css放全局的设计变量包括颜色、间距、字体、圆角等。pages/里放业务页面页面通过加载组件的 CSS 和 JS 来组合组件。命名上我习惯用>