konva-interactive-img

基于 Vue 3 + Konva 的交互式地图组件库。支持上传背景图、手动绘制多边形区域、悬停高亮、区域编辑与 JSON 导入导出。

参考 Konva Interactive Building Map 实现。

开发

pnpm install
pnpm dev          # 启动 playground（直接引用本地 src，支持热更新）
pnpm run build    # 构建组件库 dist（发布前执行）

Playground 通过 pnpm workspace + Vite alias 引用本地 src/ 源码，改组件后保存即可在 playground 验证，无需先 build 或发布 npm。

发布前可用 pnpm run build 构建 dist，再执行 npm publish。

构建

npm run build

产物输出到 dist/：es / cjs 模块、类型声明与样式文件。

安装使用

npm install @x-super/konva-interactive-img

<script setup lang="ts">
import { ref } from 'vue'
import { InteractiveMap } from '@x-super/konva-interactive-img'
import '@x-super/konva-interactive-img/style.css'
import type { Area } from 'konva-interactive-img'

const backgroundImage = ref<string | null>(null)
const areas = ref<Area[]>([])
</script>

<template>
  <InteractiveMap
    v-model:areas="areas"
    v-model:background-image="backgroundImage"
    background-fit="contain"
    mode="view"
    :width="900"
    :height="600"
  />
</template>

组件 API

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | backgroundImage | string \| null | null | 背景图 URL 或 base64 | | areas | Area[] | [] | 区域列表，支持 v-model:areas | | mode | 'view' \| 'draw' \| 'edit-area' \| 'edit-image' | 'view' | 查看 / 绘制 / 编辑区域 / 编辑图片 | | selectedId | string \| null | null | 选中区域 ID，支持 v-model:selectedId | | width | number | 800 | Stage 宽度 | | height | number | 600 | Stage 高度 | | backgroundFit | BackgroundFit | 'none' | 背景图缩放模式 | | canvasColor | string | '#e5e7eb' | 画布背景色，支持 v-model:canvasColor | | images | MapImage[] | [] | 叠加图片列表，支持 v-model:images | | selectedImageId | string \| null | null | 选中图片 ID，支持 v-model:selectedImageId |

BackgroundFit 可选值（对齐 CSS object-fit 语义）：

| 值 | 说明 | |----|------| | none | 原始尺寸，左上角对齐 | | contain | 等比缩放，完整显示在画布内（居中，可能留白） | | cover | 等比缩放，铺满画布（居中，可能裁剪） | | fill | 拉伸至画布宽高 | | scale-down | 不放大；超出画布时等同 contain |

Events

• draw-complete — 多边形绘制闭合，携带 points: number[]
• area-add / area-update / area-delete
• update:areas / update:backgroundImage / update:selectedId
• area-click — 区域单击（仅 view 模式，需绑定 @area-click 才响应），载荷 AreaInteractionEvent
• area-dblclick — 区域双击（仅 view 模式，需绑定 @area-dblclick 才响应），载荷 AreaInteractionEvent
• image-add / image-update / image-delete
• update:images / update:selectedImageId

AreaInteractionEvent 结构：

interface AreaInteractionEvent {
  area: Area
  event: MouseEvent
  pointer: { x: number; y: number }
}

区域点击示例：

<InteractiveMap
  mode="view"
  @area-click="({ area, pointer }) => console.log(area.name, pointer)"
  @area-dblclick="({ area }) => console.log('dblclick', area.name)"
/>

Expose

• exportData(): MapData
• importData(data: MapData): void
• addArea() / updateArea() / deleteArea()
• addImage() / updateImage() / deleteImage()

数据格式

{
  "version": 1,
  "backgroundImage": "data:image/png;base64,...",
  "canvasColor": "#e5e7eb",
  "areas": [
    {
      "id": "area-1",
      "name": "1st Floor",
      "color": "#3b82f6",
      "points": [100, 100, 200, 100, 200, 200]
    }
  ],
  "images": [
    {
      "id": "img-1",
      "name": "标注图片",
      "src": "data:image/png;base64,...",
      "x": 120,
      "y": 80,
      "width": 200,
      "height": 150,
      "rotation": 0
    }
  ]
}

交互说明

• 查看模式：悬停区域高亮并显示 Tooltip；可选绑定 @area-click / @area-dblclick 响应区域单击/双击
• 绘制模式：左键逐点连线，至少 3 个点后双击或 Enter 闭合，Esc 取消
• 编辑区域（edit-area）：点击选中区域，拖拽顶点调整形状，或在边线中点新增端点
• 编辑图片（edit-image）：点击选中图片，拖拽移动 / 角点缩放 / 旋转（Shift 自由拉伸）

License

MIT