Electron-OH 鸿蒙实战:截图里的字看不清——一个事件委托的全屏图片查看器
Electron-OH 鸿蒙实战:截图里的字看不清——一个事件委托的全屏图片查看器
320px 的预览上限把一张代码截图压成蚂蚁字、240px 的附件预览把长图截成一条、点一下图片想看原图却什么都没发生——这篇文章用一个跑在鸿蒙 2in1 真机上的 Electron 笔记应用,把「尺寸策略、事件归属、全屏遮罩、关闭判定」这四件事一次讲透。
欢迎加入开源鸿蒙PC社区:https://harmonypc.csdn.net/
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
0. 环境与实测设备
| 项 | 版本/型号 |
|---|---|
| 设备 | HarmonyOS 2in1(aarch64),平板与 PC 形态共用一套窗口布局 |
| 目标 SDK | HarmonyOS 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-OH | Electron 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 调整 |
| 页面 CSP | default-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-viewer | div#img-viewer | 关闭 | hidden = true,清 src |
遮罩里的大图 #img-viewer-img | img | 关闭 | 同上 |
| 页面其他位置 | 任意元素 | 不处理 | 事件正常结束 |
这张表里最关键的一行是最后一行。事件委托不是"只在图片上生效",它是"在 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-viewer | JS 显隐、CSS 定位 |
| 大图节点 | #img-viewer-img | JS 换 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. 现在怎么用:从这段代码到你的页面
接入没有依赖,也没有额外的构建配置。三步:
- 把
<div id="img-viewer" hidden><img id="img-viewer-img" alt=""></div>放到</body>前; - 把第 5.5 节的 CSS 整段贴进样式表;
- 把第 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",打开时焦点没有移进去,关闭后也没有还给触发元素。这是一个明确的缺口,不是"已经完美"。
到这里,这个查看器的全部就交代完了。它很小,小到只有一个监听器和三十行样式;但它把三件事一次说清了:尺寸该由容器决定,事件该由生命周期决定,关闭该由用户能不能点到决定。
更多推荐


所有评论(0)