lg-grid：原生JavaScript自动宫格布局库，不依赖框架

如果你在多技术栈的团队里待过，大概率碰到过这种尴尬：只是想在一个页面里放一组能自动平分、能跟随容器宽度变化的宫格，结果先得回答“项目用的是 React 还是 Vue”。我在帮不同项目做运营页、后台看板和轻量工具时，同一个自动宫格布局需求被我用 Vue 写了一遍，又用 React 复刻了一遍，后来还被一个 jQuery 老项目逼着再造了第三遍。白天写业务晚上维护组件，越写越觉得不对——这种到处都能用的底层布局能力，凭什么非得和框架绑定？lg-grid 就是在这种憋屈里冒出来的项目：不依赖任何框架，用原生 JavaScript 把“自动宫格布局”这件事做到接口简单、结果稳定，谁想接都能接，谁不想接也不影响自己跑。

这篇文章我不会只贴源码，重点讲几件比源码更值钱的事：自动宫格背后到底在算什么、为什么 lg-grid 的设计敢于摒弃框架依赖、它从纯函数到正式组件踩过哪些坑。适合正在犹豫“要不要自己造一个布局组件”的人，也适合被现有栅格方案逼疯的开发者——看完你至少能判断：轻量布局库到底应该替你做多少事，剩下的事又该留在哪一侧。

1. 不是框架不好，是“只是一个宫格”不该被框架绑死

1.1 我遇到的实际场景：同一个布局反复被重写

事情起于一个很日常的需求：运营希望在富文本里嵌入一组入口图标，数量不定，有时 6 个有时 11 个，要求自动排成整齐的行列，屏幕窄的时候列数自动变少。

听起来很简单，但放在不同项目里就完全不是一回事了。React 项目里，我第一反应是写一个 <Grid> {items.map(...)} </Grid>；Vue 项目里又要用 template v-for 再写一套；老 jQuery 页面里甚至得手工拼字符串再调 CSS。最讽刺的是，不同框架版本之间组件还不能直接迁移，光是 onMounted 和 useEffect 的时机差异就能让 resize 监听失效。

这让我意识到：开发者真正需要的不是“又一个 React 组件”或“又一个 Vue 组件”，而是一个与渲染层无关的布局内核。框架只是负责把元素放进容器，放进去之后怎么排、怎么响应尺寸变化，是另一层问题。与其让每个框架都维护一份自己的宫格实现，不如写一个原生 JavaScript 内核，谁要用谁再套一层薄薄的适配。

1.2 框架绑定到底绑住了什么

所谓“拒绝框架绑定”，不是鼓吹大家回到刀耕火种，而是把话说清楚：框架绑定是一种成本，只有当收益大于成本时才该接受。

绑在 React 上，意味着这个组件只能吃 React 的 props、只能在组件树里存在、只能通过 hooks 管理副作用。绑在 Vue 上，意味着指令、响应式依赖、模板编译一个都不能少。绑定带来的收益是开发体验顺畅，但代价是：换一个项目技术栈，这个组件基本作废；同页面里混用多个框架（比如微前端架构很常见），组件之间没法共用；甚至连一个纯静态页也要为了一个宫格强行拉进一整套框架运行时。

lg-grid 选择不绑，原因是这个场景的“交互状态”太薄了。宫格不需要框架帮忙管理复杂状态，它需要的只是：给我一个容器，我负责把容器里的子元素按行列坐标摆放好。这种能力放在 DOM 层就足够，外面包多少层框架，反而让它变慢、变重。

1.3 lg-grid 想解决的核心矛盾

说到底，lg-grid 想解决的核心矛盾是“布局逻辑的复用性”和“框架生态的割裂性”之间的矛盾。

我希望它做到三件事。第一，独立运行：原生 JavaScript 写成，不 import React 也不依赖 Vue，放进任何 HTML 页面都能直接工作。第二，框架友好：不是“不支持框架”，而是“不强制框架”，你要在 Vue 里用也可以，花十行代码包一个组件即可。第三，生命周期干净：组件实例可以创建、可以销毁、可以重新计算，绝不留下全局监听器污染页面。

这套设计思路听起来不复杂，但真做起来，布局的算法细节、事件监听的边界、尺寸计算的标准，都比想象中磨人。下面就从最内核的部分讲起。

2. 布局的数学内核：列数、间距、格子宽度如何一次算清

2.1 需求边界先理清：lg-grid 管什么、不管什么

写布局库最怕做“万能工具”，因为需求一旦发散，实现就会失控。lg-grid 给自己划定的边界非常窄：它解决的是“N 个子元素在宽度为 W 的容器里，自动分配成 K 列、M 行均匀格子”的问题。

管的事包括：根据容器实际宽度计算合适列数、把列数和间距转成可落地的格子宽度、处理子元素增加或删除后的重新布局、在容器尺寸变化时自动响应。不管的事包括：子元素内部的图文排版、拖拽排序、分页加载、虚拟滚动。这些功能不是不重要，而是它们各有专属插件生态，硬塞进一个 4KB 的代码库里只会让每个人都用不顺手。

另外要明确一点：lg-grid 布局的最小单元是容器的一级子元素。它不会递归去分析你孙子节点里的内容，也不会管你每个格子里是不是图片、是不是 a 链接。因此设计上要求容器必须真实存在于 DOM 中，所有子元素默认按 DOM 顺序从左到右、从上到下填充。

2.2 容器尺寸 → 列数换算，核心公式拆开看

“自动宫格”的“自动”主要体现在列数不是写死的，而是根据容器宽度实时算出来的。网上很多实现喜欢硬编码断点，比如小于 768px 两列、小于 1024px 三列，这种方案一旦容器不是全屏宽度就失效——侧边栏里可能只有 300px，主区域有 900px，断点却无从判定。

lg-grid 换了个思路：不看屏幕宽度，只看容器自身宽度，并且引入一个 minItemWidth 参数，表示“每个格子至少要多宽才算舒适”。有了这个参数，列数就等于：

code复制可用宽度 = 容器内容宽度 W
带间距总宽 = W + 间距 gap
每个单元占位 = 最小格子宽 minItemWidth + 间距 gap
列数 columns = Math.floor((W + gap) / (minItemWidth + gap))

然后格子真实宽度不是简单地“W / columns”，而要把总间距扣除掉：

code复制格子宽 cellWidth = (W - (columns - 1) * gap) / columns

举例来说：容器宽度 640px，间距 16px，最小格子宽 150px，那么 (640 + 16) / (150 + 16) = 3.95，向下取整得 3 列，每个格子真实宽度就是 (640 - 2 * 16) / 3 = 202.67px。注意这里 202.67 大于 150，说明格子有富余，这是正常现象：自动列数本来就是为了保证格子不会窄到难看，而不是追求“塞下尽可能多列”。

同样的容器，如果最小格子宽改成 100px，列数就会变成 4，甚至更多。这个参数的语义非常直观：给团队成员配置时，谁都不用去理解复杂的 media query，只要说“格子至少 120px 宽”就够了。

2.3 行列坐标分配：先写一个纯函数当算法的锚点

列数算出来之后，剩下的事情就是把每个子元素的序号映射到行列坐标。在行优先填充模式下，第 i 个子元素（从 0 开始）的列号是 i % columns，行号是 Math.floor(i / columns)。

我强烈建议在写任何 DOM 操作之前，先把这部分抽成一个纯函数。核心原因在于：纯函数不碰 DOM，没有任何副作用，你可以用单元测试覆盖它，也可以把翻页、过滤后重新布局的逻辑和渲染彻底分离。lg-grid 最初的版本里，我甚至先用 Node 跑测试验证了公式，之后才敢把它接进浏览器。

下面是布局计算函数的骨架，它接收宽度、间距、最小格子宽，输出每个格子的坐标：

javascript复制function calcGridLayout({ width, gap, minItemWidth, maxColumns, itemCount }) {
  const usableWidth = Math.max(width, 0);
  let columns = Math.max(1, Math.floor((usableWidth + gap) / (minItemWidth + gap)));
  if (maxColumns) {
    columns = Math.min(columns, maxColumns);
  }
  if (itemCount > 0) {
    columns = Math.min(columns, itemCount);
  }
  const cellWidth = (usableWidth - (columns - 1) * gap) / columns;
  const rows = Math.max(1, Math.ceil(itemCount / columns));
  const positions = [];

  for (let i = 0; i < itemCount; i++) {
    const col = i % columns;
    const row = Math.floor(i / columns);
    positions.push({
      left: col * (cellWidth + gap),
      top: row * (cellWidth + gap), // 等宽模式下行高暂时等于格子宽
      width: cellWidth,
      height: cellWidth,
    });
  }

  return { columns, rows, cellWidth, positions };
}

这个函数看起来简单，但几个细节都是经验之谈。itemCount 不足一列时强制 Math.min(columns, itemCount)，能避免“只有 2 个元素却排成 6 列”的怪象；Math.max(usableWidth, 0) 是防御性写法，防止容器隐藏时 clientWidth 返回 0 后算出负数；坐标计算统一用 加间距 的方式，避免在循环里反复乘 (cellWidth + gap) 产生精度累积错误。

2.4 为什么选择 CSS Grid 作为最终落地方式，而不是纯 JS 定位

纯函数算出来的 left/top/width 是最原始的布局结果，但在 lg-grid 实际渲染时，我并没有把每个格子都用 style.left 和 style.top 塞一遍。默认模式是让 JS 只管“列数、间距、格子宽度”这些参数，最终用 CSS Grid 的 grid-template-columns 来铺格子。

这样做的最大好处是省掉大量手工定位代码。CSS Grid 天然处理了换行、对齐、间距和未知高度的行，性能也比反复修改子元素 left/top 好得多。而 lg-grid 只需要把计算得到的列数、间距通过 CSS 变量传递下去：

css复制.lg-grid {
  display: grid;
  grid-template-columns: repeat(var(--lg-cols, 4), 1fr);
  gap: var(--lg-gap, 12px);
}
.lg-grid > * {
  min-width: 0;
}

在实际容器宽 640px 的场景里，默认 --lg-cols 就是 3，CSS Grid 会自动把 3 列均分。JS 完全不需要知道每个格子的像素坐标，只需要在容器 resize 后更新变量。

这不代表绝对定位模式没有价值。我在 lg-grid 里保留了一个 mode: 'abs' 选项，用于那些必须“精确控制格子位置”的场景，比如后续要做拖拽动画、需要知道每个格子当前绝对坐标来配合特效。但在默认情况下，能让浏览器原生布局引擎干的事，就不要用 JavaScript 重复造。

3. 从几个纯函数到一个可用的组件：lg-grid 手写记录

3.1 初始化入口与整体结构

纯函数解决的是“怎么算”，组件的核心任务则是“什么时候算、算完怎么落”。lg-grid 采用类的方式对外暴露：构造函数接收一个容器和配置，内部负责初始化监听并执行第一次布局。

javascript复制class LGGrid {
  constructor(container, options = {}) {
    if (typeof container === 'string') {
      container = document.querySelector(container);
    }
    if (!container || !container.nodeType) {
      throw new Error('lg-grid 需要一个有效的容器元素或选择器');
    }

    this.container = container;
    this.options = {
      gap: 12,
      minItemWidth: 150,
      maxColumns: 0,
      itemClass: 'lg-grid-item',
      mode: 'grid',
      equalHeight: false,
      ...options,
    };

    this.lastWidth = -1;
    this.destroyed = false;
    this._rafId = 0;
    this._resizeObserver = null;
    this._mutationObserver = null;

    this.applyContainerClass();
    this.observeContainer();
    this.render();
  }
}

这段初始化代码里有几处容易被新手忽略的地方。第一，容器既支持传元素也支持传选择器，这是原生库提升易用性最便宜的方式；第二，构造函数里把 destroyed 标记成 false，是为了后续所有异步回调都能先检查它，避免销毁后还去操作无效 DOM；第三，真正观察容器之前，先调用一次 render，保证页面一加载出来布局就是对的。

applyContainerClass 会给容器追加一个 lg-grid 类名，让用户不用在 HTML 里手动写那一长串 display:grid 样式。这个设计很“库”味：让 JS 自动补齐运行所需的类名，但类名对应的样式又由库自带的 CSS 文件提供，用户完全不用理解内部类与样式的关系。

3.2 观察容器尺寸：ResizeObserver 加 rAF，别让 resize 事件把你拖垮

自动宫格最核心的自动能力来自对容器尺寸变化的响应。传统的 window.addEventListener('resize') 只能监听视口变化，一旦容器宽度不是百分之百视口宽，比如侧边栏、弹窗、可拖拽分割面板里的宫格，传统方案就失灵了。

lg-grid 使用的是 ResizeObserver，它能精确观察某个 DOM 元素的尺寸变化，不需要关心位置、视口、滚动条等外部因素，比 window resize 准确得多。

但 ResizeObserver 的回调触发频率非常高，如果每次回调里都直接执行重排，布局计算、样式写入、浏览器 reflow 叠加起来会在快速拖拽窗口时造成明显掉帧。处理方式是把回调里的操作放进 requestAnimationFrame 里合并：

javascript复制observeContainer() {
  if (typeof ResizeObserver === 'undefined') {
    window.addEventListener('resize', this.handleResize);
    return;
  }

  this._resizeObserver = new ResizeObserver((entries) => {
    cancelAnimationFrame(this._rafId);
    this._rafId = requestAnimationFrame(() => {
      for (const entry of entries) {
        if (entry.target === this.container) {
          this.render();
        }
      }
    });
  });
  this._resizeObserver.observe(this.container);
}

cancelAnimationFrame 加 requestAnimationFrame 的组合在这里起到防抖作用：同一帧内无论 ResizeObserver 触发了多少次，最终只会执行一次真正渲染。这是一个所有尺寸敏感组件都应该有的习惯。

值得注意的是 handleResize 这个兼容分支。较老浏览器不支持 ResizeObserver 时，退化为 window resize 监听，此时需要额外判断“容器当前宽度和上次是否真的不同”，否则滚动条出现、隐藏等操作也会误触发重排。lg-grid 在 render 函数里做了一次宽度缓存判断，这也算一个双保险。

3.3 子元素变化监听：让新增和删除也能自动重排

容器宽度变化只是触发重排的一半来源，另一半是子元素数量变化。在一个用 jQuery 或原生 JS 动态渲染数据的页面里，列表项经常是异步加载的：先渲染 3 个占位，等接口返回后又塞进 10 个真实数据项。如果组件只监听尺寸，子元素数量变了也不会重新计算列数，就会出现前 3 个排在正确位置、后面的元素直接溢出容器的尴尬情况。

lg-grid 用 MutationObserver 监听容器的 childList 变化，子元素增加或删除时自动触发重排：

javascript复制observeChildren() {
  if (typeof MutationObserver === 'undefined') return;

  this._mutationObserver = new MutationObserver((mutations) => {
    const needRelayout = mutations.some((mutation) => {
      return mutation.type === 'childList' && mutation.addedNodes.length + mutation.removedNodes.length > 0;
    });
    if (needRelayout) {
      cancelAnimationFrame(this._rafId);
      this._rafId = requestAnimationFrame(() => this.render());
    }
  });

  this._mutationObserver.observe(this.container, {
    childList: true,
  });
}

这里刻意只观察 childList，不去观察 attributes。一开始我确实想连子元素的 hidden 属性、class 变化也一起监听，后来发现会产生非常多无效重排：用户给格子加一个动画 class 也要触发布局计算，得不偿失。所以 lg-grid 的理念是：只管数量结构性变化，其余变化通过公开方法 refresh() 让用户按需触发。

3.4 用 CSS 变量传递计算结果，避免反复读写布局属性

render 函数是整个组件的执行中枢，先取容器实际宽度，再调用布局计算，最后把结果同步到 DOM。它的性能关键点在于：尽量少地触发强制同步布局。

javascript复制render() {
  if (this.destroyed) return;

  const width = this.container.clientWidth;

  if (width === this.lastWidth && this.container.childElementCount === this.lastCount) {
    return;
  }

  this.lastWidth = width;
  this.lastCount = this.container.childElementCount;

  const info = calcGridLayout({
    width,
    gap: this.options.gap,
    minItemWidth: this.options.minItemWidth,
    maxColumns: this.options.maxColumns,
    itemCount: this.container.childElementCount,
  });

  this.container.style.setProperty('--lg-cols', String(info.columns));
  this.container.style.setProperty('--lg-gap', `${this.options.gap}px`);

  if (this.options.mode === 'abs') {
    this.layoutAbsolute(info);
  }

  this.emit('layout', info);
}

在默认 grid 模式下，render 函数全程只写入 CSS 变量，不读取任何子元素的几何属性。写入 --lg-cols 和 --lg-gap 之后，浏览器会在下一帧统一完成 grid 排版，中间没有读写交错，因此不会引起 layout thrash。lastWidth 与 lastCount 两个缓存字段是重排过滤器，很多无效调用在进入真正计算前就被拦住了。

3.5 绝对定位模式：给需要特效的场景留一扇门

layoutAbsolute 用于那些需要精确坐标的场景。它做的事很简单：给容器设置 position: relative，然后遍历所有子元素，把每个元素的 left、top、width 直接写成像素值。

javascript复制layoutAbsolute(info) {
  const children = Array.from(this.container.children);

  children.forEach((child, index) => {
    const position = info.positions[index];
    if (!position) {
      child.style.display = 'none';
      return;
    }
    child.style.position = 'absolute';
    child.style.left = `${position.left}px`;
    child.style.top = `${position.top}px`;
    child.style.width = `${position.width}px`;
    child.style.display = '';
  });

  this.container.style.height = `${info.rows * (info.cellWidth + this.options.gap)}px`;
}

绝对定位模式下由于所有子元素脱离了文档流，容器自身高度不会被内容撑开，所以必须手动把高度写进容器 style。这也是为什么 lg-grid 把“等宽模式下行高等于格子宽”作为 abs 模式默认假设——想要真正的瀑布流，那不是宫格布局该做的是，早该换 masonry 类库了。

4. 接口是组件的脸：lg-grid 的配置、事件与生命周期设计

4.1 最小可用接口：一个构造函数就能跑起来

一个库好不好用，不看文档写多长，看用户从安装到跑通需要几行代码。lg-grid 的最小用法是三行：

html复制<script src="dist/lg-grid.umd.js"></script>
<link rel="stylesheet" href="dist/lg-grid.css">

<div class="demo-grid">
  <div>1</div>
  <div>2</div>
  <div>3</div>
  <div>4</div>
  <div>5</div>
</div>

<script>
  const grid = new LGGrid('.demo-grid', {
    gap: 16,
    minItemWidth: 120,
  });
</script>

没有 webpack 配置、没有 import 路径、没有框架插件，只要容器和子元素在页面上，它自己就能完成初始化。这也是原生库该有的自觉：使用者不应该为了一个自动宫格去理解模块打包器。

为了让静态页面使用更顺手，lg-grid 还支持通过 data-lg-grid 配置自动初始化。页面加载完成后，从 DOM 里查找所有带这个属性的元素，读取属性值里的 JSON 配置并创建实例，这样连 script 标签里的手动 new 都省了：

html复制<div class="demo-grid" data-lg-grid='{"gap": 12, "minItemWidth": 100}'>
  <div>item</div>
</div>

这种自动化能力很轻，但很符合“不绑框架”的定位：在 CMS 渲染的静态页面、营销落地页里，运营只需要在 HTML 容器上挂一个属性，布局就自动生效了。

4.2 配置项怎么设计才“不用读文档就能猜对”

lg-grid 的配置项不多，每个都尽量单一看名字就能理解。常用配置项整理如下：

固定列数和自动列数是两种独立诉求。有些场景里用户就想“管你容器多宽，永远5列”，这时 columns: 5 应该直接覆盖 minItemWidth 计算；

另一类场景则相反，希望格子宽度跟着容器走，越宽排越多列。两个配置同时存在，用户选择权更大，但必须明确优先级：columns 显式设置时优先生效，否则才走 minItemWidth 自动计算。这种“显式大于隐式”的原则避免了两种配置互相打架的困惑。

4.3 实例方法与事件：让外部可以按需介入

构造函数返回的实例不是只能作为摆设，lg-grid 暴露了四个方法，覆盖绝大多数使用场景：

• refresh()：重新读取容器子元素并计算布局。用于数据更新后列数没变但内容需要重新核准的场景。
• destroy()：解除所有监听器、清空 CSS 变量、移除容器类名，把 DOM 还原成组件初始化之前的状态。
• getInfo()：返回当前列数、行数、格子宽宽等布局元数据，方便外部读取后去做其他逻辑。
• on(event, handler)：订阅自定义事件，当前主要支持 layout。

这些方法的命名刻意避开了框架里常见的复杂术语。用户不需要理解 reconcile、renderer、dispatcher，直觉就知道 refresh 是刷新布局、destroy 是销毁组件。接口命名遵循直觉，是小型原生库减少沟通成本最有效的手段。

4.4 销毁逻辑里最容易被忽视的清理工作

很多初学者写的原生插件根本没有 destroy 方法，或者只是把 DOM 节点隐藏起来，导致页面反复进入退出后，旧实例的监听器还挂在容器上，每次 resize 都触发几份重复计算。

lg-grid 的 destroy 会做三件事：断开 ResizeObserver、断开 MutationObserver、移除容器上的内联样式与自定义属性。这三件事缺一不可，否则最典型的问题是：实例已经不用了，ResizeObserver 还盯着容器；一旦容器尺寸变化，旧回调里又去操作已经被外部替换过的子节点，轻则报错，重则产生双份布局相互打架。

javascript复制destroy() {
  this.destroyed = true;

  if (this._resizeObserver) {
    this._resizeObserver.disconnect();
    this._resizeObserver = null;
  }
  if (this._mutationObserver) {
    this._mutationObserver.disconnect();
    this._mutationObserver = null;
  }

  this.container.style.removeProperty('--lg-cols');
  this.container.style.removeProperty('--lg-gap');
}

5. 适配 React / Vue 不用改库：把管理权留在框架侧

5.1 适配原则：框架负责“什么时候调”，lg-grid 负责“怎么排”

很多人听到“不依赖框架”会误以为“不能和框架一起用”，这是两码事。lg-grid 的设计目标恰恰是：在 React 里用起来像 React 组件，在 Vue 里用起来像 Vue 组件，但代码库里没有任何框架依赖。

要把这个平衡做好，核心原则只有一句话：框架的组件负责调用 lg-grid 的生命周期，lg-grid 不反向感知框架的存在。换句话说，React 的 useEffect 告诉我们“组件挂载了、可以初始化了”，Vue 的 onMounted 告诉我们“DOM 就绪了”，那么就在这些时机去 new LGGrid；框架的卸载钩子告诉我们“组件要没了”，那就调 destroy。lg-grid 完全不需要知道外面是 React 还是 Vue，它只管自己那一亩三分地。

5.2 React 适配：一个 15 行的自定义组件

下面这个 AutoGrid 组件说明了所有需要做的事：用 useRef 拿容器 DOM，用 useEffect 初始化实例，在卸载时销毁，在 children 变化时刷新布局。

jsx复制import { useEffect, useRef } from 'react';
import LGGrid from 'lg-grid';
import 'lg-grid/dist/lg-grid.css';

export default function AutoGrid({ children, minItemWidth = 120, gap = 12 }) {
  const rootRef = useRef(null);
  const gridRef = useRef(null);

  useEffect(() => {
    const grid = new LGGrid(rootRef.current, { minItemWidth, gap });
    gridRef.current = grid;
    return () => grid.destroy();
  }, [minItemWidth, gap]);

  useEffect(() => {
    gridRef.current?.refresh();
  }, [children]);

  return <div className="lg-grid" ref={rootRef}>{children}</div>;
}

这里最容易踩的坑是第二个 useEffect 的依赖问题。如果把 children 换成 props，那么任何一次父组件渲染都会触发 refresh，而 refresh 内部有宽度和数量双重缓存，一般不会造成性能灾难，但仍然不够优雅。监听 children 本身意味着只有当 React 重新渲染出的子元素数量或结构真正变化时，lg-grid 才会收到刷新指令。React 侧完全掌控了调用时机，lg-grid 只负责执行布局。

5.3 Vue 适配：setup 语法下的生命周期映射

Vue 3 的适配思路与 React 本质上一致，只是生命周期钩子名称不同。下面的封装放在业务项目里可以直接使用：

vue复制<script setup>
import { onMounted, onBeforeUnmount, ref, watch } from 'vue';
import LGGrid from 'lg-grid';
import 'lg-grid/dist/lg-grid.css';

const props = defineProps({
  minItemWidth: { type: Number, default: 120 },
  gap: { type: Number, default: 12 },
});

const root = ref(null);
let gridInstance = null;

onMounted(() => {
  gridInstance = new LGGrid(root.value, {
    minItemWidth: props.minItemWidth,
    gap: props.gap,
  });
});

onBeforeUnmount(() => {
  gridInstance?.destroy();
  gridInstance = null;
});

watch(() => root.value?.childElementCount, () => {
  gridInstance?.refresh();
});
</script>

<template>
  <div class="lg-grid" ref="root">
    <slot />
  </div>
</template>

有人可能会问：为什么不直接用 Vue 的响应式数据把子元素渲染逻辑也搬进 lg-grid？答案是没必要。lg-grid 只关心容器里的元素怎么排队，至于那些元素是 Vue 渲染的还是 jQuery 动态插进去的，它并不想管。这恰恰是“解除绑定”的价值：底层能力保持中立，上层业务想怎么组织就怎么组织。

5.4 不写适配也能用的高频场景：后台动态 HTML 与微前端

除了 React 和 Vue，lg-grid 还有一个让我自己都很意外的广泛用途：在微前端架构里，同一个壳页面可能混合了 React 子应用、Vue 子应用甚至原生子应用。如果宫格组件绑死框架，子应用之间根本没法共用。而 lg-grid 的原生属性让它可以被任何子应用里的任意一段 script 创建，实例之间互不干扰。

另一个高频场景是后台管理系统的表格筛选区。很多后端返回的筛选项数量不确定，有些筛选条件只在特定权限下出现。用传统 CSS 写死列数，筛选区在窄屏下会乱七八糟；lg-grid 挂上去后，只要容器里的每个筛选项都是一个 DOM 子元素，它就能自动排布，数据接口回来多少就排多少。

6. 实测中反复出现的四类问题与最终处理方案

6.1 隐藏容器与图片加载：两个最容易“白屏”的场景

开发 lg-grid 的过程中，我遇到最多的 bug 都和一个看起来无害的场景有关：容器刚初始化时是隐藏的。当容器 display: none 或有某个祖先元素 display: none 时，clientWidth 返回 0，布局函数会算出 0 列或 1 列，CSS Grid 渲染出来的结果自然就是一团乱。

最典型的是弹窗类组件：页面打开时弹窗还不显示，等用户点按钮弹出弹窗，里面的宫格已经初始化过了，宽度为 0 的瞬间所有格子挤成一列。解决这个问题有几个角度：lg-grid 本身在 render 中加入宽度为 0 早退逻辑；同时建议使用者在弹窗真正显示后再初始化组件。

第二类问题是图片加载造成的容器尺寸变化。格子里如果是纯文字，宽度通常不会突变；但格子里放图片时，图片加载前后可能把格子撑高，进而改变容器整体高度。虽然 lg-grid 的默认 CSS Grid 模式能自动处理行高变化，但在 abs 模式下，图片加载会导致格子底部重叠或者留白。

针对图片场景，一个非常实用的处理是给容器加一个 capture 阶段的 load 监听。图片的 load 事件不会冒泡，但监听器如果用 capture 方式挂在容器上，可以捕获到子图片的加载完成事件，进而触发一次 refresh：

javascript复制this.container.addEventListener('load', this.handleImageLoad, true);

这个问题的通用兜底手段是给图片容器设置固定高度，或者在图片外层用一个比例占位容器。但从库的角度，lg-grid 能做到的是：只要图片加载完成触发了 load，就重新测量一次并刷新布局。

6.2 ResizeObserver 的循环触发问题：靠宽度缓存化解

ResizeObserver 有一个让刚上手的人非常头疼的特性：如果你在回调里修改了被观察元素的尺寸，它又会触发新一轮回调，两轮之间没有任何自然间隔，操作不当就会形成无限循环。

lg-grid 的 render 开头就做了两次判断：一次是销毁标记，一次是宽度和子元素数量缓存。这意味着即使外部代码在 layout 事件回调里又改了容器宽度，第二轮 render 进来会直接命中缓存判断，提前返回。这就切断了“布局 → 改宽度 → 再布局 → 再改宽度”的死亡循环。

实践中我还额外建议：不要在 layout 事件回调里同步去操作引起容器尺寸变化的内容，比如往格子里塞一个很宽的图片。如果你确实需要这么做，请用 setTimeout 或下一帧再执行，让浏览器先稳定当前布局。

6.3 子节点变化监听的粒度：childList 和 attributes 要做取舍

前文已经说过 lg-grid 的 MutationObserver 只监听 childList，这里面其实有教训。最初版本我打开了 subtree 选项，结果一个格子内部的图片 src 变化、class 变化都来触发重排，布局计算被无效调用打满，页面在某些场景下明显卡顿。

正确做法是想清楚“哪些变化才是布局需要的”。lg-grid 认为只有一级子元素的数量变化才需要重算，子元素内部的任何状态变化都不是它该管的。如果真的需要根据子元素高度变化调整布局，应该由开发者显式调用 refresh()。库要做的事情是提供可靠的基线和手动出口，而不是用一堆自动监听把浏览器拖垮。

6.4 兼容性与体积自律：4KB 的克制

最后聊聊发布层面的取舍。lg-grid 的目标是能在各种环境中跑，因此它的构建产物需要同时支持现代浏览器脚本和普通 script 标签引入。发布物通常是一个 UMD 格式文件加一个 CSS 文件，不依赖 npm 生态也能独立下载使用。

代码体积方面，我给自己定的红线是压缩后不超过 5KB。这不是为了炫技，而是因为一旦库的定位是“任何项目都能接入”，代码每大 1KB，使用者心里的负担就重一分。为了守住体积，我砍掉了所有边缘功能，比如拖拽排序、动画插值、跨列支持，这些需求出现的时候，让开发者直接用函数回调或者社区插件去补，比在核心库里堆代码健康得多。

在构建 lg-grid 的过程中，我最大的感受是：组件库与框架的关系，不是谁必须依赖谁，而是谁能在合适的层次做合适的事。布局是一种底层能力，把它放在框架无关的 DOM 层，反而让它在 React 项目、Vue 项目、甚至完全没有框架的静态页面里都能活下来。如果你也在折腾自己的通用组件，不妨把“不绑框架”当作一个设计约束试试——它会逼你把接口想得更清楚，把生命周期管得更严，最后做出来的东西往往比一开始就长在某个框架里的组件更耐用。