@aizhushou/layout-designer v1.1.18

布局设计器 (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

Events

Slots

布局项数据结构

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

方法

组件实例提供以下方法：

高级用法

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. 建议在组件外部实现布局数据的持久化存储