布局设计器 (Layout Designer)

布局设计器是一个功能强大的可视化布局编辑组件，支持在背景图片上进行元素的拖拽、调整大小、添加和删除等操作。主要用于设计和编辑各类布局方案。

特性

• 支持背景图片自适应缩放
• 支持元素拖拽定位
• 支持元素大小调整
• 支持固定宽度/高度两种模式
• 支持实时数据展示
• 提供丰富的事件回调
• 支持编程式控制

安装

pnpm add @aizhushou/layout-designer

基本用法

<template>
  <LayoutDesigner
    v-model="items"
    :bg-img="backgroundImage"
    :width="800"
    :height="600"
    @deleted="handleDelete"
    @added="handleAdd"
    @resized="handleResize"
    @dragged="handleDrag"
    @changed="handleChange"
  />
</template>

<script setup>
import { ref } from 'vue'
import { LayoutDesigner } from '@aizhushou/layout-designer'

const items = ref([])
const backgroundImage = ref('path/to/image.jpg')

const handleDelete = (item) => {
  console.log('Item deleted:', item)
}

const handleAdd = (item) => {
  console.log('Item added:', item)
}

const handleResize = (item) => {
  console.log('Item resized:', item)
}

const handleDrag = (item) => {
  console.log('Item dragged:', item)
}

const handleChange = (item) => {
  console.log('Item changed:', item)
}
</script>

Props

| 属性名 | 类型 | 默认值 | 必填 | 说明 | | ------------ | ------- | ------ | ---- | ---------------------------------------- | | modelValue | Array | [] | 是 | 布局项数组，用于v-model双向绑定 | | bgImg | String | '' | 是 | 背景图片路径 | | width | Number | 0 | 否 | 容器宽度，单位像素 | | height | Number | 0 | 否 | 容器高度，单位像素 | | showDataList | Boolean | false | 否 | 是否显示数据列表，用于调试和查看元素信息 | | isFixedWidth | Boolean | false | 否 | 是否固定宽度模式，false时为固定高度模式 |

Events

| 事件名 | 参数类型 | 说明 | | ------- | -------- | ------------------------ | | deleted | Item | 删除布局项时触发 | | added | Item | 添加新的布局项时触发 | | resized | Item | 调整布局项大小时触发 | | dragged | Item | 拖拽布局项时触发 | | changed | Item | 布局项属性发生变化时触发 |

Slots

| 插槽名 | 返回值 | 说明 | | ------ | ------------ | ---------------------------- | | label | {item,index} | 标注框标签显示自定义内容 | | type | {item,index} | 标注框类型选择显示自定义内容 |

布局项数据结构

interface Item {
  x: number;        // 横坐标位置
  y: number;        // 纵坐标位置
  width: number;    // 宽度
  height: number;   // 高度
  id: string;    // 唯一标识
  type:string;  // 元素类型
  scale?: number;   // 缩放比例
  active?: boolean; // 是否处于选中状态
}

方法

组件实例提供以下方法：

| 方法名 | 参数 | 返回值 | 说明 | | ---------- | ----------- | ------ | -------------------- | | selectItem | (item:Item) | void | 编程式选中指定布局项 |

高级用法

1. 自适应模式切换

组件支持固定宽度和固定高度两种自适应模式：

<template>
  <!-- 固定高度模式（默认） -->
  <LayoutDesigner
    v-model="items"
    :bg-img="backgroundImage"
    :width="800"
    :height="600"
  />

  <!-- 固定宽度模式 -->
  <LayoutDesigner
    v-model="items"
    :bg-img="backgroundImage"
    :width="800"
    :height="600"
    :is-fixed-width="true"
  />
</template>

2. 调试模式

通过开启数据列表来查看布局项的详细信息：

<template>
  <LayoutDesigner
    v-model="items"
    :bg-img="backgroundImage"
    :show-data-list="true"
  />
</template>

3. 编程式控制

<template>
  <LayoutDesigner
    ref="designerRef"
    v-model="items"
    :bg-img="backgroundImage"
  />
  <button @click="selectLayoutItem">选中第一个元素</button>
</template>

<script setup>
import { ref } from 'vue'

const designerRef = ref(null)
const items = ref([])

const selectLayoutItem = () => {
  if (items.value.length > 0) {
    designerRef.value?.selectItem(items.value[0])
  }
}
</script>

最佳实践

1. 性能优化

   • 背景图片建议进行适当压缩，避免过大文件影响加载性能
   • 合理控制布局项数量，避免过多元素导致性能下降

2. 布局建议

   • 为容器设置合适的宽高，确保有足够空间展示所有元素
   • 根据实际需求选择合适的自适应模式（固定宽度/高度）

3. 数据管理

   • 确保每个布局项都有唯一的label属性
   • 注意保存布局项的坐标和尺寸信息

4. 错误处理

   • 监听相关事件以处理用户操作
   • 实现适当的错误处理机制

注意事项

1. 组件会自动处理背景图片的缩放，无需手动计算缩放比例
2. 布局项的坐标和尺寸会根据容器大小自动调整
3. 所有的坐标和尺寸单位均为像素
4. 确保提供的背景图片URL有效且可访问
5. 建议在组件外部实现布局数据的持久化存储