跳到正文

我所理解的前端框架最佳实践(3):正确拆分组件

我所理解的前端框架最佳实践

  1. 用表格组件减少通用渲染和交互的维护成本
  2. 利用派生值减少维护成本和心智负担
  3. 正确拆分组件(当前)
  4. 抽取业务逻辑后,谁持有状态和副作用
  5. 按入口和依赖组织大型模块
  6. 用 kebab-case 格式统一文件名
  7. 合理使用全局状态

拆组件时,我会先想下次改交互要去哪里。局部行为能在负责它的组件里改完,影响多个区域的决定能在共同的父层找到,日后调整就知道从哪里入手。

组件持有能一起变化的一组界面行为

属于同一次交互、修改时也经常一起变的模板、样式和行为,可以放在同一个组件里。焦点、位置测量和定时器等细节由实现交互的一方管理,它也负责在卸载时释放相应资源。

由共同的父层协调跨区域操作

多个区域都能发起同一个业务动作,或者一次操作需要同时改变几个区域时,把决定放在这些区域共同的父层。子组件只提供表达意图所需的数据,父层负责校验和决定更新顺序。Vue 可以用 props 和 emit,React 可以 把状态提到父组件并通过 props 传回调。

没有独立界面的生命周期放进 composable 或 Hook

一段逻辑有自己的启动、更新和清理过程,又没有独立的界面时,可以抽到 composable 或 Hook。视图负责呈现结果,原来持有状态的那一层仍负责更新它。单纯把输入转换成输出的规则可以提成普通函数。订阅逻辑和数据状态的分工见《抽取业务逻辑后,谁持有状态和副作用》。

使用自有 composable 的组件负责接线和调度

读工作台组件时,应该能先看到目录菜单怎样打开对比、工具栏怎样选择基线、阅读区怎样导出。显示状态、模板 ref 和短事件转发可以就在组件里。获取 Git 基线的流程有自己的互斥状态、仓库归属检查和失败收尾,适合提取到负责文档操作的 composable。组件把它返回的动作接到对应事件即可。一个小组件只有切换开关和通知父层两步时,可以在同一个文件里读完。

Vue 的 <script setup> 已经在调用自有 composable,又有一个顶层异步函数同时包含等待、异常处理和分支或收尾时,共享预设里的 @sheng/vue-prefer-extract-setup-workflow 会提示复核。先确认哪个模块应该持有这段流程的状态,再决定把它放进已有 composable,还是提取新的 composable。工作台的命令分派虽然是同步的,也可以按动作归属做同样的判断。

工作台入口只装配模块

工作台的 App.vue 可以再进一步。脚本先声明启动用的 props,然后按顺序建立仓库会话、阅读标签、文档操作和快捷键。读到 useReadingViews() 时,直接从它的返回值取 current 和 history 就能接下去。让入口反复调用 readingViews.field('snapshot') 会让同一个活动标签字段在多个地方各建一份响应式绑定。

目录树只从阅读标签接收当前文档和保存状态,文档操作则另取历史和切换标签的动作。入口逐项传递,读者顺着调用就能看到每个模块实际用到什么。相关的入参写法见《会演进的函数用对象参数》。

阅读区的导出逻辑也是这样接的。入口用 toRefs(props) 取出文档快照和渲染选项,只把导出需要的字段列在 useReadingExport({ content, dark, onFailure, renderMath, renderMermaid, snapshot }) 里。要改一个 prop 时,从调用处就能看出它会影响哪个模块。模块返回具名动作,组件就地解构并接到模板上。

短函数也可以回到它操作的地方。聚焦阅读区只需一行,持有阅读区实例的 useReadingDeck 可以直接提供 focusReading。工作区切换收到保存阅读状态的动作,先保存并等位置写回,再切换仓库和恢复目录。模板收到仓库工具更新书签的事件时,把它转交给 updateWorkspaceBookmarks,偏好如何合并在仓库会话里就能找到。

@sheng/vue-require-composable-only-setup 根据真实私有 composable 调用识别这种结构。它允许 Vue 编译宏、composable 调用、返回值解构和模板事件转发,包括显式接收多个参数后直接转发。参数里的嵌套调用和模板事件里的状态赋值仍会被检出。没有调用私有 composable 的小组件仍可以在自己的脚本里管理交互状态。

选定组件作为装配入口后,可以同时在入口和私有 composable 上开启 @sheng/project-prefer-named-hook-bindings 的 explicitContracts 与 composeInComponent。前者检查对象简写、就地解构和整份 props 转交,后者检查自有 composable 是否在实现里继续调用同类模块。组件按依赖顺序直接调用它们,参数里的每一项都能从入口追到来源。

在入口用同一层级的部件组织模板

脚本的调用和模板里的组件标签都可以按同一个尺度来读。我希望从入口一眼看出工作台有哪些区域,它们接收什么、发出什么事件。模板里的业务区域可以用私有组件并列组织,入口保留整体布局和接线。只要打开某个业务子组件,就能看到这个区域独有的操作、状态和样式。再往下一层,按钮、选择器和对话框提供通用的展示、焦点与键盘行为。

先确定子组件完成这件事需要知道什么,再设计 props。独立的信息可以分别声明,天然一起使用的数据可以组成一个字段明确的对象。把文档快照、界面设置和所有操作都塞进一个 context,调用处虽然只写一个 prop,子组件能访问的信息却更多了,查看影响范围时还得去找它实际读了哪些字段。

子组件已经收到所有输入时,只供它自己使用的标题、样式和控件模式可以就地计算。如果子组件只负责显示一句提示,传这句提示就够了。如果计算结果还要供侧栏、工具栏或快捷键使用,就由共同父层的 composable 计算,再把各区域需要的结果传下去。

阅读区的文档检查和 PDF 页面设置是同一层的功能入口。PDF 对话框自己维护纸张、页边距、预览和表单校验,提交时把通过校验的参数交给阅读区。阅读区仍然负责取得当前正文、等待图表并确认等待期间没有换稿。读入口时,两处都可以从对应的子组件标签找到,再按一层层的接口往里看。

如果一次同时改模板和状态归属,焦点、滚动和键盘交互出了问题,很难判断是哪一层引起的。可以先把源码对话框、正文、选区操作和批注卡片各自的模板放进私有组件,把现有状态和动作逐项接过去。等这些区域都能沿各自的入口检查,再根据谁读写状态、谁管理生命周期决定逻辑迁到哪一层。

在 Vue 项目里,@sheng/vue-prefer-private-child-components 默认进入共享预设。它确认模板实际使用了从同级 components/ 导入的私有组件,再标出同一模板里含事件、双向绑定或 HTML 注入的内联子树。对于有替代分支的 v-if 链,它也会标出仍然内联 dl、表格、列表或 v-for 的完整展示分支。标题、加载提示、简单空状态和组件插槽可以保留。把提示当作评审入口,沿状态读写和动作调用检查这块界面该怎样划分。

仓库工具中的关联文章和文章属性是两个这样的分支。关联文章有引用分组和定位入口,文章属性只有路径、公开地址和属性列表。可以分别用 RelatedArticles 和 ArticleProperties 承载;即使属性面板没有点击事件,它仍然有自己的展示结构。两者共享的查询、索引刷新和迟到响应校验继续由父层的结果模块维护。分组和专属样式则跟随各自的展示组件。

在新增分支时确定边界

新加一种模式时,我会先看同层区域是否已经交给私有组件。已经采用这种组织方式的入口,先列出新区域需要的最小输入、上报的意图和独有派生,再实现内部界面。需要跨区域协调的状态仍由共同父层持有。这样读入口时,各个区域的封装程度能够并列。

随后核对检查工具是否真的覆盖了这个入口。@sheng/vue-require-composable-only-setup 默认检查实际调用本目录 ./composables 的 SFC,不要求文件标记,也不需要逐个入口启用。只有导入却没有调用、类型导入或同名局部变量不构成这个前提。用无标记的真实私有调用,再加一段本地状态或计算,确认规则能拦住混写。项目预设与独立 createVueConfig() 都默认包含这组检查;消费者仍需核对忽略范围、parser 和诊断级别。

交付前再沿本次修改回看脚本和模板:脚本是否仍然直接装配各个 composable,模板是否新增了内联的完整区域,专属派生和样式是否跟随自己的区域。然后选择会受影响的定位、切换、空状态、迟到响应、键盘和焦点路径验证。工具指出结构,开发者继续核对职责与生命周期,两个步骤都放进日常开发流程。

图标分支按整张图选择

如果一个状态决定的是整张图标,可以把每个静态轮廓作为独立的 SVG 资源。Marker 的工作区树就有三个这样的状态。文件、展开目录和折叠目录原来各由一个带条件的 <path> 绘制,每一条路径都能独立表达自己的形状。把它们放入三个 .svg 文件后,树只需要根据条目类型和展开状态选择资源。

树里当前文档和目录使用强调色,其他文档使用弱化色。用 CSS mask 读取 SVG 的透明度,再用 background-color: currentColor 上色,同一份形状就能跟随树行配色。强制颜色模式下,遮罩元素单独用 forced-color-adjust: none 保住着色,并用 CanvasText 取得与背景搭配的系统文字色。相关行为见 CSS Color Adjustment 规范。

CSS 里的资源地址还要在生产构建里核对。Marker 用 UnoCSS @apply 的任意值写 url(...) 时,开发环境能显示图标,生产 CSS 仍指向未输出的相对路径。把 URL 写到普通的 CSS 自定义属性声明,让 @apply 通过 var(...) 读取,Vite 生成的 CSS 就能内联这四张 SVG。

箭头属于另一种变化。同一个形状始终在原位置,展开时转到 90 度。树把旋转角度写在展开样式里,只在 prefers-reduced-motion: no-preference 时加 120ms 的 transform 过渡。于是同一行从折叠切到展开时有动画,虚拟滚动重新挂载已展开的行时则直接画在 90 度。SVG 文件可以自行播放声明式动画。由应用状态控制的轮廓形变可以交给 MorphIcon 这样的组件,让它接收完整的图标定义并在内部控制路径。SVG 图像处理模式描述了资源图像可运行的动画和交互边界。

@sheng/vue-prefer-svg-assets-for-conditional-graphics 检查 <svg> 的直接子节点。如果它们恰好构成一条完整的 v-if 到 v-else 链,并且每个分支都是一个静态图形元素,规则会提示检查能否提取整图资源。整个 SVG 的显隐、两种状态共享的轮廓和由应用数据更新的路径,仍可以留在模板中。规则只给诊断,资源放在哪里,以及怎样保留配色和动效,由组件的实际需求决定。

沿返回值找实际消费方

父组件调用 composable 后,先看整次调用服务哪些区域,再看每个返回值去哪里。同一个子组件从一个对象读取宽度和高度,仍然是一处消费。父层用返回值决定子组件何时挂载、把它交给另一个 composable,或者通过 defineExpose() 提供给上层时,这些用法也要计入。

单个字段只有一个消费者,不足以决定逻辑应当下移。例如父层统一转换两种价格,再分别交给对应的展示组件:

<script setup lang="ts">
import { FoodPrice, OtherPrice } from './components';
import { usePriceFormat } from './composables';

const { formattedFoodPrice, formattedPencilPrice } = usePriceFormat({ foodPrice, pencilPrice });
</script>

<template>
  <food-price :formatted-price="formattedFoodPrice" />
  <other-price :formatted-price="formattedPencilPrice" />
</template>

两个字段各自只出现一次,整次调用却服务两个子组件。父层组织共同的转换步骤,这样处理可以保留。子组件如果需要不同的格式化策略、独立状态或生命周期,也可以分别调用同一个通用函数。选择依据是转换和状态由谁负责,调用次数只是迁移后需要核对的结果。

以 Markdown 阅读区的选区补色为例。以前父层算出 selectionGaps,再原样传给 ReadingArticle。正文 DOM 和补色用的 SVG 都在 ReadingArticle,所以可以在那里调用 useInlineSelectionGaps(),用同一组节点测量和绘制。父层提供当前批注范围、正文和可见性,滚动与导航继续使用子组件登记的正文节点。

批注草稿只需接收已有的 draft,就可以根据 draft.action 得出「新批注」「编辑批注」或「替换建议」,也可以决定是否使用单行输入。父层仍用草稿状态协调发布、导出和其他浮层。把草稿独用的计算放到编辑器里,改编辑器的文案或输入模式时,父层的接线就无需跟着改。

源码对话框提供了另一个边界。选中的源码和复制提示只显示在对话框里,捕获选区、复制同一版本的内容还供正文右键菜单使用。先沿这些读写路径拆分职责,再判断哪些状态可以由对话框持有。

@sheng/vue-prefer-composable-in-child 的日常模式是 mode: 'whole',默认进入 Vue 共享预设。它从 <script setup> 直接解构的私有 composable 返回值出发,确认全部解构绑定都通过具名 prop 汇入同一个静态私有子组件实例。整次调用服务多个子组件时不提示归属调整。读到诊断后,仍需结合输入、DOM 所有权、统一转换和副作用的清理时机审阅。

需要盘点局部接口时,可以手动运行 mode: 'fields',生成逐字段消费清单。它会列出来源字段、目标子组件和实际 prop 表达式。这些记录只说明当前 SFC 中的读取关系,不作为必须下移的问题,也不按记录数量阻断 CI。

正文查找能说明这个边界。useReadingSearch 内部保存匹配文字的 Range[],重建全部命中的高亮,选择当前命中,再展开所在章节并滚动正文。工具栏只需显示数量,所以父层传 :search-match-count="searchMatches.length"。字段清单仍可追到 searchMatches 这个来源,实际交给子组件的是一个数字。确认实现内的用途后,可以保留父层的搜索流程;如果调用方都只需要数量,还可以让 composable 只返回 searchMatchCount,把具体范围留在实现内部。

还有一种情况只涉及单个返回值。@sheng/vue-prefer-child-local-derived-props 追踪只读 computed() 的 Ref 输入和结果,在同一个私有子组件已通过 prop 或无修饰符的 model 收到全部输入,且结果只通过具名 prop 交给它时给出提示。计算可以在父组件内声明,也可以来自同目录的私有 composable。具名计算支持无参 .trim(),其它函数调用、动态传参和条件挂载仍留给评审。

内联表达式也可以按同一条消费关系检查。例如父层已经用 v-model="replacement" 连接替换草稿,又传入 :disabled="busy || !replacement.trim()",规则会标出 !replacement.trim()。子组件已有输入,可以在自己的按钮上组合外部不可用状态与本地空白校验,父层继续处理查询和加载。无参 .trim() 只是语法线索,移动前还要确认字符串类型、短路保护和求值时机;只为判断空白而裁剪时,提交仍保留原始文字。

父层也可以保留直接的参数适配。例如工作台用 activeTool: string | null 同时表示工具是否打开、打开哪个模式,再给子组件传 initialMode 和由 activeTool !== null 得出的 visible。这个判断放进子组件虽然算得出相同结果,却会把父层的「空值表示关闭」带入组件契约。规则因此放过完整源值的空值判断、取反和双重取反等直接适配,不按 prop 名称加白名单。内联与 computed 使用同一边界:activeTool !== null 提成 computed 后仍放过,!replacement.trim() 提成 computed 后仍作为内容校验提示。

独占草稿还要看它活多久

替换文字只供替换区域使用,但搜索结果变空或切走模式时,输入区域可能已经卸载。如果原来切回来还能继续编辑,把草稿直接搬进子组件就会丢失这个行为。文档书签的标题和章节也有类似问题:它们可能在工具创建、文档路径变化时取样,而不是第一次打开书签表单时才初始化。同一路径内继续滚动,不应覆盖用户选好的章节。

所以还要把消费范围与存活范围分开。多个区域共用的状态放在共同父层;独占但需要跨卸载保留的草稿,可以继续由父层保存,子组件通过 model 编辑。确实需要完整封闭时,再让业务组件的挂载周期覆盖草稿的存活周期,把初始化、重置和动作一起迁移。

Lint 能列出源值、派生表达式和组件挂载条件,却不能仅凭这些结构推断「用户希望何时丢弃草稿」。这部分适合交给开发者或 LLM 沿源码复核:读取真实调用点和 key,记录模式切换、隐藏重开、空结果、文档变化及保存完成时的行为,再给出每项状态的读写者、初始化与重置、建议位置和验证路径。候选可以保留父层,也可以只移动派生。静态提示与语义审阅共同参与开发流程,不把扫描条数当成必须迁移的数量。

把派生和动作放在一起看

单独看返回字段还会漏掉一类关系:一个 computed 构造目标,一个返回动作读取它,再由父模板绑定到同一个子组件的事件。派生虽然没有直接成为 prop,却仍可能属于那个区域。项目扫描脚本会按真实作用域绑定记录这组依赖,把 prop、事件、model、脚本和 CSS 的消费分开,再列出组外输入、共享状态、重置 watcher 和无法证明的调用语义。它只生成审阅清单,不作为日常 lint 错误,也不自动迁移。

仓库替换入口就是一个例子。父层保留结果列表和选中下标,只向替换区域交付当前正文命中的目标、结束位置和索引版本。子组件结合受控草稿构造最终导航目标,点击时把它上报。替换文字继续由父层保存,共享的准备状态仍决定列表确认时是否立即导航。这样下移的是目标构造和局部动作,空结果、切换模式或关闭重开时的草稿规则可以保持原样。

复核时用改前代码确认清单能连起「目标派生 → 返回动作 → 子组件事件」,改后再确认这组父层依赖已经消失。动态索引、对象展开和外部调用保留源码供检查,不把它们当成可以安全移动的证明。

用常改的交互验证拆分是否成立

拆分前选几条容易出错的操作,拆完后沿原路径走一遍,检查布局、键盘焦点和 ARIA 关系。也看一眼父组件给子组件传了什么。如果一次局部交互仍需要父层维护一串细节,或者子组件要接收一份可以随意修改的整页状态,当前的拆分就还需要调整。

vue/max-lines-per-block 和 vue/max-template-depth 可以定位过长的区块和嵌套过深的结构,也可以按文件行数定位过长的 JSX 文件。具体从哪里拆,再看哪些状态和行为需要一起变化。

Markdown 工作台的工具栏、侧栏和文档切换

工具栏和目录树都能打开文档,切换之前要检查当前批注是否已保存。把这条规则放在工作台,两个区域只需发出打开请求。工具栏的「复制为」子菜单自己测量位置,按右方向键时把焦点放到第一项,按 Esc 时归还焦点,卸载时清理延迟关闭的定时器。

工具栏和侧栏分别发出打开文档的请求,由工作台检查当前批注是否已保存并决定是否切换。

工作台提供最近打开列表,并执行应用菜单发出的打开仓库、设置和帮助等动作。菜单组件处理置顶排序、浮层开关与焦点,工具栏用一个具名插槽提供摆放位置。工作台可以直接把数据和动作接到菜单,省去工具栏的转发。点「帮助」时,菜单会在命令执行前先让焦点回到触发按钮,帮助页才能记住返回阅读时该把焦点还给谁。

目录、窗口边缘入口、分隔条和右键菜单一起组成侧栏。把鼠标移出目录时,菜单仍打开就要继续显示侧栏。菜单关闭后,如果虚拟滚动已经卸载原来的树行,侧栏可以重新定位它再归还焦点。这些控件用同一份展开和浮出状态,放在同一业务组件里。分隔条在拖动期间更新预览宽度,外层布局读取这个宽度来调整正文列,松开时再调用统一的外观保存入口。暂时隐藏侧栏时,已经展开的目录仍可在回来后继续浏览。

预览弹窗读取正文和目录摘要。关闭弹窗、改看另一篇或者切换工作区之后,旧请求的响应已经不能更新当前预览。弹窗管理请求的失效条件。目录预览得到的文档顺序还有一个关闭之后的消费者。正文末尾的「下一篇」用它决定去哪里,所以弹窗在读到目录后把文档列表交给工作台,工作台持有顺读清单,并在切换工作区时重置。

正文链接也可以在鼠标旁浮出预览。两种预览都要渲染 Markdown、解析相对资源和给代码复制提供反馈,这些行为可以放进同一个文档内容组件。正文浮层根据链接的位置测量和摆放,并负责鼠标移入移出的时序。工作台弹窗负责模态开关和关闭后的焦点。这样两个入口都只传正文及其渲染所需的输入,各自安排内容出现在哪里、何时消失。

用拆分前的代码运行逐字段检查,能看到正文、目录摘要只传给预览弹窗,也能看到导出进度只有这一个展示位置。检查导出动作会发现它还向阅读区请求排版并生成合并 PDF。成组扫描可以把「下一篇」的派生值与点击动作连起来,再由开发者检查它们用的顺读清单能存活多久。类似地,侧栏展开状态和宽度上限各有一个显示位置,哪些控件应该一起放进侧栏,还得看拖拽、定位和菜单之间的依赖。

用键盘打开复制子菜单再按 Esc,可以确认焦点回到菜单按钮。定位到刚展开的树行后,再检查该行是否滚入可见区域。

在模板声明无条件的事件取消

ShTree 把可取消的 CustomEvent 放在 select 和 toggle 的参数首位。Vue 的修饰符实现会在调用处理函数前对首参执行 preventDefault(),因此 @select.prevent="select" 和 @toggle.prevent="toggle" 可以取消树组件的默认动作,让处理函数直接打开文章或等待目录读取。ShTree 通过同步检查该事件的 defaultPrevented 决定是否执行默认动作。

contextmenu 和 auxclick 则先传节点,再传原生事件。用 .prevent 会让 Vue 试图取消第一个参数,也就是业务节点。中键处理还有一层限制,只有点中文档时才取消默认动作并打开新标签。这两处应在回调里保留对实际事件的处理。

@sheng/vue-prefer-prevent-modifier 检查模板直接绑定的 <script setup> 顶层处理函数。它要求函数只用于这一处,且第一条语句是对事件首参无条件调用 preventDefault()。编辑器建议会给监听器补上 .prevent,同时移除函数中的取消调用。批量 --fix 不会执行这项迁移。

把标签栏和阅读区放在一起

标签栏切换活动文章,阅读区根据同一组标签决定显示哪一栏、是否进入对读。把它们放在一起后,阅读区可以测量自己的宽度来布置左右栏,在关闭标签前确认草稿,并按标签找到仍挂载的实例。换工作区前要请阅读区保存两栏位置,再加载目录和恢复文档。这条调用顺序由根组件维护。

阅读区转发正文的 navigate 事件时,需要保留目标和可选的 newTab 标志。@navigate="emit('navigate', $event)" 只取第一个参数。上层只收到目标时会按默认方式在当前标签打开,组合键点击也就失去了新建标签的效果。

阅读区可以用 navigate: [target: ReadingTarget, newTab?: boolean] 声明事件,再用 @navigate="(target, newTab) => emit('navigate', target, newTab)" 转发。Vue 按发出时的顺序把值传给监听函数,详见组件事件参数。

验证时对同一个链接分别执行普通点击和组合键点击,检查普通点击仍在当前标签打开、组合键点击在新标签打开且原标签仍在。

设置页和阅读区由根组件直接组合。进入设置时,顶部工具栏仍提供「返回阅读」,阅读区暂时隐藏,两个文档实例继续挂载。返回后沿用各自的对照和滚动状态。验证时可以先展开目录,再打开两篇文章对读。进入设置后检查两个阅读区的节点都还在,返回时检查同一对节点重新可见,目录也保持展开。只检查标题会漏掉阅读实例按同一文档重新挂载的情况。

侧栏读取的目录缓存和书签已经属于工作区 Store,可以让侧栏直接消费,再把明确的字段传给内部的树组件。阅读区也直接从同一个 Store 取得书签和批注状态。两栏各自的文档快照、基线和工具栏挂载节点仍由组件明确绑定。设置页和侧栏都能修改工作区偏好,它们共用根组件的保存入口,改用按修改时间排序时从这里刷新目录。