เอกสาร / การตั้งค่า / React / Mapbox

การตั้งค่า Mapbox

ขั้นตอนการใช้ Mapbox บนเว็บผ่าน MapConductor จำเป็นต้องมี access token เฉพาะเมื่อใช้รูปแบบที่โฮสต์โดย Mapbox (สิ่งที่ขึ้นต้นด้วย mapbox://) เท่านั้น

PACKAGE
react-for-mapbox
API KEY
ขึ้นอยู่กับรูปแบบ
CSS
จำเป็น
REACT NATIVE
ไม่มี
ผู้ให้บริการเดียวกัน แพลตฟอร์มอื่นAndroidiOS

ก่อนเริ่ม

Node.js 18 ขึ้นไป
โทเค็นการเข้าถึงสาธารณะหากใช้รูปแบบที่โฮสต์โดย Mapbox
STEP 01

ติดตั้ง

mapbox-gl ถูกรวมอยู่ในแพ็กเกจแล้ว ไม่จำเป็นต้องติดตั้งแยก ไม่มีเวอร์ชัน React Native

terminalnpm
npm install @mapconductor/js-sdk-core @mapconductor/js-sdk-react \
            @mapconductor/react-for-mapbox
STEP 02

โหลดสไตล์ชีต

โหลดครั้งเดียวที่จุดเริ่มต้นของแอป หากลืม ตำแหน่งแผนที่และรูปลักษณ์ของตัวควบคุมจะเสียหาย

main.tsxTypeScript
import '@mapconductor/react-for-mapbox/style.css';
STEP 03

ส่งผ่าน access token (หากจำเป็น)

โทเค็นจะถูกส่งผ่านไปยัง state hook ภายในจะถูกตั้งค่าทั่วไปเป็น mapboxgl.accessToken สามารถข้ามได้หากใช้เฉพาะการออกแบบที่ใช้ OSM

HelloMap.tsxTypeScript · React
const mapState = useMapboxViewState({
  id: 'mapbox-map',
  accessToken: import.meta.env.VITE_MAPBOX_ACCESS_TOKEN,
  mapDesignType: MapboxDesign.Streets,
  cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
});
คีย์จะถูกส่งผ่านไปยัง state hook ไม่ใช่ไปยัง props ของ view component หากวางไว้ใน props จะปนไปในบันทึกการทดสอบและสแนปชอต
ข้อควรระวัง
คีย์ควรถูกส่งผ่านจากตัวแปรสภาพแวดล้อมขณะสร้าง (สำหรับ Vite คือ import.meta.env.VITE_*) และไม่ควรใส่ไว้ในการจัดการซอร์สโค้ด เนื่องจากถูกส่งต่อไปยัง frontend จำเป็นต้องตั้งข้อจำกัด referrer และโดเมนอย่างแน่นอนเพื่อป้องกันความเสียหายหากถูกเปิดเผย

ตรวจสอบ

สิ่งที่ควรเห็น

หากใช้ OsmBright สามารถตรวจสอบการทำงานได้โดยไม่ต้องใช้โทเค็น

HelloMap.tsxTypeScript · React
import { useState } from 'react';
import { createGeoPoint, createMapCameraPosition, createMarkerState } from '@mapconductor/js-sdk-core';
import { Marker } from '@mapconductor/js-sdk-react';
import { MapboxDesign, MapBoxMapView2D, useMapboxViewState } from '@mapconductor/react-for-mapbox';
import '@mapconductor/react-for-mapbox/style.css';

const TOKYO = createGeoPoint({ latitude: 35.6812, longitude: 139.7671 });

export function HelloMap() {
  // No token needed for the OsmBright design
  const mapState = useMapboxViewState({
    id: 'mapbox-map',
    mapDesignType: MapboxDesign.OsmBright,
    cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
  });
  const [markerState] = useState(() => createMarkerState({ id: 'tokyo', position: TOKYO }));

  return (
    <MapBoxMapView2D state={mapState} style={{ height: 480 }}>
      <Marker state={markerState} />
    </MapBoxMapView2D>
  );
}

อ็อบเจกต์สถานะ

พารามิเตอร์ที่ useMapboxViewState รับ โปรดทราบว่าชื่อ export ของมุมมองคือ MapBoxMapView / MapBoxMapView2D (B เป็นตัวพิมพ์ใหญ่)

signatureTypeScript
useMapboxViewState({
  id?: string;
  accessToken?: string;
  mapDesignType?: MapboxMapDesignType; // default MapboxDesign.Streets
  cameraPosition?: MapCameraPosition;  // default MapCameraPosition.Default
})

ดีไซน์แผนที่

MapboxDesign แบ่งออกเป็น 2 กลุ่มคือ สิ่งที่ต้องการโทเค็นและสิ่งที่ไม่ต้องการโทเค็น

MapboxDesign
Notes
Streets / Outdoors / Light / Dark
โฮสต์โดย Mapbox ต้องการโทเค็น
SatelliteStreets
ภาพดาวเทียมที่โฮสต์โดย Mapbox ต้องการโทเค็น
OsmBright / OsmBrightEn / OsmBrightJa
รูปแบบ OSM ร่วมกับ MapLibre ไม่ต้องการโทเค็น
MapTilerToner* / MapTilerBasic* / OpenMapTiles
ร่วมกับ MapLibre เช่นกัน ไม่ต้องการโทเค็น

การแก้ปัญหา

แสดงเฉพาะรูปแบบ Mapbox ไม่ได้

  • รูปแบบที่ขึ้นต้นด้วย mapbox:// จำเป็นต้องมีโทเค็น ตรวจสอบว่าได้ส่งผ่าน accessToken หรือไม่
  • ตรวจสอบว่าโทเค็นเป็นโทเค็นสาธารณะและไม่หมดอายุหรือไม่

ระดับการซูมแตกต่างจากผู้ให้บริการรายอื่น

  • MapConductor จัดระดับการซูมให้ตรงกับมาตรฐานของ Google Mapbox แปลงค่านี้โดยใช้ออฟเซ็ตจริง (googleZoom ≒ mapboxZoom + 1.0)

แผนที่ถูกเริ่มต้นสองครั้งเฉพาะระหว่างการพัฒนา

  • React StrictMode จะรัน effect สองครั้ง ผู้ให้บริการแต่ละรายได้รับการออกแบบให้ตรวจจับสิ่งนี้และทิ้งอีกตัวไป ดังนั้นจึงไม่จำเป็นต้องปิดใช้งาน StrictMode

ถัดไป

เนื่องจากมีโครงสร้างเหมือนกับ MapLibre การเปลี่ยนแปลง mapDesignType จะทำให้ต้องสร้างแผนที่ใหม่