Electron-OH 鸿蒙实战:截图里的字看不清——一个事件委托的全屏图片查看器

320px 的预览上限把一张代码截图压成蚂蚁字、240px 的附件预览把长图截成一条、点一下图片想看原图却什么都没发生——这篇文章用一个跑在鸿蒙 2in1 真机上的 Electron 笔记应用,把「尺寸策略、事件归属、全屏遮罩、关闭判定」这四件事一次讲透。

欢迎加入开源鸿蒙PC社区:https://harmonypc.csdn.net/
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper

0. 环境与实测设备

项版本/型号
设备HarmonyOS 2in1(aarch64),平板与 PC 形态共用一套窗口布局
目标 SDKHarmonyOS 6.0.0,API 20(compatibleSdkVersion: "6.0.0(20)",runtimeOS: "HarmonyOS")
开发工具DevEco Studio 6.0.0(与 6.0.0(20) SDK 配套),命令行构建走 hvigorw
构建工具hvigor modelVersion 5.0.0,hvigorw assembleHap
Electron-OHElectron 40.1.0,Chromium 144.0.7559.76
原生库libelectron.so 186,990,528 字节(约 178.3 MiB),arm64-v8a
前端resfile/resources/app/src/ 下的 index.html / style.css / renderer.js,原生 JS,无框架
应用版本1.0.12(versionCode 1000012);图片尺寸规则在 1.0.8 调整
页面 CSPdefault-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data: http: https:

先把范围钉住:附件怎么进沙箱、attach:id 怎么懒加载、远程图怎么绕防盗链,是前几篇的事。这一篇只回答一个问题——图片已经在页面里了,用户为什么还是看不清,以及点一下之后原图怎么盖上来。整篇文章没有一行原生代码,没有一次 IPC,改的全是渲染层。

1. “把 320 调大不就行了”——这个问题是怎么找上我的

我一开始也以为这是个体力活。用户说截图看不清,我去样式表里找到那条限制,把数字改大,收工。

改之前的规则就两行:

/* style.css - 改之前的尺寸规则(1.0.8 换掉) */
.md-body .md-img { max-height: 320px; }
.preview-img    { max-height: 240px; }

.md-img 是笔记正文预览里的图,.preview-img 是附件面板里点开文件后的图。两个上限的初衷都对:一张 4K 截图直接铺进笔记,会把正文挤得没影;附件面板只有 384px 宽,图片不限高会顶穿面板。

问题是这两个数字对"图"一视同仁,而图和人一样,分种类。

第一类,照片和插画,320px 高刚好,扫一眼知道是什么。

第二类,代码截图、终端输出、报错弹窗。用户导入这类图的目的是读字,不是看构图。一张 1920×1080 的截图,在 700px 宽的预览列里被 max-height: 320px 一压,等比缩到 569×320,正文里 14px 的字变成 4px。

第三类,长截图。手机截的聊天记录、网页全文,动辄 1080×6000。它同时受 max-width: 100% 和 max-height: 320px 约束,浏览器为了保持比例,会把整张图缩成 58×320 的一条竖线。注意,max-height 不是裁剪,是缩放——它不会让你看到截图的上半截,而是把六千里长的图整体压进三百二十像素,字直接消失。

真机上用户给我发的对比图很直观:左边是笔记预览,一张接口文档截图缩成巴掌大;右边是他把图存到相册再放大,字清清楚楚。同一张图,同一个屏幕,差别只在容器给不给它高度。

我的第一版改动很符合直觉:把 320 改成 70vh。

窗口内容区 900px 高时,70vh 就是 630px,普通截图确实大了。可长截图还是不行——700px 宽、6000px 高的图,等比之后仍然要被 630px 压成 73px 宽。改完当天晚上,用户又发来一张截图,还是看不清。

第二版才想明白:正文预览和附件面板的约束目标根本不一样。正文是文档流,图片应该按宽度铺满,高度由内容决定,读长图就往下滚;附件面板是浮层,高度有硬上限,不能让一张图把面板撑到屏幕外。于是 .md-img 的 max-height 直接改成 none,.preview-img 留在 70vh。

尺寸解决了一半,另一半是"点开看原图"。

第一版我给每张图单独挂监听:

// renderer.js - 第一版 showPreview() 之后的逐图绑定(已删)
mdPreviewEl.querySelectorAll('img.md-img').forEach((img) => {
  img.addEventListener('click', () => {
    imgViewerImgEl.src = img.src;
    imgViewerEl.hidden = false;
  });
});

第一次进预览能点开。切到另一篇笔记,再切回来,点不动了。勾一个任务复选框,预览重渲染,也点不动了。附件面板里的图更直接——那些 img 是 createElement 出来的,压根没走过这段绑定。

到这里,题目的边界才清楚:这次要解决的不是"图片能不能显示",而是"同一张图片在三种容器里各有各的尺寸上限,而查看原图这件事必须和容器的重渲染解耦"。

拆下来是三件事:

  • 尺寸:正文图按宽度铺满、不限高;面板图用视口高度封顶;
  • 事件:监听器不能挂在那批会被 innerHTML 换掉的节点上;
  • 关闭:遮罩打开之后,用户点哪里算退出,要有明确判定。

下面是干完之后的完整记录,包括我踩的每一个坑。

2. 效果展示:先看图,再讲为什么

按老规矩,先给效果再讲原理。

请添加图片描述

图1 正文长截图:max-height: none 之后,1080px 宽的图在 700px 预览列里等比缩到 700px 宽,高度按原比例展开

图1 里最明显的变化不是"图变大了",是滚动方向变了。以前长截图被压成一条,用户横向看;现在图按宽度铺满,用户纵向滚。这是文档该有的阅读方向。

请添加图片描述

图2 全屏查看器:遮罩 position: fixed; inset: 0; z-index: 9999,原图 max-height: none,超出视口的部分在遮罩内滚动

图2 是这次改动的核心。遮罩把整个视口盖住,图片按原尺寸渲染,只有 max-width: 100% 这一条约束。窗口装不下就滚,不再二次缩小。

请添加图片描述

图3 附件面板:384px 宽的面板 + max-height: 70vh,面板总高度仍受 calc(100vh - 74px) 约束

请添加图片描述

图3 是取舍的结果。附件面板是浮层,不是文档。它可以滚动,但不能因为一张图变成一整屏。70vh 留出了标题栏、面板头和下方列表的位置。

请添加图片描述

图4 关闭提示:#img-viewer.hint::after 固定在底部居中,颜色 rgba(255,255,255,0.65)

图4 这行提示不是装饰。第一次用的人不知道这个黑罩子怎么退出去,尤其是在触屏上——没有 Esc,没有浏览器返回键。一行 12px 的灰字,比任何交互文档都有效。

请添加图片描述

这里每个状态都能对上一条具体的样式或代码:

  • 图能铺满:.md-body .md-img { max-width: 100%; max-height: none; };
  • 图能点:.md-img 和 .preview-img 都加了 cursor: zoom-in,鼠标形态先告诉用户"这个能点";
  • 遮罩能盖住一切:z-index: 9999,压过提醒弹窗的 200、设置面板的 50;
  • 大图能滚:滚动发生在 #img-viewer 自己身上,overflow: auto,不是背后的文档在滚;
  • 关得掉:点遮罩空白、点大图本身,都走同一个关闭分支。

效果部分只交代边界:这几张截图是在 2in1 形态下拍的,窗口宽度接近 1200px。平板竖屏时预览列会窄一些,长截图仍然是按宽度铺满,只是每一屏能看到的字更少。

3. 原理:一次点击在 DOM 里走了哪几步

先把"点击"这件事拆开。

浏览器处理一次点击,顺序是:最内层的元素先收到事件,然后一层一层往上冒泡,直到 document,再往上到 window。e.target 始终是那个最内层的元素,e.currentTarget 是当前正在执行监听器的那一层。

我把监听器挂在 document 上,所以:

  • 用户点在图片上,e.target 是那个 <img>;
  • 用户点在遮罩空白处,e.target 是 #img-viewer;
  • 用户点在大图上,e.target 是 #img-viewer-img;
  • 用户点在按钮、输入框、正文文字上,e.target 是那些元素,两个分支都不命中,函数直接走完。

映射成表:

点击位置e.target命中分支结果
正文图 img.md-img该 img打开遮罩显示,换成原图 src
附件图 img.preview-img该 img打开同上
加载失败块 img.md-img-broken该 img不处理什么也不发生
遮罩空白 #img-viewerdiv#img-viewer关闭hidden = true,清 src
遮罩里的大图 #img-viewer-imgimg关闭同上
页面其他位置任意元素不处理事件正常结束

这张表里最关键的一行是最后一行。事件委托不是"只在图片上生效",它是"在 document 上生效,然后自己筛"。筛的条件写错,就会误伤;筛的条件写全,就只需要一个监听器。

为什么非得是 document?因为这套预览的 DOM 是消耗品。

renderMarkdown() 每次返回一整段 HTML 字符串,showPreview() 用 mdPreviewEl.innerHTML = html 一次性替换。进预览是一次替换,勾任务是一次替换,切换笔记再回来又是一次。替换之后,旧的 <img> 节点全部被丢弃,挂在它们身上的监听器也一起消失。document 不在替换范围里,它从页面加载到关闭一直在。

所以这里有一条模型判断:监听器要挂在"生命周期比内容长"的节点上。 内容可以重建一百次,监听器只挂一次。

第二个原理点在 CSS 的层叠上。

hidden 属性听起来像"隐藏",但它在浏览器默认样式表里只是一条 [hidden] { display: none }。默认样式表属于 UA 来源,优先级低于作者样式。而查看器自己写了 display: flex——作者样式赢了,hidden 就失效了。这就是为什么样式表里必须再补一条:

/* style.css - 图片全屏查看器 */
#img-viewer[hidden] {
  display: none;
}

没有这一条,imgViewerEl.hidden = true 设置了也白设,遮罩永远关不掉。这不是洁癖,是层叠规则在收账。

第三个原理点是 fixed 和滚动的分工。

position: fixed; inset: 0 做两件事:把元素脱离文档流,并让它的包含块变成视口。它不负责"内容超出时怎么办"。图片高度超过视口时,如果遮罩没有 overflow: auto,超出的部分就只是溢出,不会产生滚动条,用户看不到图片下半截。滚动容器必须自己声明。

这三个点——事件归属、层叠归属、滚动归属——决定了后面所有代码的形状。

4. 工程怎么搭:三个文件,二十行 JS

这次改动没有新增依赖,也没有新增文件。全部落在已有的三个渲染层文件里:

web_engine/src/main/resources/resfile/resources/app/
├── main.js                     主进程:窗口、文件、提醒调度
├── preload.js                  contextBridge 暴露 filesApi / winApi / todosApi 等
├── package.json                应用元信息
└── src/
    ├── index.html              唯一页面;查看器容器挂在 </body> 前
    ├── style.css               图片尺寸规则 + 遮罩 + 底部提示
    └── renderer.js             渲染、预览、事件委托(1872–1890 行)

三处改动的职责很清楚:

  • index.html 只提供一个空壳:一个 div#img-viewer,里面一个 img#img-viewer-img,默认 hidden;
  • style.css 负责尺寸和层叠:两种图片类各自的 max-height、遮罩的定位、[hidden] 的兜底、底部提示;
  • renderer.js 负责状态:谁被点、显示什么 src、什么时候关。

没有 IPC。查看器拿到的 src 就是页面上那张图已经在用的 src——可能是 data:image/...;base64,...,可能是 attach: 懒加载回填后的 data URI,也可能是 https:// 远程地址。它不需要知道来源,也不重新读文件。这是这次设计里最省事的一点:放大不产生新的数据,只换一个显示容器。

最小接入只有三步。第一步,HTML 里放壳子:

<!-- index.html - 放在 </body> 前,和 renderer.js 的 script 同级 -->
<div id="img-viewer" hidden>
  <img id="img-viewer-img" alt="">
</div>

第二步,CSS 里放样式(完整版在第 5.5 节)。第三步,JS 里放一个监听器。

要注意 CSP。这个页面的策略是 script-src 'self'、style-src 'self',内联 <script> 和内联 style 都会被拦。所以这段代码不能写成 <img onclick="...">,也不能塞一个 <script>...</script> 进 HTML。要么放进已有的 renderer.js,要么新建一个 viewer.js 用 src 引进来。样式同理,只能进 style.css。

事件契约只有五条:

契约值谁依赖它
遮罩容器#img-viewerJS 显隐、CSS 定位
大图节点#img-viewer-imgJS 换 src 和 alt
可点击类.md-img / .preview-img委托函数识别
排除类.md-img-broken委托函数跳过
提示类.hint::after 文案

只要这五个名字不变,查看器可以整段搬走。反过来,谁改了类名,谁就要回来改这段委托。

这里有一个很容易被忽略的窗口期:hydrateAttachImages() 是异步的。

// renderer.js - hydrateAttachImages()
const imgs = root.querySelectorAll('img[data-attach]');
for (const img of imgs) {
  const r = await filesApi.read(img.dataset.attach).catch(() => null);
  if (r && r.ok && r.file && r.file.base64) {
    img.src = 'data:' + (r.file.mime || 'application/octet-stream') + ';base64,' + r.file.base64;
  } else {
    img.classList.add('md-img-broken');
    img.removeAttribute('data-attach');
  }
}

img 节点先出现在 DOM 里,src 后到。用户如果在这个间隙点一下,t.src 还是空串,委托函数不会打开遮罩——这是对的,因为那时候确实没有图可看。等 IPC 回来、src 填上,同一个节点不需要重新绑定,再点就能开。委托把"节点存在"和"节点可用"这两个时刻解耦了,这是逐图绑定做不到的。

5. 把代码讲透

5.1 一个 document 监听器,接住所有重渲染

完整代码就这一段,十九行:

// renderer.js - 图片全屏查看器(1872–1890 行,原样)
/* ---- 图片全屏查看器:缩略图里文字看不清时,点一下看原图 ---- */

const imgViewerEl = document.getElementById('img-viewer');
const imgViewerImgEl = document.getElementById('img-viewer-img');

document.addEventListener('click', (e) => {
  const t = e.target;
  const isImg = t && t.tagName === 'IMG' && (t.classList.contains('md-img') || t.classList.contains('preview-img'));
  if (isImg && t.src && !t.classList.contains('md-img-broken')) {
    imgViewerImgEl.src = t.src;
    imgViewerImgEl.alt = t.alt || '';
    imgViewerEl.hidden = false;
    imgViewerEl.classList.add('hint');
    imgViewerEl.scrollTop = 0;
  } else if (t === imgViewerEl || t === imgViewerImgEl) {
    imgViewerEl.hidden = true;
    imgViewerImgEl.src = '';
  }
});

场景句先交代清楚:这段代码执行时,页面已经加载完,#img-viewer 和 #img-viewer-img 一定存在,因为 <script src="renderer.js"> 放在 </body> 前,HTML 解析到那里时上面的节点都建好了。不需要 DOMContentLoaded,也不需要空值判断。

三个细节值得单独说:

第一,tagName 是大写。 HTML 文档里 document.createElement('img') 出来的元素,tagName 是 'IMG',不是 'img'。写成小写永远不命中。这个坑很浅,但每次换语言写 DOM 都会再踩一次。

第二,判断用 classList.contains,不用 className.indexOf。 因为一张图可能同时有多个类,比如 md-img 加上后面的 md-img-broken。className 是整串字符串,indexOf('md-img') 会把 md-img-broken 也匹配进去——这正好是我们要排除的那一类。classList 是按 token 比较,不会误伤。

第三,e.target 不需要 closest()。 <img> 是替换元素,不能有子节点,点它的时候 target 就是它本身。只有当你把图片包在 <a> 或 <picture> 里,才需要往上找。现在没有,就不写。

这里有一个反直觉的地方:不要用 e.currentTarget 判断图片。 监听器挂在 document 上,currentTarget 永远是 document,跟点到了谁没关系。判断"点了什么"只能看 target。

降级说明也放在这里。document 级委托有一个前提:图片在同一个文档树里。如果以后把预览搬进 Shadow DOM,点击事件在 document 上看到的是被重定向后的宿主元素,e.target 不再是 img,这段代码会整体失效。真到那一步,监听器要挂在 shadow root 上,而不是 document。现在这套页面没有 Shadow DOM,我不提前付这笔复杂度。

5.2 四个判断:是不是图、是不是业务图、有没有地址、是不是坏图

isImg 这一行看着长,其实是三个条件的与:

// renderer.js - 委托函数里的识别条件(1879 行,原样)
const isImg = t && t.tagName === 'IMG' && (t.classList.contains('md-img') || t.classList.contains('preview-img'));

后面还有一层业务判断:

// renderer.js - 委托函数,打开分支的前置条件(1880 行)
if (isImg && t.src && !t.classList.contains('md-img-broken')) {

拆开看:

  • t && t.tagName === 'IMG':排除所有非图片元素。点到文字、按钮、空白,都在这里被挡掉。
  • md-img || preview-img:只认这两种业务图片。页面里还有标题栏的 logo、按钮里的图标,它们也是 IMG,但不该打开查看器。
  • t.src:没有地址的图不打开。src 为空时,遮罩打开也是一片黑。
  • !md-img-broken:加载失败的图不打开。这一类后面第 6 节单独讲。

三个细节:

第一,类名白名单比"排除法"稳。 我见过用 t.tagName === 'IMG' && !t.classList.contains('tb-logo') 的写法,页面上每加一个图标就要补一条排除。白名单只放行业务图片,新增图标不用改代码。

第二,t.src 读的是解析后的绝对地址。 你写 src="a.png",读出来是 file:///.../a.png 或 app://.../a.png。这对查看器是好事——直接把同一个绝对地址赋给另一个 img,不用关心相对路径的基准。

第三,顺序有讲究。 先判断"是不是图片",再判断"是不是业务图片",最后判断"能不能用"。把 t.src 放到最前面也能跑,但一旦 t 是 document 或文本节点,访问 .src 就是 undefined,虽然不报错,可读性差。先收窄类型,再取属性。

反直觉的地方在于:这里的 isImg 不是为了性能,是为了正确性。 一个页面几十张图,就算逐张绑监听也不会卡。真正的问题是生命周期——重渲染会把节点换掉。委托只是顺带把性能也省了。把动机搞反,就容易在"图不多,随便绑"的侥幸里翻车。

降级说明:classList 在 Chromium 144 上没问题。如果这段代码要被搬到更老的 WebView(比如某些定制浏览器内核),classList 从 IE10 起就有,也不用降级。真正需要降级的是 Element.prototype.closest,但这里没用它。

5.3 打开:三次赋值和一次归零

打开分支只有五行:

// renderer.js - 委托函数,打开分支(1881–1885 行)
imgViewerImgEl.src = t.src;
imgViewerImgEl.alt = t.alt || '';
imgViewerEl.hidden = false;
imgViewerEl.classList.add('hint');
imgViewerEl.scrollTop = 0;

三个细节:

第一,先给 src,再取消 hidden。 顺序反了也能跑,但先设 src 会让浏览器更早开始解码,遮罩出现时图片更可能已经就绪。尤其是 base64 大图,解码不是零成本。这里没有做 await img.decode(),因为那段代码会变成异步,打开手感反而可能更慢;现在这样,先出遮罩再出图,用户能感知到"点到了"。

第二,alt 要跟着走。 查看器里的大图不是纯装饰,它需要同样的替代文本。t.alt || '' 保证空值也安全。屏幕阅读器读到的是原图的描述,不是空字符串。

第三,scrollTop = 0 是必须的。 遮罩是复用的同一个 DOM 节点。上一张长图你滚到了中间,关掉,再点另一张,如果不归零,新图会从中间开始显示——用户以为图缺了一块。这一行把"每次打开都是新的"这件事落实到滚动位置上。

反直觉的点:classList.add('hint') 每次打开都加,但从不清除。 因为提示本来就该一直在,直到遮罩关闭。add 是幂等的,加一百次也只占一个类。如果哪天要做"3 秒后提示淡出",才需要定时器;现在不做,是因为这行提示是关闭方式的唯一说明,撤掉它反而增加困住用户的概率。

降级说明:这段代码没有用 requestAnimationFrame。设置 hidden = false 之后立刻设 scrollTop = 0,浏览器会在下一帧布局时应用。Chromium 144 上实测正常。如果换成某些老内核,遮罩刚显示时还没有布局,scrollTop 赋值会被忽略;真遇到,把它挪进 requestAnimationFrame 里就行。这一条我没在真机上遇到,写在这里备查。

5.4 关闭:为什么点大图本身也算关闭

关闭分支:

// renderer.js - 委托函数,关闭分支(1886–1889 行)
} else if (t === imgViewerEl || t === imgViewerImgEl) {
  imgViewerEl.hidden = true;
  imgViewerImgEl.src = '';
}

三个细节:

第一,t === imgViewerEl 只匹配遮罩本身。 不是 closest('#img-viewer')。closest 会从当前元素往上找,只要点在遮罩里的任何地方都返回遮罩——包括点在大图上。这听起来正好是我们要的,但它也会把以后可能加进来的关闭按钮、图片说明文字一并当成"关闭区域",交互就没法扩展了。精确相等,语义最窄。

第二,t === imgViewerImgEl 是必须补的一条。 因为大图 max-height: none,一张竖图在遮罩里可能占满整个视口,四周没有空白可点。如果只判断遮罩本身,用户点图片,事件目标是 img,不关闭;点边缘,可能只有几像素的 padding。最后就是"打开了退不出去"。把大图本身也算作关闭区域,等于告诉用户:这个遮罩上没有"安全区",点哪都退出。

第三,关闭时清 src。 一张 2MB 的 base64 图,解码后的位图可能占十几 MB。查看器关掉后如果还把 src 挂着,这份内存就一直被这个隐藏的 img 持有。清空之后,下一次打开重新赋值,浏览器重新走一遍加载(命中缓存会很快)。

这里有一个边角值得说清楚:imgViewerImgEl.src = '' 严格来说不是"删除属性"。空字符串会被 URL 解析器当成相对地址,解析成当前页面地址,浏览器会尝试把 HTML 页面当图片加载一次,这次请求注定失败。它不可见,也不影响功能,所以我留着了。要绝对干净,用 removeAttribute('src')。这不是必须改的 bug,是一个可以更讲究的点。

反直觉的地方:关闭判定不能只看"点在遮罩上"。 因为遮罩的可见区域和可点区域不是一回事。图片小的时候,四周全是可点的背景;图片大的时候,背景可能为零。判定必须覆盖这两种形态,否则就是在"图小的时候能用,图大的时候卡死"。

降级说明:现在只支持点击关闭,没有 Esc。要加的话,在 document 上再挂一个 keydown,判断 e.key === 'Escape' 且 !imgViewerEl.hidden 再关。注意别在输入框里抢 Esc 的语义——笔记正文是 textarea,用户可能用 Esc 取消输入法候选。加之前先想清楚作用域。触屏上没有 Esc,所以点击仍然是主路径。

5.5 尺寸:320/240 改成 none/70vh 之后

最终的尺寸规则:

/* style.css - 图片尺寸与查看器(1.0.8 起) */
.md-body .md-img {
  max-width: 100%;
  max-height: none;
  border-radius: 10px;
  display: block;
  margin: 8px 0;
  cursor: zoom-in;
}

.preview-img {
  max-width: 100%;
  max-height: 70vh;
  border-radius: 10px;
  display: block;
  margin: 0 auto;
  cursor: zoom-in;
}

#img-viewer {
  position: fixed;
  inset: 0;
  z-index: 9999;
  background: rgba(15, 18, 25, 0.92);
  display: flex;
  align-items: center;
  justify-content: center;
  overflow: auto;
  padding: 24px;
}

#img-viewer[hidden] {
  display: none;
}

#img-viewer img {
  max-width: 100%;
  max-height: none;
  border-radius: 6px;
  box-shadow: 0 8px 40px rgba(0, 0, 0, 0.5);
}

#img-viewer.hint::after {
  content: "点击任意处关闭";
  position: fixed;
  left: 50%;
  bottom: 18px;
  transform: translateX(-50%);
  color: rgba(255, 255, 255, 0.65);
  font-size: 12px;
}

三个细节:

第一,max-height: none 让长截图按宽度铺满。 图片的宽度受 max-width: 100% 约束,高度按原比例展开。1080×6000 的图在 700px 宽的容器里变成 700×3889,字的大小是原来的 65%,能读。用户要读完就往下滚,这是文档的正常行为。

第二,70vh 是给浮层的,不是给文档的。 附件面板宽度 384px,max-height: calc(100vh - 74px),本身还有 overflow: hidden。如果面板里的图也 max-height: none,一张长图会把面板内容撑到几千像素,面板的高度上限会把它裁掉,底部的按钮再也够不着。70vh 让图最多占视口高度的七成,剩下的三成留给面板头、文件名和关闭按钮。

第三,两个 max-height: none 的对象不同。 正文图是 .md-body .md-img,查看器大图是 #img-viewer img。前者在文档流里,后者在 fixed 遮罩里。它们恰好都需要"不限高",但原因不一样:前者要按宽度铺满,后者要按原尺寸显示。

反直觉的地方:max-height 不是裁剪,是等比缩放。 很多人第一次看到"长截图被压成一条",以为是图片被截断了。其实不是,整张图都在,只是被缩到了 320px 高。理解这一点,才知道为什么把 320 改成 800 仍然不够——只要还有上限,长图就会被压。

关于两个滚动条,也要说清楚:

  • #md-preview 自己有 overflow: auto,它负责整个笔记正文的滚动;
  • #img-viewer 是 position: fixed,它自己的 overflow: auto 负责大图的滚动。

查看器打开时,它盖住了整个视口,指针事件落在遮罩上,不会落到背后的预览区。所以两个滚动容器不会同时响应一次滚轮。关闭之后,遮罩 hidden,滚动又回到 #md-preview。这是 fixed 带来的隔离,不需要额外加 body { overflow: hidden }。

降级说明:inset 是 Chromium 87 之后才支持的简写。这个项目跑在 Chromium 144 上,没问题。如果要把这段样式搬到更老的 WebView,把它拆成 top: 0; right: 0; bottom: 0; left: 0 就行。另一个平台差异是 vh:在带动态工具栏的移动浏览器上,100vh 可能大于真正可见的高度,70vh 会跟着偏大。这是桌面和平板应用,窗口高度稳定,vh 够用;真要上手机浏览器,换成 dvh 更稳。

6. 我踩过的坑(每一条都有真实代码)

这一节可能是全文最值钱的部分。以下坑全部来自这次开发的真实改动和排查记录。

坑1:给每张 img 挂监听,重渲染一次就全丢。

现象:第一次进预览,点图能打开;切到另一篇笔记再切回来,点图没反应。勾一个任务复选框,也没反应。

第一版代码:

// renderer.js - 第一版 showPreview() 之后的逐图绑定(已删)
mdPreviewEl.querySelectorAll('img.md-img').forEach((img) => {
  img.addEventListener('click', () => {
    imgViewerImgEl.src = img.src;
    imgViewerEl.hidden = false;
  });
});

排查过程:一开始以为是被别的元素挡住了,用 document.elementFromPoint 查,命中的确实是 img。后来才反应过来,问题不在点击,在节点。showPreview() 里有一次 mdPreviewEl.innerHTML = html,任务勾选的处理里还有一次 mdPreviewEl.innerHTML = renderMarkdown(...)。每次执行,旧的 img 全部被销毁,新 img 上没有监听器。

修复:删掉逐图绑定,改成一个 document 级监听器,靠 e.target 筛。

// renderer.js - 委托函数,最终写法(1877 行起)
document.addEventListener('click', (e) => {
  const t = e.target;
  const isImg = t && t.tagName === 'IMG' && (t.classList.contains('md-img') || t.classList.contains('preview-img'));
  // ...
});

教训:DOM 会被重建,监听器不会跟着重建;要挂就挂在不会被重建的父节点上。

坑2:加载失败的图点开是空遮罩。

现象:附件读失败时,正文里会出现一个灰色虚线块(.md-img-broken)。第一版只按标签和类判断,点它遮罩会打开,里面全黑。补了 t.src 之后大部分场景被挡住,但这个类还是留着。

相关代码:

// renderer.js - hydrateAttachImages() 的失败分支(1079–1082 行)
} else {
  img.classList.add('md-img-broken');
  img.removeAttribute('data-attach');
}

排查过程:一开始觉得 t.src 能挡住——没有 src 的图,t.src 应该是空串。大部分情况确实如此。但有两个边角:一是某些路径下 src 被赋过空字符串,img.src 会被解析成当前页面地址,非空,判断就漏了;二是远程图加载失败时 src 仍然在,只是图裂了。t.src 只能证明"有地址",不能证明"有图"。光靠属性判断不够,业务状态要显式排除。

修复:在 isImg 的业务判断里显式排除这个类。

// renderer.js - 委托函数,打开分支(1880 行)
if (isImg && t.src && !t.classList.contains('md-img-broken')) {

教训:判断"能不能看"要看业务状态,不要只看标签名和属性。

坑3:大图铺满遮罩后,点哪都关不掉。

现象:小图打开后,点四周黑色区域能关;换成一张竖版长截图,图占满整个遮罩,点图没反应,点边缘也没有足够的空白,最后只能杀进程。

第一版关闭判断只有一句:

// renderer.js - 委托函数,第一版关闭判断(反例)
} else if (t === imgViewerEl) {

排查过程:打开开发者工具,点图,看到 e.target 是 #img-viewer-img,不是 #img-viewer。事件没有冒泡到遮罩吗?冒泡了,但判断用的是精确相等,img 不等于 div,所以不命中。

修复:把大图本身也纳入关闭区域。

// renderer.js - 委托函数,关闭分支(1886 行)
} else if (t === imgViewerEl || t === imgViewerImgEl) {

教训:关闭手势的判定要覆盖"没有空白可点"的形态,否则图越大越退不出去。

坑4:长图能铺满了,但下半截看不到。

现象:把 .md-img 的 max-height 改成 none 之后,正文能滚,没问题。查看器里的大图却只显示上半截,滚轮转不动。

第一版遮罩只写了定位和居中,没写 overflow:

/* style.css - 第一版遮罩,缺 overflow */
#img-viewer {
  position: fixed;
  inset: 0;
  z-index: 9999;
  display: flex;
  align-items: center;
  justify-content: center;
}

排查过程:一开始以为是图片被 max-height 限制,检查过,是 none。后来在 DevTools 里看遮罩的盒子,高度等于视口,图片高度远大于它,超出的部分画在外面但没有滚动条。fixed 只负责定位,不负责滚动。

修复:给遮罩加 overflow: auto,并在每次打开时把 scrollTop 归零。

/* style.css - 最终的遮罩规则 */
#img-viewer {
  position: fixed;
  inset: 0;
  z-index: 9999;
  background: rgba(15, 18, 25, 0.92);
  display: flex;
  align-items: center;
  justify-content: center;
  overflow: auto;
  padding: 24px;
}
// renderer.js - 委托函数,打开时归零(1885 行)
imgViewerEl.scrollTop = 0;

教训:fixed 只负责脱离文档流,不负责让你滚;滚动容器要自己声明。

坑5:附件面板的图不限高,把面板撑爆。

现象:正文图改成 max-height: none 之后,我顺手把 .preview-img 也改了。结果附件面板里点开一张长截图,图片把面板内容顶得老长,列表和沙箱目录被挤到视口外,要滚很久才够得着。

面板的约束:

/* style.css - 附件面板(806–819 行,节选:省略背景与圆角阴影) */
#files-panel {
  position: fixed;
  top: 58px;
  right: 14px;
  width: 384px;
  max-height: calc(100vh - 74px);
  display: flex;
  flex-direction: column;
  overflow: hidden;
  z-index: 50;
}

排查过程:面板本身有 max-height,也有 overflow: hidden,所以它不会真的长到屏幕外,而是把超出的内容裁掉。图片在 #file-preview 这个 <pre> 里,图一高,下面的内容就被挤走。正文能靠页面滚动解决,面板没有那么多空间。

修复:.preview-img 保留视口上限,从 240px 提到 70vh,而不是 none。

/* style.css - 附件图(1102–1109 行) */
.preview-img {
  max-width: 100%;
  max-height: 70vh;
  border-radius: 10px;
  display: block;
  margin: 0 auto;
  cursor: zoom-in;
}

教训:同一个"看清"目标,正文和浮层要用两套上限;容器越小,越要给它自己的视口单位。

五条坑走完,你会发现它们其实指向同一个设计问题:查看器不是一个组件,是三个容器之间的一份契约。HTML 提供壳,CSS 提供层和尺寸,JS 提供状态。任何一方擅自改约束,另外两方就会出问题。

7. 现在怎么用:从这段代码到你的页面

接入没有依赖,也没有额外的构建配置。三步:

  1. 把 <div id="img-viewer" hidden><img id="img-viewer-img" alt=""></div> 放到 </body> 前;
  2. 把第 5.5 节的 CSS 整段贴进样式表;
  3. 把第 5.1 节的监听器放进一个在 DOM 之后执行的脚本里。

构建还是老命令:

hvigorw assembleHap

产物在 electron/build/default/outputs/default/ 下,签名后是 electron-default-signed.hap,装到真机上验证。这个改动只动渲染层资源,不重编原生库。

我自己的验证清单是六个手工用例,每次改这块都跑一遍:

  • 正文里放一张 1080×6000 的长截图,预览时应按宽度铺满,能滚到底;
  • 点长截图,遮罩打开,图从顶部开始显示,能滚到最底部;
  • 在遮罩里滚动到中间,关闭,再点另一张图,新图应从顶部开始;
  • 点遮罩空白处,关闭;点大图本身,也关闭;
  • 找一张加载失败的附件图(灰色虚线块),点击应无反应;
  • 打开附件面板,点一张长图,面板不应被撑出屏幕,图内可滚。

六个用例里,最容易回归的是第三个。只要有人把 scrollTop = 0 删掉,或者改成在 hidden = false 之前设置,就会出现"新图从中间开始"的怪现象。

硬限制也列清楚,免得读者踩到同一堵墙:

  • 只支持点击放大,不支持双指缩放、滚轮缩放、拖拽平移;
  • 一次只能看一张,没有左右切换上一张/下一张;
  • 没有 Esc 关闭,触屏上也没有下滑手势,只有点击;
  • 不接管视频、SVG 动画、<canvas>,只认 img;
  • 超大 base64 图首次打开可能先出遮罩、后出图,没有加载指示;
  • 遮罩颜色固定为 rgba(15, 18, 25, 0.92),不跟随浅色/深色主题。

写到这里,我对这个功能的判断已经和最初完全不同了。一开始我以为它是个"图片放大"功能,后来发现它其实是在解决容器和内容打架:正文容器要排版,浮层容器要限高,而用户要的是"这一次,让我看清"。查看器做的事情,是把图片从原来的容器里借出来一次,放到一个只服务于阅读的层里,读完再还回去。

如果这篇文章只能留一句话,我会留这句:用户说"图太小",要的从来不是全屏动画,而是一个能看清字的尺寸。

8. 快问快答

Q1:为什么不用 <dialog>?

<dialog> 的 showModal() 会进 top layer,还能自带焦点陷阱,听起来正合适。但这个页面已经有一套自己的遮罩层(提醒弹窗、设置面板),再引入一套模态语义,焦点和 z-index 要重新对齐。一个 div 加 hidden 已经够用,少一层概念。

Q2:为什么不装一个 lightbox 库?

这个应用的前端是随 HAP 打包的本地文件,没有 npm 运行时,加一个库要连同它的样式、图标、字体一起塞进 resfile。二十行代码能解决的事,不值得多几百 KB,也不值得为它调整 CSP。

Q3:支持滚轮缩放吗?

没做。要做的话,在 wheel 里改 transform: scale(),但会和遮罩的 overflow: auto 打架:缩放之后滚动范围要重算,指针位置也要换算。现阶段先保证"原图 1:1 可读",缩放留到有人真的需要时再加。

Q4:为什么用 max-width: 100% 而不是 width: 100%?

width: 100% 会把小图也拉大,一张 200px 宽的图标会被拉成 700px,糊得没法看。max-width 只约束上限,小图保持原尺寸,大图才缩。这是"不放大"的默认。

Q5:点开的是原图,还是被 CSS 压过的缩略图?

是同一份资源。CSS 的 max-height 只影响布局,不改图片数据。查看器把同一个 src 赋给另一个 img,浏览器通常直接命中已解码的缓存,不会再请求一次。远程图这里有个边界:正文里的 img 带了 referrerpolicy="no-referrer",查看器里的 img 没带;如果缓存没命中,第二次请求可能被图床拦。当前没有遇到,下一版会给 #img-viewer-img 也补上这个属性。

Q6:触屏上怎么关闭?

点遮罩空白,或者点大图本身。没有做下滑手势。这是取舍:手势要处理 touchstart/touchmove/touchend 和滚动冲突,收益不如一行"点击任意处关闭"的提示直接。

Q7:为什么关闭时要清空 src?

为了释放引用。base64 图的数据、解码后的位图都挂在这个 img 上,遮罩隐藏不等于资源释放。清空之后,下一次打开重新赋值,浏览器按缓存策略处理。代价是关闭瞬间可能有一次注定失败的页面请求,不影响功能。

Q8:图片很多会不会卡?

监听器只有一个,成本不在绑定数量。真正的成本在 renderMarkdown 重建 HTML 和 base64 解码,这两件事跟查看器无关。委托在这个场景里是顺带省了内存,不是性能优化的主角。

Q9:深色主题下遮罩颜色会变吗?

不会。遮罩固定用深色半透明,因为它的职责是"把注意力留给图片",不是跟随应用主题。浅色主题下突然出现一块深色遮罩,看着突兀,但看图的体验是一致的。真要跟随主题,改一个 CSS 变量就行,现在没这个需求。

Q10:无障碍做了什么?

alt 从原图透传到查看器,屏幕阅读器能读到图片描述。没做的是:遮罩没有 role="dialog" 和 aria-modal="true",打开时焦点没有移进去,关闭后也没有还给触发元素。这是一个明确的缺口,不是"已经完美"。

到这里,这个查看器的全部就交代完了。它很小,小到只有一个监听器和三十行样式;但它把三件事一次说清了:尺寸该由容器决定,事件该由生命周期决定,关闭该由用户能不能点到决定。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐