企业官网建设流程全解析

Timeline Visualizer二次开发指南：fork后如何自定义地图风格与主题色

【免费下载链接】google-timeline-visualizerVisualize your year in travel using your Google Location History (Timeline) data项目地址: https://gitcode.com/GitHub_Trending/go/google-timeline-visualizer

Timeline Visualizer是一款把 Google 位置历史（Timeline）导出文件变成动态旅行视频的开源项目。很多新手 fork 仓库后都想动手改造它：换一套地图底图风格，或者把标志性玫红色主题色换成自己喜欢的配色。本文将带你快速定位地图渲染与主题色的核心代码，并给出 Android、Web、桌面 Python 三端各自的修改方法。

1. 先看懂项目结构，找到地图相关代码

Timeline Visualizer 有三个可渲染端，地图瓦片逻辑各自独立但思路一致：

三个端都默认使用 CARTO 的light_all浅色底图（基于 OpenStreetMap 数据），瓦片 URL 模板类似：

https://a.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png

fork 后先跑通一次构建，确认基线正常：

git clone https://gitcode.com/GitHub_Trending/go/google-timeline-visualizer

2. 自定义地图风格：换底图最快的 3 个位置

地图风格（浅色/深色/地形图等）由瓦片 URL 决定，改动集中在下面几处：

• Android：TileRepository.kt 中的cartoTileUrl()函数拼接瓦片地址，把light_all换成 CARTO 其他图层（如dark_matter、rastertiles/voyager）即可切换风格。
• Web：web/src/renderer.ts 中的TILE_TEMPLATE常量与cartoTileUrl()函数，改法相同；画布底色#f2edf0也在这里，建议与底图背景保持一致，避免边缘露白。
• Python CLI：visualizer.py 的TILE_URL与carto_tile_url()函数。

💡 提示：底图服务需要 API Key。Android 构建时通过环境变量CARTO_BASEMAP_API_KEY注入（见 app/build.gradle.kts），Web 端用VITE_CARTO_BASEMAP_API_KEY，Python 端直接读同名环境变量。本地开发：

export CARTO_BASEMAP_API_KEY="your-project-key"

换底图后，别忘了让瓦片缓存失效（Android 端缓存在carto-tiles-v2目录，见 TileRepository.kt），否则预览还是旧图。

3. 自定义主题色：一处改动，全局生效

项目默认品牌色是玫红色#E90064，主题色分散在两层：

第一层：UI 主题色（按钮、导航、背景）

• 浅色主题：app/src/main/res/values/colors.xml 中的brand与interactive
• 深色主题：app/src/main/res/values-night/colors.xml，记得两处同步改
• 主题组装：app/src/main/res/values/themes.xml，这里把颜色绑定到 Material3 的colorPrimary等槽位，一般无需改动

把#E90064改为你想要的色值（例如深蓝#1A56DB），重建后整个界面的按钮、选中态、图标着色都会跟着变。

第二层：地图上的轨迹线颜色

轨迹线、移动标记的描边色硬编码在 TimelinePainter.kt 的几组Paint里（oldTrailPaint、middleTrailPaint、recentTrailPaint、headRingPaint均使用Color.rgb(233, 0, 100)）。建议把它们提取为可配置常量，再统一替换成你的品牌色，预览和导出视频会同时生效。

Web 端对应的是 web/src/renderer.ts 中的轨迹宽度与颜色常量，以及页面整体样式 web/src/style.css。

4. 保持地图署名：别删 attribution

无论换哪套底图，预览和导出视频中都必须保留署名文字：

© OpenStreetMap contributors © CARTO

这是许可证要求。三端各自定义了MAP_ATTRIBUTION常量（visualizer.py、web/src/renderer.ts），项目用测试 tests/test_carto_configuration.py 校验底图配置，改动后跑一下可以防止漏改：

./gradlew test lint python -m pytest

隐私细节（瓦片请求会向底图服务透露浏览区域）参见 docs/privacy.md。

5. 验证你的定制效果

1. 导入一份样例 Timeline 文件（仓库自带 test-fixtures/seoul-bohol-sample.json）
2. 选择日期区间，点击 Preview 查看新底图与轨迹颜色
3. 生成一段 10 秒以内的 MP4，确认导出视频中的颜色与署名正确

按「底图 URL → 主题颜色值 → 轨迹 Paint 常量」这条路径修改，基本就覆盖了自定义地图风格与主题色的全部要点。改完记得提交前跑一遍完整测试，让上游合并你的改动时更顺利 🚀

【免费下载链接】google-timeline-visualizerVisualize your year in travel using your Google Location History (Timeline) data项目地址: https://gitcode.com/GitHub_Trending/go/google-timeline-visualizer