📦 大空间模型平面图

MapviewFloorplanPlugin

此插件强依赖于平面图数据，请率先了解如何获取平面图数据。

功能说明

大空间模型平面图插件 是对模型平面图插件的升级版本，新增了缩放和拖动的手势操作。

借助此插件，您可以在 VR 3D 模型状态下展示更详细的二维平面图，除却以下同模型平面图插件实现的相同功能：

支持二维平面图( png / svg 格式)展示。
房屋标签展示: 支持自定义标签样式。
展示进入二维平面图前，相机位置和朝向: 支持自定义相机图标。
支持多楼层 VR 房源，即支持多楼层切换。
俯视视角上，二维平面图与 VR 3D 模型的自适应对齐。
点击二维平面图房间，会自动进入到 VR 对应房间的合适点位。
指北针展示: 暂不支持配置，但可以借助 CSS 选择器优先级方式覆盖原有样式。
支持手势快捷操作：在二维平面图界面进行滑动，会快速切换到模型状态；在模型状态松手时，如果比较接近平面图的展示角度，会自动旋转模型，并展示平面图。此功能支持配置是否禁用。

大空间模型平面图还增加了以下功能：

等比放大、缩小二维平面图与 VR 3D模型，保证二者的对齐。
拖动查看放大后的平面图展示，可以精准查看平面图的某一区域内容。

示例效果

安装引用

请按需选择 yarn 或 npm 安装方式：

npm
Yarn
pnpm

npm install @realsee/dnalogel

yarn add @realsee/dnalogel

pnpm add @realsee/dnalogel

通过 es 引用：

import MapviewFloorplanPlugin from "@realsee/dnalogel"

开发指南

提示

此插件的使用方式与模型平面图插件完全一致，包括初始化、数据载入、核心方法调用、自定义配置以及事件 hooks 使用，展示效果也基本相同，主要区别于大空间模型平面图插件增加了缩放和拖动功能，如果您已经掌握了模型平面图插件的使用，您也就掌握了大空间模型平面图插件的使用方式，只需要根据合适的使用场景调用即可。

初始化

在初始化 Five 实例的时候，将 MapviewFloorplanPlugin 配置在初始化插件参数即可。

import Five, { FivePluginInits } from '@realsee/five'
import MapviewFloorplanPlugin from '@realsee/dnalogel'

// 初始化 five 实例
const five = new Five({
  plugins: [
    [MapviewFloorplanPlugin, "mapviewFloorplanPlugin", {
      // 初始化参数
    }]
  ]
})

React 初始化

在创建 FiveProvider 组件时将 MapviewFloorplanPlugin 配置在初始化插件参数即可。

import { createFiveProvider } from '@realsee/five/react'

// 创建 FiveProvider 组件
const FiveProvider = createFiveProvider({
    plugins: [
        [MapviewFloorplanPlugin, "mapviewFloorplanPlugin", {
            // 初始化参数
        }]
    ]
})

Vue 初始化

在使用 FiveProvider 时，将 MapviewFloorplanPlugin 配置在初始化插件参数即可。

<template>
  <FiveProvider :fiveInitArgs="fiveInitArgs">
  </FiveProvider>
</template>
<script setup>
import  MapviewFloorplanPlugin from "@realsee/dnalogel/libs/MapviewFloorplanPlugin";
import { FiveProvider, FiveCanvas } from "@realsee/five/vue";
const fiveInitArgs = {
    plugins: [
        [
            MapviewFloorplanPlugin,
            'mapviewFloorplanPlugin', // 自定义插件名称
            {
                // 参数配置
            }
        ]
    ]
}
</script>

载入数据

// 获取插件实例
const pluginInstance = five.plugins.mapviewFloorplan
// 载入数据
pluginInstance.load(floorplanServerData)

插件核心方法

MapviewFloorplanPlugin 提供的核心方法有：

load(data: FloorplanServerData) 载入平面图数据

您需要手动载入平面图数据，[FloorplanServerData] 的数据来源请阅读如视开放平台 API

appendTo(wrapper: Element) 挂载 DOM 节点

您可以将平面图DOM模块载入您的 HTML 结构中。

async show(opts?: ShowOpts): true 展示

调用插件的 show() 方法，插件会自动操作 five 实例到模型俯视状态，并展示当前点位对应楼层的平面图。

const floorplanPlugin = five.plugins.floorplan
floorplanPlugin.show()
floorplanPlugin.show(options)

如果需要自定义展示逻辑，也可以传入 options 进行配置，配置项声明如下：

interface ShowOpts {
  floorIndex?: number   // 要展示的楼层，默认是当前点位对应的楼层
  userAction?: boolean  // 在平面图展示时，调用 Five 相关 API 会透传 userAction
  modelOpacity?: number // 展示平面图时，模型对应的透明度，默认是 0.01
  immediately?: boolean // 图片出现是否要立即出现，默认会有 500ms 的动画，注意这个 immediately 不能取消模型动画
}

hide(options?: { isAutoHide?: boolean; userAction?: boolean )

您可以直接调用 hide() 方法将平面图隐藏，如果在配置项autoShowEnable设置为true（默认设置）时，当用户在平面图上进行滑动操作时，超过一定滑动幅度会自动关闭平面图。

changeFloor(floorIndex: number) 更改户型楼层

有些房源是多楼层的（复式、别墅等），每一层的户型均不同，您可以通过changeFloor()直接切换对应楼层的户型。
需要注意的是，对于多楼层房源仅会高亮当前楼层的三维模型的模块。
当然，当用户在 VR 全景中走点时，对应的楼层发生变化平面图展示期间也会自动展示当前点位的楼层。

自定义配置

MapviewFloorplanPlugin 支持丰富的自定义配置选项（详见[MapviewFloorplanParameterType]），常见的配置项有：

selector?: string | Element 插件挂载的 DOM 节点

DOM 选择器或 DOM 节点实例。需要注意的是：DOM容器必须与 five canvas 宽高一样，且层级z-index比 five canvas 高。

scale?: number 平面图缩放比例

修改此参数会连同平面图下方的VR模型比例一同更改，默认为1。

hoverEnable?: boolean 是否开启鼠标 hover 高亮分间

默认值是 false。功能是：当鼠标 hover 至对应分间时，改分间会高亮。

getLabelElement?: (room: FloorplanRoomItem) => Element | null 配置房屋标签

如果配置了这个函数，对于每一个房屋标签，都会调用此函数，并把标签的 Element 替换成回调函数返回的 ELement。如果返回结果为 null 这类空值时，当前标签不展示。
如果不配置此函数，默认为所有标签都展示。

cameraImage?: { style: React.CSSProperties } 配置相机图标

style传入的 CSS 样式会覆盖默认样式，包括 backgroundImage、width、height等。

autoShowEnable: boolean 手势快捷操作

在二维平面图界面进行滑动，会快速切换到模型状态；在模型状态松手时，如果比较接近平面图的展示角度，会自动旋转模型，并展示平面图。默认开启。

事件 Hooks

平面图相关的事件绑定在 hooks 对象上，可以使用 hooks.on 方法监听事件。如：

showAnimationEnded

平面图展示结束，只会在从不可见到可见触发，调用多次show只会触发一次 showAnimationEnded。

five.plugins.mapviewFloorplan.hooks.on('showAnimationEnded', ({ auto, userAction }) => {
  console.log('是否是用户滑动模型导致的平面图自动展示: ', auto)
  console.log('是否是用户行为导致的平面图展示: ', userAction)
  console.log('平面图展示完成')
})

hide

平面图消失完成

five.plugins.mapviewFloorplan.hooks.on('hide', ({ auto, userAction }) => {
  console.log('是否是用户滑动模型导致的平面图自动消失: ', auto)
  console.log('是否是用户行为导致的平面图消失: ', userAction)
  console.log('平面图已经消失')
})

MapviewFloorplanPlugin​

功能说明​

示例效果​

安装引用​

开发指南​

初始化​

React 初始化​

Vue 初始化​

载入数据​

插件核心方法​

自定义配置​

事件 Hooks​

demo 源码参考​