qwantresearch/erdapfel

Erdapfel

Erdapfel是Qwant Maps的前端应用，是一个JavaScript单页应用，支持地图浏览、地点搜索、查看个人位置等功能。

!https://raw.githubusercontent.com/QwantResearch/qwantmaps/master/screenshot.png

如需Qwant Maps的整体概述及各组件详情，可查看https://github.com/QwantResearch/qwantmaps/%E4%BB%93%E5%BA%93%E3%80%82

镜像概述和主要用途

Erdapfel作为Qwant Maps的前端层，负责用户交互界面的呈现与功能实现。其核心用途是提供地图浏览体验，包括地图可视化、地点搜索、位置定位等，并通过配置连接后端服务（如瓦片服务器、地理编码器等）实现完整功能。

核心功能和特性

• 地图交互：支持地图浏览、缩放、平移等基础操作
• 地点搜索：集成地理编码服务，实现地点查询与定位
• 位置服务：支持获取并显示用户当前位置
• 配置灵活：通过配置文件或环境变量自定义服务连接
• 多环境支持：可通过npm命令构建开发/生产模式，支持Docker部署
• 可扩展性：支持自定义瓦片服务器，满足个性化地图需求

使用场景和适用范围

• Qwant Maps前端服务部署
• 地图应用开发与测试
• 自定义地图服务前端构建
• 需要地图浏览和地点搜索功能的Web应用集成

使用方法和配置说明

配置

Erdapfel依赖多个后端服务，需通过配置定义服务交互方式。默认配置文件见https://github.com/QwantResearch/erdapfel/blob/master/config/default_config.yml%EF%BC%8C%E9%9C%80%E6%9B%B4%E6%96%B0%E4%BB%A5%E4%B8%8B%E5%85%B3%E9%94%AE%E6%9C%8D%E5%8A%A1URL%EF%BC%9A

• 瓦片服务器（tile server）：用于地图显示
• 地理编码器（geocoder）：用于地点搜索
• 地点API（place API）：用于显示地点详情
• 存储应用（storage app）：用于存储收藏地点

环境变量覆盖配置

配置可通过环境变量覆盖，变量需以TILEVIEW_为前缀，嵌套结构通过_分隔。例如：

yaml
# 配置文件中
system:
  timeout: 5

可通过环境变量TILEVIEW_system_timeout=10覆盖。

加载.env文件

可在项目根目录创建.env文件定义环境变量，启动时会自动加载。

从源码运行

依赖要求

• npm >= 6.13
• Node.js 10

构建与启动命令

bash
# 安装依赖
npm install

# 构建（生产模式）
npm run build

# 构建（开发模式）
npm run build -- --mode=development

# 启动应用
npm start

参考：https://github.com/QwantResearch/erdapfel/blob/master/docs/src/windows.md

使用Docker运行

拉取Docker镜像：

bash
docker pull qwantresearch/erdapfel

启动容器示例（设置自定义瓦片服务器）：

bash
docker run -d \
  -e TILEVIEW_mapStyle_baseMapUrl='["http://your-server/basemap-tiles/{z}/{x}/{y}.pbf"]' \
  -e TILEVIEW_mapStyle_poiMapUrl='["http://your-server/poi-tiles/{z}/{x}/{y}.pbf"]' \
  -p 8080:8080 \
  qwantresearch/erdapfel

开发指南

项目文档

• https://github.com/QwantResearch/erdapfel/blob/master/docs/src/project_structure.md
• https://github.com/QwantResearch/erdapfel/blob/master/docs/src/i18n.md
• https://github.com/QwantResearch/erdapfel/blob/master/docs/src/code_convention.md
• https://github.com/QwantResearch/erdapfel/blob/master/docs/src/tests.md

![Travis构建状态]([***]

使用自定义瓦片服务器

通过环境变量配置自定义瓦片服务器：

bash
TILEVIEW_mapStyle_baseMapUrl='["http://your-server/basemap-tiles/{z}/{x}/{y}.pbf"]' \
TILEVIEW_mapStyle_poiMapUrl='["http://your-server/poi-tiles/{z}/{x}/{y}.pbf"]' \
npm start

• TILEVIEW_mapStyle_baseMapUrl：地图基础瓦片服务器
• TILEVIEW_mapStyle_poiMapUrl：POI（兴趣点）瓦片服务器
• {z}/{x}/{y}.pbf为必填路径格式，用于定位和缩放

本地Node TLS错误处理（仅开发调试，禁止生产环境使用）

开发环境中可能出现TLS证书错误：

text
"msg":"unable to get local issuer certificate"

可通过以下命令临时绕过（生产环境禁止使用）：

bash
NODE_TLS_REJECT_UNAUTHORIZED=0 npm run start

Web字体说明

图标字体来自icomoon，项目文件为dev/erdapfel_iconmoon.json，可拖拽至icomoon网页编辑。

测试

全部测试

bash
TEST=true npm run build
npm run test

单元测试

bash
npm run unit-test

集成测试

bash
npm run integration-test

测试详情参考https://github.com/QwantResearch/erdapfel/blob/master/docs/src/tests.md

基准测试

bash
npm run bench

构建生产包并返回大小和JS执行时间指标，用于跟踪应用性能变化。

入口点

样式接口

/style.json提供预构建样式（支持语言参数），由https://github.com/QwantResearch/map-style-builder%E7%94%9F%E6%88%90%EF%BC%8C%E5%9C%B0%E5%9B%BE%E6%96%87%E6%9C%AC%E5%AD%97%E4%BD%93%E9%80%9A%E8%BF%87https://github.com/QwantResearch/fonts%E6%9E%84%E5%BB%BA%E3%80%82

参数说明

开发技巧

获取地图当前显示项信息

在浏览器开发者控制台执行，建议在高缩放级别（显示项较少）下操作：

js
let objs = window.map.mb.queryRenderedFeatures();
// objs为数组，遍历查找目标项

window.map.mb为mapbox-gl对象，详情参考mapbox-gl文档，queryRenderedFeatures方法文档见此处。

修改最大缩放级别

js
// 在浏览器开发者控制台执行
window.map.mb.setMaxZoom(25); // 默认最大缩放级别为20

开发环境HTTPS配置

设置环境变量HTTPS=true自动生成自签名证书：

bash
HTTPS=true npm start

许可证

本项目采用Apache License 2.0许可证。请注意，其依赖多个其他开源项目，各项目有独立的条款和条件。