用iframe嵌入sdk示例页最稳妥，可隔离跨域、执行时机和样式污染问题；src须为同源html文件，通过url参数传参，加title提升可访问性，用defer或es module确保dom就绪后执行，样式加命名空间前缀，iframe需设sandbox属性。
用 iframe 嵌入 SDK 示例页最稳妥
直接在文档页里跑 SDK 示例，最容易遇到跨域、执行时机、样式污染三连问题。别硬扛，用 iframe 隔离是最小代价的解法。
常见错误现象：ReferenceError: SDK is not defined、按钮点击无反应、UI 错位、控制台报 Blocked a frame with origin ... from accessing...。
-
iframe的src必须是同源 HTML 文件（比如./examples/init.html），不能是 data URL 或 inline HTML - 不要用
document.write动态写入示例代码——它会清空整个页面上下文 - 若需传参（如测试不同
appId），用 URL 查询参数传递，示例页内用new URL(window.location).searchParams.get('appId')读取 - 给
iframe加title属性，满足基础可访问性要求
script 标签的 defer 和 async 别乱配
SDK 初始化逻辑依赖 DOM 就绪，但又不能阻塞页面渲染。新手常把 async 一加了事，结果 init() 执行时 document.getElementById('container') 还是 null。
Article To Html
下载
文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。
- 如果 SDK 提供了模块化入口（如
import { init } from './sdk.js'），优先走 ES Module +type="module"，天然支持延迟执行 - 否则用
defer：它保证脚本按顺序下载、DOM 解析完后执行，适合依赖 DOM 的初始化 -
async只适用于完全独立的埋点或上报脚本，和 UI 绑定的 SDK 不适用 - 务必检查 SDK 文档是否要求放在
还是底部——有些老 SDK 会直接操作document.body
示例页里模拟真实调用场景，不是罗列 API
新手看文档最怕“调用 showModal() 即可”，结果粘贴过去报错。示例页要还原真实链路：加载 → 配置 → 就绪回调 → 用户触发。
<script>
// 正确示范：等 SDK 就绪再绑定事件
window.SDK_READY = false;
window.addEventListener('SDK_LOADED', () => {
window.SDK_READY = true;
});
document.getElementById('btn').addEventListener('click', () => {
if (!window.SDK_READY) return;
SDK.showModal({ title: '测试弹窗' });
});
</script>
- 避免在
DOMContentLoaded里直接调用 SDK 方法，除非文档明确说“同步可用” - 所有示例必须带错误兜底：
try/catch或检查typeof SDK.showModal === 'function' - 配置项用真实值（如
appId: 'test-123'），别写YOUR_APP_ID占位符——新手真会复制粘贴然后卡住 - 每个示例页只做一件事：一个功能点、一种参数组合、一次用户交互
CSS 隔离不靠 scoped，靠命名空间前缀
SDK 自带 UI 组件（如弹窗、浮层）很容易被宿主页面 CSS 覆盖，比如全局 button { padding: 0 } 把 SDK 按钮压扁。别指望 <style scoped></style>，它对 iframe 外部无效，且不兼容旧浏览器。
- SDK 内部样式必须用强选择器前缀，例如
.sdk-modal .sdk-btn，禁止裸写.modal或button - 示例页自身样式也加前缀（如
.demo-page-header），避免和 SDK 样式冲突 - 用
all: initial重置关键继承属性（font-size,color,line-height）比逐个覆盖更可靠 - 如果 SDK 支持主题色配置，示例页要演示如何通过
data-theme="dark"切换，而不是只写 CSS
iframe 缺少 sandbox 属性。哪怕只是本地预览，也该加上 sandbox="allow-scripts allow-same-origin"，否则 Chrome 95+ 会静默禁用 localStorage 和 postMessage——而很多 SDK 初始化依赖它们。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
