思源笔记 HTML 嵌入：3 个能点、能看的玩法

思源笔记 HTML 嵌入：3 个能点、能看的玩法

【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间，让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan

上周整理周会纪要，我总想给行动项加一排"点一下就算完成"的勾选框，纯文本待办做不到。翻了翻文档才发现，思源笔记 HTML 嵌入 这条路是通的——在笔记里直接写 HTML，编辑器会把它渲染成能点的界面，而不是显示成一堆源码。这篇文章把我实际试过的路径记下来，从最简卡片到几个真正好用的交互，以及我踩过的坑。

先弄懂它是什么：写在笔记里的"活"代码

一句话：在文档里直接写标准 HTML 和 CSS，编辑器会把它们渲染成真实元素，而不是显示源码。类比一下，它相当于给静态 Markdown 开了一扇小窗——窗里可以放按钮、卡片、折叠面板这类轻交互内容，所见即所得。

边界要划清楚。适合：临时美化、单页展示、点按反馈这类不需要记住状态的小需求；把第三方页面嵌进来当快捷入口。不适合：需要持久保存数据、跨笔记共享状态的应用。这些需求请用原生功能块，HTML 块里的改动一旦刷新就回到你写的样子，它不是数据库。

粘贴、看到、改完：三步走通

最省事的路径是"粘贴 → 渲染 → 微调"：把代码直接输入或粘贴进文档，编辑器识别后自动把它当作独立内容块渲染；改几个字就即时生效，不用保存也不用重新构建。先拿一个最简卡片开刀：

<div style="background:#f6f7f9;padding:14px 16px;border-radius:8px;max-width:420px;"> <strong>周会纪要 · 行动项</strong> <p style="margin:8px 0 0;color:#555;">负责人：小李 ｜ 截止：本周五</p> <button onclick="this.textContent='已确认'" style="margin-top:10px;padding:4px 12px;border:none;border-radius:4px;background:#4a6fa5;color:#fff;cursor:pointer;">确认收到</button> </div>

粘贴完成后，文档里会出现一块带浅灰底、圆角阴影的卡片，按钮可以点，文字可以直接编辑。我试了一下，改background里的颜色值后卡片底色立刻变化，不用做任何额外操作。

如果要把第三方服务嵌进来，思路一样：SiYuan 里有专门的嵌入块语法，指向另一篇只放 iframe 的笔记即可。这样第三方内容就成了一个可管理、可移动、可删除的块：

<iframe src="https://example.com/embed" width="100%" height="320" style="border:0;border-radius:8px;"></iframe>

三个值得试的玩法

能点的待办清单

场景：周会行动项希望勾选后有直观反馈，但不想为此搭一套应用。核心是一行内联事件，勾选即划线、取消即还原，刷新后回到未勾状态，够用就行。

<ul style="list-style:none;padding:0;font-size:14px;line-height:2;"> <li><input type="checkbox" oninput="this.nextElementSibling.style.textDecoration=this.checked?'line-through':'none';this.nextElementSibling.style.opacity=this.checked?'.55':'1'"> <label style="margin-left:8px;cursor:pointer;">输出接口文档初稿</label></li> <li><input type="checkbox" oninput="this.nextElementSibling.style.textDecoration=this.checked?'line-through':'none';this.nextElementSibling.style.opacity=this.checked?'.55':'1'"> <label style="margin-left:8px;cursor:pointer;">同步进度给测试组</label></li> </ul>

效果：点击文字前的方框，对应条目划线并变淡，视觉上就是"已完成"，无需任何外部依赖。

一排数据速览卡

场景：月报开头想横着摆几个关键指标，原生表格做不到卡片式布局。这段纯 CSS flex 布局，思源笔记自定义样式 到这一层面完全够用：

<div style="display:flex;gap:10px;"> <div style="flex:1;background:#eef4fb;border-radius:8px;padding:12px;"><strong style="font-size:20px;">128</strong><span style="color:#555;">本月新增笔记</span></div> <div style="flex:1;background:#eefbf0;border-radius:8px;padding:12px;"><strong style="font-size:20px;">36</strong><span style="color:#555;">完成待办</span></div> <div style="flex:1;background:#fbf3ee;border-radius:8px;padding:12px;"><strong style="font-size:20px;">7h</strong><span style="color:#555;">日均专注</span></div> </div>

效果：三张并排小卡随窗口宽度自适应伸缩，换数字、换配色都是改几个值的事。

不写 JS 的折叠面板

场景：长文档里的常见问题、补充说明，希望默认收起。这个思路最讨巧——<details>是浏览器原生折叠元素，零 JavaScript，兼容性反而最好：

<details style="border:1px solid #ddd;border-radius:8px;padding:10px 14px;"> <summary style="cursor:pointer;font-weight:600;">常见问题：嵌入的第三方内容离线还能看吗？</summary> <p style="margin:8px 0 0;color:#444;">依赖网络的 iframe 内容在断网时会显示空白，本地样式卡片不受影响。</p> </details>

效果：点标题行展开/收起整段说明，适合做 SiYuan 交互笔记 里的"延伸阅读"或 FAQ 区块。

它是怎么工作的

不用看代码也能说清核心思路。思源笔记把每段 HTML 都当作一个独立内容块来管理，块有自己的身份和可编辑属性，这一点和标题、表格块没有本质区别。渲染时，编辑器先按块类型分发：嵌入块会先套上统一的容器样式，再执行后续管线——代码高亮、公式渲染、块属性视图依次处理，最后才把内容挂进页面。顺序上是"先包裹、后渲染"，好处是嵌入块内部如果有代码或公式，也能被后续管线正确识别；代价是它遵循块的通用规则，不能为某一段 HTML 单独定制渲染逻辑。另一个值得知道的细节：嵌入块可以嵌套，最多四层，再深就停止递归，这是防止循环引用把编辑器卡死的保险丝。想追细节的话，延伸阅读 app/src/protyle/render/blockRender.ts，它负责整条嵌入渲染链路。

容易踩的坑 & 推荐做法

问题：两段 HTML 里的按钮"串台"。原因：同页多块 HTML 若用了相同id，事件和样式都会互相命中。 解法：给不同块的元素 id 加块主题前缀，比如faq1-title、faq2-title；样式尽量内联，少依赖全局 id 选择器。

问题：嵌了三个 iframe 之后长文档开始卡。原因：每个 iframe 都是独立文档，加载、滚动都会吃资源。 解法：同一笔记里 iframe 控制在两三个以内；重内容拆到独立笔记，再用嵌入块引过来。笔记嵌入第三方内容 时优先选轻的静态页。

问题：桌面端好好的样式，手机上看走样。原因：移动端 WebView 对部分 CSS 特性的支持不一致，尤其是较新的布局属性。 解法：核心内容降级为纯样式展示，交互留给桌面端；关键数据另存一份表格块，保证任何端都读得到。

问题：导出成 PDF 或 Markdown 后，按钮不能点了。原因：交互能力只存在于编辑器运行时环境，导出产物只保留结构和样式。 解法：HTML 块只当"展示层"，真正重要的数据放表格或原生块里，导出不会丢。

收尾

先拿临时文档把交互调顺，再贴进正式笔记——比直接在生产环境试错省事得多。更多细节可以看官方 API 文档 docs/API.zh-CN.md，以及仓库内的更新日志 CHANGELOG.md。

【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间，让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan