开发者文档代码示例与复制契约

大理论

开发者文档的代码块不是装饰性截图，而是用户会执行的界面。一个健康的代码示例要回答：这段代码要解决什么任务、用户应该复制哪一部分、占位符是否安全、当前语言/包管理器如何切换、复制成功或失败如何知道、移动端长命令如何阅读、没有 JS 高亮时是否仍可用。

小知识点

1. 先定义示例任务：安装、鉴权、请求 API、初始化 SDK、处理响应、迁移配置或调试错误；任务不同决定单块、tabs、request/response、diff 或 playground。
2. 代码块要有语言、文件名或上下文标签；YOUR_API_KEY、PROJECT_ID 等 placeholder 必须明显，不用真实 token、客户 ID 或内部 URL。
3. 复制按钮要复制确定的 payload，不应包含行号、shell prompt、视觉标签或意外空白；失败时给手动选择、重试或快捷键路径。
4. 复制状态要有可见文案和 polite live region；不能只用图标颜色表达 Copied/Error。
5. 多语言 tabs 要遵循 APG tabs 语义：tablist、方向键、Enter/Space 激活、active panel 可聚焦；持久化语言偏好时不应让同页其他示例混乱。
6. 代码长行可以局部横向滚动，但页面正文仍应 reflow；320px 宽度、200% zoom 和长 token 要检查 copy button 是否遮挡内容。
7. Shiki、Prism、Sandpack 是实现资源，不是完整 UX：高亮器不解决复制、焦点、错误、响应式或授权记录。

设计判断

如果用户能在不猜测的情况下知道复制什么、复制后发生了什么、不同语言如何切换、错误如何恢复，并且移动端不会因为代码块导致整页横向滚动，这个契约成立。若代码只是漂亮卡片、复制按钮无反馈、tabs 只能鼠标用、或 placeholder 像真实 secret，就不应上线。

实现建议

建立 CodeExampleContract：id、title、language、filename、code、copyText、copyLabel、copySuccessText、copyErrorText、lineNumbers、highlightLines、wrapMode、sensitivePlaceholders。React 实现中让复制状态局部化，navigator.clipboard.writeText 必须 catch rejection；失败时显示 fallback。静态代码优先 pre > code，高亮尽量 build/server 渲染；live playground 需要 loading、error、reset、安全边界和性能预算。代码容器设置局部 overflow，页面级容器不能因此 overflow-x 溢出。

反例/风险

复制 shell 示例时把 $ 一起复制；把 API key 写成看似真实的长 token；复制按钮 sticky 到右上角遮住横向滚动条；tabs 没有键盘方向键；Copied 只变绿色；Sandpack playground 加载失败无 fallback；深色代码主题 token 对比过低；在安全上下文外调用 Clipboard API 后静默失败。

案例分析

Mintlify 当前公开文档强调 AI-native documentation、MDX 组件、API playground/manual API pages、docs.json navigation、tabs 和 keyboard-accessible navigation。设计推断：这种文档平台的首屏和正文都应把搜索、侧栏、当前文章、代码示例、API 调用和 AI answer 入口视为同一个阅读/执行系统。代码块的价值不在拟物卡片，而在让开发者从阅读到复制、切换语言、调用 API、处理错误的路径保持连续。

来源链接

MDN Clipboard writeText: https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/writeText MDN Clipboard API: https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API MDN pre element: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/pre MDN code element: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/code MDN ARIA live regions: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions WAI-ARIA APG Tabs: https://www.w3.org/WAI/ARIA/apg/patterns/tabs/ WCAG Reflow: https://www.w3.org/WAI/WCAG21/Understanding/reflow.html Shiki: https://shiki.style/ Prism: https://prismjs.com/ Sandpack: https://github.com/codesandbox/sandpack Mintlify docs: https://www.mintlify.com/docs