npm package: @juqiao/jq-heatmap-3d-vue
Description: Vue 3 wrapper for @juqiao/jq-heatmap-3d components. Requires Three.js dependency.
Latest version: 1.0.3

# @juqiao/jq-heatmap-3d-vue

Vue 3 包装器，用于在 Vue 3 项目中轻松使用 @juqiao/jq-heatmap-3d 3D 热力图组件。

## 特性

- 🎯 **Vue 3 原生支持**: 专为 Vue 3 设计的组件包装器
- 🔧 **TypeScript 支持**: 完整的类型定义
- 📱 **响应式**: 支持 Vue 的响应式数据绑定
- ⚡ **高性能**: 基于 Web Components 标准
- 🎨 **易于使用**: 简单的 Vue 组件 API

## 安装

```bash
npm install @juqiao/jq-heatmap-3d-vue
```

> ⚠️ **前置条件**: 使用前请确保已安装 Three.js 依赖，否则组件将无法正常渲染。

```bash
npm install three@^0.177.0
```

或者使用 yarn：

```bash
yarn add three@^0.177.0
```

## 使用方法

### 1. 注册组件

```javascript
// main.js
import { createApp } from 'vue'
import { JqHeatmap3d, initJqHeatmap3d } from '@juqiao/jq-heatmap-3d-vue'
import App from './App.vue'

initJqHeatmap3d().then(() => {
  createApp(App).mount('#app')
}).catch(err => {
  console.error('Web components 注册失败:', err)
  // 即使失败也挂载应用
  createApp(App).mount('#app')
})
```

### 2. 使用组件

#### 2.1 使用setup语法

```vue
<template>
  <div class="heatmap-container">
    <JqHeatmap3d
      :data="heatmapData"
      :data-width="32"
      :data-height="32"
      :width-interpolation="4"
      :height-interpolation="2"
      :border-padding="4"
      :blur-radius="2"
      :color-scale="2000"
      :height-scale="0.2"
      :smoothness="1"
      :camera-distance="240"
      :x-axis-angle="-45"
      :width="'100%'"
      :height="'600px'"
      @data-updated="handleDataUpdated"
      @render-complete="handleRenderComplete"
      @heatmap-error="handleError"
    />
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue'
import { JqHeatmap3d } from '@juqiao/jq-heatmap-3d-vue'

// 热力图数据
const heatmapData = ref([])

// 生成测试数据
const generateTestData = () => {
  const data = new Array(1024).fill(0).map((_, i) => {
    const row = Math.floor(i / 32)
    const col = i % 32
    const centerX = 16
    const centerY = 16
    const distance = Math.sqrt(Math.pow(row - centerY, 2) + Math.pow(col - centerX, 2))
    return Math.max(0, Math.floor(100 - distance * 5))
  })
  heatmapData.value = data
}

// 事件处理
const handleDataUpdated = (event) => {
  console.log('数据已更新:', event.detail)
}

const handleRenderComplete = (event) => {
  console.log('渲染完成:', event.detail)
}

const handleError = (event) => {
  console.error('热力图错误:', event.detail)
}

// 初始化数据
generateTestData()
</script>

<style scoped>
.heatmap-container {
  width: 100%;
  height: 600px;
  border: 2px solid #333;
  background-color: #000;
}
</style>
```

#### 2.2. 使用 Options API

```vue
<template>
  <div class="heatmap-container">
    <JqHeatmap3d
      :data="heatmapData"
      :data-width="32"
      :data-height="32"
      @data-updated="handleDataUpdated"
      @render-complete="handleRenderComplete"
    />
  </div>
</template>

<script>
import { JqHeatmap3d } from '@juqiao/jq-heatmap-3d-vue'

export default {
  name: 'HeatmapDemo',
  components: {
    JqHeatmap3d
  },
  data() {
    return {
      heatmapData: []
    }
  },
  async mounted() {
    // 生成测试数据
    this.generateTestData()
  },
  methods: {
    generateTestData() {
      this.heatmapData = new Array(1024).fill(0).map((_, i) => {
        const row = Math.floor(i / 32)
        const col = i % 32
        const centerX = 16
        const centerY = 16
        const distance = Math.sqrt(Math.pow(row - centerY, 2) + Math.pow(col - centerX, 2))
        return Math.max(0, Math.floor(100 - distance * 5))
      })
    },
    handleDataUpdated(event) {
      console.log('数据已更新:', event.detail)
    },
    handleRenderComplete(event) {
      console.log('渲染完成:', event.detail)
    }
  }
}
</script>
```

## 组件属性

| 属性 | 类型 | 默认值 | 描述 |
|-----|------|--------|------|
| `data` | Array | `[]` | 热力图数据数组 |
| `dataWidth` | number | `32` | 数据宽度 |
| `dataHeight` | number | `32` | 数据高度 |
| `widthInterpolation` | number | `4` | 宽度插值 |
| `heightInterpolation` | number | `2` | 高度插值 |
| `borderPadding` | number | `4` | 边框填充 |
| `blurRadius` | number | `2` | 模糊半径 |
| `colorScale` | number | `2000` | 颜色缩放 |
| `heightScale` | number | `0.2` | 高度缩放 |
| `smoothness` | number | `1` | 平滑度 |
| `cameraDistance` | number | `240` | 相机距离 |
| `xAxisAngle` | number | `-45` | X轴角度 |
| `width` | string | `'100%'` | 组件宽度 |
| `height` | string | `'600px'` | 组件高度 |

## 事件

| 事件名 | 描述 | 参数 |
|--------|------|------|
| `dataUpdated` | 数据更新时触发 | `event.detail` |
| `renderComplete` | 渲染完成时触发 | `event.detail` |
| `heatmapError` | 发生错误时触发 | `event.detail` |

## 数据格式

一个长度为1024的一维数组，表示热力图的数值：

```javascript
// 32x32 的热力图数据 (1024个点)
const data = new Array(1024).fill(0).map((_, i) => {
  const row = Math.floor(i / 32)
  const col = i % 32
  const centerX = 16
  const centerY = 16
  const distance = Math.sqrt(Math.pow(row - centerY, 2) + Math.pow(col - centerX, 2))
  return Math.max(0, Math.floor(100 - distance * 5))
})
```

## 响应式数据绑定

组件支持 Vue 的响应式数据绑定，当数据变化时组件会自动更新：

```vue
<template>
  <div>
    <button @click="updateData">更新数据</button>
    <JqHeatmap3d :data="heatmapData" />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { JqHeatmap3d, initJqHeatmap3d } from '@juqiao/jq-heatmap-3d-vue'

const heatmapData = ref([])

const updateData = () => {
  // 更新数据，组件会自动重新渲染
  heatmapData.value = generateNewData()
}
</script>
```

## 许可证

MIT