Tuya Robot Map

Appearance

地图方法 ​

了解 RobotMap 提供的 API 方法。

使用示例 ​

通过 onMapReady 回调获得 MapApi 实例，该实例包含所有可调用的地图方法。这些方法让你可以主动控制地图行为、查询数据和执行各种操作。

tsx
import { MapApi } from '@ray-js/robot-map'

function MapPage() {
  const mapApi = useRef<MapApi>(null)

  const handleMapReady = (mapApi: MapApi) => {
    mapApi.current = mapApi
  }

  const handleResetMapView = () => {
    mapApi.current?.resetPanZoom()
  }

  const handleGetCleanZones = async () => {
    const zones = await mapApi.current?.getCleanZones()
  }

  return (
    <RobotMap
      onMapReady={handleMapReady}
      // ... 其他属性
    />
  )
}

TIP

注意所有地图方法都是异步的Promise，需要使用 await 或 then 来获取结果。

areRoomsAdjacent() ​

判断指定的房间是否相邻（连通）。

判定阈值由 config.map.adjacencyThreshold 配置决定。

类型:

ts
function areRoomsAdjacent(roomIds: number[]): Promise<boolean>

参数:

  • roomIds: number[] - 要检测的房间ID数组

返回值: Promise<boolean>

getForbiddenSweepZones() ​

获取当前地图上所有禁扫区域数据。

类型:

ts
function getForbiddenSweepZones(): Promise<ZoneParam[]>

返回值: Promise<ZoneParam[]>

getForbiddenMopZones() ​

获取当前地图上所有禁拖区域数据。

类型:

ts
function getForbiddenMopZones(): Promise<ZoneParam[]>

返回值: Promise<ZoneParam[]>

getCleanZones() ​

获取当前地图上所有清扫区域数据。

类型:

ts
function getCleanZones(): Promise<ZoneParam[]>

返回值: Promise<ZoneParam[]>

getVirtualWalls() ​

获取当前地图上所有虚拟墙数据。

类型:

ts
function getVirtualWalls(): Promise<VirtualWallParam[]>

返回值: Promise<VirtualWallParam[]>

getSpots() ​

获取当前地图上所有定点清扫数据。

类型:

ts
function getSpots(): Promise<SpotParam[]>

返回值: Promise<SpotParam[]>

getWayPoints() ​

获取当前地图上所有途径点数据。

类型:

ts
function getWayPoints(): Promise<WayPointParam[]>

返回值: Promise<WayPointParam[]>

getEffectiveDividerPoints() ​

获取分割线有效端点。

类型:

ts
function getEffectiveDividerPoints(): Promise<Point[] | null>

返回值: Promise<Point[] | null> | null

getDividerEndPoints() ​

获取分割线端点。

类型:

ts
function getDividerEndPoints(): Promise<Point[] | null>

返回值: Point[] | null

getViewportCenterPoint() ​

获取当前视口中心点坐标。

类型:

ts
function getViewportCenterPoint(): Promise<Point | null>

返回值: Promise<Point[]> | null

getMapCenterPoint() ​

获取地图中心点坐标。

类型:

ts
function getMapCenterPoint(): Promise<Point | null>

返回值: Promise<Point[]> | null

getWallPointsByViewportCenter() ​

基于视口中心生成虚拟墙端点坐标。

类型:

ts
function getWallPointsByViewportCenter(options?: {
  width?: number
  direction?: Direction
  offsetX?: number
  offsetY?: number
}): Promise<Point[]>

参数:

  • options - 配置选项
  • options.width: number - 虚拟墙长度，单位米，默认使用配置中的最小宽度
  • options.direction: Direction - 虚拟墙方向，'horizontal' 或 'vertical'，默认为 'horizontal'
  • options.offsetX: number - X方向像素偏移，支持负数，默认为 0
  • options.offsetY: number - Y方向像素偏移，支持负数，默认为 0

返回值: Promise<Point[]>

getForbiddenSweepZonePointsByViewportCenter() ​

基于视口中心生成禁扫区域顶点坐标。

类型:

ts
function getForbiddenSweepZonePointsByViewportCenter(options?: {
  size?: number
  offsetX?: number
  offsetY?: number
}): Promise<Point[]>

参数:

  • options - 配置选项
  • options.size: number - 区域大小，单位米，默认使用配置中的最小尺寸
  • options.offsetX: number - X方向像素偏移，支持负数，默认为 0
  • options.offsetY: number - Y方向像素偏移，支持负数，默认为 0

返回值: Promise<Point[]>

getForbiddenMopZonePointsByViewportCenter() ​

基于视口中心生成禁拖区域顶点坐标。

类型:

ts
function getForbiddenMopZonePointsByViewportCenter(options?: {
  size?: number
  offsetX?: number
  offsetY?: number
}): Promise<Point[]>

参数:

  • options - 配置选项
  • options.size: number - 区域大小，单位米，默认使用配置中的最小尺寸
  • options.offsetX: number - X方向像素偏移，支持负数，默认为 0
  • options.offsetY: number - Y方向像素偏移，支持负数，默认为 0

返回值: Promise<Point[]>

getCleanZonePointsByViewportCenter() ​

类型:

ts
function getCleanZonePointsByViewportCenter(options?: {
  size?: number
  offsetX?: number
  offsetY?: number
}): Promise<Point[]>

参数:

  • options - 配置选项
  • options.size: number - 区域大小，单位米，默认使用配置中的最小尺寸
  • options.offsetX: number - X方向像素偏移，支持负数，默认为 0
  • options.offsetY: number - Y方向像素偏移，支持负数，默认为 0

返回值: Promise<Point[]>

getSpotPointByViewportCenter() ​

基于视口中心生成定点清扫的点坐标。

类型:

ts
function getSpotPointByViewportCenter(options?: {
  offsetX?: number
  offsetY?: number
}): Promise<Point>

参数:

  • options - 配置选项
  • options.size: number - 区域大小，单位米，默认使用配置中的最小尺寸
  • options.offsetX: number - X方向像素偏移，支持负数，默认为 0
  • options.offsetY: number - Y方向像素偏移，支持负数，默认为 0

返回值: Promise<Point[]>

isNearChargerOrRobot() ​

判断一个点、墙体或区域是否与充电桩或机器人距离小于阈值。

类型:

ts
function isNearChargerOrRobot(
  points: Point[],
  thresholdMeters: number,
  options?: {
    checkCharger?: boolean
    checkRobot?: boolean
  },
): boolean

参数:

  • points: Point[] - 点坐标数组，支持点/墙体/区域三种类型。
  • thresholdMeters: number - 阈值距离，单位米
  • options - 配置选项
  • options.checkCharger: boolean - 是否检查与充电桩的距离，默认为 true
  • options.checkRobot: boolean - 是否检查与机器人的距离，默认为 false

返回值: boolean - 是否在判定范围内（true 表示过近，false 表示距离足够）

示例:

ts
// 判断拖拽后的墙体是否与充电桩或机器人距离小于1米
function MapPage() {
  const [mapApi, setMapApi] = useState<MapApi | null>(null)

  const handleMapReady = (mapApi: MapApi) => {
    setMapApi(mapApi)
  }

  const handleUpdateVirtualWall = async (wall: VirtualWallParam) => {
    const isNearChargerOrRobot = await mapApi?.isNearChargerOrRobot(
      wall.points,
      1,
      { checkCharger: true, checkRobot: true },
    )
    if (isNearChargerOrRobot) {
      console.log('墙体与充电桩或机器人距离小于1米')
    } else {
      console.log('墙体与充电桩或机器人距离大于1米')
    }
  }
}

  return (
    <RobotMap
      onMapReady={handleMapReady}
      // ... 其他属性
      onUpdateVirtualWall={handleUpdateVirtualWall}
    />
  )
}

isPointInAnyRoom() ​

判断一个点是否在任意房间内。

TIP

需要传入基于机器坐标系的点

类型:

ts
function isPointInAnyRoom(point: Point): Promise<RoomData | null>

参数:

  • point: Point - 待检测的点坐标（机器坐标系）

返回值: Promise<RoomData | null> - 如果点在某个房间内，返回该房间的 RoomData；否则返回 null

示例:

ts
// 判断一个点是否在房间内
const roomData = await mapApi.isPointInAnyRoom({ x: 100, y: 200 })
if (roomData) {
  console.log(`点在房间 ${roomData.name} 内`)
} else {
  console.log('点不在任何房间内')
}

isWallIntersectsAnyRoom() ​

判断一个墙体是否与任意房间有交集。

类型:

ts
function isWallIntersectsAnyRoom(points: Point[]): Promise<boolean>

参数:

  • points: Point[] - 墙体的两个端点坐标（机器坐标系）

返回值: Promise<boolean>

示例:

tsx
// 可以在onUpdateVirtualWall回调中使用，判断墙体是否与房间有交集
import { MapApi, VirtualWallParam } from '@ray-js/robot-map'
import React, { useState } from 'react'

function MapPage() {
  const [mapApi, setMapApi] = useState<MapApi | null>(null)

  const handleMapReady = (mapApi: MapApi) => {
    setMapApi(mapApi)
  }

  const handleUpdateVirtualWall = async (wall: VirtualWallParam) => {
    const isIntersects = await mapApi?.isWallIntersectsAnyRoom(wall.points)
    if (isIntersects) {
      console.log('墙体与房间有交集')
    } else {
      console.log('墙体与房间没有交集')
    }
  }

  return (
    <RobotMap
      onMapReady={handleMapReady}
      // ... 其他属性
      onUpdateVirtualWall={handleUpdateVirtualWall}
    />
  )
}

isZoneIntersectsAnyRoom() ​

判断一个区域是否与任意房间有交集。

类型:

ts
function isZoneIntersectsAnyRoom(points: Point[]): Promise<boolean>

参数:

  • points: Point[] - 区域的四个顶点坐标（机器坐标系）

返回值: Promise<boolean>

示例:

tsx
// 可以在onUpdateForbiddenSweepZone回调中使用，判断区域是否与房间有交集
import { MapApi, ZoneParam } from '@ray-js/robot-map'
import React, { useState } from 'react'

function MapPage() {
  const [mapApi, setMapApi] = useState<MapApi | null>(null)

  const handleMapReady = (mapApi: MapApi) => {
    setMapApi(mapApi)
  }

  const handleUpdateForbiddenSweepZone = async (zone: ZoneParam) => {
    const isIntersects = await mapApi?.isZoneIntersectsAnyRoom(zone.points)
    if (isIntersects) {
      console.log('区域与房间有交集')
    } else {
      console.log('区域与房间没有交集')
    }
  }

  return (
    <RobotMap
      onMapReady={handleMapReady}
      // ... 其他属性
      onUpdateForbiddenSweepZone={handleUpdateForbiddenSweepZone}
    />
  )
}

resetPanZoom() ​

重置地图的平移和缩放状态到初始位置。

类型:

ts
function resetPanZoom(): Promise<void>

返回值: Promise<void>

snapshot() ​

当前地图截图。

类型:

ts
function snapshot(): Promise<string>

返回值: Promise<string>

snapshotByData() ​

根据指定的地图数据进行截图。

TIP

静态配置会沿用当前地图的配置。

类型:

ts
function snapshotByData(
  data: {
    map: string
    path?: string
    roomProperties?: RoomProperty[]
    customElements?: CustomElementParam[]
    forbiddenSweepZones?: ZoneParam[]
    forbiddenMopZones?: ZoneParam[]
    virtualWalls?: VirtualWallParam[]
    detectedObjects?: DetectedObjectParam[]
  },
  runtime?: DeepPartialRuntimeConfig,
): Promise<string>

参数:

  • data - 地图数据对象
  • data.map: string - 地图字符串数据
  • data.path: string - 可选的路径数据
  • data.roomProperties: RoomProperty[] - 可选的房间属性数据
  • data.customElements: CustomElementParam[] - 可选的自定义元素数据
  • data.forbiddenSweepZones: ZoneParam[] - 可选的禁扫区域数据
  • data.forbiddenMopZones: ZoneParam[] - 可选的禁拖区域数据
  • data.virtualWalls: VirtualWallParam[] - 可选的虚拟墙数据
  • data.detectedObjects: DetectedObjectParam[] - 可选的检测物体数据
  • runtime - 可选的运行时配置

返回值: Promise<string>