原生TypeScript待办清单：纯前端架构、观察者模式与拖拽排序实践

1. 项目概述一个由AI辅助构思的现代化待办清单最近在整理个人项目时我重新审视了一个之前用TypeScript写的待办清单应用。这个项目的初衷很简单我需要一个极简、快速、完全由我掌控的待办工具它不需要登录数据就存在本地打开浏览器就能用。市面上虽然有很多优秀的Todo应用但要么功能过于臃肿要么就是数据同步需要依赖第三方服务总感觉差了点什么。于是我决定自己动手用最纯粹的前端技术栈打造一个“刚刚好”的工具。这个项目被命名为“todo-cursor”一方面是因为它确实是在Cursor这个智能编辑器里借助AI辅助快速完成了原型构建和代码补全另一方面“cursor”也寓意着聚焦和指引希望这个工具能像光标一样清晰地指示你下一步该做什么。整个应用没有使用任何重型框架而是基于原生TypeScript、CSS变量和HTML5 API构建核心代码量控制在了千行以内但实现了从基础增删改查到键盘快捷键、拖拽排序、暗色模式适配等完整功能。它运行起来就像一个本地应用响应迅速界面干净完全满足了我对个人效率工具的所有想象。接下来我会带你深入这个项目的每一个细节从设计思路、技术选型到具体的实现难点和避坑经验。无论你是前端新手想学习如何组织一个结构清晰的纯前端项目还是有一定经验的开发者想了解如何优雅地实现拖拽、状态管理等交互相信都能从中获得启发。我们不止是看代码更重要的是理解每个决策背后的“为什么”。2. 核心设计思路与技术选型解析当我开始构思这个待办清单时我首先问了自己几个问题它的核心价值是什么它需要在哪些设备上运行数据如何持久化交互体验的底线和上限分别在哪里对这些问题的回答直接决定了整个项目的技术走向。2.1 为什么选择“纯前端本地存储”架构这是最根本的决策。我的核心需求是“零延迟启动”和“绝对的数据隐私”。我不希望每次打开应用都要等待网络请求更不希望我的待办事项哪怕只是购物清单被上传到某个我不知道的服务器。因此后端服务被首先排除。现代浏览器的LocalStorage API已经足够可靠能够持久化存储几MB的文本数据对于一个待办应用来说绰绰有余。它的读写是同步的这意味着状态变更可以立刻保存没有异步回调的复杂度代码逻辑会非常直观。当然LocalStorage有它的局限比如存储空间有限通常5MB、只能存字符串、以及标签页间数据同步需要监听storage事件。但对于一个待办清单这些都不是问题。一个待办项对象序列化成JSON字符串后很小即使有上千条也远达不到容量上限。我选择用JSON.stringify和JSON.parse来做序列化并在每次数据变更时自动保存这样就能获得类似数据库的持久化体验且完全离线。注意直接操作LocalStorage虽然方便但要小心性能陷阱。如果每次单个待办项的完成状态切换都触发一次全量保存在列表很长时可能会有卡顿。我的做法是引入一个简单的防抖机制将保存操作延迟100毫秒执行确保高频操作如快速勾选多个事项只触发最后一次保存这对用户体验的提升是显著的。2.2 技术栈的“克制”与“激进”在框架选择上我刻意保持了克制。没有用React、Vue或Svelte。原因有三点第一项目复杂度不高引入框架带来的 bundle 体积增加得不偿失第二我想更深入地实践原生DOM操作和TypeScript的类型系统第三这本身也是一个学习项目剥离框架的抽象层能更好地理解底层原理。但这不意味着技术栈是落后的。相反我在几个关键点上非常“激进”TypeScript全程覆盖从模型定义、工具函数到主应用逻辑全部使用TypeScript并配置了严格的tsconfig.json。这为项目提供了极佳的代码提示和重构能力尤其是在定义复杂的待办项状态类型时类型安全避免了无数潜在的错误。CSS Variables自定义属性驱动主题为了实现无缝的暗色/亮色模式切换我没有使用两套CSS文件而是完全依赖CSS变量。在:root中定义一套如--primary-color、--bg-color、--text-color的变量然后在media (prefers-color-scheme: dark)媒体查询中重新为这些变量赋一套暗色值。这样整个UI的颜色切换只需要修改CSS变量JavaScript几乎不参与性能好且易于维护。拥抱现代Web API项目大量使用了现代浏览器原生支持的能力HTML5 Drag Drop API实现列表项的拖拽排序。虽然这个API的声誉有点“臭”因为早期的实现确实反直觉但通过合理的封装和事件处理完全可以做出流畅的体验。KeyboardEvent和Focus Management实现全键盘操作的核心。这不仅对无障碍访问友好对追求效率的键盘党用户更是福音。Window.localStorage如前所述是数据层的基石。2.3 状态管理与设计模式的应用即使是一个小应用状态管理也不该是混乱的。我采用了经典的观察者模式Observer Pattern来解耦数据模型和UI视图。具体来说我设计了一个TodoList类单例模式确保全局只有一个列表实例它内部维护一个Todo对象的数组。这个TodoList类就是被观察者Subject。任何视图组件比如负责渲染列表的TodoListView类都可以注册为观察者Observer。当用户通过UI添加、删除或修改了一个待办项时TodoList实例的内部数据发生变化然后它会自动遍历所有注册的观察者调用它们的update方法并传递最新的数据。观察者收到通知后用自己的逻辑重新渲染对应的UI部分。这样做的好处非常明显数据流清晰数据修改只有一个入口TodoList的方法UI只是数据的映射。避免了视图直接操作DOM导致状态不一致的经典问题。可维护性强如果需要增加一个新的UI组件比如一个实时统计图表只需要让它实现观察者接口并注册到TodoList即可完全不用修改现有的数据逻辑。便于测试TodoList的逻辑可以单独进行单元测试因为它不依赖任何DOM环境。// 简化的观察者模式示例 interface Observer { update(data: Todo[]): void; } class TodoList { private todos: Todo[] []; private observers: Observer[] []; addObserver(observer: Observer) { this.observers.push(observer); } private notifyObservers() { this.observers.forEach(observer observer.update(this.todos)); this.saveToStorage(); // 通知后自动保存 } addTodo(todo: Todo) { this.todos.push(todo); this.notifyObservers(); // 数据变更通知所有UI更新 } // ... 其他方法 }3. 核心模块深度剖析与实现细节理解了整体架构我们深入到各个核心模块看看它们是如何被构建起来的其中有哪些值得细说的实现技巧和遇到的“坑”。3.1 数据模型Todo与TodoList这是应用的基石设计得好后面的一切都会顺理成章。Todo模型不仅仅是一个有id、title、completed字段的对象。我给它增加了更多元数据以支持丰富功能interface Todo { id: string; // 使用 crypto.randomUUID() 生成确保唯一性 title: string; completed: boolean; createdAt: number; // 时间戳用于按创建时间排序 orderIndex: number; // 手动拖拽排序后的顺序索引 }id使用crypto.randomUUID()生成这是一个现代浏览器支持的Web Crypto API比传统的Date.now()或自增ID更可靠、更唯一。createdAt存储时间戳这使得“按创建时间排序”功能非常容易实现。orderIndex是关键。当用户拖拽改变顺序后我们需要一种方式来持久化这个新顺序。简单的数组重排只在内存中有效刷新页面就没了。我的策略是在拖拽结束后遍历当前所有待办项为它们重新分配一个连续的orderIndex如0,1,2,...然后保存。之后加载时按orderIndex排序即可恢复用户自定义的顺序。TodoList类是这个模型的管理者。它的职责非常清晰增删改查CRUD提供addTodo,deleteTodo,toggleTodo,updateTodoTitle等方法。每个方法在修改内部数组后都会调用notifyObservers()。状态过滤与排序提供getFilteredTodos(filterType),getSortedTodos(sortType)等方法。这些方法是纯函数根据参数返回新的数组不修改原数据符合函数式编程的思想易于测试。与存储层对接包含loadFromStorage()和saveToStorage()方法。这里有一个细节保存时我不仅存了待办项数组还存了当前的过滤和排序状态这样用户刷新页面后看到的仍然是之前设定的视图。3.2 视图渲染高效与可访问性兼顾渲染层的工作是将Todo[]数组转化为用户看到的DOM列表。最朴素的做法是每次更新都清空列表容器然后循环todos重新创建所有li元素。这在列表项不多时没问题但不够优雅且会破坏元素的焦点focus状态对键盘操作不友好。我采用了“差异化更新”策略。当收到新的todos数据时渲染器会将当前的DOM节点列表与新的todos数组进行比对。识别出哪些是新增的项创建并插入DOM、哪些是删除的项移除DOM、哪些是更新的项例如完成状态改变只更新对应节点的类和样式而不是重建。对于顺序改变如果只是orderIndex变化而元素本身存在则使用Node.insertBefore()进行DOM节点的移动这比先删除再插入性能要好。键盘导航与无障碍是这部分的重头戏。为了让应用能被屏幕阅读器正确识别且支持键盘操作我做了以下工作正确的ARIA属性每个待办项容器li都设置了rolelistitem复选框使用真正的input typecheckbox而非用div模拟并关联了label。列表容器ul设置rolelist。这些属性帮助辅助技术理解页面结构。管理焦点当删除一个待办项时焦点不能凭空消失否则键盘用户会迷失。我的逻辑是将焦点移动到被删除项的前一项如果存在否则移动到后一项如果都没有则移动到输入框。这需要仔细处理tabindex和element.focus()。完整的键盘快捷键如前所述我为常用操作绑定了快捷键。实现时需要注意event.preventDefault()来阻止浏览器默认行为如按空格滚动页面并处理好event.key和event.code的兼容性。同时在界面上提供一个隐藏的、可通过键盘调出的帮助面板列出所有快捷键这对新用户很友好。3.3 拖拽排序的实现与优化HTML5 Drag Drop API的体验口碑不佳主要是因为它的默认行为比如拖拽图片或链接和事件流的复杂性。但要实现一个列表内部排序它仍然是原生支持最好的选择。我的实现步骤和关键点如下为可拖拽项设置属性在每个待办项的DOM元素上设置draggabletrue。处理dragstart事件当用户开始拖拽时在这个事件处理函数中使用event.dataTransfer.setData(text/plain, todo.id)将当前项的id存入数据传递对象。同时可以设置event.dataTransfer.effectAllowed move来指定操作类型。处理dragover事件这是最关键的一步。当拖拽的元素经过另一个列表项上方时会触发该列表项的dragover事件。必须在这个事件中调用event.preventDefault()才能表明“此区域允许放置”光标会变成允许移动的样式。我在这里还加入了视觉反馈比如给当前“经过”的项添加一个高亮边框或背景色提示用户松手后的放置位置。处理drop事件当用户松开鼠标时在目标列表项上触发。首先还是要event.preventDefault()来阻止浏览器可能的默认打开链接等行为。然后从event.dataTransfer.getData(text/plain)中取出被拖拽项的id。最后执行核心逻辑在数据层TodoList中找到被拖拽项和目标项计算新的顺序更新所有相关项的orderIndex并通知观察者更新UI。处理dragend事件无论拖拽是否成功完成比如用户在外面松手了都会触发。这里适合做一些清理工作比如移除所有在dragover时添加的临时视觉样式。实操心得拖拽体验的流畅度很大程度上取决于视觉反馈是否及时和准确。我最初只在drop时才更新UI感觉非常迟钝。后来改为在dragover时就实时更新一个“预览位置”例如在列表中插入一个占位符虚线框体验立刻提升了一个档次。此外一定要记得在dragover和drop中阻止默认事件这是很多拖拽失效问题的根源。3.4 样式系统CSS变量与响应式布局样式方面我追求的是“代码精简”和“主题灵活”。所有颜色、间距、字体大小都定义在:root的CSS变量中。:root { --color-bg: #ffffff; --color-text: #333333; --color-primary: #646cff; --spacing-unit: 8px; --border-radius: 8px; } media (prefers-color-scheme: dark) { :root { --color-bg: #1a1a1a; --color-text: #f0f0f0; --color-primary: #535bf2; } }然后在任何需要颜色的地方都使用var(--color-bg)这样的变量。切换暗色模式时浏览器会自动应用媒体查询中的新变量值整个界面的颜色瞬间切换无需任何JavaScript参与。响应式设计采用了移动优先的策略。基础样式针对小屏幕编写然后通过media (min-width: 768px)来增加大屏幕下的特定样式。例如在手机上操作按钮删除、编辑可能以图标形式出现在待办项右侧在平板上这些按钮可以显示为文字标签并增加一些内边距以便于触摸。CSS架构上我采用了类似BEM的扁平化命名思想但更简化。类名直接描述组件的功能如.todo-item,.todo-checkbox,.todo-actions。避免过深的嵌套选择器以提高CSS渲染性能也使得样式更容易被覆盖和修改。4. 开发、构建与工程化实践即使是一个小项目良好的工程化习惯也能让开发过程事半功倍并且为未来的维护和扩展打下基础。4.1 开发环境搭建与脚本配置项目使用pnpm作为包管理器因为它速度快、磁盘空间利用效率高。package.json中的脚本配置得非常清晰{ scripts: { dev: vite, build: tsc vite build, preview: vite preview, lint: eslint src --ext .ts, format: prettier --write src/ } }pnpm dev启动Vite开发服务器支持热模块替换HMR修改代码后浏览器几乎即时更新。pnpm build先运行TypeScript编译器(tsc)进行类型检查确保没有类型错误然后再用Vite进行打包构建。这个顺序很重要能避免将类型错误代码打包进去。pnpm lint和pnpm format分别用ESLint和Prettier来保证代码质量和风格统一。我在团队项目中会配置Git提交钩子husky lint-staged在提交前自动执行这些检查。Vite的配置vite.config.ts非常简洁主要指定了根目录、构建选项如输出目录dist和是否生成sourcemap用于生产环境调试。4.2 TypeScript配置的严格性tsconfig.json是TypeScript项目的核心。我启用了相当严格的编译选项以确保代码质量{ compilerOptions: { target: ES2020, useDefineForClassFields: true, lib: [ES2020, DOM, DOM.Iterable], module: ESNext, skipLibCheck: true, moduleResolution: bundler, allowImportingTsExtensions: true, resolveJsonModule: true, isolatedModules: true, noEmit: true, strict: true, noUnusedLocals: true, noUnusedParameters: true, noFallthroughCasesInSwitch: true, forceConsistentCasingInFileNames: true }, include: [src] }关键点在于strict: true它开启了一系列严格类型检查。noUnusedLocals和noUnusedParameters能帮助清理未使用的代码。这些设置虽然一开始可能会因为类型错误而“劝退”但长期来看它们能强制你写出更健壮、意图更清晰的代码将很多运行时错误提前到编译时发现。4.3 项目结构组织清晰的项目结构就像一个好的衣柜让你能快速找到需要的衣服。我的src目录结构是功能导向的src/ ├── models/ # 数据模型和核心逻辑Todo, TodoList ├── views/ # 视图渲染类负责将model数据变成DOM ├── services/ # “服务”如StorageService封装localStorage操作 ├── utils/ # 纯工具函数日期格式化、防抖节流等 ├── styles/ # 样式文件按功能拆分通过main.css导入 ├── types/ # 全局TypeScript类型定义 └── app.ts # 应用入口初始化所有模块并组装起来这种结构的好处是职责分离。models目录下的类不关心DOMviews目录下的类只关心如何渲染不关心数据怎么存services处理副作用如IO操作。这使得单元测试变得容易因为你可以单独测试TodoList的逻辑而无需启动浏览器。5. 实际开发中遇到的典型问题与解决方案在开发过程中我遇到了一些颇具代表性的问题它们的解决方案或许能帮你绕过同样的坑。5.1 数据持久化的“幽灵更新”问题问题描述在快速连续操作时比如按住回车键快速添加多个空待办项控制台会报错或者发现保存的数据状态错乱出现了未预期的“幽灵”数据。根因分析这是因为我的saveToStorage方法被直接绑定到了TodoList的每一个更新方法之后且没有做防抖。在极短的时间内可能会触发多次localStorage.setItem操作。虽然LocalStorage是同步的但JavaScript的事件循环和可能的UI渲染阻塞可能导致读写顺序出现竞态条件。解决方案引入一个简单的防抖函数。// utils/debounce.ts export function debounceT extends (...args: any[]) any( func: T, wait: number ): (...args: ParametersT) void { let timeout: NodeJS.Timeout | null null; return (...args: ParametersT) { if (timeout) clearTimeout(timeout); timeout setTimeout(() func(...args), wait); }; } // 在TodoList中使用 class TodoList { private saveToStorage debounce(() { localStorage.setItem(todos, JSON.stringify(this.todos)); }, 100); private notifyObservers() { // ... 通知逻辑 this.saveToStorage(); // 这里调用的是防抖后的函数 } }将保存操作延迟100毫秒执行如果在此期间有新的变更就取消之前的定时器重新计时。这确保了无论多快的连续操作最终只执行最后一次保存既解决了竞态问题也提升了性能。5.2 拖拽排序时视觉反馈的闪烁问题问题描述在拖拽元素经过其他项时通过修改dragover目标元素的样式如加背景色来提供反馈但有时会出现样式快速闪烁或跳动的情况。根因分析dragover事件触发频率极高每秒可能数十次。如果在这个事件处理函数中直接进行DOM操作如修改element.style.backgroundColor可能会频繁触发浏览器的重排reflow或重绘repaint导致性能下降和视觉闪烁。此外如果鼠标移动过快事件可能在不同元素间快速切换导致样式变化不稳定。解决方案使用CSS类替代直接样式修改预先在CSS中定义好一个.drag-over类该类包含视觉反馈样式。在dragover事件中只为当前目标元素添加这个类并移除之前其他元素上的这个类。DOM的className操作比直接操作style优化得更好。使用requestAnimationFrame节流对于更复杂的视觉更新比如动态插入占位符可以将更新逻辑包装在requestAnimationFrame回调中。这能确保视觉更新与浏览器的绘制周期同步避免不必要的中间帧渲染。优化事件处理逻辑在dragover处理函数开头可以先判断当前目标元素是否和上一次的是同一个如果是则直接返回避免重复操作。let lastDragOverElement null; function handleDragOver(event) { event.preventDefault(); const currentElement event.currentTarget; // 如果是同一个元素跳过 if (currentElement lastDragOverElement) return; // 移除上一个元素的高亮 if (lastDragOverElement) { lastDragOverElement.classList.remove(drag-over); } // 为当前元素添加高亮 currentElement.classList.add(drag-over); lastDragOverElement currentElement; }5.3 移动端触摸交互与点击延迟问题描述在手机或平板上点击复选框或按钮时感觉有大约300毫秒的延迟体验不跟手。根因分析这是早期移动浏览器为了区分“点击”和“双击缩放”而引入的著名问题。浏览器在touch事件后会等待约300ms看用户是否会再次触摸双击然后再触发click事件。解决方案现代浏览器已经通过meta nameviewport contentwidthdevice-width这个视口标签对不可缩放的页面移除了这个延迟。但为了最佳兼容性和体验我们可以采取更多措施确保视口标签正确如上所述这是基础。使用touch-actionCSS属性在可交互元素按钮、复选框上设置touch-action: manipulation;。这个属性告诉浏览器这个元素只支持平移和缩放手势从而允许浏览器立即触发click事件。监听touchstart或touchend事件对于需要极快响应的操作如开始拖拽可以直接监听触摸事件而不是等待click。但要注意这需要你手动处理点击和拖拽的冲突实现起来更复杂。对于大多数情况前两种方法已经足够。5.4 常见问题速查表为了方便你快速定位和解决问题我将开发中遇到的一些典型现象和解决方法整理成了下表问题现象可能原因解决方案页面刷新后待办项顺序恢复默认拖拽排序后未正确更新和保存orderIndex字段在拖拽drop事件中重新计算并赋值所有项的orderIndex然后触发保存。键盘快捷键在某些浏览器失效浏览器默认行为未阻止或快捷键与浏览器/系统冲突在快捷键事件监听器中调用event.preventDefault()。考虑提供可自定义快捷键的功能。暗色模式切换不生效CSS变量未在媒体查询中正确覆盖或浏览器不支持prefers-color-scheme检查CSS变量定义和作用域。为不支持该媒体查询的旧浏览器提供手动切换按钮作为降级方案。待办项文字过长时布局错乱CSS未对长文本做处理或容器宽度固定为文本容器设置overflow-wrap: break-word;或word-break: break-all;。考虑使用弹性或网格布局。生产构建后页面空白资源路径错误或JavaScript执行报错检查Vite构建输出的dist目录结构确保index.html引用的JS/CSS路径正确。打开浏览器开发者工具查看控制台报错。屏幕阅读器无法正确播报ARIA属性缺失或错误焦点管理混乱使用Chrome Lighthouse或axe工具进行无障碍审计。确保所有交互元素都有正确的role、aria-*属性和焦点顺序。6. 从项目构建中获得的经验与延伸思考做完这个项目它不仅仅是一个能用的待办清单更像是一个前端原生技术实践的微缩沙盘。回顾整个过程有几个体会特别深刻。首先理解底层API比追逐框架更重要。在实现拖拽、键盘导航、本地存储时我不得不去仔细阅读MDN文档理解每个事件的生命周期、每个API的边界情况。这个过程虽然有时痛苦但带来的掌控感和解决问题的能力是使用高阶框架封装所不能比的。当出现bug时你能清晰地知道问题可能出在事件流的哪个环节而不是在黑盒里猜测。其次TypeScript的严格类型是大型项目的“安全带”。在这个小项目中严格模式已经帮我提前捕获了十几次潜在的类型错误比如可能为undefined的值未做检查、函数返回值类型不匹配等。它强迫你在编码时就思考数据的形状和流动这极大地提升了代码的健壮性和可读性。对于任何准备长期维护或协作的项目从第一天起就使用严格TypeScript是绝对值得的投资。再者用户体验藏在细节里。一个全键盘操作的快捷键设计、拖拽时流畅的视觉反馈、移动端触摸的跟手感觉、甚至是在删除项目后焦点的合理移动这些细节单个看起来微不足道但叠加在一起就构成了产品的“质感”。开发时需要不断地把自己切换到“小白用户”和“键盘重度用户”等多种角色去使用和测试。最后关于AI辅助编程就像本项目最初得到Claude的帮助我的看法是它是一个强大的“加速器”和“灵感来源”但绝不能替代思考。AI可以快速生成模块代码、提供实现方案、甚至帮你调试错误信息。但项目的整体架构设计、技术选型的权衡、用户体验的打磨这些核心决策必须由开发者自己做出。AI生成的代码你必须一行行理解把它变成你自己的知识。这个项目从AI生成的雏形到如今每个细节都经过推敲的版本正是这种“人主导AI辅助”模式的最佳体现。它让你从重复的样板代码中解放出来更专注于那些真正创造价值的部分。