{ "version": "https://jsonfeed.org/version/1.1", "title": "程序员奇趣博客", "home_page_url": "https://kairos.cn.mt", "feed_url": "https://kairos.cn.mt/feed.json", "description": "基于 Astro 的程序员个人博客与知识工作台", "language": "zh-CN", "icon": "https://kairos.cn.mt/favicon.svg", "favicon": "https://kairos.cn.mt/favicon.svg", "authors": [ { "name": "程序员奇趣博客", "url": "https://kairos.cn.mt/about" } ], "items": [ { "id": "https://kairos.cn.mt/pitfalls/astro-prerender-content-warning/", "url": "https://kairos.cn.mt/pitfalls/astro-prerender-content-warning/", "title": "Astro 预渲染时内容集合为空提示", "summary": "在 SSR 项目中预渲染内容详情页时集合提示为空的排查——loader 显式配置、schema 校验与构建期防护的完整记录。", "content_text": "现象 构建可以完成，但预渲染阶段提示内容集合不存在或为空，文章详情页的 getStaticPaths 拿到空数组，产出 0 个页面——构建是\"绿\"的，内容却静默消失。 根因 Astro 7 的 Content Collections 不再自动推断目录结构，每个集合必须 显式声明 loader 。两个常见的静默失败点： 1. glob 的 base 路径与实际内容目录不一致（比如内容在 src/content/posts/ 而 base 指向了旧的 src/content/blog/ ），loader 不会报错，只会给出空集合； 2. 文件的 frontmatter 不符合该集合的 schema（如日期字段类型不对、必填缺失），条目被整体丢弃。 修复：显式 loader 对齐真实目录 本项目 src/content.config.ts 中每个集合都显式声明 glob loader，且 base 与内容目录一一对应： const posts = defineCollection({ loader: glob({ pattern: ' / .{md,mdx}', base: './src/content/posts' }), schema: postSchema, }); const pitfalls = defineCollection({ loader: glob({ pattern: ' / .{md,mdx}', base: './src/content/pitfalls' }), schema: postSchema.extend({ severity: z.enum(['low', 'medium', 'high']).default('medium'), }), }); 防复发：构建期三道闸 空集合最怕\"静默\"，所以把校验前移： schema 层 ：日期用 z.coerce.date() 、必填 title/description/publishedAt/tags/category ，写错字段类型在 dev 就会看到 400 行错误而不是空结果； 内容检查脚本 （ scripts/check-content.mjs ，挂进 prebuild ）：统计各集合条目数、slug 冲突、 relatedPosts 引用完整性，坏数据直接让构建失败； 详情渲染批测 ：对 sitemap 中全部文章/踩坑/项目/日志详情页断言标题与正文长度——集合又空了，批测立刻可见地失败。 验证方式 最快的自查两连： 1. 集合是否真的读到了条目 npx astro build 2>&1 | grep -oE \"prerendered [0-9]+ pages\" 2. 单个集合计数与内容文件数是否一致 ls src/content/posts/ .mdx | wc -l 两个数字对不上（或页面数骤降为文章数+0），优先查 base 路径与某个文件的 frontmatter 是否把整个集合带崩。", "date_published": "2026-07-20T00:00:00.000Z", "date_modified": "2026-09-03T00:00:00.000Z", "tags": [ "Astro", "预渲染", "Content Collections" ] }, { "id": "https://kairos.cn.mt/projects/content-governance-gates/", "url": "https://kairos.cn.mt/projects/content-governance-gates/", "title": "内容治理与发布门禁体系", "summary": "用 schema 校验、构建期生成、草稿隔离断言与运行时检查组成的四层门禁，保证内容站在\"随便写\"和\"放心发\"之间两全。", "content_text": "它解决什么问题 内容站的腐化通常不来自代码，而来自数据：缺字段的 frontmatter、改 slug 后留下的死引用、草稿混进公开索引、发布后页面出现内部术语。这套体系把这些问题挡在\"写作的下一分钟\"，而不是\"读者的下一次点击\"。 四层结构 第 1 层 结构校验 zod schema（内容集合定义）：类型、枚举、默认值、日期 第 2 层 语义校验 scripts/check-content.mjs：引用完整性、slug 唯一、 日期逻辑、字段覆盖率、各集合统计 → content-health.json 第 3 层 生成隔离 prebuild：search:index / graph:data 只读非草稿； 公开产物（索引/图谱/RSS/sitemap/dist）逐一断言无草稿泄漏 第 4 层 运行时门禁 release-gate 脚本对真实响应检查： 全路由 200、站内死链、公开文案禁用词、状态页语义正确 关键决策： 校验先于生成 ：prebuild 顺序固定 content:check → search:index → graph:data → build ，坏数据在最上游失败，下游永远消费干净输入。 草稿隔离用\"产物断言\"而不是\"信任生成器\" ：生成器已过滤草稿，但门禁仍独立扫描每个公开产物是否含任一草稿 ID——双保险，因为这里的失误不可逆（搜索引擎缓存）。 内容健康可视化 ：校验结果落 JSON，后台渲染成清单（缺什么字段、差多少内容达标），作者看到的是可执行条目而非日志墙。 人工判断保留给人 ：门禁只查可机械验证的规则（存在性、格式、泄漏、死链）；文案质量、真实性审核是独立人工环节，草稿必须经它才能转正。 运行方式 CI 与本地同一入口 npm ci && npm run check && npm run lint && npm run test \\ && npm run content:check && npm run build 发布前对运行中的站点： npm run test:release-gate:runtime 历史上这套门禁真实拦下过：新文章标题命中公开页禁用词（改文章，不降规则）、生成索引残留已删路由、 define:vars 脚本在客户端路由下崩溃（由此新增全站交互回归）。 当前状态 四层全部在跑：CI 工作流含全部质量命令；运行时检查接入发布流程；内容后台展示健康度与草稿审核清单。已知边界：禁用词扫描跳过代码块（正文内技术词合法），像素级视觉验收仍需人工（见路线图遗留记录）。 下一步 把\"订阅频道承诺 ⊆ Feed 覆盖\"这类跨产物一致性规则补进第 3 层；为运行时检查增加性能断言（复用 LHCI 产物而非另起浏览器会话）。", "date_published": "2026-09-03T00:00:00.000Z", "date_modified": "2026-09-03T00:00:00.000Z", "tags": [ "Astro", "CI", "内容系统", "质量保障" ] }, { "id": "https://kairos.cn.mt/projects/knowledge-constellation-explorer/", "url": "https://kairos.cn.mt/projects/knowledge-constellation-explorer/", "title": "知识星图浏览器", "summary": "把文章内容编译成关系图并在 Canvas 上可交互探索：构建期生成、力导向渲染、路径查询与无鼠标等价操作的系统说明。", "content_text": "它解决什么问题 \"这个站写过哪些东西、彼此怎么关联\"是传统博客回答不了的问题。知识星图把文章、项目、踩坑、笔记、标签、系列编译成一张可探索的关系网——读者可以从任何一颗星出发，顺着引力找到相关的一切。 数据链路 内容集合（frontmatter 关系字段） → scripts/generate-graph-data.mjs（构建期，仅非草稿） → public/graph-data.json（当前构建：172 节点 / 253 边） → /graph SSR 页面读取（磁盘直读，见文章《SSR 页面为什么不该向自己发 HTTP 请求》） 边类型：文章↔标签、文章↔系列、项目↔相关文章、踩坑↔标签——全部来自已校验的 frontmatter 引用（引用完整性由内容门禁保证，图里不会出现悬空边）。 渲染层的四个工程决策 1. 力导向自研而非引库 ：确定性初始布局（同一输入同一画面，可回归）、O(n²) 斥力 + 弹簧 + 向心力、alpha 衰减自动停帧——当前规模几百毫秒收敛，浏览器里算得起，无需 Web Worker。 2. 性能自律 ： requestAnimationFrame 只在有能量时运行； IntersectionObserver 离开视口即停帧，后台标签页暂停；拖拽/缩放/平移/双击复位全在 Canvas 坐标系内完成，不触发布局。 3. 降级是设计的一部分 ： prefers-reduced-motion 下同步结算 240 次迭代输出静态星图——信息量不变，只是不\"飘\"；移动端粒子/光效降级的同一原则在这里复用。 4. 无鼠标等价操作 ：星图是可发现性增强，不是唯一入口——节点列表（可过滤、键盘可达、Enter 聚焦星图对应节点）、类型筛选、路径查询（起点/终点下拉 + 本地 BFS 最短路径，含\"无可达路径\"空态）全部可纯键盘完成。 交互模型 点击节点 → 邻域高亮（相连边标记 source/target、非相关弱化）+ 邻接面板列出关系；类型筛选与关键词过滤联动重排；BFS 路径提示展示\"节点 A → B → C\"与跳数。数据在页面内联一份公开 payload（构建期直读生成物），过滤/路径全部内存态——不持久化、不上传任何输入。 当前状态与边界 星图模式已成为探索地图默认视图（节点阈值达标后从二级入口升级）。边界：图规模到千级节点时 O(n²) 斥力需要换成 Barnes-Hut 或分块布局，页面结构已为此预留（渲染器与数据层解耦，输入只是那份 JSON）。 下一步 方向筛选（只看\"文章→标签\"类边）、跨类型路径高亮动画（尊重 reduced-motion）、以及基于入度的\"枢纽文章\"榜单接入首页。", "date_published": "2026-09-03T00:00:00.000Z", "date_modified": "2026-09-03T00:00:00.000Z", "tags": [ "Canvas", "数据可视化", "图算法", "Astro" ] }, { "id": "https://kairos.cn.mt/projects/weekly-digest-pipeline/", "url": "https://kairos.cn.mt/projects/weekly-digest-pipeline/", "title": "周报订阅与投递流水线", "summary": "从邮箱确认、MySQL 持久化到可插拔邮件 provider 的订阅系统：状态机、幂等、重试和投递回执的完整链路说明。", "content_text": "它解决什么问题 内容站希望读者\"按主题订阅更新\"，但订阅是一个容易做错的功能：要防误填他人邮箱、要防刷、要在数据库故障时不丢状态、要保证确认和退订链接重复点击不出错。这套流水线覆盖从表单到回执的完整链路。 架构与关键决策 表单 → POST /api/subscribe（校验+限流） → subscription-store（pending 记录，MySQL 权威存储） → 确认邮件（token 链接）→ /api/subscribe/confirm → active / 退订 → unsubscribed 后台：周报预览（/admin/weekly-digest）→ POST /api/admin/weekly-digest 投递 → email provider adapter（console | http-api）→ 投递记录 + 回执 双阶段确认（double opt-in） ：提交只产生 pending ，邮箱点击确认后才 active ——防止把别人邮箱填进列表。 状态机九态 ： pending / confirmed / already-active / unsubscribed / already-unsubscribed / expired / invalid / conflict / rate-limited ，公开响应不返回 token 本体，确认与退订幂等（重复点击返回同型结果，不重复变更）。 fail-closed 存储保护 ：生产缺少 DATABASE URL 时禁止订阅写入而非静默落内存；开发态内存存储与 MySQL 存储共用同一接口层（ subscription-store ）。 可插拔邮件 adapter ： console （沙箱打印）与 http-api （配置化外呼）两种 provider；发送开关默认关闭，投递记录表保存每封的状态、失败原因与最多 3 次的有限重试，周期幂等防同一周重复群发。 限流按 IP+账号维度 ，10 分钟窗口 5 次，429 响应携带可渲染文案。 难点与处理 1. 错误语义透传 ：服务故障（503）与输入错误（400）不能共用一套前端文案——接口为每个失败分支返回独立 state + message ，前端优先渲染服务端 message（详见踩坑《订阅接口 503 被前端翻译成了\"邮箱格式不对\"》）。 2. 无 JS 路径可用 ：表单原生 POST 提交到同一端点，服务端 303 重定向到带状态参数的结果页，JS 版只是把反馈前置为行内提示（详见文章《渐进增强不是口号》）。 3. 数据迁移安全 ：订阅表走版本化 migration（ schema migrations + advisory lock + checksum），已在 staging 完成备份/隔离库恢复演练。 当前状态与边界 已完成：全链路沙箱闭环、migration 与恢复演练、provider adapter 与投递记录。 待完成：staging 真实发送回执验证与生产部署验收（受外部授权阻塞）。系统在所有未验证环节均选择显式失败而不是模拟成功。 下一步 真实 SMTP 验证通过后接入 bounce 处理回调；订阅统计看板增加按主题的确认率视图。", "date_published": "2026-09-03T00:00:00.000Z", "date_modified": "2026-09-03T00:00:00.000Z", "tags": [ "Node.js", "MySQL", "订阅", "邮件投递" ] }, { "id": "https://kairos.cn.mt/posts/accessibility-automated-assertions/", "url": "https://kairos.cn.mt/posts/accessibility-automated-assertions/", "title": "无障碍不是一次审计，是一串可自动化的断言", "summary": "把键盘可达、焦点可见、对比度、live region、reduced-motion 从\"上线前人工点一遍\"变成可回归的自动化检查清单。", "content_text": "无障碍审计最大的敌人不是\"不知道标准\"，而是 一次性 ：上线前请人点一遍、修一轮、三个月后新功能把老问题全带回来。解药和所有工程问题一样——把要求翻译成能进 CI 的断言。 分层：哪些能自动查，哪些必须人看 | 层 | 工具 | 能覆盖 | 不能覆盖 | | -------- | --------------------------------------------------- | ------------------------------------- | -------------- | | 静态规则 | axe-core / eslint-plugin-jsx-a118 / Lighthouse a11y | 缺 label、role 误用、对比度、landmark | 交互流是否合理 | | 键盘行为 | Playwright 驱动 | Tab 顺序、焦点陷阱、Esc、方向键 | \"好不好用\" | | 视觉偏好 | 媒体特征模拟 | reduced-motion 全静态、强制色彩 | 主观可读性 | | 读屏实测 | 人工（NVDA/VoiceOver） | 语义是否\"听起来对\" | 无法自动化 | 自动化吃下前三层，人只负责第四层——这是个人站点也养得起的分工。 五条最值得固化的断言 1. 键盘可达核心流 （每页模板化）： await page.keyboard.press('Tab'); // skip-link 第一站 // 断言：纯键盘完成 搜索→选结果→进入详情 const focusables = await page.evaluate( () => [ ...document.querySelectorAll( 'a,button,input,select,textarea,[tabindex=\"0\"]', ), ].filter((el) => el.offsetParent !== null).length, ); 2. 焦点永远可见 ：全站禁止\"只有颜色变化\"的 focus 态——断言自定义控件存在 :focus-visible 规则且伴随非颜色信号（outline/border/背景差）： const outline = await page.evaluate(() => { const el = document.activeElement; return getComputedStyle(el).outlineStyle; // 期望非 'none'，或 box-shadow/背景有可辨变化 }); 3. 模态必带焦点管理 ：每个弹层三条断言——打开后焦点在弹层内、Tab×N 不逃逸、关闭后回到触发元素。这三行是回归事故（焦点丢失到 body、Tab 掉进已卸载按钮）的捕获器。 4. 状态播报 ：一切\"结果会异步变化\"的区域必须有 live region： const live = await page.evaluate(() => [...document.querySelectorAll('[aria-live]')].map((n) => n.id), ); // 搜索计数、提交结果、成就解锁 → 断言注册在列 5. reduced-motion 全静态且信息不减 ：启动 reducedMotion: 'reduce' 的 context，逐页断言：无 running 动画、所有 [data-scroll-reveal] 内容可见、动画承载的状态仍有文本/颜色替身。本项目用 13 项检查把六页跑成了一条命令。 把颜色对比度变成数值而不是感觉 深色主题的对比度问题肉眼不可靠（显示器亮度、环境光都在骗人），交给计算——Lighthouse a11y 满分时它内置的 color-contrast 规则已经逐元素核过一遍。把 --lhci 纳入发布流程，等于免费雇了一个对比度审计员；一次真实修复（全局 a{color:inherit} 压过按钮文字色导致 1.73:1）就是它抓出来的。 反模式清单（规则能查的） ：没有键盘语义——要求交互节点是 button/a 或显式补 role + tabIndex + keydown ； 图标按钮无文本：必须有 aria-label 或视觉隐藏的文本子节点； 只用颜色传达状态：错误=红、成功=绿之外必须有图标/文本； aria-hidden 的容器里残留可聚焦元素：等于给键盘用户造黑洞——隐藏需连 inert/tabindex=-1 一起。 流程建议 1. 每个新交互组件的 PR 附\"上表五条断言\"中适用的行（写进组件模板，让复制测试比跳过测试容易）； 2. CI 跑静态规则 + 关键页 reduced-motion； 3. 发布前全量跑一遍带 Lighthouse 的门禁； 4. 每季度人工读屏一次核心流——这一项接受无法自动化的事实。 小结 无障碍的质量不取决于你懂多少 ARIA 规范，而取决于 三个月后新功能进来时，老规矩还在不在 。把标准翻译成断言，是把个人意志变成系统能力——键盘用户、读屏用户、对动效敏感的用户，从此不再依赖任何人\"记得\"测试。", "date_published": "2026-09-02T00:00:00.000Z", "date_modified": "2026-09-02T00:00:00.000Z", "tags": [ "可访问性", "测试", "键盘导航", "ARIA" ] }, { "id": "https://kairos.cn.mt/posts/animation-compositor-performance/", "url": "https://kairos.cn.mt/posts/animation-compositor-performance/", "title": "让动画跑在合成层：transform/opacity 与 layout thrash 的边界", "summary": "前端动效性能的核心是只动 GPU 能独立处理的属性。讲清 transform/opacity 为何安全、哪些属性会触发布局重排、以及读写分离避免强制同步布局。", "content_text": "流畅动画的差别不在用了多少特效，而在每一帧浏览器被迫做多少工作。理解渲染管线，就能预判一个动画是 60fps 还是掉帧。 浏览器渲染四步 JS → Style（计算样式）→ Layout（几何位置）→ Paint（填色）→ Composite（合成上屏） 每帧重跑代价递减：Layout 比 Paint 贵，Paint 比 Composite 贵。理想动画只走最后一步—— Composite ，因为合成由 GPU 处理，主线程几乎不参与。 只有 transform 和 opacity 能\"只合成\" 改动 transform （translate/scale/rotate）和 opacity 时，元素已被提升为独立合成层，浏览器只需重新合成， 跳过 Layout 与 Paint ： .card-enter { transform: translateY(0.75rem); opacity: 0; } .card-enter-active { transform: translateY(0); opacity: 1; transition: transform 220ms cubic-bezier(0.22, 1, 0.36, 1), opacity 220ms; } 而下面这些属性每变一次都会触发昂贵的重排或重绘： | 动画属性 | 触发的最贵阶段 | | --------------------------------------------------------- | -------------- | | top/left/right/bottom 、 width/height 、 margin/padding | Layout | | box-shadow 、 filter: blur() 、 background | Paint | | font-size 、 line-height | Layout | 同样\"上浮淡入\"，用 top 位移是每帧 Layout + 父级重排，用 transform 是纯合成——这就是为什么动效规范里写\"位移一律 translate，不用 top\"。 会触发 Layout 的\"隐形雷区\"：JS 读几何 即使动画只用 transform，如果在 scroll / resize 回调里 同步读取几何属性再立刻写入 ，会触发\"强制同步布局\"（layout thrash）： // 反面：每个元素读一次 offsetTop 写一次 style，读被写强制刷新布局 → N 次重排 items.forEach((el) => { el.style.transform = translateY(${el.offsetTop}px) ; }); 读写分离 ：先批量读，再批量写： const tops = items.map((el) => el.offsetTop); // 只读一次布局 requestAnimationFrame(() => { items.forEach((el, i) => { el.style.transform = translateY(${tops[i]}px) ; }); // 集中写 }); 高频事件（scroll）里还应加节流——用 requestAnimationFrame 把多次事件合并到一帧更新一次，而不是每个事件都读写。 will-change：用对是加速，用满是负债 will-change: transform 提前把元素提成合成层，动画开始前给一帧提示有益。但它有内存代价（每层独立纹理），滥用会让 GPU 内存吃紧、移动端反而更卡。原则： 只在 即将动画 的元素上加，动画结束后移除； 不要给大量列表项同时常驻 will-change ； 揭示完成后释放： el.dataset.revealed && el.style.willChange = 'auto' 。 box-shadow / filter 的光晕怎么办 光晕动效常需 box-shadow 过渡，而它是 Paint 级。折中： 静态光晕用 box-shadow （不变就不重绘）； 需要\"发光呼吸\"时用叠加一个 opacity 动画的伪元素层，把 Paint 转成合成—— ::after 画好阴影，只动它的 opacity 。 用 reduced-motion 兜底性能与体验 无论动画多便宜，都要尊重 prefers-reduced-motion ： @media (prefers-reduced-motion: reduce) { { animation-duration: 0.001ms !important; transition-duration: 0.001ms !important; } } 这既是无障碍要求（前庭功能敏感用户），也是低端设备的事实降载。 小结 动效性能的功课就三条：只动 transform/opacity 、读写分离不制造强制同步布局、 will-change 点到为止。把这三条内化成肌肉记忆，比事后拿性能面板逐帧救火省力得多。", "date_published": "2026-09-02T00:00:00.000Z", "date_modified": "2026-09-02T00:00:00.000Z", "tags": [ "性能", "动效", "渲染", "CSS" ] }, { "id": "https://kairos.cn.mt/posts/article-image-lazy-load/", "url": "https://kairos.cn.mt/posts/article-image-lazy-load/", "title": "文章页图片的懒加载与淡入：不制造布局偏移的做法", "summary": "正文图片用 loading=lazy + decode=async 延迟解码，配合占位尺寸与淡入，兼顾性能与体验，并处理失败与 reduced-motion。", "content_text": "文章里一张大图，处理不好就是 LCP 杀手 + CLS 元凶。好消息是：绝大多数收益靠几行\"该加的加上、该设的设对\"就能拿到。 基线三件套 \"架构示意图\" width/height （或 CSS aspect-ratio ）是防 CLS 的第一功臣 ——浏览器据比例预留占位空间，图片加载完成不撑动版面。缺尺寸的图是内容站最常见的布局偏移来源。 loading=\"lazy\" ：离视口远的图不请求。 首屏 LCP 图千万别加 ——懒加载会延迟它自己的加载，把最大内容元素推后。判断标准：位于首屏折叠线以上的第一张图，用 loading=\"eager\" 甚至 fetchpriority=\"high\" 。 decoding=\"async\" ：解码移出主线程，避免大图解码卡顿交互。 CSS 侧兜住尺寸 属性宽高会被样式覆盖，用 CSS 强制保持比例、限制不溢出容器： .article-content img { max-width: 100%; height: auto; aspect-ratio: attr(width) / attr(height); / 现代浏览器据属性自动推比例，这行作显式保险 / } 实际现代浏览器已由 width/height 属性自动推 Aspect Ratio，CSS 这行更多是\"确保不被某处 height: auto 之外的规则破坏\"。 淡入：锦上添花但要处理边界 想给图片加\"加载完成淡入\"，务必处理三种\"到不了 loaded\"的情况，否则图会永久隐身： function enhance(img) { if (matchMedia('(prefers-reduced-motion: reduce)').matches) return; // 直接可见 if (img.complete && img.naturalWidth) return; // 已缓存：不淡入，直接显示 img.dataset.reveal = 'pending'; const reveal = () => { img.dataset.reveal = 'done'; cleanup(); }; const fail = () => { img.dataset.reveal = 'done'; cleanup(); }; // 加载失败也要可见（别留隐藏态） const cleanup = () => { img.removeEventListener('load', reveal); img.removeEventListener('error', fail); }; img.addEventListener('load', reveal); img.addEventListener('error', fail); } [data-reveal='pending'] { opacity: 0; } [data-reveal='done'] { opacity: 1; transition: opacity 400ms ease; } 三个边界对应三条教训： 1. reduced-motion 用户跳过淡入，直接可见； 2. 命中缓存的图 complete=true ， load 事件不会再触发——不判断就会卡在 pending 永久透明； 3. 加载 失败 也必须解除隐藏——否则一张 404 图变成一块永远空白的隐形坑（比显示破图标更糟）。 客户端路由下还要在换页时移除这些 load/error 监听，避免泄漏。 响应式与格式 需要真响应式尺寸时用 srcset/sizes ，让浏览器按 DPR 与视口挑选； 截图/图表类优先 WebP/AVIF（带 type 的 或 srcset 回退）； 装饰性图 alt=\"\" （不是省略 alt），信息性图 alt 描述内容而非文件名。 小结 图片优化的收益顺序很明确： 设尺寸防 CLS > 别懒加载 LCP 图 > 异步解码 > 现代格式 > 淡入动效 。前四条是纯工程正确，最后一条是体验糖——而糖必须把\"缓存/失败/减弱动效\"三个苦口处理掉，才不会变成新 bug。", "date_published": "2026-09-02T00:00:00.000Z", "date_modified": "2026-09-02T00:00:00.000Z", "tags": [ "图片优化", "性能", "CLS", "动效" ] }, { "id": "https://kairos.cn.mt/posts/clipboard-api-failure-feedback/", "url": "https://kairos.cn.mt/posts/clipboard-api-failure-feedback/", "title": "剪贴板 API 的现实：安全上下文、权限与失败反馈", "summary": "navigator.clipboard 在非 HTTPS、无焦点、权限拒绝下的行为差异，以及为复制按钮补齐成功与失败双反馈的实践模式。", "content_text": "\"点击复制\"是工具页和代码块上最不起眼、也最容易做错的功能。做错的常见姿势是：只处理了成功。 三条铁律 navigator.clipboard.writeText() 只在以下前提成立时存在且可用： 1. 安全上下文 ：HTTPS 或 localhost 。 http:// 局域网 IP 访问时 navigator.clipboard 干脆是 undefined 。 2. 文档获得过用户手势 ：多数浏览器要求调用栈可以追溯到一次真实点击/按键，脚本自动触发会被拒绝。 3. 权限与焦点 ：页面不可见或用户在权限策略中拒绝了剪贴板写入时，Promise 以 NotAllowedError 拒绝。 任何一条不满足， clipboard API 路径就走不通——所以复制功能必须有\"失败也要被说出来\"的设计。 失败反馈是最常被遗漏的分支 一个真实做对的复制按钮应当区分三种结果： const copyText = async (text, button) => { const label = button.querySelector('[data-label]'); const original = label.textContent; try { if (!navigator.clipboard?.writeText) { throw new Error('insecure-context'); } await navigator.clipboard.writeText(text); label.textContent = '已复制'; button.classList.add('is-copied'); } catch { // 关键分支：不假装成功 label.textContent = '复制失败，请手动选择复制'; } finally { window.setTimeout(() => { label.textContent = original; button.classList.remove('is-copied'); }, 1600); } }; 两个细节： is-copied 的视觉反馈只在成功路径加上 ；失败时用文案差异即可，不要让失败看起来像成功。 定时器要记账 。若页面跑在客户端路由下（脚本体会重新执行），保存这些 timeout 并在换页前清除，否则残留回调会写进已经卸载的 DOM——这是动效批次的复盘教训在复制组件上的重演。 旧世界：execCommand 与 textarea 兜底 document.execCommand('copy') 早已废弃，且在现代浏览器中同样受权限约束，只是报错方式更暧昧（返回 false ）。它唯一还值得存在的理由是非安全上下文的兜底： const legacyCopy = (text) => { const area = document.createElement('textarea'); area.value = text; area.setAttribute('readonly', ''); area.style.position = 'fixed'; area.style.opacity = '0'; document.body.append(area); area.select(); const ok = document.execCommand('copy'); area.remove(); return ok; }; 先试 async API、失败再落 legacyCopy 、两条路都不通才提示手动复制——三层漏斗能让绝大多数用户拿到内容，同时保留诚实的兜底话术。 读剪贴板是另一回事 readText() 的权限模型严格得多（通常要求用户显式手势 + 权限弹窗），粘贴类工具（JSON 校验器、diff 对比器）应当提供\"手动粘贴\"输入区作为一等公民，把\"一键读取剪贴板\"当作锦上添花的快捷路径，而不是唯一入口。 反馈动效的克制 复制成功的动画（短脉冲、像素星星之类）适可而止：一次性、≤1 秒、可被 prefers-reduced-motion 完全关闭，关闭后文本反馈\"已复制\"依然在场。动画是强调，不是信息载体本身。 小结 剪贴板功能的质量不在\"能不能复制\"，而在 不能复制的那一刻你说了什么 。给失败一个准确、可操作的出口（选中手动复制的提示），比在成功时多放一颗星星更能建立信任。", "date_published": "2026-09-02T00:00:00.000Z", "date_modified": "2026-09-02T00:00:00.000Z", "tags": [ "浏览器 API", "剪贴板", "安全", "交互细节" ] }, { "id": "https://kairos.cn.mt/posts/command-palette-accessibility-checklist/", "url": "https://kairos.cn.mt/posts/command-palette-accessibility-checklist/", "title": "一个可访问的命令面板：从快捷键到焦点管理的全清单", "summary": "实现 Ctrl/Cmd+K 命令面板时的键盘协议、combobox 语义、焦点陷阱与恢复、移动端适配和加载态处理的完整检查清单。", "content_text": "命令面板是\"高级感\"功能里最容易做出形、丢出神的：视觉上一眼像模像样，键盘用户却在三米外迷路。本文把验收一个命令面板需要过的问题列成清单，每一条都对应真实实现过的代码。 1. 唤起与关闭 快捷键： Ctrl/Cmd + K 全局监听；在 input/textarea/[contenteditable] 聚焦时不劫持其它单键快捷键。 关闭途径必须至少三条： Esc 、遮罩点击、显式关闭按钮。面板内的按钮不要用 tabindex=\"-1\" 把自己藏起来。 关闭时清理：移除焦点圈监听、恢复 body 滚动锁、移除临时 toast。 2. 语义：dialog + combobox 两层结构 外层面板是模态：