快速开始

本文档提供一个从零开始的完整示例，帮助你在 5 分钟内运行起一个带地图和 Marker 的 Flutter 应用。

前置条件

• 已完成集成 Flutter 插件中的全部步骤
• 已获取 Android 和 iOS 的 API Key
• 已调用 TencentMapInitializer.setAgreePrivacy(true) 和 TencentMapInitializer.start()

完整示例

import 'package:flutter/material.dart';
import 'package:flutter_tencent_map/flutter_tencent_map.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // 1. 隐私合规
  await TencentMapInitializer.setAgreePrivacy(true);
  await TencentMapInitializer.start();
  
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: const QuickStartPage(),
    );
  }
}

class QuickStartPage extends StatefulWidget {
  const QuickStartPage({super.key});

  @override
  State<QuickStartPage> createState() => _QuickStartPageState();
}

class _QuickStartPageState extends State<QuickStartPage> {
  TencentMapController? _controller;
  Set<Marker> _markers = {};

  void _addMarker() {
    setState(() {
      _markers = {
        Marker(
          id: 'm1',
          position: const LatLng(39.9087, 116.3975), // 天安门
          infoWindow: const InfoWindow(
            title: '天安门',
            snippet: '北京市东城区',
          ),
          onTap: () {
            ScaffoldMessenger.of(context).showSnackBar(
              const SnackBar(content: Text('点击了 Marker')),
            );
          },
        ),
      };
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('快速开始')),
      body: Stack(
        children: [
          TencentMap(
            initialCameraPosition: const CameraPosition(
              target: LatLng(39.9087, 116.3975),
              zoom: 12,
            ),
            onMapCreated: (controller) {
              _controller = controller;
            },
            onMapLoaded: () {
              // 地图加载完成后自动添加 Marker
              _addMarker();
            },
            markers: _markers,
          ),
          Positioned(
            right: 16,
            bottom: 16,
            child: FloatingActionButton(
              onPressed: () {
                _controller?.moveCamera(
                  CameraUpdate.zoomIn(),
                  animated: true,
                );
              },
              child: const Icon(Icons.add),
            ),
          ),
        ],
      ),
    );
  }
}

运行验证

flutter run

预期效果：

1. 应用启动后显示天安门附近的地图
2. 地图上出现一个默认红色 Marker，带 InfoWindow 标注"天安门"
3. 点击 Marker 弹出 SnackBar 提示
4. 右下角浮动按钮可放大地图

常见问题排查

地图显示"鉴权失败"

• 检查 API Key 是否正确
• 检查 Android 包名 / iOS Bundle ID 是否与控制台一致
• Android 检查 AndroidManifest.xml 中 <meta-data> 是否在 <application> 标签内
• iOS 检查 apiKey 是否正确传入 TencentMap Widget 或通过原生 SDK 设置

地图白屏

• 确认已调用 TencentMapInitializer.setAgreePrivacy(true) 和 TencentMapInitializer.start()
• 确认网络连接正常（地图瓦片需要联网下载）
• Android 检查是否添加了 INTERNET 权限

iOS 编译失败

• 执行 cd ios && pod install
• 检查 Podfile 中 iOS 最低版本是否 ≥ 13.0
• 如果 SDK 版本冲突，在 Podfile 中锁定版本：pod 'QMapKit', '5.7.7'

Marker 图标不显示

• 检查 BitmapDescriptor.fromAsset 的资源路径是否正确
• 确认 assets 路径已在 pubspec.yaml 中声明