@metav_xly/decal-editor

基于 Vue3 + Element UI + Three.js 的贴花编辑器组件

特性

• 🎨 基于 Three.js 的 3D 贴花编辑功能
• 🖱️ 鼠标点击添加贴花
• ⚙️ 实时编辑贴花属性（位置、旋转、缩放、纹理类型）
• 📋 贴花列表管理
• 💾 配置导入导出
• 🎯 支持多种纹理类型
• 📦 TypeScript 支持
• 🔧 可自定义材质构造器

安装

npm install @metav_xly/decal-editor
# 或
pnpm add @metav_xly/decal-editor
# 或
yarn add @metav_xly/decal-editor

使用方法

全局注册

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import DecalEditor from '@metav_xly/decal-editor'
import App from './App.vue'

const app = createApp(App)
app.use(ElementPlus)
app.use(DecalEditor)
app.mount('#app')

局部使用

<template>
  <DecalEditorComponent
    :model-url="modelUrl"
    :textures="textures"
    @decal-added="onDecalAdded"
    @decal-selected="onDecalSelected"
    @decal-updated="onDecalUpdated"
    @decal-removed="onDecalRemoved"
    @decals-cleared="onDecalsCleared"
  />
</template>

<script setup>
import { ref } from 'vue'
import { DecalEditorComponent } from '@metav_xly/decal-editor'

// 准备纹理配置数据
const textures = ref([
  {
    label: '贴花类型1',
    diffuseUrl: '/textures/decal1-diffuse.png',
    normalUrl: '/textures/decal1-normal.jpg'
  },
  {
    label: '贴花类型2',
    diffuseUrl: '/textures/decal2-diffuse.png',
    normalUrl: '/textures/decal2-normal.jpg'
  },
  {
    label: '贴花类型3',
    diffuseUrl: '/textures/decal3-diffuse.png',
    normalUrl: '/textures/decal3-normal.jpg'
  }
])

const modelUrl = ref('/models/your-model.glb')

// 事件处理
const onDecalAdded = (decal, index) => {
  console.log('贴花已添加:', decal, index)
}

const onDecalSelected = (decal, index) => {
  console.log('贴花已选中:', decal, index)
}

const onDecalUpdated = (decal, index) => {
  console.log('贴花已更新:', decal, index)
}

const onDecalRemoved = (index) => {
  console.log('贴花已删除:', index)
}

const onDecalsCleared = () => {
  console.log('所有贴花已清空')
}
</script>

使用核心类

import * as THREE from 'three'
import { DecalEditor, DecalLoader } from '@metav_xly/decal-editor'

// 创建 Three.js 场景
const scene = new THREE.Scene()
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000)
const renderer = new THREE.WebGLRenderer()

// 准备纹理配置
const textures = [
  {
    label: '贴花类型1',
    diffuseUrl: '/textures/decal-diffuse.png',
    normalUrl: '/textures/decal-normal.jpg'
  },
  {
    label: '贴花类型2',
    diffuseUrl: '/textures/decal2-diffuse.png',
    normalUrl: '/textures/decal2-normal.jpg'
  }
]

// 创建贴花编辑器
const decalEditor = new DecalEditor(scene, camera, renderer, textures)

// 设置目标网格
decalEditor.setTargetMesh(yourMesh)

// 设置参数
decalEditor.setParams({
  minScale: 0.1,
  maxScale: 5.0,
  textureType: '0',
  rotate: false,
  helperSize: 20,
  normalLength: 20
})

// 监听事件
decalEditor.onDecalAdded = (decal, index) => {
  console.log('贴花已添加:', decal, index)
}

decalEditor.onDecalSelected = (decal, index) => {
  console.log('贴花已选中:', decal, index)
}

decalEditor.onDecalUpdated = (decal, index) => {
  console.log('贴花已更新:', decal, index)
}

decalEditor.onDecalRemoved = (index) => {
  console.log('贴花已删除:', index)
}

decalEditor.onDecalsCleared = () => {
  console.log('所有贴花已清空')
}

// 创建贴花加载器
const decalLoader = new DecalLoader(scene, textures)

// 加载配置
const config = {
  version: '1.0',
  decals: [
    {
      id: 0,
      position: { x: 0, y: 0, z: 0 },
      orientation: { x: 0, y: 0, z: 0 },
      scale: 10,
      textureType: '0',
      targetName: 'mesh'
    }
  ]
}

const loadedDecals = decalLoader.loadConfig(config, yourMesh)

API 文档

DecalEditorComponent Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|---------| | modelUrl | string | '' | 3D 模型文件 URL | | textures | TextureConfig[] | [] | 纹理配置数组 |

DecalEditorComponent Events

| 事件名 | 参数 | 说明 | |--------|------|------| | decal-added | (decal: THREE.Mesh, index: number) | 贴花添加时触发 | | decal-selected | (decal: THREE.Mesh, index: number) | 贴花选中时触发 | | decal-updated | (decal: THREE.Mesh, index: number) | 贴花更新时触发 | | decal-removed | (index: number) | 贴花删除时触发 | | decals-cleared | () | 清空所有贴花时触发 |

TextureConfig 接口

interface TextureConfig {
  label: string        // 纹理标签
  diffuseUrl?: string  // 漫反射纹理 URL
  normalUrl?: string   // 法线纹理 URL
}

TextureSet 接口

interface TextureSet {
  diffuse?: THREE.Texture  // 漫反射纹理
  normal?: THREE.Texture   // 法线纹理
  label: string           // 纹理标签
}

DecalParams 接口

interface DecalParams {
  minScale: number      // 最小缩放值
  maxScale: number      // 最大缩放值
  textureType: string   // 纹理类型索引
  rotate: boolean       // 是否随机旋转
  helperSize: number    // 辅助器大小
  normalLength: number  // 法线长度
}

DecalEditor 类方法

| 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | setTargetMesh | (mesh: THREE.Object3D) | void | 设置目标网格 | | setParams | (params: Partial) | void | 设置参数 | | createDecal | () | THREE.Mesh | null | 创建贴花 | | selectDecal | (index: number) | void | 选择贴花 | | updateDecal | (index: number, properties: DecalProperties) | void | 更新贴花 | | removeDecal | (index: number) | void | 删除贴花 | | removeAllDecals | () | void | 删除所有贴花 | | exportConfig | () | any | 导出配置 | | getDecals | () | THREE.Mesh[] | 获取所有贴花 | | getSelectedDecal | () | THREE.Mesh | null | 获取选中的贴花 | | getSelectedDecalIndex | () | number | 获取选中贴花的索引 |

DecalLoader 类方法

| 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | loadConfig | (config: DecalConfig, targetMesh: THREE.Object3D) | THREE.Mesh[] | 加载配置 | | validateConfig | (config: any) | boolean | 验证配置格式 |

自定义材质构造器

import * as THREE from 'three'
import { DecalEditor } from '@metav_xly/decal-editor'

const customMaterialConstructor = (textureSet, index) => {
  const material = new THREE.MeshPhongMaterial({
    transparent: true,
    depthTest: true,
    depthWrite: false,
    polygonOffset: true,
    polygonOffsetFactor: -4
  })
  
  if (textureSet.diffuse) {
    material.map = textureSet.diffuse
  }
  if (textureSet.normal) {
    material.normalMap = textureSet.normal
  }
  
  // 根据索引和标签自定义材质属性
  if (index === 0) {
    material.color.setHex(0xff0000)
  }
  
  // 根据纹理标签设置不同属性
  if (textureSet.label.includes('金属')) {
    material.shininess = 100
  }
  
  return material
}

// 准备纹理配置
const textures = [
  {
    label: '金属纹理',
    diffuseUrl: '/textures/metal-diffuse.png',
    normalUrl: '/textures/metal-normal.jpg'
  }
]

const decalEditor = new DecalEditor(
  scene, 
  camera, 
  renderer, 
  textures, 
  customMaterialConstructor
)

开发

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建库
pnpm build:lib

# 类型检查
pnpm type-check

许可证

MIT