Skip to content

Latest commit

 

History

History
executable file
·
274 lines (211 loc) · 10.1 KB

README.vi.md

File metadata and controls

executable file
·
274 lines (211 loc) · 10.1 KB

Vietmap Flutter Navigation

Liên hệ vietmap.vn để đăng kí key hợp lệ.

English document

Getting started

Thêm thư viện vào file pubspec.yaml

  vietmap_flutter_navigation: latest_version

Kiểm tra phiên bản của thư viện tại https://pub.dev/packages/vietmap_flutter_navigation

hoặc chạy lệnh sau để thêm thư viện vào project:

  flutter pub add vietmap_flutter_navigation

Cấu hình cho Android

Thêm đoạn code sau vào build.gradle (project) tại đường dẫn android/build.gradle

  maven { url "https://jitpack.io" }

như sau

  allprojects {
      repositories {
          google()
          mavenCentral()
          maven { url "https://jitpack.io" }
      }
  }

Cấu hình cho iOS

Thêm đoạn code sau vào file Info.plist

  <key>VietMapURL</key>
  <string>https://maps.vietmap.vn/api/maps/light/styles.json?apikey=YOUR_API_KEY_HERE</string>
  <key>VietMapAPIBaseURL</key>
  <string>https://maps.vietmap.vn/api/navigations/route/</string>
  <key>VietMapAccessToken</key>
  <string>YOUR_API_KEY_HERE</string>
  <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
  <string>This app requires location permission to working normally</string>
  <key>NSLocationAlwaysUsageDescription</key>
  <string>This app requires location permission to working normally</string>
  <key>NSLocationWhenInUseUsageDescription</key>
  <string>This app requires location permission to working normally</string>

Nâng min ios version lên 12.0 tại file Podfile (iOS), đường dẫn ios/Podfile (Bỏ comment dòng bên dưới)

  platform :ios, '12.0'

Tại terminal, cd vào thư mục ios và chạy lệnh sau để cài đặt pod file (bỏ qua bước này nếu chỉ build cho Android hoặc chạy app trên Windows/Linux PC)

  cd ios && pod install
  • Nếu project hiển thị lỗi khi nâng version mới khi chạy lệnh pod install, vui lòng xóa các thư mục ios/.symlinks, ios/Pods và file Podfile.lock, sau đó chạy lệnh pod install --repo-update để cập nhật lại pod file.

Các tính năng chính

Import thư viện

  import 'package:vietmap_flutter_navigation/vietmap_flutter_navigation.dart';

Khai báo các biến cần thiết và hàm cấu hình khởi tạo

  late MapOptions _navigationOption;
  final _vietmapNavigationPlugin = VietMapNavigationPlugin();


  List<LatLng> waypoints = const [
    LatLng(10.759091, 106.675817),
    LatLng(10.762528, 106.653099)
  ];

  /// Hiển thị hình ảnh dẫn đường vào ngã rẽ tiếp theo
  Widget instructionImage = const SizedBox.shrink();

  Widget recenterButton = const SizedBox.shrink();
  RouteProgressEvent? routeProgressEvent;
 /// The controller to control the navigation, such as start, stop, recenter, overview,... 
  MapNavigationViewController? _navigationController;

Thêm hàm initialize vào initState để khởi tạo các tùy chọn cho bản đồ

  @override
  void initState() {
    super.initState();
    initialize();
  }

  Future<void> initialize() {
    if (!mounted) return;
    _navigationOption = _vietmapNavigationPlugin.getDefaultOptions();
    _navigationOption.simulateRoute = false;

    _navigationOption.apiKey =
        'YOUR_API_KEY_HERE';
    _navigationOption.mapStyle =
        "https://maps.vietmap.vn/api/maps/light/styles.json?apikey=YOUR_API_KEY_HERE";

    _vietmapNavigationPlugin.setDefaultOptions(_navigationOption);
  }
  • Thay YOUR_API_KEY_HERE bằng apikey được cung cấp bởi VietMap

Hiển thị Navigation view, bao gồm bản đồ và đường đi, điều hướng dẫn đường

  NavigationView(
    mapOptions: _navigationOption,
    onMapCreated: (controller) {
      _navigationController = controller;
    },
    onRouteProgressChange: (RouteProgressEvent routeProgressEvent) {
      setState(() {
        this.routeProgressEvent = routeProgressEvent;
      });
      _setInstructionImage(routeProgressEvent.currentModifier,
          routeProgressEvent.currentModifierType);
    },
  ),

Hàm hiển thị hình ảnh dẫn đường

  _setInstructionImage(String? modifier, String? type) {
    if (modifier != null && type != null) {
      List<String> data = [
        type.replaceAll(' ', '_'),
        modifier.replaceAll(' ', '_')
      ];
      String path = 'assets/navigation_symbol/${data.join('_')}.svg';
      setState(() {
        instructionImage = SvgPicture.asset(path, color: Colors.white);
      });
    }
  }

Chúng tôi sử dụng flutter_svg để hiển thị hình ảnh SVG.

Icon điều hướng dẫn đường được lưu trong thư mục này, tải về, giải nén và thêm vào thư mục assets.

File thiết kế figma có thể tham khảo tại đây

Thêm banner widget chỉ dẫn điều hướng

  BannerInstructionView(
    routeProgressEvent: routeProgressEvent,
    instructionIcon: instructionImage,
  )

Banner instruction view

Thêm các nút như xem tổng quan đường đi, về giữa để điều hướng dẫn đường

  BottomActionView(
    recenterButton: recenterButton,
    controller: _navigationController,
    routeProgressEvent: routeProgressEvent
  )

Bottom action Bạn có thể tuỳ chỉnh các widget này theo ý muốn. Toàn bộ data sử dụng để hiển thị 2 widget này được lưu trong biến routeProgressEvent.

Thêm hàm dispose cho controller

  @override
  void dispose() {
    _navigationController?.dispose();
    super.dispose();
  }

Các hàm thường sử dụng

  /// Tìm đường mới từ 2 điểm, waypoint1 là điểm bắt đầu, 
  /// waypoint2 là điểm kết thúc.
  _navigationController?.buildRoute(wayPoints: <LatLng>[currentLocation, destinationLocation]);

  /// Bắt đầu dẫn đường, gọi sau khi đã gọi hàm buildRoute phía trên
  _navigationController?.startNavigation();

  /// Hàm tìm đường và bắt đầu dẫn đường khi tìm được đường đi
  _navigationController?.buildAndStartNavigation(
      wayPoints: wayPoints: <Waypoint>[waypoint1,waypoint2],
      profile: DrivingProfile.drivingTraffic);
  
  /// Hàm về giữa sau khi nhấn xem tông quan đường đi 
  /// hoặc người dùng di chuyển bản đồ tới vị trí khác
  _navigationController?.recenter();

  /// Hàm xem tổng quát đường đi
  _navigationController?.overview();

  /// Hàm tắt/bật tiếng khi dẫn đường
  _navigationController?.mute();

  /// Hàm kết thúc dẫn đường
  _navigationController?.finishNavigation();

Thêm marker lên bản đồ

Chúng tôi cung cấp hàm addImageMarkers để thêm marker từ hình ảnh từ thư mục asset lên bản đồ.

Marker

  /// Add a marker to the map
  List<NavigationMarker>? markers = await _navigationController?.addImageMarkers([
    NavigationMarker(
        imagePath: 'assets/50.png',
      latLng: const LatLng(10.762528, 106.653099)),
    NavigationMarker(
        imagePath: 'assets/40.png',
        latLng: const LatLng(10.762528, 106.753099)),
  ]);

Lưu ý khi sử dụng

  • Hàm _navigationController?.buildRouteAndStartNavigation() không nên để trong initState mà nên để trong hàm onPressed của button hoặc hàm onMapRendered của NavigationView để tránh crash app khi bản đồ chưa được khởi tạo hoàn toàn.
  onMapRendered: () {
    _navigationController?.buildAndStartNavigation(
    wayPoints: wayPoints: <Waypoint>[waypoint1,waypoint2],
    profile: DrivingProfile.drivingTraffic);  
  }
  • Hãy chắc chắn rằng quyền truy cập vị trí đã được cấp trước khi điều hướng. Chúng tôi khuyến khích bạn sử dụng thư viện geolocator để xử lý quyền truy cập vị trí và lấy vị trí hiện tại của thiết bị.

Code mẫu màn hình dẫn đường tại đây

Chúng tôi có một ứng dụng demo với flutter_bloc và clean architecture pattern tại đây. Vui lòng clone và chạy app để xem cách nó hoạt động.

Bạn cũng có thể tải ứng dụng demo để xem cách nó hoạt động.

Lưu ý: Thay apikey được VietMap cung cấp vào toàn bộ tag YOUR_API_KEY_HERE để ứng dụng hoạt động bình thường

Nếu có bất kỳ thắc mắc và hỗ trợ, vui lòng liên hệ:

Gửi email: [email protected]

Liên hệ hỗ trợ

Tài liệu api tại đây

Có bug xảy ra? Open an issue. Nếu có thể hãy đính kèm cả log lỗi.

Yêu cầu tính năng mới Open an issue. Cho chúng tôi biết bạn muốn chúng tôi cải thiện điều gì.