纯原生HTML5图片浏览需用<img>动态切换src，图列表存JS数组而非DOM查询，绑定document级键盘事件并防默认行为，ESC恢复body滚动，加载完成再移除loading，注意file://协议静默失败及viewport缩放限制。
用 <img> 和原生 JS 实现基础图片浏览，别碰框架
纯 HTML5 不提供“图片浏览器”这个组件，得自己搭骨架。核心是：<img> 显示图、src 动态切换、用 dataset 或数组存图列表。不依赖任何库，就能响应点击翻页、键盘左右键、ESC 关闭——关键在事件绑定和状态管理。
常见错误是直接写死 <img src="..."> 然后靠 CSS 遮罩模拟弹窗，结果图没加载完就显示空白，或点击缩略图后 src 没更新成功。
- 图列表建议存在 JavaScript 数组里，而不是靠
document.querySelectorAll('.thumb')实时查 DOM —— 后者容易因异步插入失败 - 切换图片前务必检查索引是否越界，否则
imgs[999]会得到undefined，<img>的src变成"undefined"，控制台报GET http://.../undefined 404 - 首次打开时，用
imgEl.addEventListener('load', ...)确保图加载完成再移除 loading 状态，别只靠setTimeout
keydown 监听要防默认行为，尤其在 <input> 里触发时
键盘翻图（← → ESC）看似简单，但实际常失效：焦点在搜索框里按方向键，事件根本没传到监听器；或者没调 event.preventDefault()，页面跟着滚动了。
正确做法是把监听挂到 document 上，并加条件判断当前是否有聚焦的可编辑元素：
立即学习“前端免费学习笔记（深入）”；
document.addEventListener('keydown', e => {
if (e.target.matches('input, textarea, [contenteditable]')) return;
if (e.key === 'Escape') closeViewer();
if (e.key === 'ArrowLeft') showPrev();
if (e.key === 'ArrowRight') showNext();
});
- 别监听
window—— 在 iframe 或 Shadow DOM 场景下可能收不到事件 - ESC 关闭时，记得恢复
body的overflow: hidden（如果之前为了遮罩禁用了滚动） - 移动端没有键盘，需补上手势支持（如
touchstart/touchend计算滑动距离），但 HTML5 本身不处理这个
图片路径错误导致 404，但 onerror 不触发？检查协议和相对路径
本地双击打开 HTML 文件（file:// 协议）时，<img src="./images/1.jpg"> 看似合理，但浏览器可能因安全限制拒绝加载，且不会触发 onerror 回调——这是个静默失败。
更隐蔽的问题是路径拼错：./pics/ 写成 ./pic/，或大小写不符（Linux 服务器区分大小写，而本地开发常忽略）。
- 调试时先在控制台手动执行
fetch('./images/1.jpg').then(r => r.blob())，看是否真能取到资源 - 给
<img>加onerror="this.src='data:image/svg+xml,...'"显示占位符，避免空白卡住 UI - 若图来自 API，确保返回的是真实 URL（含
http://或/api/images/...），不是相对路径字符串
移动端双指缩放失效？viewport 元标签必须放开
HTML5 图片浏览器在手机上打不开双指缩放，大概率是 <meta name="viewport"> 里写了 user-scalable=no 或 maximum-scale=1.0 —— 这会直接禁用所有缩放行为，包括图片本身。
正确写法是允许缩放，同时限制初始缩放比例：
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
- 别信“加了
touch-action: manipulation就能缩放”——它只优化点击延迟，和缩放无关 - 缩放功能由浏览器原生实现，JS 无法直接控制；你只能确保不拦着它
- 如果用了
transform: scale()手动缩放，记得同步更新offsetWidth/Height和拖拽边界，否则手势会错乱
最麻烦的其实是图片尺寸不确定：小图放大糊，大图加载慢，又不能靠 CSS object-fit 一劳永逸——得根据宽高比动态选策略，这部分逻辑容易被跳过，但用户一放大就糊，问题立马暴露。
