Mapbox Storytelling源码深度解析：Scrollama与Mapbox GL JS如何协作驱动滚动叙事
Mapbox Storytelling源码深度解析Scrollama与Mapbox GL JS如何协作驱动滚动叙事【免费下载链接】storytellingStorytelling with maps template项目地址: https://gitcode.com/gh_mirrors/st/storytellingMapbox Storytelling 是一个基于 Scrollama 与 Mapbox GL JS 构建的滚动驱动地图故事模板你只需在config.js里写好故事章节读者滚动页面的同时地图会自动飞行、缩放、倾斜并切换数据图层透明度——无需前端框架和构建工具。本文基于src/index.html源码拆解两个库的协作骨架并教你 4 步做出第一个 scrollytelling滚动叙事作品。 什么是 Mapbox Storytelling滚动驱动的地图叙事模板传统地图文章是静态底图 几张截图而 Mapbox Storytelling 把地图变成了会跟随阅读节奏移动的镜头。故事被拆分成若干章节chapters每个章节绑定一个地图视角坐标、缩放、俯仰角、旋转角。读者往下滚动地图就飞往对应位置——人口变化、冰川消退、城市骑行网络这类有地理背景的故事表达力立刻翻倍。上图是内置示例example/glacier/config.js的运行效果左侧文字介绍 1998 年的 Harrison Glacier右侧地图同步飞入冰川位置并淡入冰川边界数据层。整个故事由 13 个章节组成全程无人工切换地图。 项目骨架三个文件撑起整套滚动叙事系统文件角色src/index.html模板主体地图容器、故事容器与全部协作逻辑src/config.js.template故事脚本模板复制成config.js后填写章节内容src/helper.html坐标辅助工具可视化获取每章的地图位置参数example/glacier/config.js完整示例冰川国家公园 1998 vs 2015 对比故事example/bike-philly/config.js费城自行车道与共享单车示例没有打包器、没有依赖安装src/index.htmlL8-L11直接通过 CDN 引入 Mapbox GL JS v2.11.0 与 Scrollama 两个脚本拿到即开。 Scrollama 是雷达感知你滚动到了哪一章协作的第一环由 Scrollama 承担。页面加载时src/index.htmlL208-L243会把config.js里的每个章节动态生成为一个div.step滚动块并在 CSSL100-L107中给它们 50vh 的底部留白——这就是章节之间呼吸的距离来源同时默认透明度 0.25、激活后提升到 0.9形成文字淡入效果。地图本体则被钉在背景上#map使用position: fixed; height: 100vh; width: 100vwL21-L26滚动的是文字不动的是地图。等地图加载完成后Scrollama 被实例化并绑定章节侦测L306、L337-L342var scroller scrollama(); scroller.setup({ step: .step, // 侦测每个章节滚动块 offset: 0.5, // 章节越过视口50%线即触发 progress: true })随后挂上两个核心回调onStepEnter章节进入视口中央与onStepExit章节离开视口。这就是整条协作链的触发器。 Mapbox GL JS 是镜头飞行、图层与地形三级指令飞行mapAnimation三选一onStepEnter回调里最关键的一行L348mapchapter.mapAnimation || flyTo;它用动态属性访问的方式把每个章节的locationcenter / zoom / pitch / bearing交给 Mapbox GL JS 的相机动画方法执行。flyTo是最常用的弧形飞行也可换easeTo平滑滑动或jumpTo瞬间跳转。注意地图初始化时设置了interactive: falseL278——地图本身不可拖动一切移动都由脚本驱动保证阅读节奏不被打断。呼吸onChapterEnter/onChapterExit控制数据图层这是叙事感的精髓进入章节时淡入数据层、离开时淡出。回调中逐条执行L364-L366、L390-L392if (chapter.onChapterEnter.length 0) { chapter.onChapterEnter.forEach(setLayerOpacity); }setLayerOpacityL165-L176先通过map.getLayer()查出图层类型再映射到对应的透明度属性如fill层用fill-opacity、circle层同时处理circle-opacity与描边透明度最后调用map.setPaintProperty实现平滑淡入淡出。冰川示例中1998 年图层与2015 年图层正是靠这一机制在不同章节间交替显影。3D 地形use3dTerrain一行开启开启后地图load事件里会自动挂载 DEM 高程源exaggeration: 1.5、地形层与大俯仰角下的天空层L310-L330。 一次滚动的完整链路从手指到屏幕加载index.html读取config.js生成全部.step章节块并用第一章的location初始化全屏地图L271-L281。侦测Scrollama 持续计算各章节相对视口的位置offset: 0.5。触发章节越过 50% 线 →onStepEnter按element.id反查章节配置L344-L345。飞行map.flyTo(chapter.location)让镜头飞往目标视角。显影onChapterEnter逐条执行数据图层按opacity/duration淡入。附加动作标记移动到章节中心L361-L363、执行自定义callback、rotateAnimation在飞行结束后 30 秒缓慢旋转 180°L370-L379、右下角 inset 小地图同步视野L353-L360。离场章节滚出视口 →onStepExit执行onChapterExit图层淡出、文字变暗L387-L393。自适应窗口尺寸变化时调用scroller.resize重新校准L485。 快速找到地图坐标helper.html小技巧章节的location参数center / zoom / pitch / bearing手写很痛苦。src/helper.html内置了地图搜索控件移动地图时左上角会实时打印可复制的坐标定义L78-L89 的moveend监听map.on(moveend, function() { updatePosition() // 左上角实时刷新 center/zoom/pitch/bearing });操作提示右键拖动地图可以倾斜和旋转视角把镜头摆到电影感机位后一键复制进config.js即可。⚙️ 高频配置开关速查配置项作用位置说明mapAnimation每章flyTo/easeTo/jumpTo默认 flyToonChapterEnter/onChapterExit每章进/出章节时图层透明度0~1与过渡时长alignment每章文字面板位置left/right/center/fullrotateAnimation每章飞行结束后慢速旋转镜头callback每章进入该章时执行自定义 JS 函数use3dTerrain全局开启 3D 地形 天空层inset全局右下角跟随视野的小地图auto全局自动翻页模式无需手动滚动theme全局文字面板light/dark主题完整字段说明见src/config.js.template中的注释与 README 的 Configuration Options 部分。 4 步跑通你的第一个滚动叙事获取代码git clone https://gitcode.com/gh_mirrors/st/storytelling准备凭据注册一个免费 Mapbox 账号拿到 access token建议每个故事单独建 token 便于追踪流量。填写脚本进入src/目录把config.js.template复制为config.js填入 token、标题用helper.html逐章定位location。发布浏览器打开index.html滚动预览定稿后将index.html与config.js放入同一目录部署到任意静态托管即可。⚠️ 注意滚动驱动依赖整页滚动用 iFrame 嵌入其他页面时无法正常工作请给故事一个完整页面。 总结一句话看懂两者分工Scrollama 负责你在哪——侦测滚动位置、判定章节进出Mapbox GL JS 负责看到哪——相机飞行、图层显影、3D 地形渲染。src/index.html用不到 500 行代码把两者焊接成一条滚动 → 飞行 → 显影的叙事流水线。理解了这条链路你既能快速产出数据故事也能顺手魔改出自带的自动翻页、旋转镜头等效果。【免费下载链接】storytellingStorytelling with maps template项目地址: https://gitcode.com/gh_mirrors/st/storytelling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考