# 栅格布局组件（ByGridLayout）

# 组件简介

ByGridLayout 基于 vue-grid-layout 二次封装，提供可配置的栅格化卡片容器，支持拖拽调整、隐藏/恢复卡片、布局持久化等场景。组件内置编辑模式切换、隐藏卡片回收站、全部卡片隐藏时的空状态展示，适用于大屏驾驶舱、工作台等需要自定义卡片编排的页面。

# 基础用法

<template>
  <by-grid-layout
    ref="gridLayout"
    v-model="items"
    v-bind="gridLayoutAttrs"
    :item-events="itemEvents"
    toggleable
    @layout-updated="handleLayoutUpdated"
    @mode-change="handleModeChange"
    @save="handleSave"
    @reset-default="handleResetDefault"
  />
</template>

<script>
import { gridLayoutOptions } from '@/examples/grid-layout/config'

export default {
  data() {
    return {
      items: gridLayoutOptions.items,
      gridLayoutAttrs: gridLayoutOptions.layout
    }
  },
  computed: {
    itemEvents() {
      return {
        cardA_refresh: (payload, ctx) => {
          /* ... */
        }
      }
    }
  },
  methods: {
    handleLayoutUpdated(layout) {
      console.log(layout)
    },
    handleSave(snapshot) {
      // 处理保存结果
    },
    handleResetDefault(snapshot) {
      // 恢复默认
    }
  }
}
</script>

完整示例可参考 examples/src/examples/grid-layout/ByGridLayoutExample.vue。

# 主要属性（Props）

名称	类型	默认值	说明
`items`	`Array`	`[]`	栅格卡片配置数组（支持 `v-model` 双向绑定）。每项支持 `x/y/w/h/i/static/minW/minH/maxW/maxH/isDraggable/isResizable/hidden/authorized/component/props/on` 等字段。
`itemKey`	`String`	`'i'`	自定义唯一标识字段，未设置时使用 `i`。
`defaultItemSize`	`Object`	`{ w: 1, h: 1 }`	缺省卡片尺寸。
`autoLayout`	`Boolean`	`true`	当 `items` 未提供 `x/y` 时是否按顺序自动排布。
`itemEvents`	`Object \\| Function`	`null`	全局事件声明；对象形式直接透传，函数形式可根据 `item`、`index` 返回事件集合。
`toggleable`	`Boolean`	`true`	是否开启自定义模式（显示/隐藏卡片、拖拽、编辑工具条）。

其余 vue-grid-layout 原生属性（如 colNum、rowHeight、margin、isDraggable、isResizable 等）可通过 v-bind 直接透传。

# 事件（Events）

事件名	说明
`update:items`	`items` 变更时触发（`v-model` 对应事件）。
`layout-updated`	内部布局发生变化时触发，参数为 `layout` 数组。
`mode-change`	编辑 / 浏览模式切换时触发，参数为当前模式字符串（`edit` / `view`）。
`save`	点击“保存”按钮时触发，参数为 `{ items, layout }` 快照，可用于持久化。
`reset-default`	点击“恢复默认”按钮时触发，参数为当前快照，可自行恢复默认布局。

# 插槽（Slots）

名称	说明
`item`	渲染卡片内容。默认渲染 `item.component` 指定的组件，可通过具名插槽覆盖。插槽参数：`item`、`layout`、`index`。
`default`	兼容旧用法，直接编写 `<grid-item>` 时使用。

# 暴露方法

通过 ref 获取组件实例后，可调用以下方法：

方法	说明
`setItemPropsById(id, propsPatch)`	合并更新指定卡片的 `props`。
`setItemProp(id, key, value)`	设置指定卡片单个属性。

# 空状态与隐藏卡片

当所有卡片被隐藏或无可展示项时，组件会自动显示内置空状态（插画 + 文案）。文案会根据当前模式提示“添加卡片”或“自定义配置”。
编辑模式下，会在顶部展示隐藏卡片回收栏，可点击卡片快速恢复。恢复时会尽量保留原始尺寸并寻找最佳落点(遵循：1、排在最后 2、从上到下，从左到右)。

# 使用建议

建议在保存时将 save 事件返回的 snapshot 持久化（如调用接口或本地存储），配合业务自定义的缓存工具即可实现下次自动加载布局。
通过 itemEvents 可统一管理卡片内部交互事件，推荐在自定义卡片组件中使用约定事件名称向外发送动作。
若需禁用全局拖拽/缩放，可在视图模式传入 :is-draggable="false" / :is-resizable="false"；

← ByFloatingMenu 悬浮菜单组件