Kimap SDK Vue2 兼容包装器

为旧版Vue2项目提供的Kimap SDK兼容层，支持Webpack 3和Babel 6。

⚠️ 重要：升级Three.js版本

SDK要求 three >= 0.150.0。如果您的项目使用旧版本（如0.125.2），必须先升级。

升级Three.js：

npm install [email protected] --save

📦 安装

方法1：从npm安装（推荐⭐）

# 安装Vue2包装器（会自动安装原厂SDK）
npm install @zyl19950114/kimap-sdk-vue2 --save

# 同时安装Three.js（必需）
npm install [email protected] --save

一行命令安装全部：

npm install @zyl19950114/kimap-sdk-vue2 [email protected] --save

方法2：本地复制文件

将此 sdk-vue2-wrapper 文件夹复制到您的项目中：

your-project/
├── src/
│   ├── components/
│   │   └── kimap/           # 复制到这里
│   │       ├── KimapComponent.vue
│   │       ├── index.js
│   │       └── package.json

然后安装依赖：

npm install @kimap/indoor-positioning-sdk [email protected] --save

方法3：直接使用原厂SDK

如果您的Webpack配置正确，也可以直接使用原厂SDK：

npm install @kimap/indoor-positioning-sdk [email protected] --save

🚀 使用方法

方式1：使用Vue组件（最简单）

从npm包导入（方法1安装）

<template>
  <div class="map-page">
    <kimap-component
      ref="kimap"
      :obj-url="modelUrl"
      :origin="{ x: 0, y: 0, z: 0 }"
      :max-x="100"
      :max-y="50"
      :show-grid="true"
      @ready="onMapReady"
      @position-click="onPositionClick"
    />
  </div>
</template>

<script>
// 从npm包导入
import KimapComponent from '@zyl19950114/kimap-sdk-vue2/KimapComponent.vue';

export default {
  name: 'MapPage',
  components: {
    KimapComponent
  },
  data: function() {
    return {
      modelUrl: '/static/models/building.obj'
    };
  },
  methods: {
    onMapReady: function(sdk) {
      console.log('地图加载完成', sdk);
      this.addMarkers();
    },
    
    onPositionClick: function(data) {
      console.log('点击位置:', data.position);
    },
    
    addMarkers: function() {
      var THREE = require('three');
      
      // 通过ref调用组件方法
      this.$refs.kimap.addLocationMarker({
        id: 'marker-1',
        position: new THREE.Vector3(10, 0, 15),
        label: '会议室A',
        color: '#4CAF50'
      });
    }
  }
};
</script>

<style scoped>
.map-page {
  width: 100%;
  height: 100vh;
}
</style>

从本地文件导入（方法2安装）

如果使用方法2（复制文件），导入路径为：

import KimapComponent from '@/components/kimap/KimapComponent.vue';

方式2：使用包装函数

从npm包导入

<template>
  <div ref="mapContainer" class="map-container"></div>
</template>

<script>
var createKimapSDK = require('@zyl19950114/kimap-sdk-vue2').createKimapSDK;
var THREE = require('three');

export default {
  name: 'MapPage',
  data: function() {
    return {
      sdk: null
    };
  },
  mounted: function() {
    this.initMap();
  },
  beforeDestroy: function() {
    if (this.sdk) {
      this.sdk.destroy();
    }
  },
  methods: {
    initMap: function() {
      var self = this;
      
      createKimapSDK({
        container: this.$refs.mapContainer,
        objUrl: '/static/models/building.obj',
        origin: { x: 0, y: 0, z: 0 },
        maxX: 100,
        maxY: 50,
        onPositionClick: function(position) {
          self.handleClick(position);
        }
      }).then(function(sdk) {
        self.sdk = sdk;
        self.addMarkers();
      }).catch(function(error) {
        console.error('初始化失败:', error);
      });
    },
    
    addMarkers: function() {
      this.sdk.addLocationMarker({
        id: 'marker-1',
        position: new THREE.Vector3(10, 0, 15),
        label: '会议室'
      });
    },
    
    handleClick: function(position) {
      console.log('点击位置:', position);
    }
  }
};
</script>

<style scoped>
.map-container {
  width: 100%;
  height: 100vh;
}
</style>

方式3：直接使用SDK（需要Webpack支持动态导入）

<template>
  <div ref="mapContainer" class="map-container"></div>
</template>

<script>
export default {
  name: 'MapPage',
  data: function() {
    return {
      sdk: null
    };
  },
  mounted: function() {
    this.initMap();
  },
  beforeDestroy: function() {
    if (this.sdk) {
      this.sdk.destroy();
    }
  },
  methods: {
    initMap: function() {
      var self = this;
      
      // 动态导入（Webpack 3支持，但需要babel-plugin-syntax-dynamic-import）
      Promise.all([
        import('@kimap/indoor-positioning-sdk'),
        import('three')
      ]).then(function(modules) {
        var KimapSDK = modules[0].KimapSDK;
        var THREE = modules[1];
        
        self.sdk = new KimapSDK({
          container: self.$refs.mapContainer,
          objUrl: '/static/models/building.obj',
          origin: { x: 0, y: 0, z: 0 },
          maxX: 100,
          maxY: 50
        });
        
        self.sdk.addLocationMarker({
          id: 'marker-1',
          position: new THREE.Vector3(10, 0, 15),
          label: '会议室'
        });
      }).catch(function(error) {
        console.error('加载失败:', error);
      });
    }
  }
};
</script>

🔧 Webpack配置（如果需要）

如果动态导入不工作，需要在 build/webpack.base.conf.js 中添加：

module.exports = {
  // ...其他配置
  resolve: {
    extensions: ['.js', '.vue', '.json'],
    alias: {
      'vue$': 'vue/dist/vue.esm.js',
      '@': resolve('src')
    }
  },
  module: {
    rules: [
      // 确保处理node_modules中的ES6模块
      {
        test: /\.js$/,
        loader: 'babel-loader',
        include: [
          resolve('src'),
          resolve('test'),
          resolve('node_modules/@kimap') // 添加这行
        ]
      }
    ]
  }
};

📋 完整示例项目结构

your-project/
├── src/
│   ├── components/
│   │   └── kimap/
│   │       ├── KimapComponent.vue
│   │       ├── index.js
│   │       └── package.json
│   ├── views/
│   │   └── MapView.vue
│   └── main.js
├── static/
│   └── models/
│       └── building.obj
└── package.json

⚡ API方法

所有方法与SDK保持一致，通过 $refs 调用：

// 添加标记
this.$refs.kimap.addLocationMarker(marker);

// 移除标记
this.$refs.kimap.removeLocationMarker('marker-id');

// 更新当前位置
this.$refs.kimap.updateCurrentPosition(position);

// 显示弹窗
this.$refs.kimap.showPopup(info);

// 隐藏弹窗
this.$refs.kimap.hidePopup();

// 开始绘制
this.$refs.kimap.startDraw('line', {
  onDrawComplete: function(points) {
    console.log('绘制完成', points);
  }
});

// 获取原始SDK实例
var sdk = this.$refs.kimap.getSDK();

🎯 Props属性

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | objUrl | String | - | OBJ模型文件路径（必填） | | origin | Object | {x:0, y:0, z:0} | 原点坐标 | | maxX | Number | 100 | X轴最大值 | | maxY | Number | 50 | Y轴最大值 | | showGrid | Boolean | true | 显示网格 | | showAxes | Boolean | true | 显示坐标轴 | | backgroundColor | Number | 0xf0f0f0 | 背景颜色 |

📡 Events事件

| 事件名 | 参数 | 说明 | |--------|------|------| | ready | sdk | SDK初始化完成 | | error | error | 初始化失败 | | position-click | {position, object} | 点击位置 |

⚠️ 常见问题

Q1: 提示找不到模块？

解决方案： 确保已安装依赖

npm install @kimap/indoor-positioning-sdk [email protected] --save

Q2: Webpack编译错误？

解决方案： 在 webpack.base.conf.js 中添加对 @kimap 的babel处理：

{
  test: /\.js$/,
  loader: 'babel-loader',
  include: [
    resolve('src'),
    resolve('node_modules/@kimap')
  ]
}

Q3: Three.js版本冲突？

解决方案： 必须升级到0.150.0或更高版本

npm uninstall three
npm install [email protected] --save

Q4: 动态导入不支持？

解决方案： 使用提供的Vue组件，它已经处理了兼容性问题。

Q5: 在IE浏览器报错？

由于SDK使用了现代JavaScript特性，不支持IE浏览器。您的项目配置中已排除IE：

"browserslist": [
  "> 1%",
  "last 2 versions",
  "not ie <= 8"
]

建议更新为：

"browserslist": [
  "> 1%",
  "last 2 versions",
  "not ie <= 11"
]

📚 更多文档

• SDK API文档
• 完整示例
• 发布指南

💡 提示

1. 推荐使用方式1（Vue组件），最简单且兼容性最好
2. 必须升级Three.js到0.150.0+
3. 如果遇到编译问题，检查Webpack配置
4. 建议将模型文件放在 static/ 目录下，避免Webpack处理

🆘 技术支持

如有问题，请查看：

• API文档
• GitHub Issues