sharemap_maplib_flutter

Widget bản đồ dựa trên MapLibre dành cho Flutter, tích hợp với các API của ShareMap. Gói này đơn giản hóa việc tích hợp map tile, các lớp POI động như khu công nghiệp, cảng và nhà ga, đồng thời hỗ trợ tải style bằng API key và chữ ký HMAC.

Tính năng

  • Tự động cấu hình lớp POI: Đăng ký source vector dùng chung và bật các layer shape/symbol đã được định nghĩa trong style ShareMap. Ứng dụng không cần tự phân tích style JSON.
  • Chữ ký HMAC: Tự tính chữ ký HMAC Base64 động để bảo vệ yêu cầu tải style.
  • Tối ưu so sánh sâu: So sánh danh sách layerCodes để tránh tải lại bản đồ hoặc lặp yêu cầu mạng không cần thiết.
  • Môi trường dev/prod: Chọn endpoint lớp POI dev/prod; chế độ dev đồng thời bật log chẩn đoán chi tiết.
  • Hỗ trợ tile tùy chỉnh: Tích hợp MVT tileserver bên ngoài bằng URL trực tiếp.
  • Vị trí nền native: Theo dõi vị trí bằng foreground service trên Android và Core Location trên iOS, chỉ bắt đầu sau thao tác rõ ràng của người dùng. Plugin phát dữ liệu qua Dart stream đã chuẩn hóa, không tự tải lên máy chủ và không lưu lịch sử vị trí.

Bắt đầu

Package hiện không publish lên pub.flutter-io.cn. Thêm package bằng Git và pin tag hoặc commit đã được đội ShareMap phê duyệt:

dependencies:
  sharemap_maplib_flutter:
    git:
      url: git@github.com:ShareMapLive/sharemap-maplib-flutter.git
      ref: YOUR_APPROVED_TAG_OR_COMMIT

Khi phát triển hai repository trên cùng máy, có thể dùng path local:

dependencies:
  sharemap_maplib_flutter:
    path: ../sharemap-maplib-flutter

Sử dụng bản đồ

Ví dụ khởi tạo widget ShareMapLibre:

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

void main() {
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('ShareMap MapLibre Demo')),
        body: const ShareMapLibre(
          xApiKey: "YOUR_API_KEY",
          secretKey: "YOUR_SECRET_KEY",
          mode: ShareMapMode.prod,
          mapStyle: ShareMapStyle.sharemap,
          initialCameraPosition: CameraPosition(
            target: LatLng(10.2312, 107.0134),
            zoom: 11.0,
          ),
          layerCodes: [
            'vn-industrial-zones',
          ],
        ),
      ),
    );
  }
}

Thông tin thêm

Để tìm hiểu thêm về màu sắc giao diện, quản lý layer động và style tùy chỉnh, xem tài liệu trong repository hoặc liên hệ đội ngũ ShareMap Live tại sharemap.live.

Vị trí nền (bản thử nghiệm V1)

Vị trí nền là tính năng chủ động bật. Ứng dụng chỉ sử dụng bản đồ sẽ không tự nhận các khai báo quyền nhạy cảm. Sau khi thêm package, cấu hình host project một lần:

dart run sharemap_maplib_flutter:setup --dry-run
dart run sharemap_maplib_flutter:setup
dart run sharemap_maplib_flutter:doctor

Chỉ bắt đầu theo dõi từ một thao tác rõ ràng của người dùng khi ứng dụng đang hiển thị:

await ShareMapMaplib.initialize(
  androidNotification: const ShareMapAndroidNotificationOptions(
    title: 'Đang chia sẻ vị trí',
    content: 'Chạm để quay lại ứng dụng',
  ),
);

ShareMapMaplib.locationStream.listen((location) {
  // Ứng dụng host tự quyết định cách sử dụng điểm vị trí này.
});

final status = await ShareMapMaplib.start(
  options: const ShareMapTrackingOptions(
    maxDuration: Duration(hours: 3),
  ),
);

maxDuration tính cả thời gian app hiển thị và ở nền. Đây là mốc tự dừng mục tiêu; hệ điều hành có thể dừng phiên sớm hơn hoặc trì hoãn cleanup khi CPU/code ứng dụng đang bị suspend. Bỏ maxDuration nghĩa là package không đặt deadline, không phải cam kết phiên sống vĩnh viễn.

Gọi ShareMapMaplib.stop() khi người dùng kết thúc phiên. V1 chỉ có profile normal; ứng dụng host không cần chọn mode. Developer nên bắt đầu từ hướng dẫn tích hợp và cài đặt, sau đó đọc tài liệu API, hành vi theo nền tảng và danh sách kiểm thử thiết bị.

Android không thể tự khởi động lại sau khi người dùng force-stop ứng dụng. Trên iOS, hệ điều hành quyết định thời điểm và tần suất giao vị trí; plugin không thể bảo đảm một khoảng thời gian cố định.

Libraries

sharemap_maplib_flutter