高仿网易云笔记第4天：数据模型、localStorage与Markdown编辑器实现

1. 项目目标与第4天范围

1.1 这个项目到底在做什么

先交代一下背景。这个“高仿网易云的笔记记录”项目，是我最近在做的个人练手项目。目标不是重新做一个网易云播放器，而是借着网易云音乐那套成熟的视觉语言和交互框架，做一款“以音乐为灵感的个人笔记工具”。

说白了，就是把网易云那种黑胶唱片、私人FM、歌单广场的视觉氛围，嫁接到笔记记录的场景里。你在里面记录的不再是文档，而是一条条“动态”、一张张“唱片”、一段段“想记下的瞬间”。

第4天这个节点，刚好是整个项目从“能看”到“能用”的关键转折点。前两天完成了首页框架、底部Tab导航、歌单风格的列表页骨架，第三天做了播放页的静态还原（转动的唱片、进度条、封面模糊背景）。到了第4天，核心工作很明确：把笔记记录功能真正落到可操作、可持久化的状态。也就是你打开项目能记东西，关了浏览器再打开，内容还在；能编辑、能删除、能搜索、能按标签筛选。

1.2 为什么把笔记记录当作第4天的重点

很多仿写项目做到一半就放弃了，原因基本一样：静态页面已经写得够多了，一到交互和数据存储就不知道怎么下手。我这个项目刻意把“笔记记录”放在第4天而不是第1天，是想先把视觉框架定下来，让后续每加一个功能都有地方落脚。

但第4天如果还只做视觉，项目就废了。所以我给自己定的第4天任务非常聚焦：

• 笔记数据模型设计（字段、类型、默认值）
• 本地持久化方案（localStorage封装）
• 笔记编辑器（支持Markdown语法）
• 笔记列表的增删改查
• 搜索与标签筛选
• 模拟网易云风格的视觉整合

这六件事做完，项目就可以说“内部跑通了”。后面再做同步、再做分享、再做语音记录，都只是在这套地基上添砖加瓦。

2. 数据模型设计：先把笔记的“地基”打牢

2.1 笔记实体需要哪些字段

第4天一开始我干的第一件事，不是写组件，而是先定义笔记的数据结构。这个太重要了。如果数据结构一开始就有问题，后面写增删改查的时候会反复推倒重来。

我最终确定的笔记实体是这样的：

typescript复制interface Note {
  id: string;              // 唯一ID，用 crypto.randomUUID()
  title: string;           // 标题
  content: string;         // Markdown 正文
  cover?: string;          // 封面图（可空，默认用渐变色卡片）
  mood: 'joy' | 'calm' | 'melancholy' | 'passion';  // 情感标签
  albumId?: string;        // 归属“专辑”，也就是自定义分类
  color: string;           // 卡片底色，存的是色值
  createdAt: number;       // 创建时间戳
  updatedAt: number;       // 更新时间戳
  pinned: boolean;         // 是否置顶
  deleted: boolean;        // 软删除标记
}

每个字段我都有明确用途，不是拍脑袋想的。mood是我这个项目比普通笔记App多出来的维度，对应网易云里那种歌曲情绪的区分，一首歌可以标注“快乐”“安静”“伤感”，我把这个玩法带到笔记里，给每条记录打情绪标签。视觉上会直接反映在卡片颜色和icon上，非常出效果。

deleted字段走的是软删除逻辑。用户点删除时先标记，不在列表展示；而回收站页面可以恢复或彻底清除。这个设计避免了一个很常见的坑：直接删掉数据记录，用户误删就找不回来了。

时间戳用数字而不是字符串，是为了排序方便。createdAt在前端直接参与sort比较，不需要再new Date()解析。这一点如果你用字符串日期，后面做排序会后悔的。

2.2 用localStorage做持久化，配套版本号迁移

数据模型定好了，接下来就是存储。这个项目没上后端，也没用IndexedDB，第4天阶段本地存储用localStorage完全够用。但直接裸用localStorage，长期迭代会有两个麻烦：

• 数据结构改了，旧数据读出来不兼容
• 没有统一的读写入口，代码到处都是localStorage.setItem

所以我写了一个非常轻量的存储封装，加了一个version字段，预留了数据迁移的钩子：

typescript复制const STORAGE_KEY = 'netease-notes-db';
const DB_VERSION = 4;

function loadDB(): StoredDB {
  const raw = localStorage.getItem(STORAGE_KEY);
  if (!raw) {
    return { version: DB_VERSION, notes: [], albums: [] };
  }
  try {
    const parsed = JSON.parse(raw);
    // 迁移钩子：版本低了就升级
    if (parsed.version < DB_VERSION) {
      return migrate(parsed);
    }
    return parsed;
  } catch (e) {
    console.warn('存储数据损坏，已重置', e);
    return { version: DB_VERSION, notes: [], albums: [] };
  }
}

这里的migrate函数是一个switch-case的版本迁移链，从版本1一步一步升到当前版本。每升一级只做一件事，这样即使未来加了字段，老用户的数据也不会丢。

提示：localStorage有5MB左右的容量限制，纯文本笔记通常不会有压力。但如果后面要存图片，建议单独用IndexedDB，不要在localStorage里塞base64图片，很快就会爆。

踩过一次坑是JSON.parse直接写在业务代码里，结果代码里到处是try-catch。后来统一封装之后，组件层只管调用addNote、updateNote这些函数，存储细节全部收口，出了问题只需要改一个文件。

2.3 状态管理选型：为什么不用Redux而是用Zustand

数据存储搞定之后，摆在面前的是状态管理方案。在这个项目里我选了Zustand，没有上Redux。

理由很简单：项目规模不到Redux那种重型状态机的地步，Redux样板代码太多了，定义action、reducer、dispatch钩子，写起来非常鸡肋。Zustand写起来几乎没什么心智负担，代码量少，而且它天然支持从外部读写store，这对localStorage的同步非常友好。

我用它管理了一个全局store：

typescript复制import { create } from 'zustand';

interface NoteStore {
  notes: Note[];
  activeNote: Note | null;
  query: string;
  addNote: (note: Partial<Note>) => void;
  updateNote: (id: string, patch: Partial<Note>) => void;
  deleteNote: (id: string) => void;
  setQuery: (q: string) => void;
}

每个方法内部都会调用存储封装，操作完再把最新数据set回store，同时更新localStorage。UI层直接订阅notes字段即可，压根不用关心数据从哪来。

如果你对这个方案不熟，我可以直说：Zustand最大的优势是省心。在这个量级的项目里，Redux和MobX带来的架构优势体现不出来，反而是一种负担。

3. 编辑器实现：从文本域到Markdown预览

3.1 编辑器三层结构

笔记核心是编辑器。我实现的是“左边写，右边看”的双栏Markdown编辑器，整体分成三层。

第一层是工具栏。包含标题选择（H1-H3）、加粗、斜体、行内代码、引用、无序列表、有序列表、插入链接、插入图片的占位入口。每个按钮的点击行为，本质上就是向textarea的光标位置插入对应的Markdown语法片段。

第二层是textarea编辑区。这里我用了一个稍微带点技巧的做法：监听scroll事件，让左侧textarea和右侧预览区滚动同步。这个细节待会在问题排查里重点讲。

第三层是预览渲染区。把Markdown字符串转成HTML，我用的是marked + DOMPurify组合。前者负责把# 标题、**加粗**这类的语法变成HTML，后者负责消毒，防止XSS注入。

三层结构代码组织非常清晰，每个区域一个组件，状态提升到父组件的useState里：

tsx复制const [content, setContent] = useState('');
const [html, setHtml] = useState('');

输入时更新content，通过useMemo或useEffect生成html：

tsx复制useEffect(() => {
  const rawHtml = marked.parse(content);
  const cleanHtml = DOMPurify.sanitize(rawHtml);
  setHtml(cleanHtml);
}, [content]);

这里为什么要用DOMPurify？因为如果用户粘了一段带<script>的文本，marked会原样输出，浏览器执行后就出大问题了。小项目也要养成消毒的习惯。

3.2 工具栏按钮与Markdown语法映射

工具栏按钮看起来简单，但实现的时候有几个边界情况要处理。

拿加粗来说，点击按钮后需要在光标位置包一层**。关键代码如下：

typescript复制function wrapSelection(before: string, after: string) {
  const el = textareaRef.current;
  const start = el.selectionStart;
  const end = el.selectionEnd;
  const selected = content.substring(start, end);
  const next = content.substring(0, start)
    + before + selected + after
    + content.substring(end);

  setContent(next);

  // 下一帧重新聚焦并把光标放在选中文本后面
  requestAnimationFrame(() => {
    el.focus();
    el.setSelectionRange(start + before.length, end + before.length);
  });
}

几个边界情况：

• 光标没有选中任何文本时，直接插入****，然后把光标定位到两个星号中间
• 选中内容本身就是加粗状态（以**开头并以**结尾）时，应该反操作去掉加粗
• 光标在行首时插入列表符号，光标在行尾时直接append

这些细节单独写都不难，但合在一起就需要反复测来测去。我写了一个工具函数专门处理“当前选中文本的语法状态”，避免用户多点一次按钮就格式错乱。

3.3 代码块与标题目录提取

网易云风格的文章型笔记，往往有多级标题。所以我做了一个很有项目特色的功能：自动提取笔记里的标题，生成侧边目录。

实现方式很简单。在读预览HTML的同时，我把Markdown源码按行扫描一遍，用正则匹配^#{1,3} 开头的行，记录标题级别和文本，然后生成一个锚点列表：

typescript复制function extractHeadings(md: string): HeadingItem[] {
  const lines = md.split('\n');
  const result: HeadingItem[] = [];
  for (let i = 0; i < lines.length; i++) {
    const match = /^(#{1,3})\s+(.*)$/.exec(lines[i]);
    if (match) {
      result.push({
        level: match[1].length,
        text: match[2].replace(/[#*`]/g, ''),
        line: i
      });
    }
  }
  return result;
}

目录出现在预览区域右上角，点击后滚动到对应位置。我用的是给h1/h2/h3标签注入id属性的方式，然后document.getElementById(id).scrollIntoView({ behavior: 'smooth' })。

如果你也想做这个功能，有个细节要注意：标题文本里可能有重复。两个标题都叫“总结”，生成的id就会重复。我处理方式是在id后面加序号，比如summary-1、summary-2。

代码块的高亮我用了highlight.js，因为项目是Vite构建的，直接按需引入，没把全量语言包塞进来，不然打包体积会大得离谱。

4. 列表页与详情页的交互还原

4.1 卡片式列表：复刻网易云的专辑宫格布局

数据模型、编辑能力都有了，接下来就是把数据视觉化。列表页我复刻的是网易云“我的收藏专辑”宫格布局——两列卡片，每张卡片上面是封面图区域，下面是标题和情绪标签。

卡片封面的默认方案是纯色渐变背景，色值由笔记的color字段决定。这里我用了一个基于标题字符串hash的随机色生成器，保证同一标题每次生成的颜色一致，但又具备随机感：

typescript复制function getColorFromString(str: string): string {
  let hash = 0;
  for (let i = 0; i < str.length; i++) {
    hash = str.charCodeAt(i) + ((hash << 5) - hash);
  }
  const hue = Math.abs(hash) % 360;
  return `linear-gradient(135deg, hsl(${hue}, 70%, 80%), hsl(${(hue + 40) % 360}, 70%, 60%))`;
}

这个做法的好处是：不需要真正的封面图，也能让每张卡片看起来完全不一样，和网易云那种每个专辑有独立视觉的感觉很像。

卡片上还放了情绪icon。joy是太阳，calm是月牙，melancholy是雨滴，passion是火焰。我用的是SVG内联图标，没有引第三方icon库。这个项目里我尽可能少装依赖，一来是控制体积，二来是加深对SVG的理解。

列表的排序逻辑是这样的：按deleted === false过滤，按pinned优先，其次按updatedAt倒序。置顶的卡片会有个小的图钉标记，这个细节同样是仿网易云的“置顶歌曲”功能。

4.2 左侧滑动操作：置顶、删除、收藏

移动端还原网易云，有一个交互是必须做的：向左滑动卡片，底部露出操作按钮。我实现了三个操作：置顶/取消置顶、标签编辑、删除。

滑动实现没引组件库，自己写了一个：

• 监听touchstart记录触摸起始X
• 监听touchmove计算水平位移，如果位移大于0则忽略（向右滑不触发）
• 位移小于0且超过阈值50px时，打开操作面板

面板宽度预设90px，里面竖排三个按钮。这个功能的难点有两个。

第一个是防冲突：列表本身可以上下滚动，左右滑动是卡片操作。如果用户在卡片上先垂直移动再水平移动，很容易误触发。我的判断逻辑是：如果Math.abs(deltaX) < Math.abs(deltaY)，直接当成纵向滚动处理，不触发横向滑动。

第二个是手动回弹。松手后卡片要么完全展开，要么完全收起。用一个transition: transform 0.2s ease来实现。展开时把整张卡片translateX(-90px)。

如果你也想自己写这个，建议用translate3d而不是translateX，性能差别在低端安卓机上特别明显。这个内容在“常见问题”一节里我会再提一次。

4.3 详情页的沉浸式头部与毛玻璃效果

第4天的最后一个重点，是把详情页做成网易云那种“点开卡片就是沉浸式专辑页”的感觉。顶部是封面大图区域，下面铺渐变背景，标题和情绪信息悬浮在图上。

毛玻璃效果用的是backdrop-filter: blur(20px)配合半透明背景。但这里有个坑需要注意：backdrop-filter在某些浏览器上会把子元素也一起模糊掉。我的规避方案是：毛玻璃容器和内容容器是兄弟节点，不是父子嵌套。一个负责背景模糊，一个负责内容显示，通过绝对定位叠在一起。

详情页还加了一个“正在翻阅”的进发感。进入页面时，封面区域自动播放一个从0到1的淡入加轻微缩放的动画。动画结束时，封面会像网易云黑胶唱片落下去一样，有一个极短的下沉位移。这个动画时间控制在450ms，太短没感觉，太长影响阅读。

动画实现直接写在CSS里，用animation和@keyframes，没有额外引入动画库。

还有一个体验细节：详情页向上滚动时，头部区域会像网易云那样逐渐缩小并模糊，固定成一个小型导航条。我实现的是监听window.scrollY，当超过一定阈值时给头部容器加一个collapsed类，控制高度变化与背景透明度。

5. 搜索与标签体系的搭建

5.1 按内容全文检索

搜索功能在笔记应用里是刚需，但很多笔记类项目会忽略它，直到笔记多到翻不完才后悔。

我实现的是一个轻量的全文检索。不需要搜索引擎，因为本地笔记数据量级在几千条以内，直接遍历一次不会有性能问题。

typescript复制const filteredNotes = notes.filter((note) => {
  const keyword = query.trim().toLowerCase();
  if (!keyword) return true;
  return (
    note.title.toLowerCase().includes(keyword)
    || note.content.toLowerCase().includes(keyword)
    || note.mood.toLowerCase().includes(keyword)
  );
});

这里的细节在于：关键词输入时不能每次都重新遍历所有笔记，否则会有卡顿感。我用了useMemo把过滤结果缓存起来，依赖项是notes和query。

如果你想来点更高级的玩法，可以考虑分词搜索。中文场景下，简单的方案是把关键词拆成单字，也可以按词频权重给标题匹配和内容匹配分别打分。但第4天阶段，includes方法已经完全够用了，“够用就好”是这次迭代的原则。

5.2 标签筛选与“情感标签”玩法

标签筛选做得很轻。顶部一排Tab，分别是“全部”“快乐”“安静”“伤感”“热烈”，点击后过滤出对应mood的笔记。

为什么刻意做情绪标签？因为这是“网易云氛围感”的核心所在。网易云听歌时每首歌都被赋予情绪基调，这个场景放到笔记里，就是每条记录都有情绪底色。这个差异点做完之后，整个项目的辨识度就出来了——它不是普通笔记App，是“有情绪的笔记”。

这里我想分享一个延伸玩法。你可以给每个情绪标签配一段动画反馈。比如点击“伤感”标签时，列表顶部弹出一句“此刻你有点低落”，配合卡片背景变成冷色调。这种细节堆叠起来，会让用户觉得这个产品“有灵性”。

如果继续迭代，我打算给标签增加自定义能力，用户可以创建自己的情绪标签，然后统计一周内各类情绪笔记的数量，做成一个简单的“情绪周报”，模仿网易云的年度听歌报告。这个功能非常出彩，强烈建议你试试。

6. 视觉还原中的几个关键细节

6.1 色板提取与CSS变量设计

视觉还原做得好不好，决定性因素是对原产品色板的提取。我参考了网易云的品牌色，但并不是直接抄，而是提取了它的视觉节奏：强烈的红色点缀、大面积暗色背景、柔和的白灰色文本。

项目里我用了CSS变量管理颜色，方便主题切换和全局统一调整：

css复制:root {
  --primary-color: #ec4141;
  --background-color: #f5f5f7;
  --card-background: #ffffff;
  --text-primary: #1a1a1a;
  --text-secondary: #666666;
  --shadow-color: rgba(0, 0, 0, 0.06);
}

这个做法的好处太明显了：后面如果想做暗黑模式，只需要替换这几个变量，全站颜色自动切换。第6天做主题切换功能时，我只要写一套暗色变量，然后给根节点加上data-theme="dark"，就完成了。

6.2 微交互：点击反馈、加载状态、空状态

高保真还原不只是“长得像”，更重要的是“手感像”。第4天我重点做了三类微交互。

点击反馈。所有可点击按钮都加了按下态，不是靠默认的浏览器效果，而是手动定义:active样式。比如卡片点击后有一个0.2s的缩放反馈，缩放比例为0.97。这个细微的缩放给用户的“按下感”非常强。

加载状态。虽然localStorage的数据读取本地极快，但为了后续接后端做准备，我在数据初始化时做了一个假loading，至少展示600ms的骨架屏。骨架屏用纯CSS动画实现，灰色块在呼吸式闪烁。

空状态。笔记为空时，页面中央展示一个大大的唱片icon，旁边写着“还没有记录，点右下角开始写下第一张唱片”。这是仿网易云空歌单的展示方式。空状态文案我改了好久，既要符合产品调性，又要给用户明确的下一步操作指引。

这三类微交互做完，整个项目的完成度确实上了一个台阶。视觉还原类项目，很多初学者只关注静态长什么样，忽略动态反馈，导致成品看起来“死气沉沉”。如果你也在做仿写项目，强烈建议把这三个细节纳入日常清单。

7. 常见问题与排查技巧实录

7.1 移动端横向滑动卡顿

我在真机上测试时发现，卡片左滑偶尔会有卡顿，尤其在列表项多的页面。排查方向锁定在GPU渲染上。

解决方案是把卡片的transform加上translate3d，主动开启GPU加速：

css复制.note-card {
  transform: translate3d(var(--slide-offset, 0), 0, 0);
  will-change: transform;
}

注意will-change不能滥用。如果每个卡片都加了will-change: transform，反而会造成大量内存占用。我只在滑动开始时才动态添加，滑动结束就移除。

另外要提一下，iOS上backdrop-filter非常吃性能，如果一个页面有多个毛玻璃元素，很容易掉帧。我的做法是能不用就不用，只在详情页头部用一个。

7.2 Markdown预览与Textarea滚动同步

这个功能做出来很加分，但第一次实现时我没处理好几毫秒的时间差，导致左右滚动不同步，左边滚到第300行，右边才到第200行，体验非常割裂。

正确做法是通过滚动比例来计算目标位置：

typescript复制function handleScroll() {
  const el = textareaRef.current;
  const preview = previewRef.current;
  if (!el || !preview) return;

  const ratio = el.scrollTop / (el.scrollHeight - el.clientHeight);
  const target = ratio * (preview.scrollHeight - preview.clientHeight);
  preview.scrollTop = target;
}

但这里有个问题：右边预览区的实际内容高度远大于textarea。右边有标题、段落、代码块，每个内容块的高度都不一样，用比例计算在大多数情况下是对的，但在代码块非常多的笔记里会偏差明显。

一个更精确但更复杂的方法是给每个标题和段落块打上标记，根据左边可见的第一行文本去右边找对应元素。第4天我没做这么深，采用的是比例算法，实践中效果已经够好了。

7.3 大段内容输入时的性能抖动

输入光标快速移动或粘贴大量文本时，预览区渲染经常卡顿。这其实是React组件频繁重渲染的经典问题。

我的优化方案有三个，按优先级排列：

• 预览区组件用React.memo包裹，只有当html变化时才重渲染
• marked.parse的调用放在useMemo里，依赖项只有content，避免每次组件重新渲染都重复解析
• 在textarea输入时，不实时更新全局store，而是用一个局部状态承接，等输入停止500ms后再把内容同步到store

typescript复制useEffect(() => {
  const timer = setTimeout(() => {
    updateNote(note.id, { content });
  }, 500);
  return () => clearTimeout(timer);
}, [content]);

这个500ms防抖确实减少了大量的状态更新频率。数据持久化也从每次击键都写一次localStorage，变成停下来才写一次。对用户体验完全没影响，但对性能提升非常明显。

7.4 数据损坏与异常恢复

有一次我在调试时手动改了localStorage里的数据格式，导致页面白屏。这个问题的根因是JSON.parse成功但字段类型不对，代码里用了note.tags.map，而tags已经变成undefined。

稳妥的做法是给数据读取加一层schema校验。不引第三方校验库，手写一个极简的校验函数：

typescript复制function isNoteShape(data: any): data is Note {
  return (
    typeof data?.id === 'string'
    && typeof data?.title === 'string'
    && typeof data?.content === 'string'
    && typeof data?.createdAt === 'number'
    && typeof data?.updatedAt === 'number'
  );
}

筛选数据时先过滤掉不合格对象，宁可丢数据也不能让整个页面崩掉。如果后续项目有后端，这层校验依然有意义，它可以拦住大部分脏数据入口。

最后再分享两个实际操作中的小技巧

第一个是命名规范。做这种中等复杂度的前端项目，我建议所有store方法统一用add、update、delete前缀，组件里的回调函数统一用handle前缀。这个习惯帮我省掉了特别多“这个函数到底在哪定义”的查找时间。

第二个是调试技巧。localStorage存储层我写了一段调试代码，开发环境会在控制台打印每次数据变更的简略日志，包括变更类型、笔记ID和更新后的总条数。上线前直接用环境变量关掉。刚开始觉得多此一举，后来有几次数据异常，靠这段日志快速锁定了原因。如果你也在做类似有状态的本地项目，这个习惯真的推荐养成。

第4天的内容到这里就完成了。项目从静态骨架变成了一个能记、能存、能搜、能筛选的完整工具，而且保留了网易云式的视觉氛围。下一阶段的计划是给笔记增加“导入音乐”的能力，让每条笔记可以绑定一首歌作为背景音乐，进一步强化音乐笔记的定位。这个迭代做完，整个项目的主题会彻底立起来。