小蓝书 Go
开发与源码

前端工程:页面状态、真实 API 与生活手册设计

前一站:评论与关系 · 接着读:从零实现

先知道每个文件#

文件 作用
frontend/index.html 文档标题、root 容器和入口脚本
src/main.tsx 创建 React root、加载全局与品牌样式
src/App.tsx 屏幕切换、登录、首页、详情、编辑、个人页、搜索、设置和后台
src/api.ts fetch、token、超时、错误、统一解包、401事件
src/types.ts 请求/响应相关类型
src/mock.ts 仅显式开启原型演示时使用的数据
src/styles.css 原有组件的基础布局
src/journal.css 本次生活手册品牌层和响应式调整
public/assets 默认本地摄影和头像
vite.config.ts React 插件、开发代理、固定本机监听

当前采用 App 内屏幕状态,没有新引入路由库。刷新会回到默认首页,token仍恢复登录;它不承诺每篇笔记有可直接分享的独立 URL。未来引入路由应同时处理浏览器后退、刷新、加载权限和404。

React 的四个概念#

组件是返回页面的函数,例如 NoteCard。props 是上层传入的数据和动作;state 是本组件会变化的数据;effect 在挂载或依赖变化后与外部系统同步。useState([]) 保存笔记,setNotes 触发重新渲染;不能直接改数组然后期待页面知道。

useEffect 不是“任意代码都放进去”的容器。首页请求依赖页签、页码和登录状态,清理函数让旧请求结果不覆盖已切换页签。React StrictMode 开发时可能额外运行 effect 检查清理,因此网络看到两次初始读取并不一定是业务重复写入。

请求封装的真实数据结构#

request 设置 Accept、JSON 或 FormData 请求格式,附带 token,15秒AbortController超时,验证响应是 JSON,检查 HTTP 状态与 success,返回业务 data。FormData 不手动写 Content-Type,因为浏览器需要自动加 boundary。

401 清理失效 token 并派发 session-expired,App 切回首页和提示登录。网络错误不会静默返回 demoNotes。发布与修改返回 Note,页面拿真实 ID;资料更新返回 Profile,因此实际头像 URL 替换本地 blob 预览。

页面的几个边界#

发现推荐、关注、最新使用同一真实搜索入口;关注需要登录,空态给出下一步。搜索区分笔记/用户,筛选枚举统一映射;个人笔记使用 cursor;评论、关系和搜索用页码。用户不能因为一个列表只加载了20条就误以为总共只有20条。

详情点赞和收藏乐观更新,失败回滚。加载详情的 effect 依赖笔记 ID 和登录状态,不能每次按钮改变对象引用就重读旧状态覆盖刚刚的操作。删除和私密后,列表重新读取后端,不能只本地隐藏却让直接请求继续成功。

视觉 skill 的应用#

参考文件在 third_party/skills/frontend-design,来源和许可在第三方说明 ↗。先写视觉方案再实现:蓝色书脊、摄影主导、黄色便签集中表达个性;删除轨道装饰和大面积渐变;标题不靠单词变色制造层次。

桌面4列、平板3/2列、手机2列;小屏首屏重排拼贴;主题入口可横向滚动但整页不溢出。字号、留白、作者行和图片裁切共同决定层级,不能只把按钮换成另一种蓝色就说完成设计。

可访问性和安全#

所有交互保留键盘焦点,卡片可 Enter/Space 激活,内层按钮事件不误触整张卡。弹窗声明 dialog/aria-modal,Escape关闭;反馈使用 role=status;减少动画媒体查询禁用非必要运动。标题和昵称用 JSX 文本,不直接插入服务端 HTML。图片带 alt,失败头像回本地资源且移除重复 onError 防循环。

构建与联调#

npm.cmd ci --prefix frontend
npm.cmd run build --prefix frontend

构建包括 TypeScript 严格检查;依赖的 peer 兼容不等于页面行为正确,仍需浏览器上传、发布、评论与后台检查。截图保存在 docs/reports/screenshots;实际通过范围以验证报告为准。

— 本篇阅读完毕 —
来源:小蓝书 Go / docs / 03-development/frontend.md 下载原文
输入关键词,在三个知识库中搜索
支持正文检索 · 直接定位章节Esc 关闭