DiRecommendSpotManager

等候点插件

DiRecommendSpotManager 用于展示中心大头针、周边推荐点和运营区域围栏，并提供拖动选点、自动吸附及自定义推荐点数据源能力。

快速开始

从 DiMapPlugin 中获取 DiRecommendSpotManager

html

<div id="container" style="width: 100vw; height: 100vh"></div>

<script>
  window._DiMapSecurityConfig = {
    securityJsCode: "js安全密钥"
  }
</script>
<script src="https://lbs.xiaojukeji.com/api/v2/static/loader.js"></script>
<script>
  window.DiMapLoader.load({
    key: "您申请的 key",
    plugins: ["DiRecommendSpotManager"]
  }).then(({ DiMap, DiMapPlugin }) => {
    const map = new DiMap.Map({
      container: "container",
      style: "dimap://styles/normal",
      center: [116.397428, 39.90923],
      zoom: 16
    })

    const waitingSpotManager = new DiMapPlugin.DiRecommendSpotManager(map, {
      pinColor: 0x26c281,
      areaVisible: true
    })

    waitingSpotManager.requestRecommendSpot([116.397428, 39.90923])
  })
</script>

创建实例

javascript

const waitingSpotManager = new DiMapPlugin.DiRecommendSpotManager(map, options)

参数	必填	类型	说明
`map`	是	`DiMap.Map`	已创建的地图实例。
`options`	否	`DiRecommendSpotOptions`	推荐点、围栏的样式及场站行为配置。

DiRecommendSpotOptions

参数	类型	说明
`pinColor`	`number \| string`	中心大头针主色，影响圆形大头针和气泡连接杆。
`dotIcon`	`string \| HTMLElement`	周边推荐点图标。字符串仅支持 HTTP(S) 地址；传入 DOM 元素时，使用该元素作为推荐点图标。
`circleRadius`	`number`	推荐点圆点半径，单位为像素，范围 `4-20`，默认 `8`。
`textColor`	`number \| string`	推荐点名称颜色。
`textSize`	`number`	推荐点名称字号，单位为像素，范围 `5-40`。
`fenceStyle`	`DiRecommendSpotFenceStyles`	普通围栏和管制围栏的填充色、描边色、描边宽度；未设置的字段使用服务端样式。
`areaVisible`	`boolean`	是否绘制运营区域围栏，默认 `true`。
`forceDepartureInStation`	`boolean`	是否启用强吸场站的拖出拉回能力，默认 `false`。仅服务端返回强吸场站围栏时生效。

注：颜色数值支持 0xRRGGBB，例如 0x26c281；字符串支持 #RRGGBB 与 #RRGGBBAA，例如 #26C281、#26C28180。

fenceStyle 示例：

javascript

const waitingSpotManager = new DiMapPlugin.DiRecommendSpotManager(map, {
  fenceStyle: {
    normal: {
      fillColor: "#26C28133",
      strokeColor: "#26C281",
      strokeWidth: 2
    },
    controlled: {
      fillColor: "#FF7A0033",
      strokeColor: "#FF7A00",
      strokeWidth: 2
    }
  }
})

请求推荐点

requestRecommendSpot

请求并刷新指定坐标附近的推荐点（更新推荐点、围栏、中心大头针）。

没有推荐点时，大头针展示当前位置的反解或兜底点，坐标顺序为 [longitude, latitude]。

requestRecommendSpot(lnglat: [number, number]): Promise<void>

示例：

javascript

waitingSpotManager.requestRecommendSpot([116.397428, 39.90923])

setCurrentLocation

设置用户真实定位，传入 null 清除定位。

注：仅影响后续服务端请求的定位参数，不会移动地图或立即发起请求。

setCurrentLocation(location: DiRecommendSpotLocation | null): void

参数说明：

字段	类型	必填	说明
`longitude`	`number`	是	经度。
`latitude`	`number`	是	纬度。
`accuracy`	`number`	否	定位精度，单位米。

示例：

javascript

waitingSpotManager.setCurrentLocation({
  longitude: 116.397428,
  latitude: 39.90923,
  accuracy: 20
})

自定义推荐点

setRecommendSpotDisplayMode

设置请求使用的数据源。

setRecommendSpotDisplayMode(mode: 0 | 1 | 2): void

参数说明：

数值	含义
`0`	仅展示业务方通过 Provider 提供的推荐点。
`1`	合并两类推荐点；同坐标点会去重，围栏优先使用滴滴服务端数据。
`2`	仅展示滴滴服务端推荐点，默认值。

注：修改展示模式或 Provider 后，需调用 requestRecommendSpot 或拖图刷新显示。

setRecommendSpotProvider

设置业务方自定义数据源，传入 null 移除数据源。

setRecommendSpotProvider(provider: IDiRecommendSpotProvider | null): void

IDiRecommendSpotProvider

业务方实现该接口，为 SDK 提供自定义推荐点数据。

interface IDiRecommendSpotProvider {
  getDiRecommendSpotInfos(
    center: [number, number]
  ): DiRecommendSpotInfo[] | Promise<DiRecommendSpotInfo[]>
  getDiRecommendSpotEntity?(
    center: [number, number]
  ): DiRecommendSpotCustomEntity | Promise<DiRecommendSpotCustomEntity>
}

方法	必填	说明
`getDiRecommendSpotInfos(center)`	是	返回自定义推荐点。`center` 的顺序为 `[longitude, latitude]`。
`getDiRecommendSpotEntity(center)`	否	返回推荐点和可选运营区域；实现该方法时，SDK 优先使用其结果。

示例：

只需要返回推荐点时，实现 getDiRecommendSpotInfos 即可：

javascript

waitingSpotManager.setRecommendSpotProvider({
  async getDiRecommendSpotInfos(center) {
    // center 是本次请求中心，格式为 [longitude, latitude]
    console.log("请求中心", center)
    return [
      { name: "A 出入口推荐点", longitude: 116.3978, latitude: 39.9094 },
      { name: "B 出入口推荐点", longitude: 116.3969, latitude: 39.9088 }
    ]
  }
})

waitingSpotManager.setRecommendSpotDisplayMode(0)
waitingSpotManager.requestRecommendSpot([116.397428, 39.90923])

需要同时返回推荐点和自定义运营区域时，实现 getDiRecommendSpotEntity：

javascript

waitingSpotManager.setRecommendSpotProvider({
  getDiRecommendSpotInfos() {
    return []
  },
  getDiRecommendSpotEntity() {
    return {
      diRecommendSpotInfos: [
        { name: "南门推荐点", longitude: 116.3978, latitude: 39.9094 }
      ],
      diRecommendSpotArea: {
        id: "south-gate",
        name: "南门等候区",
        parentName: "示例园区",
        polygon: [[
          [116.3972, 39.909],
          [116.3981, 39.909],
          [116.3981, 39.9097],
          [116.3972, 39.9097],
          [116.3972, 39.909]
        ]]
      }
    }
  }
})

注：polygon 是坐标环列表，坐标顺序为 [longitude, latitude]，每个环首尾坐标必须相同。

setRequestCustomRecommendSpotTimeout

设置自定义 Provider 的超时毫秒数，time 必须是正数。超时后本次自定义结果按空处理，在合并模式下滴滴服务端推荐点仍可展示。

setRequestCustomRecommendSpotTimeout(time: number): void

setRecommendSpotProviderResultListener

监听自定义 Provider 的每次请求结果，适用于埋点和降级观测；传入 null 取消监听。

setRecommendSpotProviderResultListener(
  listener: DiRecommendSpotProviderResultListener | null
): void

回调参数说明：

字段	类型	说明
`status`	`success \| empty \| error \| timeout`	自定义数据源的结果状态。
`center`	`[number, number]`	本次请求中心，顺序为 `[longitude, latitude]`。
`entity`	`DiRecommendSpotCustomEntity \| null`	自定义推荐点及可选区域；未配置 Provider、异常或超时时为 `null`，空列表时仍为对象。
`error`	`unknown`	Provider 异常时的原始错误。

示例：

javascript

waitingSpotManager.setRecommendSpotProviderResultListener(
  ({ status, center, entity, error }) => {
    console.log("自定义推荐点状态", status, center, entity, error)
  }
)

吸附与显示控制

setAttachDistance

设置普通近距离自动吸附半径。用户拖动地图结束后，若中心大头针距最近推荐点小于该阈值，SDK 自动选中该推荐点作为等候点。

setAttachDistance(
  distance: number,
  unit: 0 | 1 | 2
): void

参数说明：

数值	可用范围	含义
`0`	`1-80`	屏幕像素。
`1`	`1-50`	物理距离，单位米，会按当前缩放级别换算。
`2`	`1-20`	地图容器宽度百分比，例如 `5` 表示容器宽度的 5%。

示例：

javascript

waitingSpotManager.setAttachDistance(
  40,
  0
)

setAutoAttachEnable

控制拖图结束后的普通近距离自动吸附。

setAutoAttachEnable(enable: boolean): void

注：设为 false 后，服务端推荐、强吸围栏和强制拉回不受影响。

setForceDepartureInStation

开启后，用户拖出强吸场站围栏时，自动拉回并选中场站内最近推荐点。普通围栏不受影响。

setForceDepartureInStation(enable: boolean): void

setZoomLevel

设置周边推荐点的最低展示缩放级别。

地图 zoom < zoomLevel 时，隐藏推荐点圆点与名称；
地图 zoom >= zoomLevel 时恢复展示
传入 null 取消限制（默认值）。

注：该设置只影响周边推荐点圆点和名称。

setZoomLevel(zoomLevel: number | null): void

回调与请求控制

setAttachRecommendSpotCallback

每次自动选点或调用 requestRecommendSpot 完成后触发。两者参数都只包含名称和经纬度：

attachedRecommendSpot：自动吸附、强制吸附或重新请求后吸附到推荐点时触发，参数为选中的等候点。
attachedRecommendSpotFailed：未吸附到推荐点时触发，参数为当前中心位置的反解点或“当前位置”兜底点。

用户主动点击推荐点不触发该回调，请使用 setOnRecommendSpotClickListener 监听。

setAttachRecommendSpotCallback(callback: DiRecommendSpotAttachCallback): void

示例：

javascript

waitingSpotManager.setAttachRecommendSpotCallback({
  attachedRecommendSpot(spot) {
    console.log("已选等候点", spot)
  },
  attachedRecommendSpotFailed(rgeoSpot) {
    console.log("未吸附，当前反解或兜底点", rgeoSpot)
  }
})

setOnRecommendSpotClickListener

用户主动点击周边推荐点时调用，不会在自动吸附时调用。

setOnRecommendSpotClickListener(listener: DiRecommendSpotClickListener | null): void

示例：

javascript

waitingSpotManager.setOnRecommendSpotClickListener((spot) => {
  console.log("用户点击了推荐点", spot)
})

setOnAreaChangedListener

监听实际生效围栏的变化。

setOnAreaChangedListener(listener: DiRecommendSpotAreaChangeListener | null): void

示例：

javascript

waitingSpotManager.setOnAreaChangedListener((areaInfo) => {
  console.log("当前运营区", areaInfo)
})

setOnPinCalloutClickListener

设置中心大头针气泡的点击监听。

注：注册后气泡显示箭头，传入 null 会取消监听并隐藏箭头。

setOnPinCalloutClickListener(
  listener: DiRecommendSpotPinCalloutClickListener | null
): void

示例：

javascript

waitingSpotManager.setOnPinCalloutClickListener((spot) => {
  console.log("点击中心大头针气泡", spot)
})

DiRecommendSpotPinCalloutClickListener

中心大头针气泡点击回调类型。

type DiRecommendSpotPinCalloutClickListener = (
  spot: DiRecommendSpotInfo
) => void

参数	类型	说明
`spot`	`DiRecommendSpotInfo`	当前大头针选中的等候点，未吸附时为当前位置的反解或兜底点。

pauseRequest

暂停地图手势结束时的自动请求。不影响在途请求和手动请求。

pauseRequest(): void

resumeRequest

恢复地图手势结束时的自动请求。

resumeRequest(): void

清理与销毁

clearRecommendSpots

清空周边推荐点和当前选中态，中心大头针和已显示围栏保留。

clearRecommendSpots(): void

destroy

销毁 SDK 创建的覆盖物和地图事件监听。

页面或组件卸载时调用：

destroy(): void

示例：

javascript

waitingSpotManager.destroy()

数据类型

DiRecommendSpotInfo

自定义 Provider 推荐点、点击回调中的推荐点、吸附成功回调中的等候点对象等会使用该类型，必须包含以下字段：

interface DiRecommendSpotInfo {
  name: string
  longitude: number
  latitude: number
}

DiRecommendSpotAreaInfo

自定义 Provider 区域、区域变化回调返回的区域对象等会使用该类型：

interface DiRecommendSpotAreaInfo {
  id: string
  name: string
  parentName: string
  stationType?: number
  polygon: [number, number][][]
}

字段	类型	必填	说明
`id`	`string`	是	区域唯一标识。区域变化回调以该字段判断是否进入或切换区域。
`name`	`string`	是	区域名称。
`parentName`	`string`	是	上级区域或场站名称；无上级名称时传空字符串。
`stationType`	`number`	否	场站或区域类型，取值见下表。
`polygon`	`[number, number][][]`	是	区域边界坐标环列表。坐标顺序为 `[longitude, latitude]`，每个环必须闭合。

DiRecommendSpotStationType

stationType 是可选数值。区域没有明确场站类型时可省略。

数值	区域类型
`1`	机场。
`2`	火车站。
`3`	客运站。
`4`	商场。
`5`	地铁站。
`9`	管制围栏。

javascript

const stationType = 2 // 火车站

DiRecommendSpotFenceStyles

用于配置围栏样式；未设置的字段使用服务端样式。

interface DiRecommendSpotFenceStyles {
  normal?: DiRecommendSpotFenceStyle
  controlled?: DiRecommendSpotFenceStyle
}

interface DiRecommendSpotFenceStyle {
  fillColor?: number | string
  strokeColor?: number | string
  strokeWidth?: number
}

顶层字段

字段	类型	说明
`normal`	`DiRecommendSpotFenceStyle`	普通围栏样式。
`controlled`	`DiRecommendSpotFenceStyle`	管制围栏样式。

DiRecommendSpotFenceStyle 字段

字段	类型	说明
`fillColor`	`number \| string`	填充色。颜色格式与 `pinColor` 相同。
`strokeColor`	`number \| string`	描边色。
`strokeWidth`	`number`	描边宽度，单位像素，范围 `0-20`。

DiRecommendSpotCustomEntity

interface DiRecommendSpotCustomEntity {
  diRecommendSpotInfos: DiRecommendSpotInfo[]
  diRecommendSpotArea?: DiRecommendSpotAreaInfo
}

字段	类型	必填	说明
`diRecommendSpotInfos`	`DiRecommendSpotInfo[]`	是	推荐点列表。
`diRecommendSpotArea`	`DiRecommendSpotAreaInfo`	否	运营区域。

DiRecommendSpotManager ​

快速开始 ​

创建实例 ​

DiRecommendSpotOptions ​

请求推荐点 ​

requestRecommendSpot ​

setCurrentLocation ​

自定义推荐点 ​

setRecommendSpotDisplayMode ​

setRecommendSpotProvider ​

IDiRecommendSpotProvider ​

setRequestCustomRecommendSpotTimeout ​

setRecommendSpotProviderResultListener ​

吸附与显示控制 ​

setAttachDistance ​

setAutoAttachEnable ​

setForceDepartureInStation ​

setZoomLevel ​

回调与请求控制 ​

setAttachRecommendSpotCallback ​

setOnRecommendSpotClickListener ​

setOnAreaChangedListener ​

setOnPinCalloutClickListener ​

DiRecommendSpotPinCalloutClickListener ​

pauseRequest ​

resumeRequest ​

清理与销毁 ​

clearRecommendSpots ​

destroy ​

数据类型 ​

DiRecommendSpotInfo ​

DiRecommendSpotAreaInfo ​

DiRecommendSpotStationType ​

DiRecommendSpotFenceStyles ​

DiRecommendSpotCustomEntity ​

DiRecommendSpotManager

快速开始

创建实例

DiRecommendSpotOptions

请求推荐点

requestRecommendSpot

setCurrentLocation

自定义推荐点

setRecommendSpotDisplayMode

setRecommendSpotProvider

IDiRecommendSpotProvider

setRequestCustomRecommendSpotTimeout

setRecommendSpotProviderResultListener

吸附与显示控制

setAttachDistance

setAutoAttachEnable

setForceDepartureInStation

setZoomLevel

回调与请求控制

setAttachRecommendSpotCallback

setOnRecommendSpotClickListener

setOnAreaChangedListener

setOnPinCalloutClickListener

DiRecommendSpotPinCalloutClickListener

pauseRequest

resumeRequest

清理与销毁

clearRecommendSpots

destroy

数据类型

DiRecommendSpotInfo

DiRecommendSpotAreaInfo

DiRecommendSpotStationType

DiRecommendSpotFenceStyles

DiRecommendSpotCustomEntity