@epxing/dashboard 0.0.0-stage → 5.3.0-beta.2

package/src/grid/geometry.js

@@ -0,0 +1,55 @@
+// 看板几何：网格坐标 → 像素矩形。公式与 vue-grid-layout 1.x 的 calcPosition 完全一致，且 padding = gap 时
+// 连浮点运算顺序都与旧库相同（.5 边界的舍入方向才不会分歧），保证旧页面逐位一致；运行态与垫片都只依赖这里，不依赖任何布局库。
+
+// 把网格参数解析成数值：'auto' 行高 = body 高 / 1000 * 10；'auto' 间距 = 2×行高；padding 缺省跟随间距
+export function resolveGrid (grid, { containerWidth = 0, bodyHeight = 0 } = {}) {
+  const colNum = grid.colNum
+  // 勿化简成 bodyHeight / 100：旧实现 calculateHeight 写的是 offsetHeight / 1000 * 10，两者浮点结果不逐位相等
+  const rowHeight = grid.rowHeight === 'auto' ? Math.max(1, bodyHeight / 1000 * 10) : grid.rowHeight
+  const autoGap = [rowHeight * 2, rowHeight * 2]
+  const gap = grid.gap === 'auto' ? autoGap : grid.gap
+  const padding = grid.padding == null ? gap : (grid.padding === 'auto' ? autoGap : grid.padding)
+  const [gapX, gapY] = gap
+  const [padX, padY] = padding
+  // padding 跟随间距时用旧库 calcColWidth 的原式 (宽 − margin × (列 + 1)) / 列，保持浮点运算顺序；显式 padding 走通用式。
+  // 容器比 (列 + 1) × 间距 还窄时列宽为负（移动端 48 列 × 8px 间距在手机宽度下就是这样），与旧库一样照算：
+  // 整行项的宽 = 列宽 × 48 + 47 × 间距 仍等于容器宽 − 2 × 间距；夹成 0 会让它变成 47 × 间距、撑出容器。只有还没量到宽度（0）时才归 0
+  const rawColWidth = padX === gapX
+    ? (containerWidth - gapX * (colNum + 1)) / colNum
+    : (containerWidth - padX * 2 - gapX * (colNum - 1)) / colNum
+  const colWidth = containerWidth > 0 ? rawColWidth : 0
+  return { colNum, rowHeight, gapX, gapY, padX, padY, colWidth, containerWidth }
+}
+
+// 与旧库 calcPosition 同一运算顺序：colWidth * x + (x + 1) * margin；padding 与间距不同时末项补差值，
+// padding = gap 时末项精确为 0，加 0 不改变浮点值，退化为旧库表达式
+export function itemRect (item, r) {
+  const x = Number(item.x) || 0
+  const y = Number(item.y) || 0
+  const w = Math.max(1, Number(item.w) || 1)
+  const h = Math.max(1, Number(item.h) || 1)
+  return {
+    left: Math.round(r.colWidth * x + (x + 1) * r.gapX + (r.padX - r.gapX)),
+    top: Math.round(r.rowHeight * y + (y + 1) * r.gapY + (r.padY - r.gapY)),
+    width: Math.round(r.colWidth * w + Math.max(0, w - 1) * r.gapX),
+    height: Math.round(r.rowHeight * h + Math.max(0, h - 1) * r.gapY)
+  }
+}
+
+// 整个网格的像素高度（最底一项的底边 + 下内边距）；不取整（旧库 containerHeight 也不取整）
+export function layoutHeight (items, r) {
+  let bottom = 0
+  for (const item of items || []) {
+    if (!item) continue
+    const b = (Number(item.y) || 0) + Math.max(1, Number(item.h) || 1)
+    if (b > bottom) bottom = b
+  }
+  if (!bottom) return 0
+  // padding 跟随间距时与旧库 containerHeight 同式同序：bottom × (行高 + 间距) + 间距
+  if (r.padY === r.gapY) return bottom * (r.rowHeight + r.gapY) + r.gapY
+  return r.padY * 2 + bottom * (r.rowHeight + r.gapY) - r.gapY
+}
+
+export function rectStyle (rect) {
+  return { left: rect.left + 'px', top: rect.top + 'px', width: rect.width + 'px', height: rect.height + 'px' }
+}

package/src/grid/gridstackParams.js

@@ -0,0 +1,72 @@
+// v3 网格参数（resolveGrid 的结果）与 gridstack 13 选项之间的换算。
+// gridstack 的 margin 是「格子内的内容 inset」，格子本身连续；vue-grid-layout / itemRect 的 gap 是「项间距」。
+// 取 cellHeight = rowHeight + gapY、margin = gap / 2，则内容高 = h·(rowHeight + gapY) − gapY = h·rowHeight + (h − 1)·gapY，与 itemRect 同式；
+// 宽度方向让根元素比容器宽 gapX − 2·padX，再用负 / 正外边距对齐，使 x 列内容左沿 = padX + x·(colWidth + gapX)。
+function px (n) { return `${n}px` }
+
+export function toGridstackOptions (resolved, { float = false, engineClass, staticGrid = false } = {}) {
+  const { colNum, rowHeight, gapX, gapY } = resolved
+  const mx = gapX / 2
+  const my = gapY / 2
+  const options = {
+    column: colNum,
+    cellHeight: rowHeight + gapY,
+    margin: `${px(my)} ${px(mx)} ${px(my)} ${px(mx)}`,
+    float,
+    staticGrid,
+    // R23：被推挤的项走库的 .grid-stack-animate 过渡（旧库也有 200ms transform 过渡，关掉会显得生硬）；
+    // 库在从空 load / 跨网格 drop 时会自行临时关闭再恢复
+    animate: true,
+    resizable: { handles: 'all' },
+    // 把手常驻 DOM（库按 !alwaysShowResizeHandle 决定 autoHide、会覆盖 resizable.autoHide；autoHide 靠壳的 mouseover 摘类，
+    // 嵌套网格下 overResizeElement 被子项先占住就摘不掉）；把手透明，视觉由 epx-dashboard-design-item 的圆点负责
+    alwaysShowResizeHandle: true,
+    // 整卡可拖（R22，与旧版 dragIgnoreFrom=".resize-point" 的手感一致）：handle 用库默认的内容盒；
+    // cancel 排除操作条（库内置已跳过 input / textarea / button / select / option / contenteditable / .ui-resizable-handle），
+    // 以及子网格里按在锁定项上时子实例给所在层根元素打的「按下」标记（锁定的是子项、容器不因此起拖，任何嵌套层级都适用；
+    // 子网格空白处按下不打标记、容器由此起拖。不能直接写 .grid-stack——cancel 是 e.target.closest()，任何项的祖先链都含自己所在的网格，写了就全都拖不动）
+    // pause（库为嵌套网格设计的全局开关，写进 DDManager.pauseDrag）：这里显式关掉、占位块实时跟手；DesignGrid 在拖拽中按「被拖的壳是否碰到
+    // 还没进入的容器」动态打开 100ms 停顿（NEAR_CONTAINER_PAUSE）——不停顿的话碰撞会先把容器推开、指针永远进不去（R27 实测），常开又手感拖沓
+    // appendTo 只对 helper: 'clone' 生效（库只在 helper 没有父节点时才 appendTo）；本项目拖的是壳本体、无 clone helper，此项实际不起作用，
+    // 不要把它当成起手成本的来源（Task 9 审查 M5 注记，值不改）
+    draggable: { handle: '.grid-stack-item-content', appendTo: 'body', cancel: '.epx-dashboard-design-item__operates, .epx-dashboard-design-grid__stack--pressed', pause: false }
+  }
+  // 13.3.0 的 GridStackOptions 有 engineClass 且实例选项优先于 GridStack.registerEngine 的全局注册；
+  // 由 Task 3 决定用实例选项还是 GridStack.registerEngine
+  if (engineClass) options.engineClass = engineClass
+  return options
+}
+
+export function rootStyle (resolved) {
+  const { containerWidth, gapX, gapY, padX, padY } = resolved
+  return {
+    width: px(containerWidth - 2 * padX + gapX),
+    marginLeft: px(padX - gapX / 2),
+    marginRight: px(padX - gapX / 2),
+    marginTop: px(padY - gapY / 2)
+  }
+}
+
+// item → GridStackWidget；static 项在 gridstack 里对应 locked + noMove + noResize
+export function toWidget (item) {
+  const w = { id: String(item.id), x: Number(item.x) || 0, y: Number(item.y) || 0, w: Number(item.w) || 1, h: Number(item.h) || 1 }
+  for (const k of ['minW', 'maxW', 'minH', 'maxH']) if (item[k] != null) w[k] = Number(item[k])
+  if (item.static) { w.locked = true; w.noMove = true; w.noResize = true }
+  return w
+}
+
+// 设计态参考网格：把组件之间的「间距槽」画成极淡的带（竖带宽 gapX、横带高 gapY），按格距（列宽 + 间距 / 行高 + 间距）重复，
+// 带的两边正好是相邻组件的内容边沿——拖拽 / 缩放落位后组件边沿压在带边上。画 1px 细线的话线只能落在槽中间、组件永远差半个间距碰不到线；
+// 只画列条（Figma layout grid）用户觉得不够直观。颜色要浅：默认 2.5% 黑，只作参考、不抢内容（用户已否决 5%）。
+// 起点 = 第 0 列内容左沿 − gapX（padding 跟随间距时从 0 起、四边留白也画成槽）；间距 0 没有槽可画，退化成 1px 细线贴在内容边沿
+export function gridLineStyle (resolved, color = 'rgba(0,0,0,.025)') {
+  const { containerWidth, gapX, padX, colNum, rowHeight, gapY, padY } = resolved
+  const colPitch = (containerWidth - 2 * padX + gapX) / colNum
+  const bandX = gapX > 0 ? gapX : 1
+  const bandY = gapY > 0 ? gapY : 1
+  return {
+    backgroundImage: `linear-gradient(to right, ${color} ${px(bandX)}, transparent ${px(bandX)}), linear-gradient(to bottom, ${color} ${px(bandY)}, transparent ${px(bandY)})`,
+    backgroundSize: `${colPitch}px ${rowHeight + gapY}px`,
+    backgroundPosition: `${px(padX - bandX)} ${px(padY - bandY)}`
+  }
+}

package/src/grid/mixins.js

@@ -0,0 +1,114 @@
+// 看板页面级网格混入：服务于 Dashboard.vue（看板页面）与 Widget.vue（看板组件版）两个运行态宿主。
+// 两者的「图表加载方式 / 页面级网格参数 / 容器网格透传 / autoHeight 换算基准」逻辑完全相同，抽到这里共用；
+// provide 里的 getDashboardLoadWay / getDashboardLegacy 两个 getter 仍留在各组件自己的 provide() 里。
+// 另有容器级混入 containerGridMixin：服务于 Div.vue（dashboard-div）与 Tabs.vue（dashboard-tabs）两个容器的运行态分支。
+import { getPageGrid, getContainerGrid, isLegacyConfig, isContainerType, normalizeGridParams, MOBILE_GRID, LEGACY_CONTAINER_GRID } from './model'
+import { stackMobileLayout } from '../layout-util'
+
+export const pageGridMixin = {
+  data () {
+    return {
+      // rowHeight / gap 为 'auto'（旧 autoHeight）时的换算基准，随 window resize 更新
+      bodyHeight: typeof document !== 'undefined' ? document.body.offsetHeight : 0,
+      // 以下两项是兼容别名：仅供复刻旧模板的产品子类（extends: Dashboard 且复刻了 <grid-layout> 模板）使用，运行态自身不用。
+      // 旧模板写 v-if="loadPlugin"（原来等 import('grid-layout-plus') 完成后置 true）与 v-if="!load"；
+      // 垫片 GridLayout / GridItem 在包安装时已同步注册，这里直接给出「已就绪」的终值
+      loadPlugin: true,
+      load: false
+    }
+  },
+  computed: {
+    mobileDashboard () {
+      return this.$configs.designTarget === 'mobile'
+    },
+    mobileRendering () {
+      return !!(this.$isMobile || this.mobileDashboard)
+    },
+    // 图表加载方式：all 全部挂载 / current 进入可视区后挂载不卸载 / viewport 进入挂载远离卸载
+    loadWay () {
+      const v = this.$configs.loadWay
+      return v === 'current' || v === 'viewport' ? v : 'all'
+    },
+    // 页面级网格参数：旧配置按 autoHeight 推导；移动端只把间距收紧成堆叠参数（原 gridMargin 的移动端分支），行高语义沿用页面
+    gridParams () {
+      const page = getPageGrid(this.$configs)
+      return this.$isMobile || this.mobileDashboard ? { ...page, gap: MOBILE_GRID.gap, padding: null } : page
+    },
+    // 容器项（dashboard-div / dashboard-tabs）内部网格参数，透传给容器组件；非容器返回 undefined
+    containerGrid () {
+      return component => (isContainerType(component.contentType)
+        ? getContainerGrid(component, this.gridParams, isLegacyConfig(this.$configs))
+        : undefined)
+    },
+    // 以下三项是兼容别名：仅供复刻旧模板的产品子类（extends: Dashboard 且复刻了 <grid-layout> 模板）使用，运行态自身不用。
+    // 旧模板 :row-height="rowHeight"：'auto'（旧 autoHeight）时按原 calculateHeight 的 body 高 / 1000 * 10（勿化简，保证浮点逐位一致），否则取配置数值
+    rowHeight () {
+      const { rowHeight } = this.gridParams
+      return rowHeight === 'auto' ? this.bodyHeight / 1000 * 10 : rowHeight
+    },
+    // 旧模板 :margin="gridMargin"：移动端 [8, 8]；间距 'auto' 时 [rowHeight × 2, rowHeight × 2]（原 gridMargin 语义），否则取配置间距
+    gridMargin () {
+      if (this.mobileRendering) return [8, 8]
+      const { gap } = this.gridParams
+      return gap === 'auto' ? [this.rowHeight * 2, this.rowHeight * 2] : gap
+    },
+    // 旧模板 v-if="loadComponent(component.id)"：复刻模板走垫片、没有可视区门控，恒为「挂载」（等价于 loadWay 'all'）
+    loadComponent () {
+      return () => true
+    }
+  },
+  methods: {
+    updateBodyHeight () {
+      this.bodyHeight = document.body.offsetHeight
+    }
+  }
+}
+
+// 容器级网格混入：容器的内部网格参数由父看板按配置版本算好经 comp-grid 传入（无显式 grid 时是引用稳定的
+// 冻结常量 / 父级缓存，有显式 grid 时才是新对象；只用 computed 派生、不 watch），门控策略与配置版本标记经页面 provide 注入。
+export const containerGridMixin = {
+  inject: {
+    // 页面级门控策略与配置版本标记；产品复刻模板 / 独立挂载时可能没有提供方，缺省按「全部挂载 + 旧配置」
+    getDashboardLoadWay: { default: () => () => 'all' },
+    getDashboardLegacy: { default: () => () => true },
+    // 移动端设计器（DashboardMobile）的手机框预览标记：它跑在 PC 端（$isMobile 为 false），容器内部要和真机一样按堆叠渲染
+    epxMobilePreview: { default: false },
+    getMobileDashboard: { default: () => () => false }
+  },
+  props: {
+    // 本容器的内部网格参数（由父看板按配置版本算好传入；没传按历史写死值）
+    compGrid: { type: Object, default: null }
+  },
+  data () {
+    return {
+      // rowHeight / gap 为 'auto' 时的换算基准
+      bodyHeight: typeof document !== 'undefined' ? document.body.offsetHeight : 0
+    }
+  },
+  computed: {
+    // 移动端渲染（真机或手机框预览）：容器内子项按堆叠算法重排、间距收紧成堆叠参数
+    mobileStacked () {
+      return !!(this.$isMobile || this.epxMobilePreview || this.getMobileDashboard())
+    },
+    gridParams () {
+      const base = normalizeGridParams(this.compGrid, LEGACY_CONTAINER_GRID)
+      return this.mobileStacked ? { ...base, gap: MOBILE_GRID.gap, padding: null } : base
+    },
+    loadWay () {
+      return this.getDashboardLoadWay()
+    },
+    // 嵌套容器：v3 继承本容器网格，旧配置仍用历史写死值（是否旧版由页面 provide 下发）；非容器返回 undefined
+    childGrid () {
+      return item => (isContainerType(item.contentType) ? getContainerGrid(item, this.gridParams, this.getDashboardLegacy()) : undefined)
+    }
+  },
+  methods: {
+    // 容器子项在移动端的渲染列表：真机 / 手机框预览时按堆叠算法重排（整块保留的容器内部同样堆叠，不再按 PC 的列布局压缩），
+    // 保留子项 style（容器内没有「移动端样式覆盖层」）；PC 原样返回
+    mobileItems (items) {
+      const list = items || []
+      if (this.getMobileDashboard()) return list.filter(item => !item.mobileHidden)
+      return this.mobileStacked ? stackMobileLayout(list.filter(item => !item.mobileHidden), this.gridParams.colNum, { keepStyle: true }) : list
+    }
+  }
+}

package/src/grid/model.js

@@ -0,0 +1,259 @@
+// 看板布局模型：页面配置（v2 / v3）的规范化、默认值、容器网格、保存前剥离、悬浮分区、跨网格尺寸换算，
+// 以及设计器面板用的 grid ↔ 扁平键映射、改列数换算、容器网格有效值解析。
+// 纯函数、不依赖 Vue；结构说明见 docs/superpowers/specs/2026-09-16-dashboard-grid-refactor-design.md §7。
+import { normalizeGridItem } from '../layout-util'
+
+export const CONFIG_VERSION = '3.0'
+export const CONTAINER_TYPES = ['dashboard-div', 'dashboard-tabs']
+// 全局设置「布局」组在面板上的扁平键（面板控件只认标量），与 grid 对象经 fromGrid / toGrid 互转；只存在于面板，不落盘
+export const GRID_FLAT_KEYS = ['gridColNum', 'gridRowHeight', 'gridGap', 'gridPadding', 'gridMode']
+// 网格项自身的布局字段（真值在 item 上）：属性面板把项字段铺给 visual 面板后会随提交漏进 itemConfigs，保存前剥掉
+export const ITEM_LAYOUT_KEYS = ['x', 'y', 'w', 'h', 'i', 'float', 'z', 'static', 'minW', 'minH', 'maxW', 'maxH']
+// 页面级默认：与现状一致（48 列、10px 行高、20px 间距）。padding 为 null 表示跟随 gap，
+// 即旧版 margin 同时作用于项间与容器四边的语义，保证旧页面逐像素一致。
+export const DEFAULT_GRID = Object.freeze({ colNum: 48, rowHeight: 10, gap: [20, 20], padding: null, mode: 'grid', canvas: 'fluid' })
+// 历史容器（dashboard-div / dashboard-tabs）内部网格原本写死的参数，v2 配置升级时显式写入以免变形
+export const LEGACY_CONTAINER_GRID = Object.freeze({ colNum: 48, rowHeight: 30, gap: [10, 10], padding: null, mode: 'grid', canvas: 'fluid' })
+// 移动端堆叠布局的网格参数（原 Dashboard.gridMargin 的移动端分支）
+export const MOBILE_GRID = Object.freeze({ colNum: 48, rowHeight: 10, gap: [8, 8], padding: null, mode: 'grid', canvas: 'fluid' })
+
+const isPosInt = v => Number.isInteger(v) && v > 0
+const nonNeg = v => v !== null && v !== '' && !Array.isArray(v) && Number.isFinite(Number(v)) && Number(v) >= 0
+
+// [x, y] 数对：接受 'auto'、二元数组、单个数字（横纵同值）；其余回落
+function pair (v, fallback) {
+  if (v === 'auto') return 'auto'
+  if (Array.isArray(v) && v.length === 2 && v.every(nonNeg)) return [Number(v[0]), Number(v[1])]
+  if (nonNeg(v)) return [Number(v), Number(v)]
+  return fallback
+}
+
+export function isContainerType (contentType) {
+  return CONTAINER_TYPES.includes(contentType)
+}
+
+export function normalizeGridParams (grid, fallback = DEFAULT_GRID) {
+  const g = grid && typeof grid === 'object' ? grid : {}
+  const colNum = isPosInt(Number(g.colNum)) ? Number(g.colNum) : fallback.colNum
+  let rowHeight = fallback.rowHeight
+  if (g.rowHeight === 'auto') rowHeight = 'auto'
+  else if (nonNeg(g.rowHeight) && Number(g.rowHeight) > 0) rowHeight = Number(g.rowHeight)
+  const gap = pair(g.gap, fallback.gap)
+  const padding = g.padding == null ? (fallback.padding == null ? null : fallback.padding) : pair(g.padding, fallback.padding)
+  const mode = g.mode === 'float' ? 'float' : 'grid'
+  const canvas = g.canvas === 'fixed' ? 'fixed' : 'fluid'
+  const out = { colNum, rowHeight, gap, padding, mode, canvas }
+  if (canvas === 'fixed') out.size = pair(g.size, [1920, 1080])
+  return out
+}
+
+// 旧版配置：version 缺失或主版本号 < 3（'3.1' 等后续小版本仍按 v3 语义读 grid 键）
+export function isLegacyConfig (config = {}) {
+  return !config || !(parseFloat(config.version) >= 3)
+}
+
+// 旧版（无 grid 键）的页面级参数：autoHeight ⇒ 行高与间距都按视口高度等比（与原实现同义）
+function legacyPageGrid (config = {}) {
+  return config.autoHeight ? { ...DEFAULT_GRID, rowHeight: 'auto', gap: 'auto' } : { ...DEFAULT_GRID }
+}
+
+export function getPageGrid (config = {}) {
+  const c = config || {}
+  return isLegacyConfig(c) ? normalizeGridParams(c.grid, legacyPageGrid(c)) : normalizeGridParams(c.grid)
+}
+
+// 容器内部网格：容器显式 grid 优先；旧版配置无 grid 用历史写死值；v3 无 grid 继承父网格。
+// 无显式 grid 时直接返回 base（冻结常量 / 父级 computed 缓存），引用稳定：它经 comp-grid 传给容器，
+// 每次渲染换新对象会让父看板的每次 render 级联到容器内全部子组件重新 render
+export function getContainerGrid (item = {}, parentGrid = DEFAULT_GRID, legacy = false) {
+  const base = legacy ? LEGACY_CONTAINER_GRID : parentGrid
+  if (item && item.grid) return normalizeGridParams(item.grid, base)
+  return base
+}
+
+// 深度优先遍历网格项（父先于子）。dashboard-tabs 的 items 是页签对象（无 contentType），不回调，只下钻其 items
+export function walkItems (items, fn, parent = null) {
+  if (!Array.isArray(items)) return
+  for (const item of items) {
+    if (!item || typeof item !== 'object' || !item.contentType) continue
+    fn(item, parent)
+    if (item.contentType === 'dashboard-tabs') {
+      for (const tab of (item.items || [])) walkItems(tab && tab.items, fn, item)
+    } else {
+      walkItems(item.items, fn, item)
+    }
+  }
+}
+
+// 升级 / 规范化整份看板配置（深拷贝，不改入参）。运行态不调用它（运行态逐项用 normalizeGridItem +
+// getPageGrid / getContainerGrid），设计器加载时调用并在保存时写回。
+export function normalizeDashboardConfig (config = {}) {
+  const out = JSON.parse(JSON.stringify(config || {}))
+  out.designTarget = out.designTarget === 'mobile' ? 'mobile' : 'pc'
+  const legacy = isLegacyConfig(out)
+  out.grid = getPageGrid(out)
+  walkItems(out.items, (item, parent) => {
+    normalizeGridItem(item)
+    if (item.float !== undefined) item.float = !!item.float
+    if (item.static !== undefined) item.static = !!item.static
+    if (isContainerType(item.contentType)) {
+      const parentGrid = parent && parent.grid ? parent.grid : out.grid
+      // 展开成可变副本：getContainerGrid 可能直接返回冻结常量，不能把它挂进要被设计器改写的配置树
+      item.grid = { ...getContainerGrid(item, parentGrid, legacy) }
+    }
+  })
+  out.version = CONFIG_VERSION
+  return out
+}
+
+// 保存前剥离运行时字段 i（页签对象也可能被布局库写入 i），以及漏进 itemConfigs 的网格项布局键
+// （容器条目的 grid 同样只认 item 上的那份；非容器的 grid 是组件自己的配置，不碰）。
+// 只剥「存在对应 item」的条目：孤儿条目（画布上已没有这个 id）与自定义键原样保留，产品仓可能靠它们存别的东西
+export function stripDashboardConfig (config = {}) {
+  const out = JSON.parse(JSON.stringify(config || {}))
+  const itemIds = new Set()
+  const containerIds = new Set()
+  walkItems(out.items, item => {
+    delete item.i
+    itemIds.add(String(item.id))
+    if (isContainerType(item.contentType)) containerIds.add(String(item.id))
+    if (item.contentType === 'dashboard-tabs') {
+      for (const tab of (item.items || [])) if (tab) delete tab.i
+    }
+  })
+  const itemConfigs = out.itemConfigs
+  if (itemConfigs && typeof itemConfigs === 'object') {
+    for (const id in itemConfigs) {
+      const cfg = itemConfigs[id]
+      if (!cfg || typeof cfg !== 'object' || !itemIds.has(id)) continue
+      for (const key of ITEM_LAYOUT_KEYS) delete cfg[key]
+      if (containerIds.has(id)) delete cfg.grid
+    }
+  }
+  return out
+}
+
+// 行距：每行占位高度 = 一行内容高（存储的 rowHeight）+ 纵向间距；'auto' 行高为 null。
+// 面板上的「行高」就是它：存储与几何仍按旧语义（组件高 = h·rowHeight + (h−1)·gap，与 Vue2 线上版逐像素一致），
+// 面板改间距时按行距反推 rowHeight 落盘，于是改间距只改组件之间的空隙与四边留白、不改变组件位置和页面高度，改行高（行距）才改
+export function gridPitch (grid) {
+  if (!grid || grid.rowHeight === 'auto') return null
+  return grid.rowHeight + (grid.gap === 'auto' ? 0 : grid.gap[1])
+}
+
+// 行距下间距的上限：一行内容高至少 1px
+export function maxGapForPitch (pitch) {
+  return pitch == null ? Infinity : Math.max(0, pitch - 1)
+}
+
+// grid 对象 → 全局面板扁平键：gridRowHeight 是行距（见 gridPitch）；'auto' 行高 / 间距在面板上是空值（由 autoHeight 开关承载），
+// 内边距取单值（缺省 null = 跟随间距）
+export function fromGrid (grid) {
+  const g = normalizeGridParams(grid)
+  return {
+    gridColNum: g.colNum,
+    gridRowHeight: gridPitch(g),
+    gridGap: g.gap === 'auto' ? null : g.gap[0],
+    gridPadding: g.padding == null || g.padding === 'auto' ? null : g.padding[0],
+    gridMode: g.mode
+  }
+}
+
+const numOr = (v, fallback) => (v == null || v === '' || !Number.isFinite(Number(v)) ? fallback : Number(v))
+// 只认非负数，其余（含负数）回落
+const nonNegOr = (v, fallback) => (numOr(v, -1) < 0 ? fallback : Number(v))
+
+// 全局面板扁平键（+ autoHeight 开关）→ grid 对象：gridRowHeight 是行距，落盘 rowHeight = 行距 − 间距（间距夹到行距 − 1）；
+// 空 / 非法值回落页面默认；autoHeight 开着时行高与间距都是 'auto'；面板没有的键（canvas / size）从现有 grid 带过来
+export function toGrid (configs = {}, grid = DEFAULT_GRID) {
+  const c = configs || {}
+  const auto = !!c.autoHeight
+  const padding = numOr(c.gridPadding, null)
+  const pitch = Math.max(1, numOr(c.gridRowHeight, gridPitch(DEFAULT_GRID)))
+  const gap = Math.min(nonNegOr(c.gridGap, DEFAULT_GRID.gap[0]), maxGapForPitch(pitch))
+  return normalizeGridParams({
+    ...(grid || {}),
+    colNum: numOr(c.gridColNum, DEFAULT_GRID.colNum),
+    rowHeight: auto ? 'auto' : pitch - gap,
+    gap: auto ? 'auto' : [gap, gap],
+    padding: padding == null ? null : [padding, padding],
+    mode: c.gridMode || DEFAULT_GRID.mode
+  })
+}
+
+// 设计器外壳：把全局面板的补丁并入页面全局配置（不改入参）。扁平键折进 grid 后从配置里删掉；
+// autoHeight ↔ grid.rowHeight 'auto' 双向同步（运行态 v3 只读 grid，开关只是它的面板形态）；
+// 返回列数是否变化（外壳据此询问是否按比例换算现有组件）
+export function mergeGridConfigs (globalConfigs = {}, patch = {}) {
+  const next = { ...(globalConfigs || {}), ...(patch || {}) }
+  const current = getPageGrid(next)
+  const touched = Object.keys(patch || {}).some(key => key === 'autoHeight' || GRID_FLAT_KEYS.includes(key))
+  let grid = current
+  if (touched) {
+    const flat = { ...fromGrid(current) }
+    for (const key of GRID_FLAT_KEYS) if (key in patch) flat[key] = patch[key]
+    grid = toGrid({ ...flat, autoHeight: next.autoHeight }, current)
+  }
+  next.grid = grid
+  const auto = grid.rowHeight === 'auto'
+  if (auto !== !!next.autoHeight) next.autoHeight = auto
+  for (const key of GRID_FLAT_KEYS) delete next[key]
+  return { configs: next, colNum: current.colNum !== grid.colNum ? { from: current.colNum, to: grid.colNum } : null }
+}
+
+// 改列数：现有项按比例换算 x / w 与宽度约束 minW / maxW（就地改；y / h / minH / maxH 不动）。有自己列数的容器（显式 grid.colNum）
+// 本身参与换算、其子项按容器网格布局不换算；继承父网格的容器（含页签）子项跟着换算
+export function rescaleItemsToColNum (items, from, to) {
+  if (!(from > 0) || !(to > 0) || from === to) return items
+  const ratio = to / from
+  const stopped = new Set()
+  walkItems(items, (item, parent) => {
+    if (parent && stopped.has(parent)) {
+      stopped.add(item)
+      return
+    }
+    const w = Math.min(to, Math.max(1, Math.round((Number(item.w) || 1) * ratio)))
+    item.x = Math.max(0, Math.min(Math.round((Number(item.x) || 0) * ratio), to - w))
+    item.w = w
+    // 宽度约束同比换算（round(v·new/old)，至少 1 列）；没设的不补
+    for (const key of ['minW', 'maxW']) {
+      if (item[key] != null && item[key] !== '' && Number.isFinite(Number(item[key]))) item[key] = Math.max(1, Math.round(Number(item[key]) * ratio))
+    }
+    if (isContainerType(item.contentType) && item.grid && isPosInt(Number(item.grid.colNum))) stopped.add(item)
+  })
+  return items
+}
+
+// 容器项的有效内部网格（含继承链）：从根开始逐层 getContainerGrid，找到 id 为止。
+// 返回 { item, grid, parentGrid, explicit }（explicit：是否有显式 grid）；不是容器 / 找不到返回 null
+export function resolveContainerGrid (items, id, pageGrid = DEFAULT_GRID, legacy = false) {
+  let found = null
+  const grids = new Map()
+  walkItems(items, (item, parent) => {
+    if (found || !isContainerType(item.contentType)) return
+    const parentGrid = parent && grids.has(parent) ? grids.get(parent) : pageGrid
+    const grid = getContainerGrid(item, parentGrid, legacy)
+    grids.set(item, grid)
+    if (String(item.id) === String(id)) found = { item, grid, parentGrid, explicit: !!(item.grid && typeof item.grid === 'object') }
+  })
+  return found
+}
+
+export function partitionItems (items = []) {
+  const flow = []
+  const float = []
+  for (const item of items || []) {
+    if (!item) continue
+    (item.float ? float : flow).push(item)
+  }
+  return { flow, float }
+}
+
+// 跨网格移动时按视觉尺寸换算 w/h：像素宽 W = w·colWidth + (w−1)·gapX，反解目标网格的 w'
+export function convertItemBetweenGrids (item, from, to) {
+  const px = item.w * from.colWidth + (item.w - 1) * from.gapX
+  const py = item.h * from.rowHeight + (item.h - 1) * from.gapY
+  const w = Math.max(1, Math.round((px + to.gapX) / (to.colWidth + to.gapX)))
+  const h = Math.max(1, Math.round((py + to.gapY) / (to.rowHeight + to.gapY)))
+  return { ...item, w: Math.min(w, to.colNum), h }
+}

package/src/grid/useViewportGate.js

@@ -0,0 +1,57 @@
+// 可视区门控：用两个 IntersectionObserver 管全部项——进入「近区」（默认 ±1 屏）激活、离开「远区」
+// （默认 ±2 屏）停用，中间是滞后带，避免滚动边缘反复挂卸。不依赖 Vue，便于单测。
+export function createViewportGate ({ root = null, mountMargin = '100%', unmountMargin = '200%', sticky = false, onChange } = {}) {
+  const IO = typeof window !== 'undefined' ? window.IntersectionObserver : undefined
+  if (typeof IO !== 'function') {
+    // 环境不支持：一律视为可见，调用方按「全部挂载」处理
+    return { supported: false, observe () {}, unobserve () {}, isActive: () => true, destroy () {} }
+  }
+  const idOf = new WeakMap()
+  const active = new Set()
+  const emit = (id, on) => {
+    if (id == null) return
+    if (on && !active.has(id)) {
+      active.add(id)
+      if (onChange) onChange(id, true)
+    } else if (!on && active.has(id)) {
+      active.delete(id)
+      if (onChange) onChange(id, false)
+    }
+  }
+  const near = new IO(entries => {
+    for (const e of entries) if (e.isIntersecting) emit(idOf.get(e.target), true)
+  }, { root, rootMargin: `${mountMargin} 0px` })
+  const far = sticky ? null : new IO(entries => {
+    for (const e of entries) if (!e.isIntersecting) emit(idOf.get(e.target), false)
+  }, { root, rootMargin: `${unmountMargin} 0px` })
+  return {
+    supported: true,
+    observe (el, id) {
+      // 同一元素换绑新 id（未经过 unobserve）：near/far 对已在观察列表中的目标重复 observe
+      // 是 no-op，不会补发一次通知，所以要先把旧 id 的激活态按「离开」清掉，否则 active 里
+      // 会残留旧 id、新 id 又读不到激活态，直到元素下次真正跨越阈值触发回调才会纠正
+      const prevId = idOf.get(el)
+      if (prevId !== undefined && prevId !== id) emit(prevId, false)
+      idOf.set(el, id)
+      near.observe(el)
+      if (far) far.observe(el)
+    },
+    unobserve (el) {
+      near.unobserve(el)
+      if (far) far.unobserve(el)
+      const id = idOf.get(el)
+      idOf.delete(el)
+      // 直接清 active、不经过 emit：调用方主动 unobserve（如元素被移除）时自行收尾该 id 的
+      // 状态即可，门控不再补发 onChange(id, false) 通知
+      if (id != null) active.delete(id)
+    },
+    isActive (id) {
+      return active.has(id)
+    },
+    destroy () {
+      near.disconnect()
+      if (far) far.disconnect()
+      active.clear()
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,28 @@
+import Dashboard from './Dashboard'
+import DashboardTabs from './Tabs'
+import DashboardTitle from './Title'
+import DashboardDiv from './Div'
+import DashboardWidget from './Widget'
+import Preview from './Preview.vue'
+import CompatGridLayout from './grid/compat/GridLayout.vue'
+import CompatGridItem from './grid/compat/GridItem.vue'
+
+/* istanbul ignore next */
+Dashboard.install = function install (Vue) {
+  Vue.component(Dashboard.name, Dashboard)
+  Vue.component(DashboardTabs.name, DashboardTabs)
+  Vue.component(DashboardTitle.name, DashboardTitle)
+  Vue.component(DashboardDiv.name, DashboardDiv)
+  Vue.component(DashboardWidget.name, DashboardWidget)
+  Vue.component(Dashboard.name + '--preview', Preview)
+  // 垫片：原先由 Dashboard.created 动态 import grid-layout-plus 后 registerComponent；
+  // 产品子类复刻的模板里直接写 <grid-layout>/<grid-item>，改为安装时注册只读实现。
+  // 用旧的注册名挂全局（模板标签解析走注册名、不走组件 name 选项），
+  // 组件自身 name 按仓库命名规范带 epx- 前缀
+  Vue.component('GridLayout', CompatGridLayout)
+  Vue.component('GridItem', CompatGridItem)
+}
+
+export default Dashboard
+
+export { Dashboard, DashboardTabs, DashboardTitle, DashboardDiv, DashboardWidget }