English | [简体中文](./README-zh_CN.md) # @ray-js/gyro-map-component [![latest](https://img.shields.io/npm/v/@ray-js/gyro-map-component/latest.svg)](https://www.npmjs.com/package/@ray-js/gyro-map-component) [![download](https://img.shields.io/npm/dt/@ray-js/gyro-map-component.svg)](https://www.npmjs.com/package/@ray-js/gyro-map-component) > Gyro navigation robot map component ## Installation ```sh $ yarn add @ray-js/gyro-map-component @ray-js/gyro-map-sdk // or $ npm install @ray-js/gyro-map-component @ray-js/gyro-map-sdk ``` ## Development ```sh # Install dependencies yarn # Compile demo code in real-time yarn start:tuya ``` ## Usage ## GridMapComponent (Grid Map) ### Component Props | Property | Type | Required | Description | | ---------- | --------------------------------------------------- | -------- | ------------------------------------------------- | | config | `DeepPartialGridMapConfig` | No | Map configuration options | | onMapReady | `(funcs: MapApiFuncGridMap, mapId: string) => void` | No | Callback when map is initialized and API is ready | ### Configuration Options (DeepPartialGridMapConfig) #### Basic Configuration | Property | Type | Description | Default | | --------------------- | ------------- | ------------------------------------- | ------------------------- | | backgroundColor | `string` | Map background color | '#f6f8fa' | | fitMarginPercent | `number` | Map fit margin percentage | 20 | | containerTop | `string` | Map container top position | '0px' | | containerLeft | `string` | Map container left position | '0px' | | containerWidth | `string` | Map container width | '100%' | | containerHeight | `string` | Map container height | '100%' | | minZoom | `number` | Min zoom level | 0.5 | | maxZoom | `number` | Max zoom level | 2 | | robotColor | `ColorSource` | Robot coordinate point color | '#2ca7ff' | | robotRadius | `number` | Robot coordinate point radius | 10 | | cellSize | `number` | Grid map cell size (in pixels) | 20 | | mapCurrentColor | `ColorSource` | Grid map current point color | 'rgba(44, 167, 255, 0.1)' | | mapBarrierColor | `ColorSource` | Grid map barrier color | '#8da8ba' | | mapCleanColor | `ColorSource` | Grid map clean point color | 'rgba(44, 167, 255, 0.1)' | | mapUnknownColor | `ColorSource` | Grid map unknown point color | 'rgba(255, 255, 255, 0)' | | showPath | `boolean` | Whether to show grid map path | true | | pathColor | `ColorSource` | Grid map path color | '#42657f' | | pathWidth | `number` | Grid map path width | 4 | | robotStrokeColor | `ColorSource` | Grid map robot point stroke color | 'ffffff' | | robotStrokeWidth | `number` | Grid map robot point stroke width | 4 | | chargingStationSrc | `string` | Grid map charging station icon path | - | | chargingStationHeight | `number` | Grid map charging station icon height | 32 | | chargingStationWidth | `number` | Grid map charging station icon width | 32 | #### Map API Functions (MapApiFuncGridMap) Once the map is initialized, the `onMapReady` callback function will provide the following API methods: #### drawMap(mapData: GridMapData): void Draw the grid map. **Parameters:** - `mapData`: GridMapData - Map data containing grid map point type data **Usage:** ```javascript const handleMapReady = (api, mapId) => { api.drawMap({ origin: {x: 0, y: 0}, width: 20, height: 20, data: [...] // Grid map point type data }); }; ``` #### drawCleanPath(pathData: MapPoint[]): void Draw the cleaning path. **Parameters:** - `pathData`: MapPoint[] - Array of cleaning path points **Usage:** ```javascript const handleMapReady = (api, mapId) => { api.drawCleanPath([ { x: 5, y: 10 }, { x: 10, y: 15 }, { x: 15, y: 20 }, ]); }; ``` #### drawChargingStation(position: MapPoint): void Draw the charging station. **Parameters:** - `position`: MapPoint - Charging station position point **Usage:** ```javascript const handleMapReady = (api, mapId) => { api.drawChargingStation({ x: 5, y: 5 }); }; ``` ### Usage Example ```tsx import { GridMapComponent } from '@ray-js/gyro-map-component'; import { MapApiFuncGridMap } from '@ray-js/gyro-map-sdk'; export default () => { // Get map data and configuration through API or mqtt stream service (Template for reference) const { mapData, mapConfig } = useMapData(subRecordId); const [mapApi, setMapApi] = useState(null); useEffect(() => { if (mapData && mapApi) { const gridMapData = parseGridMapData([mapData], mapConfig, false); const { mapData: convertedMapData, pathData: convertedPathData, pilePosition } = gridMapData; mapApi.drawMap(convertedMapData); convertedPathData.length > 0 && mapApi.drawCleanPath(convertedPathData); pilePosition && mapApi.drawChargingStation(pilePosition); } }, [mapData, mapApi]); return ( ); }; ``` ## CoverageMapComponent (Coverage Map) ### Component Props | Property | Type | Required | Description | | ---------- | ------------------------------------------------------- | -------- | ------------------------------------------------- | | config | `DeepPartial` | No | Map configuration options | | onMapReady | `(funcs: MapApiFuncCoverageMap, mapId: string) => void` | No | Callback when map is initialized and API is ready | ### Configuration Options (CoverageMapConfig) #### Basic Configuration | Property | Type | Description | Default | | ---------------- | ------------- | ----------------------------- | --------- | | backgroundColor | `string` | Map background color | '#f6f8fa' | | fitMarginPercent | `number` | Map fit margin percentage | 20 | | containerTop | `string` | Map container top position | '0px' | | containerLeft | `string` | Map container left position | '0px' | | containerWidth | `string` | Map container width | '100%' | | containerHeight | `string` | Map container height | '100%' | | minZoom | `number` | Min zoom level | 0.5 | | maxZoom | `number` | Max zoom level | 2 | | robotColor | `ColorSource` | Robot coordinate point color | '#fe5332' | | robotRadius | `number` | Robot coordinate point radius | 0.5 | | borderColor | `ColorSource` | Coverage map border color | '#8da8ba' | | borderWidth | `number` | Coverage map border width | 1 | | fillColor | `ColorSource` | Coverage map fill color | '#e1f0fb' | | fillWidth | `number` | Coverage map fill width | 1.5 | #### Map API Functions (MapApiFuncCoverageMap) Once the map is initialized, the `onMapReady` callback function will provide the following API methods: #### drawMap(points: Array): void Draw the coverage map boundary. **Parameters:** - `points`: Array - Boundary point data used to build SVG path **Usage:** ```javascript const handleMapReady = (api, mapId) => { api.drawMap([ { x: 0, y: 0 }, { x: 10, y: 0 }, { x: 10, y: 10 }, { x: 0, y: 10 }, { x: 0, y: 0 }, ]); }; ``` #### drawRobot(point: MapPoint): void Draw the robot position. **Parameters:** - `point`: MapPoint - Current robot position point **Usage:** ```javascript const handleMapReady = (api, mapId) => { api.drawRobot({ x: 5, y: 5 }); }; ``` ### Usage Example ```tsx import { CoverageMapComponent } from '@ray-js/gyro-map-component'; import { MapApiFuncCoverageMap } from '@ray-js/gyro-map-sdk'; export default () => { // Get map data and configuration through API or mqtt stream service (Template for reference) const { mapData, mapConfig } = useMapData(subRecordId); const [mapApi, setMapApi] = useState(null); useEffect(() => { if (mapData && mapApi) { const { pointsData, currentPos } = parseMapData([mapData], mapConfig); mapApi.drawMap(pointsData); currentPos && mapApi.drawRobot(currentPos); } }, [mapData, mapApi]); return ( ); }; ``` ## Notes - **Type Definitions**: - `ColorSource` type represents acceptable color value formats, typically including color strings (like '#RRGGBB') or other color representations - `DeepPartial` indicates that all properties in the configuration object are optional, and properties in nested objects are also optional - `MapPoint` type represents a point object with x and y coordinates, for example `{ x: 10, y: 20 }` - `GridMapData` contains width, height, and point type data array for grid maps - **Map Type Selection**: - **Grid Map**: Suitable for scenarios that require accurate display of obstacles, cleaned areas, and uncleaned areas, commonly used for precise navigation and cleaning path recording in complex indoor environments - **Coverage Map**: Suitable for scenarios that only focus on cleaning coverage area, using boundary drawing to show the cleaned area, with a more concise visual presentation - **Version Dependencies**: - Ensure installation of matching version of the dependency library `@ray-js/gyro-map-sdk` to avoid API incompatibility issues - App baseline version >= **6.7.0**