简介seat-map.js 是一套基于 JavaScript 的互动式座位图解决方案面向需要在网页中实现在线选座、场地可视化的 Web 开发者。其核心是创建设置工厂函数 createSeatMap 与预置场馆对象 venues调用时传入目标容器和场馆名称即可异步下载 SVG 座位图并完成渲染适用于演唱会、体育赛事、剧院等预订场景。压缩包内共 5 个文件、8KB 大小包含 2 个 SVG 场馆地图、1 个核心 JS 脚本、1 个 JSON 配置文件和 1 份 Markdown 说明。SVG 地图可自定义或替换JS 负责座位交互与渲染逻辑JSON 与 MD 便于调整参数和快速了解用法。目录结构简洁源码与地图文件分离利于二次开发。已有 898 人学习下载。从中可以学习模块化导入、全局挂载 window.seatMapJS 的集成方式查看 rod-laver 与 sydney-myer-bowl 两套场馆地图的 SVG 结构还能参考 package.json 和 readme 在自己的前端项目中搭建一个轻量级选座模块适合希望快速实现座位图效果的前端开发者。1. 把座位图做成交互组件seat-map.js 解决的不是画座位是选座流程做活动报名、剧院订票、影院选座这类页面难点从来不在画出矩形格子而在从座位点下去那一刻开始的状态管理哪些座可点、哪些已售、一次最多选几个、切换区域后价格怎么变、缩放平移后点击坐标还准不准。seat-map.js 就是围绕这套流程封装的一个 JavaScript 交互式座位图库它帮你把座位渲染、单选/多选、区域划分、锁座状态串成一条完整链路而不是只给你一堆画布 API。适合正在折腾 H5 选座页面的前端也适合需要快速给运营后台塞一个可视化排座工具的后端同学。如果你也遇到过自己拼 Canvas 点击偏移越来越离谱的翻车现场这篇会把坐标模型、配置参数和真正容易踩的坑一次性捋清。2. 象棋盘还是自由落座seat-map.js 的坐标模型与渲染原理2.1 座位数据模型不是二维数组那么简单第一次用 seat-map.js 的人最先容易踩的误区是把它当成传个行数和列数就自动画格子的工具。实际上库的底层依赖的是带坐标的座位对象数组每一个座位都是一个独立节点拥有自己的x、y、row、col、state等字段。这种设计的好处是支持不规则排布——比如剧场两侧的边座可以是单列VIP 区可以只摆四排甚至能做出中间走道断开的布局而纯二维数组做这种结构会非常痛苦。// 最小座位对象示例 const seat { id: seat_A1, x: 14, // 相对座位图原点的横向偏移单位 px由布局算法算出 y: 26, row: 1, col: 1, state: available, // available / selected / sold / disabled price: 80, // 可选字段用于联动价格 areaId: front // 可选字段用于区域分组 };这里x和y不是表格里的行列索引而是渲染层用的像素坐标。数据初始化时seat-map.js 会根据你传入的行列间隔、座位半径和 maybe 走道间隙自动把逻辑行列换算成像素坐标。你只需要关注row和col画布上的点位交给库处理。state是交互的开关available可点选selected表示已被当前用户选中sold灰色不可点disabled则用于后排柱子遮挡这类物理不可售座。注意price和areaId是可选字段但如果你要做分区定价建议在建数据时就带上不然后面还要再遍历一遍地图。2.2 渲染方案Canvas 还是 SVGseat-map.js 选了后者这个库的渲染层默认走 SVG而不是 Canvas。原因是选座交互的 DOM 命中检测太方便了每个座位是一个rect或circle元素点击事件天然携带元素引用不需要自己做坐标反算。Canvas 在高频重绘上有性能优势但一旦座位数量上千你还要手动处理缩放后的点击偏移、元素唯一标识、重绘节流工作量直接翻倍。seat-map.js 守住的是中等规模场景——几百到一两千个座位SVG 的 DOM 节点数量还在可控范围并且能直接用 CSS 控制 hover 态。// 初始化核心代码无框架环境示例 const map new SeatMap({ container: document.getElementById(seatMapBox), seats: seatList, // 上面定义过的座位对象数组 config: { rowSpacing: 28, // 排与排之间的像素间隔 colSpacing: 28, // 座与座之间的像素间隔 seatSize: 18, // 座位图形直径 showRowLabel: true, maxSelectable: 4 } }); map.render();参数说明rowSpacing和colSpacing决定排布密度如果你的座位名称是「A1、A2」这种行间距可以比列间距大几像素视觉上更透气。seatSize是座位的展示直径鼠标点击的命中区域也会跟随这个值放大不要设得太小否则手机端点不准。maxSelectable是硬上限——当用户已经选了 4 个再去点其他座位seat-map.js 会拒绝选中并触发limit事件这比你每次点击后再去判断数组长度靠谱得多。2.3 缩放与平移坐标变化背后的 transform 链路座位图一旦塞进窄屏缩放平移就是刚需。seat-map.js 的做法是把整个 SVG 包在一个视口层里通过改变视口层的transform: translate()和scale()实现平移缩放而每个座位的x、y保持绝对坐标不变。这样做的最大好处是你永远不用修正每个座位的坐标命中的时候只需要把点击的 clientX/clientY 转换成视口层坐标系再和座位坐标比对。库内部用了一个比较经典的逆矩阵换算但你基本感知不到。// 启用缩放平移库内部已处理点位的坐标换算 map.setZoomEnabled(true, { minScale: 0.6, maxScale: 2.5, zoomStep: 0.2 }); map.setPanEnabled(true);如果你自己手写过 Canvas 版本应该秒懂这里有多省事Canvas 缩放后你必须手动把 canvas 的width、height和每个座位的绘制坐标全部乘一遍 scale否则点一下偏移一截。SVG transform 的思路把原始坐标和展示坐标分离map.setZoomEnabled只是暴露了缩放边界。注意minScale不要设太大否则缩小到完整视图时可能放不下全部座位zoomStep是鼠标滚轮或双击放大时每档的增量设成 0.2 手感比较线性设成 0.5 会忽大忽小。3. 快速落地一个选座页面初始化、配置项与联动价格3.1 在 Vue 里把 seat-map.js 包成一个组件虽然 seat-map.js 本身不依赖框架但在项目里直接用最少要处理容器的挂载时机、组件销毁时释放实例、状态同步这三件事。以 Vue 3 为例我习惯把它封装成一个子组件父组件管座位数据子组件只负责实例化和对外抛事件。这样选座状态就只留在父组件的ref里后续提交订单、计算价格都方便。// SeatMapVue.vue关键部分 script setup import { onMounted, onUnmounted, ref } from vue; const props defineProps({ seats: { type: Array, required: true }, maxSelectable: { type: Number, default: 4 } }); const containerRef ref(null); let mapInstance null; const emit defineEmits([select-change, limit]); onMounted(() { mapInstance new SeatMap({ container: containerRef.value, seats: props.seats, config: { maxSelectable: props.maxSelectable } }); mapInstance.on(selectChange, (selectedSeats) { emit(select-change, selectedSeats); }); mapInstance.on(limit, () { // 这里可以弹提示最多选 4 个 console.warn(reached max selectable); }); mapInstance.render(); }); onUnmounted(() { mapInstance.destroy(); }); /script template div refcontainerRef classseat-map-container/div /template逻辑说明onMounted里实例化onUnmounted里destroy()避免内存泄漏——这是我最早偷懒不加销毁时踩过的坑SPA 切页返回后旧实例还挂在 DOM 上导致事件监听重复触发。selectChange每次选座或取消时都会触发事件回调里带的是当前已选中的完整座位对象数组而不是只给你一个变化了的信号。这里我特别强调不要自己去查座位数组然后手动比对差异库已经帮你算好直接用。注意limit事件不包含具体触发者所以 UI 提示要写在父组件里提示文案不要写死。3.2 核心配置项从“能跑”到“好用”的参数调优seat-map.js 对配置项的处理是“显式优于魔法”所有影响交互的参数都在config对象里。下面是几个高频调整项直接决定页面拿过去能不能用配置项类型默认值作用与建议maxSelectablenumber1限制最多选几座。超过后触发limit事件配合 toast 提示showRowLabelbooleantrue显示左侧行号A/B/C…。如果座位图很窄可以关掉省空间showLegendbooleantrue是否显示 可售/已售/已选 图例。移动端建议关掉自己写图例更灵活seatLabelVisiblebooleanfalse在线座位图上显示座位号。座位直径小于 20px 时建议关否则糊成一团enablePinchZoombooleanfalse移动端双指缩放。桌面端用滚轮移动端如果开启要记得同时关闭页面默认的手势滚动disabledSeatOpacitynumber0.3已售/不可用座位的透明度。0.3 是肉眼能识别又不刺眼的经验值maxSelectable是业务强相关早鸟票、团建选座这类场景往往需要限制人数。如果你要让用户多选区混排比如前区选 2 个、后区选 2 个maxSelectable只能卡总数不能按区域卡配额。这种需求得在selectChange回调里自己统计——先触发limit或者提前 return这属于进阶用法后面第 5 章会讲。3.3 区域价格联动不是改座位价格是监听选中事件很多 docs 里只说“每个座位可以带 price 字段”但真正做选座页面价格是随选中数量动态变化的。seat-map.js 不建议你渲染时去读 price 来更新 UI而是让你监听selectChange拿到当前选中的所有座位再统一算出总价。map.on(selectChange, (selectedSeats) { const totalPrice selectedSeats.reduce((sum, seat) sum seat.price, 0); document.getElementById(totalPrice).textContent totalPrice; document.getElementById(selectionInfo).textContent selectedSeats.map((s) s.row - s.col).join(, ); });这段逻辑看似简单但有个隐藏坑seat.price来自你初始化时传入的对象如果你在业务代码里直接修改了座位对象上的 price而 seat-map.js 内部持有的是同一对象引用那 price 会被污染。正确做法是价格数据单独放在一份映射表比如MapseatId, price渲染时从映射表里取 price 传给 seat-map.js业务改价只更新映射表。这样既不会污染数据源也方便后面做价格策略调整。选座位只是链路的一环真正核心的是把选中的座位数据安全地交到订单提交那里用引用类型要慎之又慎。4. 避坑交互状态不同步、坐标偏差与变更事件丢失的排查记录4.1 缩放后点击座位命中位置偏移了几个座位现象桌面端滚轮缩小scale 1之后点击 A6 座位突出的是 A4 或 A7越边缘偏移越严重。刷新页面变正常。原因这个坑跟坐标换算有关。如果容器样式里出现了padding或border视口层的clientWidth和getBoundingClientRect().left会被拉伸或偏移。seat-map.js 内部做逆矩阵换算时会拿容器的 rect一旦 rect 不是从 (0,0) 起缩放的基准点就错了。另一个高频来源是移动端页面meta nameviewport设置不正确导致 SVG 实际占位和渲染尺寸不一致。解决给 seat-map 容器单独一个类清掉 padding、border并且显式设置width: 100%; height: …px; overflow: hidden。如果是移动端确认 viewport 设为widthdevice-width, initial-scale1.0不要用maximum-scale2.0这种会缩放视觉环境的写法。如果还有偏移检查是不是有全局 CSS 对svg做了transform有的话加个transform-box: fill-box或者隔离作用域。4.2 Vue 中座位选中状态与表单数据不同步现象用户点了 4 个座位后界面上四个座位变蓝但提交订单时数据少了一个或者反过来用户取消一个弹出层还把它算在总数里。原因seat-map.js 触发selectChange时回调里的selectedSeats是从内部状态拷贝出来的但某些版本或使用方式下如果你的onMounted里直接对props.seats做了原地修改比如把state改成selectedVue 的响应式追踪会延迟一轮导致emit出去时读取一个旧快照。我在实际项目里遇到过一次父组件用watch监听selectChange去更新ref结果watch回调里的selectedSeats已经被下一次点击覆盖。解决不要在selectChange里做异步监听或二次计算直接把它放进一个pendingSelection变量然后在提交动作点击“购票”按钮时从pendingSelection里读取。如果必须依赖 Vue 响应式给selectChange回调里加setTimeout(() {...}, 0)或者nextTick让 DOM 更新走完一轮。更稳妥的做法是库只负责展示和交互数据校验完全交给父组件在提交时从pendingSelection拿不要把 seat-map.js 当成“状态仓库”。4.3 座位数量过千后拖拽平移明显掉帧现象超过 1200 个座位的剧院图开启panEnabled后鼠标拖动画布时 SVG 里每个rect都在响应用户事件CPU 占用高普通笔记本掉帧明显。原因SVG 的 DOM 节点数量在几千个时每次 transform 变化都要浏览器重新计算布局。虽然座位的绝对坐标没变但浏览器在每一帧都需要把 transform 应用到整个子树节点一多合成线程压力大。这不是 seat-map.js 的特殊问题是所有 SVG 方案的通病。解决这个规模下建议把座位图拆分渲染——首屏只渲染可视区域附近的部分座位拖动或手动缩放结束后再更新可见范围。seat-map.js 支持给座位列表传入一个“裁剪后”的数组你可以在panChange事件里根据当前视口范围过滤座位map.on(panChange, (viewport) { const visibleSeats allSeats.filter( (s) s.x viewport.left s.x viewport.right s.y viewport.top s.y viewport.bottom ); map.updateSeats(visibleSeats); });注意updateSeats这个方法会重排整个列表并重绘不能高频调用。我一般在panChange里加一个requestAnimationFrame节流保证 1 秒最多更新 10 次。如果你的座位分布很分散裁剪后更新反而会有明显的“空白区域尚未加载”的视觉跳动所以这个策略只建议在确认真卡顿后采用别一上来就盲优化。4.4limit事件触发了但已选中座位没有自动回滚现象设置了maxSelectable: 4用户已经选了 4 个再去点第 5 个座位时控制台收到了limit事件但第 5 个座位也变蓝了界面上有 5 个选中态。原因这个跟库的版本有关。某些实现里limit只是通知业务方“已经达到上限”不会主动把超出的那次点击回滚。如果你没有在limit回调里手动取消最后一次点击的座位UI 就会停留在“5 个选中”。解决在所有使用maxSelectable的场景里监听limit并主动回滚map.on(limit, () { map.revertLastSelection(); // 或根据库 API 调 deselectLast() });如果你用的版本没有revertLastSelection那就退而求其次在 select 事件里自己判断如果selectedSeats.length maxSelectable直接执行map.deselectSeat(selectedSeats[selectedSeats.length - 1])。别问我为什么知道。5. 超出基础选座自定义选区、锁座与联动重排的后置接口到了实际项目阶段很多人不再满足于“选座 计价”这种模板功能而是需要把座位图嵌进复杂的运营后台比如“临时锁定某排某座 10 分钟”、“按区域批量改价”、“清空当前选中”。这些场景要用好 seat-map.js 后置接口否则你会陷入重复render()导致的白屏。// 批量锁定两个座位用于黄牛拦截或订单超时释放 function lockSeats(seatIds) { map.updateSeats( seatIds.map((id) ({ id: id, state: disabled, lockTime: Date.now() })), { merge: true } // 关键参数不整体替换座位数组只更新对应 id 的状态 ); }这里updateSeats的merge: true是我最常用的参数。如果不传merge,这个方法会把你传入的数组当成新的完整座位列表直接替换导致未涉及的座位全部丢失。lockTime是自定义字段seat-map.js 不会修改它但你可以用它做超时解锁的判断依据。// 清空用户当前所有选中并重置计数 map.deselectAll(); map.setMaxSelectable(4);deselectAll比手动遍历selectedSeats再逐个调用deselectSeat要安全因为selectChange事件不会在清空过程中反复触发避免你的联动逻辑被连续打断。如果你需要模拟“清空后重新选一个”先调用deselectAll()然后在下一个事件循环里调用map.selectSeat({ row: 1, col: 1 })这样能保证 UI 先是全空再出现一个选中态。另一个容易被忽视的接口是setSeatLabelFormatter它可以改变每个座位显示的文字。默认显示row - col比如A-5但运营的人想看到的是“分区-区域-座位号”比如甲区-5排-6号。我一般这样挂map.setSeatLabelFormatter((seat) { const areaMap { front: 甲区, mid: 乙区, back: 丙区 }; return ${areaMap[seat.areaId] || 散座}-${seat.row}排-${seat.col}号; });这个接口不会影响座位唯一的id只是改变 SVG 内部text的内容。注意如果你开启了seatLabelVisible: false这个 formatter 是无效的所以需要在初始化时同时开启seatLabelVisible: true。排号 A 和 1 的混用也是我经常看到的坑row字段可以是数字也可以是字符你初始化时用了字符 A那么setSeatLabelFormatter里就不应该再seat.row直接当数字运算要提前Number(seat.row.replace(/\D/g, ))做一次清洗。最后说一个我自己的习惯每上线一个新的选座回归测试我都会让测试同事特意去点击那些「已售」的座位而不是只测正常选座流程。因为很多数据源在出票后把state从sold改成disabled时没人验证 disabled 座位点击后是否真的不触发任何事件。seat-map.js 在这方面做得还算克制但如果你的版本遇到 disabled 座位触发selectChange的问题先检查是不是你在初始化时手动改过座位对象上的state导致内部状态与渲染状态不同步。从那以后我每次接 seat-map.js 需求都会强制走一遍“点击已售座 → 点击已选座 → 连续换选 → 缩放平移后点击”四步自测这套流程帮我拦下了不下三次线上事故。希望帮到你。本文还有配套的精品资源点击获取
