Skip to content

dsh-notes v0.8.0 — 网页演示:笔记里就地跑可交互 HTML

Latest

Choose a tag to compare

@Phy-D Phy-D released this 03 Nov 14:45
· 4 commits to master since this release

v0.8.0 — 网页演示:笔记里就地跑可交互 HTML(2026-11-03)

动机

笔记里一直只能指向一个 HTML 演示(写个链接,点开去浏览器看),而这类东西的意义就在
"拖一下、看它变" —— 离开笔记、切窗口、再切回来,理解成本全在切换上。用户原话:
「就是插入 html 的网页演示……让网页能够在笔记里面直接显示,而不仅仅是插入路径」。

新功能

  • ```embed <路径> 围栏 → 就地沙箱 iframe:脚本真的执行(用户在 Analog IC 的
    三电平 SAR 演示上验收:拖 ΔV 滑块,图跟着变)。路径相对笔记目录解析;也可写
    title: / height: 两行配置(path: / src: 同义),高度 160–2400、默认 560。
  • 底边拖拽调高度,按文件记在 localStorage['dsh-notes:embed-size'](最近 200 条),
    重开笔记仍是上次的高度;拖完不会因为"点了下别处"就把 iframe 重载。
  • 条上三枚按钮:「源码」(光标回到围栏)、「刷新」(带 nonce 重载)、「在新标签打开」
    (仅 http(s) 载体;桌面壳的自定义 scheme 下不显示)。
  • 工具栏 21 → 22 键:插入组新增「插入网页演示」;右键「插入」子菜单同步加一条。
  • 光标进入围栏 → 显示原始 markdown(与代码卡一致);移开 → 恢复 iframe。

安全模型(这是本版最需要知道的)

  • 服务端是插件自己的 GET /dsh-notes/embed,不是官方 /api/file:后者响应头是
    Content-Security-Policy: sandbox; default-src 'none',HTML 进 iframe 后脚本/样式全被禁,
    做不出交互。
  • 响应头 EMBED_CSP:sandbox(不带 allow-same-origin)+ 放行内联脚本/样式 + 断网
    (default-src 'none' / connect-src 'none')+ nosniff / no-referrer / no-store。
    于是演示页拿不到 parent.document、document.cookie、localStorage,也发不出网络请求 ——
    演示页必须自包含(内联 CSS/JS、data: 图片;CDN 与相对资源都不行)。
  • 读取边界 = 当前工作区(笔记面板可切到别的已登记工作区,所以 workspaceKey 一路从面板传到
    路由);两边都用 fs.processPath 的 realpath 派生路径比对,挡 .. 与符号链接逃逸;
    只认 .html/.htm,单文件上限 8MB。越界/非 HTML/缺失/超限在 iframe 里显示可读的错误页,
    而不是一坨 JSON。
  • 配置 htmlEmbed(默认 true):关掉 = 该路由一律 403 错误页,其他功能不变。

实现要点(给后来改这块的人)

  • 块级替换只能在 table.ts 的 StateField 里做,且围栏要独占整行(被 > 引用/列表包住的
    退回代码卡)。EmbedWidget.eq() 刻意不比 from(否则在块上方打字就重载 iframe)、也
    不比"算出来的初始高度"(拖拽只改 localStorage),位置用 view.posAtDOM(root, 0) 现取。
  • 纯逻辑独立成 embed-model.ts(解析/路径/URL/高度夹取)与 embed-size.ts(高度记忆),
    在 Node 里可测;Host 侧 service.readEmbed(只读,readBytes 缺失时退化 readText)。
  • 新增单测:317 条全绿(新增 embed-model / embed-size / service-embed,并扩了 routes
    与 locale-guard)。

已知边界(不是 bug)

  • 演示页滚出视口再滚回来,iframe 会被 CM6 重建、演示状态重置(没有做 keep-alive);
  • iframe 获得焦点时编辑器快捷键不生效(点回正文即恢复);滚轮在 iframe 上滚的是演示页;
  • 只支持自包含页面;需要 CDN / 相对资源 / 联网的演示,请用「在新标签打开」或直接在浏览器里看。

本次 Release 同时纳入此前未单独发版的 v0.7.1 / v0.7.2 / v0.7.3(公式字体、外部改动不丢位置 + 图片预留尺寸、历史兜底覆盖 notes/ 之外)——对应 CHANGELOG 里的同名段。