syncfusion-flutter-maps
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSyncfusion Flutter Maps
Syncfusion Flutter Maps
This skill covers the Syncfusion Flutter Maps (SfMaps) widget for displaying and visualizing geographical and spatial data. The widget supports two primary layer types: MapShapeLayer (for GeoJSON-based shape rendering) and MapTileLayer (for web map tile services like OpenStreetMap and Bing Maps).
本技能介绍用于展示和可视化地理空间数据的Syncfusion Flutter Maps (SfMaps) 组件。该组件支持两种核心图层类型:MapShapeLayer(用于基于GeoJSON的形状渲染)和MapTileLayer(用于对接OpenStreetMap、Bing Maps等web地图瓦片服务)。
When to Use This Skill
什么时候使用本技能
Use this skill when you need to:
- Display interactive maps with zoom, pan, and selection capabilities
- Visualize geographical data using shapes, colors, and bubbles
- Render GeoJSON data as maps (countries, states, regions, custom shapes)
- Integrate tile-based maps from OpenStreetMap, Bing Maps, Google Maps, or TomTom
- Add markers to maps for locations, points of interest, or custom coordinates
- Create choropleth maps with color-coded regions based on data values
- Build bubble maps showing data through size and color variations
- Display data labels and legends for map interpretation
- Implement tooltips for shapes, bubbles, and markers
- Enable map interactions including selection, zoom, pan, and navigation
- Add vector layers (arcs, circles, lines, polygons, polylines) for custom overlays
- Visualize spatial relationships with sublayers and hierarchical data
- Create location-based applications with coordinate mapping
当你需要实现以下功能时可以使用本技能:
- 展示支持缩放、平移、选择功能的交互式地图
- 使用形状、颜色、气泡可视化地理数据
- 将GeoJSON数据渲染为地图(国家、省份、区域、自定义形状)
- 集成来自OpenStreetMap、Bing Maps、Google Maps或TomTom的瓦片地图
- 为地点、兴趣点或自定义坐标在地图上添加标记
- 基于数据值创建颜色编码区域的分级统计地图
- 通过尺寸和颜色变化展示数据的气泡地图
- 展示数据标签和图例方便地图解读
- 为形状、气泡、标记实现提示框
- 启用包括选择、缩放、平移、导航在内的地图交互能力
- 添加矢量图层(弧线、圆形、线条、多边形、折线)作为自定义覆盖层
- 通过子图层和层级数据可视化空间关系
- 开发支持坐标映射的位置类应用
Component Overview
组件概览
The SfMaps widget is a comprehensive mapping solution for Flutter that supports two primary layer types:
MapShapeLayer - GeoJSON-based shape rendering for statistical and geographical data visualization. Features include choropleth maps with color/range mapping, bubble visualizations, data labels, shape selection, legends, tooltips, sublayers for hierarchical data, vector layers (arcs, circles, lines, polygons, polylines), markers, zoom and pan gestures, and offline support. Ideal for election maps, sales territories, census data, and region-based analytics.
MapTileLayer - Web map tile service integration for OpenStreetMap, Bing Maps, Google Maps, and TomTom. Features include real-world street maps with detailed geography, markers for location pins, sublayers, vector layers, zoom and pan with configurable levels, initial focal point and zoom, and WMTS URL templates. Requires internet connectivity. Perfect for store locators, delivery tracking, and navigation apps.
Both layer types support markers (built-in symbols and custom widgets), zoom/pan behavior with pinch/mouse wheel/double-tap gestures, vector layer overlays, accessibility features, RTL support, and theming through .
SfMapsThemeSfMaps 是Flutter的全功能地图解决方案,支持两种核心图层类型:
MapShapeLayer - 基于GeoJSON的形状渲染,用于统计和地理数据可视化。功能包括支持颜色/范围映射的分级统计图、气泡可视化、数据标签、形状选择、图例、提示框、层级数据子图层、矢量图层(弧线、圆形、线条、多边形、折线)、标记、缩放手势、离线支持。适用于选举地图、销售区域地图、人口普查数据、区域分析等场景。
MapTileLayer - 对接OpenStreetMap、Bing Maps、Google Maps、TomTom等web地图瓦片服务。功能包括包含详细地理信息的真实世界街道地图、位置标记、子图层、矢量图层、可配置级别的缩放平移、初始中心点和缩放级别、WMTS URL模板。需要联网使用,适用于门店定位、配送跟踪、导航应用等场景。
两种图层类型都支持标记(内置符号和自定义组件)、捏合/滚轮/双击缩放平移手势、矢量图层覆盖、无障碍功能、RTL支持,以及通过实现主题定制。
SfMapsThemeChoosing the Right Layer Type
选择合适的图层类型
Use MapShapeLayer when:
以下场景选择MapShapeLayer:
- You have GeoJSON data defining geographical shapes
- You need choropleth maps (color-coded by region/country)
- Your data is statistical and tied to geographical boundaries
- You want complete control over shape appearance and data binding
- You need offline maps that don't require external tile services
- Custom shapes or specific regions need to be highlighted
- Building: election maps, sales territory maps, census data visualizations, region comparisons
- 你有定义地理形状的GeoJSON数据
- 你需要实现分级统计地图(按区域/国家进行颜色编码)
- 你的数据是与地理边界关联的统计类数据
- 你需要完全控制形状的外观和数据绑定
- 你需要不依赖外部瓦片服务的离线地图
- 需要高亮自定义形状或特定区域
- 开发场景:选举地图、销售区域地图、人口普查数据可视化、区域对比
Use MapTileLayer when:
以下场景选择MapTileLayer:
- You need real-world street maps from providers like OpenStreetMap
- Your app requires detailed geographical features (roads, landmarks, terrain)
- Online connectivity is available for tile loading
- You want standard map views without custom data rendering
- Street-level detail or satellite imagery is needed
- You need to show precise locations on familiar map backgrounds
- Building: store locators, delivery tracking, navigation apps, location pickers
- 你需要来自OpenStreetMap等服务商的真实世界街道地图
- 你的应用需要详细的地理特征(道路、地标、地形)
- 有网络连接支持瓦片加载
- 你需要不需要自定义数据渲染的标准地图视图
- 需要街道级细节或卫星影像
- 你需要在大众熟悉的地图背景上展示精确位置
- 开发场景:门店定位、配送跟踪、导航应用、位置选择器
Key Differences Summary:
核心差异汇总:
| Feature | MapShapeLayer | MapTileLayer |
|---|---|---|
| Data Source | GeoJSON files | Web tile services (URLs) |
| Offline Support | ✅ Yes (embedded GeoJSON) | ❌ Requires internet |
| Data Binding | ✅ Full support | ❌ Limited to markers |
| Choropleth Maps | ✅ Yes | ❌ No |
| Bubble Visualization | ✅ Yes | ❌ No |
| Data Labels | ✅ Yes | ❌ No |
| Shape Selection | ✅ Yes | ❌ No |
| Color Mapping | ✅ Yes | ❌ No |
| Legend | ✅ Yes | ❌ No |
| Markers | ✅ Yes | ✅ Yes |
| Zoom & Pan | ✅ Yes | ✅ Yes |
| Street Maps | ❌ No | ✅ Yes |
| Sublayers | ✅ Yes | ✅ Yes |
| Vector Layers | ✅ Yes (arc, circle, line, etc.) | ✅ Yes (arc, circle, line, etc.) |
| Tooltips | ✅ Yes (shapes & bubbles) | ❌ Limited |
| Real-world Detail | ❌ Limited | ✅ High detail |
| 功能 | MapShapeLayer | MapTileLayer |
|---|---|---|
| 数据源 | GeoJSON文件 | web瓦片服务(URL) |
| 离线支持 | ✅ 支持(内嵌GeoJSON) | ❌ 需要联网 |
| 数据绑定 | ✅ 完全支持 | ❌ 仅支持标记 |
| 分级统计图 | ✅ 支持 | ❌ 不支持 |
| 气泡可视化 | ✅ 支持 | ❌ 不支持 |
| 数据标签 | ✅ 支持 | ❌ 不支持 |
| 形状选择 | ✅ 支持 | ❌ 不支持 |
| 颜色映射 | ✅ 支持 | ❌ 不支持 |
| 图例 | ✅ 支持 | ❌ 不支持 |
| 标记 | ✅ 支持 | ✅ 支持 |
| 缩放平移 | ✅ 支持 | ✅ 支持 |
| 街道地图 | ❌ 不支持 | ✅ 支持 |
| 子图层 | ✅ 支持 | ✅ 支持 |
| 矢量图层 | ✅ 支持(弧线、圆形、线条等) | ✅ 支持(弧线、圆形、线条等) |
| 提示框 | ✅ 支持(形状和气泡) | ❌ 支持有限 |
| 真实世界细节 | ❌ 有限 | ✅ 高细节 |
Documentation and Navigation Guide
文档与使用指南
Getting Started
入门指南
📄 Read: references/getting-started.md
- Installation and package setup
- Basic MapShapeLayer implementation
- Basic MapTileLayer implementation
- Loading GeoJSON data (asset, network, memory)
- OpenStreetMap quick start
- Package dependencies and imports
📄 阅读: references/getting-started.md
- 安装与包配置
- 基础MapShapeLayer实现
- 基础MapTileLayer实现
- 加载GeoJSON数据(本地资源、网络、内存)
- OpenStreetMap快速入门
- 包依赖和导入
Layer Overview
图层概览
📄 For Shape Layer: references/shape-layer.md
- MapShapeLayer widget overview and features
- GeoJSON data source configuration
- Shape data field mapping
- Shape appearance (color, stroke)
- Loading progress indicator
- When to use Shape Layer
- Basic shape rendering
📄 For Tile Layer: references/tile-layer.md
- MapTileLayer widget overview and features
- URL template format (WMTS)
- OpenStreetMap integration
- Bing Maps setup and API keys
- Other providers (TomTom, MapBox, Google Maps)
- Initial focal point configuration
- Initial zoom level setup
📄 形状层相关: references/shape-layer.md
- MapShapeLayer组件概览与功能
- GeoJSON数据源配置
- 形状数据字段映射
- 形状外观(颜色、边框)
- 加载进度指示器
- 形状层适用场景
- 基础形状渲染
📄 瓦片层相关: references/tile-layer.md
- MapTileLayer组件概览与功能
- URL模板格式(WMTS)
- OpenStreetMap集成
- Bing Maps配置与API密钥
- 其他服务商(TomTom、MapBox、Google Maps)
- 初始中心点配置
- 初始缩放级别设置
Markers
标记
📄 Read: references/markers.md
- Adding markers to both layer types
- Built-in marker symbols (circle, diamond, triangle, etc.)
- Custom marker widgets
- Marker positioning (latitude/longitude)
- Marker appearance customization
- Dynamic marker management (add/update/remove)
- Marker controllers (MapShapeLayerController/MapTileLayerController)
- Marker alignment and offset
- Zoom markers to fit bounds
📄 阅读: references/markers.md
- 为两种图层添加标记
- 内置标记符号(圆形、菱形、三角形等)
- 自定义标记组件
- 标记定位(经纬度)
- 标记外观自定义
- 动态标记管理(添加/更新/删除)
- 标记控制器(MapShapeLayerController/MapTileLayerController)
- 标记对齐与偏移
- 缩放标记适配边界
Data Visualization Features (Shape Layer)
数据可视化功能(形状层)
📄 Read: references/data-labels.md
- Showing data labels on shapes
- Data label mapper configuration
- Label text customization
- Label trimming and overflow handling
- Label styling and positioning
📄 Read: references/legend.md
- Legend configuration and positioning
- Legend for shape colors
- Legend for bubbles
- Legend customization (icons, text, layout)
- Legend toggling feature
- Legend interactions
📄 Read: references/tooltip.md
- Shape tooltips with builders
- Bubble tooltips
- Marker tooltips
- Tooltip customization
- Tooltip styling and positioning
- Tooltip settings (color, stroke, padding)
📄 Read: references/bubble.md
- Bubble visualization overview
- Bubble size mapping based on data
- Bubble color mapping
- Bubble appearance customization
- Bubble tooltips
- Use cases for bubble maps
📄 阅读: references/data-labels.md
- 在形状上展示数据标签
- 数据标签映射器配置
- 标签文本自定义
- 标签裁剪与溢出处理
- 标签样式与定位
📄 阅读: references/legend.md
- 图例配置与定位
- 形状颜色图例
- 气泡图例
- 图例自定义(图标、文本、布局)
- 图例切换功能
- 图例交互
📄 阅读: references/tooltip.md
- 带构建器的形状提示框
- 气泡提示框
- 标记提示框
- 提示框自定义
- 提示框样式与定位
- 提示框设置(颜色、边框、内边距)
📄 阅读: references/bubble.md
- 气泡可视化概览
- 基于数据的气泡大小映射
- 气泡颜色映射
- 气泡外观自定义
- 气泡提示框
- 气泡地图适用场景
Color and Data Mapping
颜色与数据映射
📄 Read: references/color-mapping.md
- Equal color mapping (discrete values)
- Range color mapping (continuous ranges)
- Shape color value mapper
- Bubble color value mapper
- Color mappers configuration
- Opacity settings (min/max)
- Returning colors directly vs using mappers
- Color mapping patterns
📄 阅读: references/color-mapping.md
- 等值颜色映射(离散值)
- 范围颜色映射(连续范围)
- 形状颜色值映射器
- 气泡颜色值映射器
- 颜色映射器配置
- 透明度设置(最小/最大)
- 直接返回颜色 vs 使用映射器
- 颜色映射模式
Selection and Interaction
选择与交互
📄 Read: references/selection.md
- Shape selection feature
- Selection callbacks
- Selection styling and decoration
- Single vs multi-selection
- Programmatic selection
- Toggling selection
📄 Read: references/zoom-pan.md
- MapZoomPanBehavior configuration
- Pinch zoom (mobile)
- Mouse wheel zoom (desktop)
- Zoom toolbar (web platform)
- Double-tap zoom
- Zoom level configuration
- Pan behavior and restrictions
- Focal latitude/longitude bounds
- Zoom callbacks and events
📄 阅读: references/selection.md
- 形状选择功能
- 选择回调
- 选择样式与装饰
- 单选 vs 多选
- 程序化选择
- 切换选择状态
📄 阅读: references/zoom-pan.md
- MapZoomPanBehavior配置
- 捏合缩放(移动端)
- 滚轮缩放(桌面端)
- 缩放工具栏(web端)
- 双击缩放
- 缩放级别配置
- 平移行为与限制
- 经纬度边界范围
- 缩放回调与事件
Advanced Features
高级功能
📄 Read: references/vector-layers.md
- MapArcLayer (arcs between two coordinates)
- MapCircleLayer (circles at specific coordinates)
- MapLineLayer (lines connecting coordinates)
- MapPolygonLayer (polygon shapes)
- MapPolylineLayer (connected line segments)
- Vector layer styling and customization
- Use cases for each vector type
📄 Read: references/shape-sublayer.md
- Adding sublayers to MapShapeLayer
- Sublayer configuration and nesting
- Sublayer markers and bubbles
- Hierarchical data visualization
- Use cases for sublayers
📄 阅读: references/vector-layers.md
- MapArcLayer(两点间的弧线)
- MapCircleLayer(指定坐标的圆形)
- MapLineLayer(连接坐标的线条)
- MapPolygonLayer(多边形形状)
- MapPolylineLayer(连接的线段)
- 矢量图层样式与自定义
- 各类矢量类型的适用场景
📄 阅读: references/shape-sublayer.md
- 为MapShapeLayer添加子图层
- 子图层配置与嵌套
- 子图层标记与气泡
- 层级数据可视化
- 子图层适用场景
Customization and Theming
自定义与主题
📄 Read: references/customization.md
- SfMapsTheme integration
- Visual appearance customization
- Shape styling (colors, borders)
- Hover effects (web platform)
- Theme integration
- Responsive design patterns
- Custom map styling
📄 Read: references/accessibility.md
- Screen reader support
- Semantic labels for shapes
- Keyboard navigation
- WCAG compliance
- Focus indicators
- Accessible map interactions
📄 阅读: references/customization.md
- SfMapsTheme集成
- 视觉外观自定义
- 形状样式(颜色、边框)
- 悬停效果(web端)
- 主题集成
- 响应式设计模式
- 自定义地图样式
📄 阅读: references/accessibility.md
- 屏幕阅读器支持
- 形状语义标签
- 键盘导航
- WCAG合规
- 焦点指示器
- 无障碍地图交互
Quick Start Examples
快速入门示例
Basic Shape Layer with GeoJSON
基础GeoJSON形状层
dart
import 'package:flutter/material.dart';
import 'package:syncfusion_flutter_maps/maps.dart';
class MyShapeMap extends StatefulWidget {
_MyShapeMapState createState() => _MyShapeMapState();
}
class _MyShapeMapState extends State<MyShapeMap> {
late MapShapeSource _dataSource;
void initState() {
super.initState();
_dataSource = MapShapeSource.asset(
'assets/world_map.json',
shapeDataField: 'name',
);
}
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: Text('World Map')),
body: Padding(
padding: EdgeInsets.all(15),
child: SfMaps(
layers: [
MapShapeLayer(
source: _dataSource,
color: Colors.blue[100],
strokeColor: Colors.blue,
strokeWidth: 0.5,
),
],
),
),
);
}
}dart
import 'package:flutter/material.dart';
import 'package:syncfusion_flutter_maps/maps.dart';
class MyShapeMap extends StatefulWidget {
_MyShapeMapState createState() => _MyShapeMapState();
}
class _MyShapeMapState extends State<MyShapeMap> {
late MapShapeSource _dataSource;
void initState() {
super.initState();
_dataSource = MapShapeSource.asset(
'assets/world_map.json',
shapeDataField: 'name',
);
}
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: Text('World Map')),
body: Padding(
padding: EdgeInsets.all(15),
child: SfMaps(
layers: [
MapShapeLayer(
source: _dataSource,
color: Colors.blue[100],
strokeColor: Colors.blue,
strokeWidth: 0.5,
),
],
),
),
);
}
}Basic Tile Layer with OpenStreetMap
基础OpenStreetMap瓦片层
dart
import 'package:flutter/material.dart';
import 'package:syncfusion_flutter_maps/maps.dart';
class MyTileMap extends StatelessWidget {
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: Text('OpenStreetMap')),
body: SfMaps(
layers: [
MapTileLayer(
urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
initialFocalLatLng: MapLatLng(27.1751, 78.0421),
initialZoomLevel: 5,
),
],
),
);
}
}dart
import 'package:flutter/material.dart';
import 'package:syncfusion_flutter_maps/maps.dart';
class MyTileMap extends StatelessWidget {
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: Text('OpenStreetMap')),
body: SfMaps(
layers: [
MapTileLayer(
urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
initialFocalLatLng: MapLatLng(27.1751, 78.0421),
initialZoomLevel: 5,
),
],
),
);
}
}Choropleth Map with Color Mapping
带颜色映射的分级统计图
dart
class ChoroplethMap extends StatefulWidget {
_ChoroplethMapState createState() => _ChoroplethMapState();
}
class _ChoroplethMapState extends State<ChoroplethMap> {
late List<Model> _data;
late MapShapeSource _dataSource;
void initState() {
super.initState();
_data = [
Model('India', 280),
Model('United States of America', 190),
Model('Brazil', 120),
];
_dataSource = MapShapeSource.asset(
'assets/world_map.json',
shapeDataField: 'name',
dataCount: _data.length,
primaryValueMapper: (int index) => _data[index].country,
shapeColorValueMapper: (int index) => _data[index].value,
shapeColorMappers: [
MapColorMapper(from: 0, to: 100, color: Colors.red),
MapColorMapper(from: 101, to: 300, color: Colors.green),
],
);
}
Widget build(BuildContext context) {
return Scaffold(
body: SfMaps(
layers: [
MapShapeLayer(
source: _dataSource,
legend: MapLegend(MapElement.shape),
showDataLabels: true,
),
],
),
);
}
}
class Model {
Model(this.country, this.value);
final String country;
final double value;
}dart
class ChoroplethMap extends StatefulWidget {
_ChoroplethMapState createState() => _ChoroplethMapState();
}
class _ChoroplethMapState extends State<ChoroplethMap> {
late List<Model> _data;
late MapShapeSource _dataSource;
void initState() {
super.initState();
_data = [
Model('India', 280),
Model('United States of America', 190),
Model('Brazil', 120),
];
_dataSource = MapShapeSource.asset(
'assets/world_map.json',
shapeDataField: 'name',
dataCount: _data.length,
primaryValueMapper: (int index) => _data[index].country,
shapeColorValueMapper: (int index) => _data[index].value,
shapeColorMappers: [
MapColorMapper(from: 0, to: 100, color: Colors.red),
MapColorMapper(from: 101, to: 300, color: Colors.green),
],
);
}
Widget build(BuildContext context) {
return Scaffold(
body: SfMaps(
layers: [
MapShapeLayer(
source: _dataSource,
legend: MapLegend(MapElement.shape),
showDataLabels: true,
),
],
),
);
}
}
class Model {
Model(this.country, this.value);
final String country;
final double value;
}Map with Markers
带标记的地图
dart
class MapWithMarkers extends StatefulWidget {
_MapWithMarkersState createState() => _MapWithMarkersState();
}
class _MapWithMarkersState extends State<MapWithMarkers> {
late List<MarkerData> _markers;
late MapShapeSource _dataSource;
void initState() {
super.initState();
_markers = [
MarkerData('New York', 40.7128, -74.0060),
MarkerData('London', 51.5074, -0.1278),
MarkerData('Tokyo', 35.6762, 139.6503),
];
_dataSource = MapShapeSource.asset(
'assets/world_map.json',
shapeDataField: 'name',
);
}
Widget build(BuildContext context) {
return Scaffold(
body: SfMaps(
layers: [
MapShapeLayer(
source: _dataSource,
initialMarkersCount: _markers.length,
markerBuilder: (BuildContext context, int index) {
return MapMarker(
latitude: _markers[index].latitude,
longitude: _markers[index].longitude,
iconColor: Colors.red,
iconType: MapIconType.circle,
size: Size(15, 15),
child: null,
);
},
),
],
),
);
}
}
class MarkerData {
MarkerData(this.city, this.latitude, this.longitude);
final String city;
final double latitude;
final double longitude;
}dart
class MapWithMarkers extends StatefulWidget {
_MapWithMarkersState createState() => _MapWithMarkersState();
}
class _MapWithMarkersState extends State<ChoroplethMapState> {
late List<MarkerData> _markers;
late MapShapeSource _dataSource;
void initState() {
super.initState();
_markers = [
MarkerData('New York', 40.7128, -74.0060),
MarkerData('London', 51.5074, -0.1278),
MarkerData('Tokyo', 35.6762, 139.6503),
];
_dataSource = MapShapeSource.asset(
'assets/world_map.json',
shapeDataField: 'name',
);
}
Widget build(BuildContext context) {
return Scaffold(
body: SfMaps(
layers: [
MapShapeLayer(
source: _dataSource,
initialMarkersCount: _markers.length,
markerBuilder: (BuildContext context, int index) {
return MapMarker(
latitude: _markers[index].latitude,
longitude: _markers[index].longitude,
iconColor: Colors.red,
iconType: MapIconType.circle,
size: Size(15, 15),
child: null,
);
},
),
],
),
);
}
}
class MarkerData {
MarkerData(this.city, this.latitude, this.longitude);
final String city;
final double latitude;
final double longitude;
}Common Patterns
常用模式
Pattern 1: Interactive Choropleth Map with Selection
模式1:带选择功能的交互式分级统计图
dart
// Common pattern for election results, sales data by region, etc.
late MapShapeSource _dataSource;
int? _selectedIndex;
_dataSource = MapShapeSource.asset(
'assets/usa_states.json',
shapeDataField: 'name',
dataCount: _statesData.length,
primaryValueMapper: (index) => _statesData[index].state,
shapeColorValueMapper: (index) => _statesData[index].value,
shapeColorMappers: [
MapColorMapper(from: 0, to: 50, color: Colors.red),
MapColorMapper(from: 51, to: 100, color: Colors.blue),
],
);
MapShapeLayer(
source: _dataSource,
legend: MapLegend(MapElement.shape),
showDataLabels: true,
onSelectionChanged: (int index) {
setState(() {
_selectedIndex = index;
});
},
selectionSettings: MapSelectionSettings(
color: Colors.yellow,
strokeColor: Colors.black,
strokeWidth: 2,
),
)dart
// 适用于选举结果、区域销售数据等场景
late MapShapeSource _dataSource;
int? _selectedIndex;
_dataSource = MapShapeSource.asset(
'assets/usa_states.json',
shapeDataField: 'name',
dataCount: _statesData.length,
primaryValueMapper: (index) => _statesData[index].state,
shapeColorValueMapper: (index) => _statesData[index].value,
shapeColorMappers: [
MapColorMapper(from: 0, to: 50, color: Colors.red),
MapColorMapper(from: 51, to: 100, color: Colors.blue),
],
);
MapShapeLayer(
source: _dataSource,
legend: MapLegend(MapElement.shape),
showDataLabels: true,
onSelectionChanged: (int index) {
setState(() {
_selectedIndex = index;
});
},
selectionSettings: MapSelectionSettings(
color: Colors.yellow,
strokeColor: Colors.black,
strokeWidth: 2,
),
)Pattern 2: Tile Layer with Custom Markers
模式2:带自定义标记的瓦片层
dart
// Common pattern for store locator, delivery tracking
late List<LocationData> _locations;
late MapTileLayerController _controller;
void initState() {
_controller = MapTileLayerController();
_locations = [/* your location data */];
super.initState();
}
MapTileLayer(
urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
initialFocalLatLng: MapLatLng(37.7749, -122.4194),
initialZoomLevel: 10,
controller: _controller,
initialMarkersCount: _locations.length,
markerBuilder: (context, index) {
return MapMarker(
latitude: _locations[index].latitude,
longitude: _locations[index].longitude,
child: Icon(Icons.location_pin, color: Colors.red, size: 30),
);
},
zoomPanBehavior: MapZoomPanBehavior(
enableDoubleTapZooming: true,
enablePinching: true,
enablePanning: true,
),
)dart
// 适用于门店定位、配送跟踪等场景
late List<LocationData> _locations;
late MapTileLayerController _controller;
void initState() {
_controller = MapTileLayerController();
_locations = [/* 你的位置数据 */];
super.initState();
}
MapTileLayer(
urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
initialFocalLatLng: MapLatLng(37.7749, -122.4194),
initialZoomLevel: 10,
controller: _controller,
initialMarkersCount: _locations.length,
markerBuilder: (context, index) {
return MapMarker(
latitude: _locations[index].latitude,
longitude: _locations[index].longitude,
child: Icon(Icons.location_pin, color: Colors.red, size: 30),
);
},
zoomPanBehavior: MapZoomPanBehavior(
enableDoubleTapZooming: true,
enablePinching: true,
enablePanning: true,
),
)Pattern 3: Map with Bubbles and Tooltips
模式3:带气泡和提示框的地图
dart
// Common pattern for population density, sales volume visualization
_dataSource = MapShapeSource.asset(
'assets/world_map.json',
shapeDataField: 'name',
dataCount: _data.length,
primaryValueMapper: (index) => _data[index].country,
bubbleSizeMapper: (index) => _data[index].population,
bubbleColorValueMapper: (index) => _data[index].density,
);
MapShapeLayer(
source: _dataSource,
showDataLabels: true,
legend: MapLegend.bar(MapElement.bubble),
bubbleSettings: MapBubbleSettings(
maxRadius: 50,
minRadius: 10,
color: Colors.blue,
),
shapeTooltipBuilder: (context, index) {
return Padding(
padding: EdgeInsets.all(8),
child: Text(
'${_data[index].country}: ${_data[index].population}M',
style: TextStyle(color: Colors.white),
),
);
},
bubbleTooltipBuilder: (context, index) {
return Padding(
padding: EdgeInsets.all(8),
child: Text(
'Density: ${_data[index].density}/km²',
style: TextStyle(color: Colors.white),
),
);
},
)dart
// 适用于人口密度、销售额可视化等场景
_dataSource = MapShapeSource.asset(
'assets/world_map.json',
shapeDataField: 'name',
dataCount: _data.length,
primaryValueMapper: (index) => _data[index].country,
bubbleSizeMapper: (index) => _data[index].population,
bubbleColorValueMapper: (index) => _data[index].density,
);
MapShapeLayer(
source: _dataSource,
showDataLabels: true,
legend: MapLegend.bar(MapElement.bubble),
bubbleSettings: MapBubbleSettings(
maxRadius: 50,
minRadius: 10,
color: Colors.blue,
),
shapeTooltipBuilder: (context, index) {
return Padding(
padding: EdgeInsets.all(8),
child: Text(
'${_data[index].country}: ${_data[index].population}M',
style: TextStyle(color: Colors.white),
),
);
},
bubbleTooltipBuilder: (context, index) {
return Padding(
padding: EdgeInsets.all(8),
child: Text(
'密度: ${_data[index].density}/km²',
style: TextStyle(color: Colors.white),
),
);
},
)Pattern 4: Zoom to Fit Markers
模式4:缩放适配标记范围
dart
// Show specific region with markers
late MapZoomPanBehavior _zoomPanBehavior;
void initState() {
_zoomPanBehavior = MapZoomPanBehavior(
enableDoubleTapZooming: true,
enablePinching: true,
enablePanning: true,
);
super.initState();
}
// Button to fit bounds
void _fitToMarkers() {
setState(() {
// Define bounds to show all markers
_zoomPanBehavior.latLngBounds = MapLatLngBounds(
MapLatLng(southwestLat, southwestLng),
MapLatLng(northeastLat, northeastLng),
);
});
}
MapShapeLayer(
source: _dataSource,
zoomPanBehavior: _zoomPanBehavior,
// ... markers
)dart
// 展示包含所有标记的特定区域
late MapZoomPanBehavior _zoomPanBehavior;
void initState() {
_zoomPanBehavior = MapZoomPanBehavior(
enableDoubleTapZooming: true,
enablePinching: true,
enablePanning: true,
);
super.initState();
}
// 适配边界的按钮事件
void _fitToMarkers() {
setState(() {
// 定义展示所有标记的边界
_zoomPanBehavior.latLngBounds = MapLatLngBounds(
MapLatLng(southwestLat, southwestLng),
MapLatLng(northeastLat, northeastLng),
);
});
}
MapShapeLayer(
source: _dataSource,
zoomPanBehavior: _zoomPanBehavior,
// ... 标记配置
)Pattern 5: Dynamic Marker Addition (Tap to Add)
模式5:动态添加标记(点击添加)
dart
// Add markers where user taps
late MapLatLng _markerPosition;
late MapShapeLayerController _controller;
late CustomZoomPanBehavior _zoomPanBehavior;
void initState() {
_controller = MapShapeLayerController();
_zoomPanBehavior = CustomZoomPanBehavior()
..onTap = _handleTap;
super.initState();
}
void _handleTap(Offset position) {
_markerPosition = _controller.pixelToLatLng(position);
if (_controller.markersCount > 0) {
_controller.clearMarkers();
}
_controller.insertMarker(0);
}
MapShapeLayer(
source: _dataSource,
controller: _controller,
zoomPanBehavior: _zoomPanBehavior,
markerBuilder: (context, index) {
return MapMarker(
latitude: _markerPosition.latitude,
longitude: _markerPosition.longitude,
child: Icon(Icons.location_on, color: Colors.red),
);
},
)
class CustomZoomPanBehavior extends MapZoomPanBehavior {
late Function(Offset) onTap;
void handleEvent(PointerEvent event) {
if (event is PointerUpEvent) {
onTap(event.localPosition);
}
super.handleEvent(event);
}
}dart
// 在用户点击的位置添加标记
late MapLatLng _markerPosition;
late MapShapeLayerController _controller;
late CustomZoomPanBehavior _zoomPanBehavior;
void initState() {
_controller = MapShapeLayerController();
_zoomPanBehavior = CustomZoomPanBehavior()
..onTap = _handleTap;
super.initState();
}
void _handleTap(Offset position) {
_markerPosition = _controller.pixelToLatLng(position);
if (_controller.markersCount > 0) {
_controller.clearMarkers();
}
_controller.insertMarker(0);
}
MapShapeLayer(
source: _dataSource,
controller: _controller,
zoomPanBehavior: _zoomPanBehavior,
markerBuilder: (context, index) {
return MapMarker(
latitude: _markerPosition.latitude,
longitude: _markerPosition.longitude,
child: Icon(Icons.location_on, color: Colors.red),
);
},
)
class CustomZoomPanBehavior extends MapZoomPanBehavior {
late Function(Offset) onTap;
void handleEvent(PointerEvent event) {
if (event is PointerUpEvent) {
onTap(event.localPosition);
}
super.handleEvent(event);
}
}Key Properties
核心属性
MapShapeLayer Essential Properties
MapShapeLayer核心属性
- - MapShapeSource with GeoJSON data and mappings
source - - Default color for all shapes
color - - Border color for shapes
strokeColor - - Border width for shapes
strokeWidth - - Legend configuration (bar or default)
legend - - Show labels on shapes
showDataLabels - - Number of markers to display
initialMarkersCount - - Builder function for markers
markerBuilder - - MapShapeLayerController for dynamic updates
controller - - Zoom and pan configuration
zoomPanBehavior - - Callback when shape is selected
onSelectionChanged - - Selection appearance settings
selectionSettings - - Custom tooltip for shapes
shapeTooltipBuilder - - Custom tooltip for bubbles
bubbleTooltipBuilder - - Custom tooltip for markers
markerTooltipBuilder - - Tooltip styling configuration
tooltipSettings - - Bubble appearance settings
bubbleSettings - - Data label styling
dataLabelSettings - - Legend appearance settings
legendSettings - - List of MapSublayer widgets
sublayers - - Widget shown while loading GeoJSON
loadingBuilder
- - 包含GeoJSON数据和映射规则的MapShapeSource
source - - 所有形状的默认颜色
color - - 形状的边框颜色
strokeColor - - 形状的边框宽度
strokeWidth - - 图例配置(条形或默认样式)
legend - - 是否展示形状上的标签
showDataLabels - - 展示的标记数量
initialMarkersCount - - 标记的构建函数
markerBuilder - - 用于动态更新的MapShapeLayerController
controller - - 缩放和平移配置
zoomPanBehavior - - 形状被选中时的回调
onSelectionChanged - - 选中状态的外观设置
selectionSettings - - 形状的自定义提示框
shapeTooltipBuilder - - 气泡的自定义提示框
bubbleTooltipBuilder - - 标记的自定义提示框
markerTooltipBuilder - - 提示框样式配置
tooltipSettings - - 气泡外观设置
bubbleSettings - - 数据标签样式
dataLabelSettings - - 图例外观设置
legendSettings - - MapSublayer组件列表
sublayers - - GeoJSON加载时展示的组件
loadingBuilder
MapTileLayer Essential Properties
MapTileLayer核心属性
- - Tile provider URL in WMTS format
urlTemplate - - Initial center point (latitude, longitude)
initialFocalLatLng - - Initial zoom level (1-15+)
initialZoomLevel - - Number of markers to display
initialMarkersCount - - Builder function for markers
markerBuilder - - MapTileLayerController for dynamic updates
controller - - Zoom and pan configuration
zoomPanBehavior - - Custom tooltip for markers
markerTooltipBuilder - - Bounds to fit on load
initialLatLngBounds
- - WMTS格式的瓦片服务商URL
urlTemplate - - 初始中心点(经纬度)
initialFocalLatLng - - 初始缩放级别(1-15+)
initialZoomLevel - - 展示的标记数量
initialMarkersCount - - 标记的构建函数
markerBuilder - - 用于动态更新的MapTileLayerController
controller - - 缩放和平移配置
zoomPanBehavior - - 标记的自定义提示框
markerTooltipBuilder - - 加载时适配的边界范围
initialLatLngBounds
MapShapeSource Essential Properties
MapShapeSource核心属性
- - Field name in GeoJSON to match with data
shapeDataField - - Number of data items
dataCount - - Maps data index to shape identifier
primaryValueMapper - - Maps data index to label text
dataLabelMapper - - Maps data index to color value
shapeColorValueMapper - - Color mappers for equal/range mapping
shapeColorMappers - - Maps data index to bubble size
bubbleSizeMapper - - Maps data index to bubble color
bubbleColorValueMapper - - Color mappers for bubbles
bubbleColorMappers
- - GeoJSON中与数据匹配的字段名
shapeDataField - - 数据项数量
dataCount - - 将数据索引映射到形状标识符
primaryValueMapper - - 将数据索引映射到标签文本
dataLabelMapper - - 将数据索引映射到颜色值
shapeColorValueMapper - - 等值/范围映射的颜色映射器
shapeColorMappers - - 将数据索引映射到气泡尺寸
bubbleSizeMapper - - 将数据索引映射到气泡颜色
bubbleColorValueMapper - - 气泡的颜色映射器
bubbleColorMappers
MapZoomPanBehavior Essential Properties
MapZoomPanBehavior核心属性
- - Enable double-tap to zoom
enableDoubleTapZooming - - Enable pinch zoom (mobile)
enablePinching - - Enable pan gesture
enablePanning - - Enable mouse wheel zoom
enableMouseWheelZooming - - Show zoom toolbar (web)
showToolbar - - Toolbar appearance
toolbarSettings - - Current zoom level (read/write)
zoomLevel - - Current center point (read/write)
focalLatLng - - Bounds to fit dynamically
latLngBounds - - Minimum zoom level
minZoomLevel - - Maximum zoom level
maxZoomLevel - - Callback during zoom
onZooming - - Callback during pan
onPanning
- - 启用双击缩放
enableDoubleTapZooming - - 启用捏合缩放(移动端)
enablePinching - - 启用平移手势
enablePanning - - 启用滚轮缩放
enableMouseWheelZooming - - 展示缩放工具栏(web端)
showToolbar - - 工具栏外观设置
toolbarSettings - - 当前缩放级别(可读可写)
zoomLevel - - 当前中心点(可读可写)
focalLatLng - - 动态适配的边界范围
latLngBounds - - 最小缩放级别
minZoomLevel - - 最大缩放级别
maxZoomLevel - - 缩放过程中的回调
onZooming - - 平移过程中的回调
onPanning
Common Use Cases
常见使用场景
- Election Results Map - Use MapShapeLayer with color mapping by state/region
- Store Locator - Use MapTileLayer with custom marker icons
- Sales Territory Map - Use MapShapeLayer with bubbles showing sales volume
- Population Density Map - Use MapShapeLayer with choropleth coloring
- Delivery Tracking - Use MapTileLayer with real-time marker updates
- Weather Map - Use MapShapeLayer with color mapping for temperature/conditions
- Property Finder - Use MapTileLayer with markers and zoom-to-fit
- Regional Analytics - Use MapShapeLayer with legends, tooltips, and selection
- Route Planning - Use MapTileLayer with polyline vector layers
- Census Data Visualization - Use MapShapeLayer with data labels and legends
- 选举结果地图 - 使用MapShapeLayer按州/区域进行颜色映射
- 门店定位 - 使用MapTileLayer搭配自定义标记图标
- 销售区域地图 - 使用MapShapeLayer搭配气泡展示销售额
- 人口密度地图 - 使用MapShapeLayer搭配分级统计着色
- 配送跟踪 - 使用MapTileLayer搭配实时标记更新
- 天气地图 - 使用MapShapeLayer搭配颜色映射展示温度/天气状况
- 房产查找 - 使用MapTileLayer搭配标记和缩放适配
- 区域分析 - 使用MapShapeLayer搭配图例、提示框和选择功能
- 路线规划 - 使用MapTileLayer搭配折线矢量图层
- 人口普查数据可视化 - 使用MapShapeLayer搭配数据标签和图例