Flutter+高德地图实战：5分钟搞定周边POI搜索功能（附完整代码）

Flutter高德地图实战5分钟搞定周边POI搜索功能附完整代码在移动应用开发中位置服务功能已经成为标配需求。无论是外卖App寻找附近餐厅还是旅游应用发现周边景点快速获取当前位置并展示周边信息(POI)都是提升用户体验的关键功能。本文将带你用Flutter和高德地图SDK在5分钟内实现一个完整的周边搜索模块包含权限管理、定位获取、关键词搜索和列表优化等实用技巧。1. 环境准备与基础配置1.1 添加必要依赖首先在pubspec.yaml中添加以下依赖项dependencies: amap_location: ^0.2.0 # 高德定位SDK amap_search_fluttify: ^0.8.21 # 高德搜索SDK permission_handler: ^5.0.1 # 权限管理 dio: ^4.0.0 # 网络请求 flutter_easyrefresh: ^2.2.1 # 下拉刷新运行flutter pub get安装依赖后需要进行高德开发者平台的配置前往高德开放平台注册账号进入控制台创建新应用获取Web服务的API Key注意不是Android/iOS的SDK Key1.2 权限配置最佳实践在AndroidManifest.xml中添加以下权限uses-permission android:nameandroid.permission.ACCESS_COARSE_LOCATION/ uses-permission android:nameandroid.permission.ACCESS_FINE_LOCATION/ uses-permission android:nameandroid.permission.INTERNET/对于iOS需要在Info.plist中添加keyNSLocationWhenInUseUsageDescription/key string需要获取您的位置以提供周边服务/string keyNSLocationAlwaysAndWhenInUseUsageDescription/key string需要持续获取位置以提供更好的服务/string权限请求的最佳实践Futurebool _checkLocationPermission() async { final status await Permission.location.request(); if (status.isGranted) { return true; } else if (status.isPermanentlyDenied) { // 引导用户前往设置开启权限 await openAppSettings(); } return false; }2. 核心功能实现2.1 定位服务封装创建一个LocationService类封装定位功能class LocationService { static final LocationService _instance LocationService._internal(); factory LocationService() _instance; LocationService._internal(); AMapLocation? _currentLocation; FutureAMapLocation? getCurrentLocation() async { try { await AMapLocationClient.startup(AMapLocationOption( desiredAccuracy: CLLocationAccuracy.kCLLocationAccuracyBest )); final hasPermission await _checkLocationPermission(); if (!hasPermission) return null; _currentLocation await AMapLocationClient.getLocation(true); return _currentLocation; } catch (e) { print(定位失败: $e); return null; } } }2.2 POI搜索功能实现创建POIService处理搜索逻辑class POIService { final Dio _dio Dio(); final String _apiKey 你的高德Web服务Key; FutureListPoi searchAround({ required double longitude, required double latitude, String? keywords, int radius 1000, int page 1, int size 20, }) async { final response await _dio.get( https://restapi.amap.com/v3/place/around, queryParameters: { key: _apiKey, location: $longitude,$latitude, keywords: keywords ?? , radius: radius, page: page, offset: size, extensions: all, }, ); if (response.data[status] 1) { return (response.data[pois] as List) .map((e) Poi.fromJson(e)) .toList(); } else { throw Exception(response.data[info]); } } }2.3 自动配置API Key的安全方案为避免将API Key硬编码在代码中推荐使用环境变量或后端中转方案Flutter环境变量方案// 在启动时注入 void main() { const apiKey String.fromEnvironment(AMAP_API_KEY); runApp(MyApp(apiKey: apiKey)); }运行命令flutter run --dart-defineAMAP_API_KEYyour_key_here后端中转方案FutureString _getApiKey() async { final response await Dio().post(你的后端API); return response.data[apiKey]; }3. UI实现与优化技巧3.1 搜索界面布局创建一个高效的搜索界面class POISearchPage extends StatefulWidget { override _POISearchPageState createState() _POISearchPageState(); } class _POISearchPageState extends StatePOISearchPage { final TextEditingController _searchController TextEditingController(); ListPoi _poiList []; bool _isLoading false; override Widget build(BuildContext context) { return Scaffold( appBar: AppBar( title: TextField( controller: _searchController, decoration: InputDecoration( hintText: 搜索周边..., border: InputBorder.none, suffixIcon: IconButton( icon: Icon(Icons.search), onPressed: _handleSearch, ), ), onSubmitted: (_) _handleSearch(), ), ), body: _buildBody(), ); } Widget _buildBody() { if (_isLoading) return Center(child: CircularProgressIndicator()); return EasyRefresh( onRefresh: _handleRefresh, onLoad: _handleLoadMore, child: ListView.builder( itemCount: _poiList.length, itemBuilder: (ctx, index) _buildPOIItem(_poiList[index]), ), ); } Widget _buildPOIItem(Poi poi) { return ListTile( leading: Icon(Icons.location_on, color: Colors.blue), title: Text(poi.name), subtitle: Text(poi.address ?? ), trailing: Text(${poi.distance}米), onTap: () _handlePOISelected(poi), ); } Futurevoid _handleSearch() async { // 实现搜索逻辑 } }3.2 性能优化技巧列表性能优化ListView.builder( itemCount: _poiList.length, itemBuilder: (ctx, index) { final poi _poiList[index]; return RepaintBoundary( // 使用RepaintBoundary减少重绘 child: POIListItem( poi: poi, key: ValueKey(poi.id), // 使用唯一key ), ); }, )图片加载优化CachedNetworkImage( imageUrl: poi.photos?.first?.url ?? , placeholder: (ctx, url) Container( color: Colors.grey[200], width: 80, height: 80, ), errorWidget: (ctx, url, err) Icon(Icons.error), fit: BoxFit.cover, width: 80, height: 80, )搜索防抖处理Timer? _searchDebounce; void _onSearchTextChanged(String text) { if (_searchDebounce?.isActive ?? false) { _searchDebounce?.cancel(); } _searchDebounce Timer(const Duration(milliseconds: 500), () { _handleSearch(text); }); }4. 高级功能扩展4.1 分类筛选功能实现多分类筛选ListString _categories [ 餐饮, 酒店, 景点, 购物, 交通 ]; Widget _buildCategoryFilter() { return SizedBox( height: 50, child: ListView.builder( scrollDirection: Axis.horizontal, itemCount: _categories.length, itemBuilder: (ctx, index) { return Padding( padding: EdgeInsets.symmetric(horizontal: 8), child: FilterChip( label: Text(_categories[index]), selected: _selectedCategory _categories[index], onSelected: (selected) { setState(() { _selectedCategory selected ? _categories[index] : null; _handleSearch(); }); }, ), ); }, ), ); }4.2 地图集成展示将搜索结果展示在地图上AmapView( onMapCreated: (controller) { _mapController controller; _showPoisOnMap(); }, options: AmapOptions( zoom: 15, center: LatLng( _currentLocation?.latitude ?? 39.909187, _currentLocation?.longitude ?? 116.397451, ), ), ) Futurevoid _showPoisOnMap() async { final markers _poiList.map((poi) { final location poi.location?.split(,); if (location null || location.length 2) return null; return MarkerOptions( position: LatLng( double.parse(location[1]), double.parse(location[0]), ), title: poi.name, snippet: poi.address, icon: assets/marker.png, ); }).whereTypeMarkerOptions().toList(); await _mapController?.addMarkers(markers); }4.3 离线缓存策略实现简单的离线缓存class POICache { static const _cacheKey poi_cache; static const _cacheDuration Duration(hours: 1); final SharedPreferences _prefs; POICache(this._prefs); Futurevoid save(String query, ListPoi pois) async { final data { timestamp: DateTime.now().millisecondsSinceEpoch, data: pois.map((e) e.toJson()).toList(), }; await _prefs.setString(${_cacheKey}_$query, json.encode(data)); } FutureListPoi? get(String query) async { final cached _prefs.getString(${_cacheKey}_$query); if (cached null) return null; final data json.decode(cached) as MapString, dynamic; final timestamp data[timestamp] as int; if (DateTime.now().millisecondsSinceEpoch - timestamp _cacheDuration.inMilliseconds) { return null; } return (data[data] as List).map((e) Poi.fromJson(e)).toList(); } }5. 常见问题与解决方案5.1 定位失败处理Futurevoid _getLocationWithRetry() async { int retryCount 0; const maxRetry 3; while (retryCount maxRetry) { try { final location await LocationService().getCurrentLocation(); if (location ! null) { _currentLocation location; return; } } catch (e) { retryCount; if (retryCount maxRetry) { ScaffoldMessenger.of(context).showSnackBar( SnackBar(content: Text(定位失败请检查GPS和网络设置)) ); } await Future.delayed(Duration(seconds: 1)); } } }5.2 搜索API限制处理高德地图API有QPS限制需要做好错误处理和重试机制FutureListPoi _safeSearch({ required double lat, required double lng, String? keyword, }) async { int retry 0; const maxRetry 2; while (retry maxRetry) { try { return await POIService().searchAround( latitude: lat, longitude: lng, keywords: keyword, ); } on DioError catch (e) { if (e.response?.statusCode 429) { retry; await Future.delayed(Duration(seconds: 1)); continue; } rethrow; } } throw Exception(请求过于频繁请稍后再试); }5.3 跨平台兼容性问题处理Android和iOS的差异FutureString _getPlatformSpecificKey() async { if (Platform.isAndroid) { return android_web_key; } else if (Platform.isIOS) { return ios_web_key; } throw UnsupportedError(不支持的平台); } Widget _buildPlatformSpecificUI() { return Platform.isIOS ? CupertinoButton(onPressed: () {}, child: Text(搜索)) : ElevatedButton(onPressed: () {}, child: Text(搜索)); }6. 完整代码示例以下是整合后的主要页面代码class POISearchScreen extends StatefulWidget { final String apiKey; const POISearchScreen({required this.apiKey}); override _POISearchScreenState createState() _POISearchScreenState(); } class _POISearchScreenState extends StatePOISearchScreen { final _searchController TextEditingController(); final _poiService POIService(); final _locationService LocationService(); final _scrollController ScrollController(); AMapLocation? _currentLocation; ListPoi _poiList []; bool _isLoading false; int _currentPage 1; String? _lastQuery; override void initState() { super.initState(); _initLocation(); _scrollController.addListener(_scrollListener); } Futurevoid _initLocation() async { setState(() _isLoading true); _currentLocation await _locationService.getCurrentLocation(); if (_currentLocation ! null) { await _searchPOIs(); } setState(() _isLoading false); } Futurevoid _searchPOIs({String? query, bool loadMore false}) async { if (_currentLocation null) return; try { setState(() _isLoading true); if (!loadMore) { _currentPage 1; _lastQuery query; } else { _currentPage; } final pois await _poiService.searchAround( latitude: _currentLocation!.latitude, longitude: _currentLocation!.longitude, keywords: query, page: _currentPage, ); setState(() { if (loadMore) { _poiList.addAll(pois); } else { _poiList pois; } }); } catch (e) { ScaffoldMessenger.of(context).showSnackBar( SnackBar(content: Text(搜索失败: ${e.toString()})) ); } finally { setState(() _isLoading false); } } void _scrollListener() { if (_scrollController.position.pixels _scrollController.position.maxScrollExtent) { _searchPOIs(query: _lastQuery, loadMore: true); } } override Widget build(BuildContext context) { return Scaffold( appBar: AppBar( title: _buildSearchField(), actions: [ IconButton( icon: Icon(Icons.my_location), onPressed: _initLocation, ) ], ), body: _buildBody(), ); } Widget _buildSearchField() { return TextField( controller: _searchController, decoration: InputDecoration( hintText: 搜索周边..., border: InputBorder.none, suffixIcon: IconButton( icon: Icon(Icons.search), onPressed: () _searchPOIs(query: _searchController.text), ), ), onSubmitted: (query) _searchPOIs(query: query), ); } Widget _buildBody() { if (_isLoading _poiList.isEmpty) { return Center(child: CircularProgressIndicator()); } return Column( children: [ if (_currentLocation ! null) Padding( padding: EdgeInsets.all(8), child: Text( 当前位置: ${_currentLocation!.address}, style: TextStyle(color: Colors.grey), ), ), Expanded( child: ListView.builder( controller: _scrollController, itemCount: _poiList.length (_isLoading ? 1 : 0), itemBuilder: (ctx, index) { if (index _poiList.length) { return Center(child: CircularProgressIndicator()); } return _buildPOIItem(_poiList[index]); }, ), ), ], ); } Widget _buildPOIItem(Poi poi) { return Card( margin: EdgeInsets.symmetric(horizontal: 8, vertical: 4), child: ListTile( leading: Icon(Icons.place, color: Colors.red), title: Text(poi.name), subtitle: Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ if (poi.address ! null) Text(poi.address!), if (poi.distance ! null) Text(距离: ${poi.distance}米, style: TextStyle(fontSize: 12)), ], ), trailing: Icon(Icons.chevron_right), onTap: () _showPOIDetail(poi), ), ); } void _showPOIDetail(Poi poi) { // 跳转到详情页 } override void dispose() { _scrollController.dispose(); _searchController.dispose(); super.dispose(); } }在实际项目中这个基础版本已经可以满足大多数周边搜索需求。根据我的经验关键是要处理好定位权限和网络请求的错误情况这两个点最容易导致用户体验问题。另外列表项的渲染优化也很重要特别是当搜索结果较多时合理的复用机制可以显著提升滚动流畅度。