react-public-components 1.1.15 → 1.1.17

package/README.md

@@ -2,11 +2,12 @@
 
 封装 react 常用的组件，欢迎更多同学提出大众化普遍存在的业务场景。
 
-本仓库包含三个独立的 React 组件：
+本仓库包含四个独立的 React 组件：
 
 1. **CollapseBox** — 可折叠的内容容器组件
 2. **Splitter** — 可拖拽调整、可折叠的分屏面板组件
 3. **DisabledBox** — 禁用态包装容器组件（带锁图标及拦截事件）
+4. **Masonry** — 瀑布流布局组件（一比一复刻 Ant Design V6 规范）
 
 ---
 
@@ -198,7 +199,65 @@ export default function Demo() {
 
 ---
 
-## 四、目录结构
+## 四、Masonry 瀑布流组件
+
+### 简介
+
+`Masonry` 是一个符合 Ant Design V6 规范的瀑布流布局组件。支持固定或响应式列数配置（`columns`）、水平垂直间距配置（`gutter`）、持续监听子项尺寸变化（`fresh`）、自定义语义化结构样式/类名（`styles`/`classNames`）以及列排序回调（`onLayoutChange`）。
+
+### 引入方式
+
+```tsx
+import { Masonry } from 'react-public-components';
+```
+
+### Masonry Props
+
+| 参数             | 说明                                         | 类型                                                                                                        | 默认值  |
+| ---------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------- |
+| `classNames`     | 自定义内部语义化结构 class，支持对象或函数   | `Record<'root' \| 'item', string> \| ((info: { props }) => Record<'root' \| 'item', string>)`               | `-`     |
+| `columns`        | 列数，固定数字或响应式配置                   | `number \| { xs?: number; sm?: number; md?: number; lg?: number; xl?: number; xxl?: number }`               | `3`     |
+| `fresh`          | 是否持续监听子项尺寸变化                     | `boolean`                                                                                                   | `false` |
+| `gutter`         | 间距，固定数字、响应式配置或水平垂直间距配置 | `Gap \| [Gap, Gap]`                                                                                         | `0`     |
+| `items`          | 瀑布流数据项                                 | `MasonryItem[]`                                                                                             | `-`     |
+| `itemRender`     | 自定义数据项渲染函数                         | `(item: MasonryItem) => ReactNode`                                                                          | `-`     |
+| `styles`         | 语义化结构 style，支持对象和函数形式         | `Record<'root' \| 'item', CSSProperties> \| ((info: { props }) => Record<'root' \| 'item', CSSProperties>)` | `-`     |
+| `onLayoutChange` | 列排序计算完成回调                           | `(layout: { key: React.Key; column: number }[]) => void`                                                    | `-`     |
+
+### MasonryItem 属性
+
+| 参数       | 说明                                             | 类型               | 默认值 |
+| ---------- | ------------------------------------------------ | ------------------ | ------ |
+| `children` | 自定义展示内容，相对 `itemRender` 具有更高优先级 | `ReactNode`        | `-`    |
+| `column`   | 自定义指定放置列（0-indexed）                    | `number`           | `-`    |
+| `data`     | 自定义存储数据                                   | `T`                | `-`    |
+| `height`   | 高度（手指定时优先使用）                         | `number`           | `-`    |
+| `key`      | 唯一标识                                         | `string \| number` | `-`    |
+
+### 基础用法
+
+```tsx
+import { Masonry } from 'react-public-components';
+
+export default function Demo() {
+	return (
+		<Masonry
+			columns={{ xs: 1, sm: 2, md: 3, lg: 4 }}
+			gutter={[16, 16]}
+			fresh={true}
+			items={[
+				{ key: '1', height: 120, children: <div>卡片 1</div> },
+				{ key: '2', height: 180, children: <div>卡片 2</div> },
+				{ key: '3', height: 150, children: <div>卡片 3</div> },
+			]}
+		/>
+	);
+}
+```
+
+---
+
+## 五、目录结构
 
 ```
 .
@@ -207,14 +266,17 @@ export default function Demo() {
 │   └── index.less
 ├── Splitter/
 │   └── index.tsx
-└── DisabledBox/
+├── DisabledBox/
+│   ├── index.tsx
+│   └── index.less
+└── Masonry/
     ├── index.tsx
     └── index.less
 ```
 
 ---
 
-## 五、发布到 npm
+## 六、发布到 npm
 
 ### 1. 前置准备
 

package/dist/index.cjs

@@ -32,6 +32,7 @@ var index_exports = {};
 __export(index_exports, {
   CollapseBox: () => CollapseBox_default,
   DisabledBox: () => DisabledBox_default,
+  Masonry: () => Masonry_default,
   Splitter: () => Splitter_default
 });
 module.exports = __toCommonJS(index_exports);
@@ -630,7 +631,8 @@ var CustomSplitter = (props) => {
                 boxSizing: "border-box",
                 display: isHidden ? "none" : "block",
                 height: "100%",
-                overflow: "auto",
+                overflowX: "hidden",
+                overflowY: "auto",
                 padding: ((_e = sizes[index]) != null ? _e : 0) < 32 ? 0 : 16,
                 width: "100%"
               },
@@ -864,10 +866,252 @@ var DisabledBox = (props) => {
   );
 };
 var DisabledBox_default = DisabledBox;
+
+// Masonry/index.tsx
+var import_react3 = __toESM(require("react"), 1);
+var import_jsx_runtime5 = require("react/jsx-runtime");
+var BREAKPOINT_ORDER = ["xs", "sm", "md", "lg", "xl", "xxl"];
+function getBreakpoint(width) {
+  if (width >= 1600) return "xxl";
+  if (width >= 1200) return "xl";
+  if (width >= 992) return "lg";
+  if (width >= 768) return "md";
+  if (width >= 576) return "sm";
+  return "xs";
+}
+function resolveResponsiveValue(value, currentBp, defaultValue) {
+  if (value === void 0 || value === null) return defaultValue;
+  if (typeof value === "object") {
+    const obj = value;
+    if (obj[currentBp] !== void 0) return obj[currentBp];
+    const currentIdx = BREAKPOINT_ORDER.indexOf(currentBp);
+    for (let i = currentIdx - 1; i >= 0; i--) {
+      const bp = BREAKPOINT_ORDER[i];
+      if (obj[bp] !== void 0) return obj[bp];
+    }
+    for (let i = currentIdx + 1; i < BREAKPOINT_ORDER.length; i++) {
+      const bp = BREAKPOINT_ORDER[i];
+      if (obj[bp] !== void 0) return obj[bp];
+    }
+    return defaultValue;
+  }
+  return value;
+}
+function resolveGutter(gutter, currentBp) {
+  if (!gutter) return [0, 0];
+  if (Array.isArray(gutter)) {
+    const h = resolveResponsiveValue(gutter[0], currentBp, 0);
+    const v = resolveResponsiveValue(gutter[1], currentBp, 0);
+    return [h, v];
+  }
+  const g = resolveResponsiveValue(gutter, currentBp, 0);
+  return [g, g];
+}
+var Masonry = (props) => {
+  const {
+    classNames,
+    columns = 3,
+    fresh = false,
+    gutter = 0,
+    items,
+    itemRender,
+    styles,
+    onLayoutChange,
+    className,
+    style,
+    children
+  } = props;
+  const rootRef = (0, import_react3.useRef)(null);
+  const [containerWidth, setContainerWidth] = (0, import_react3.useState)(0);
+  const [measuredHeights, setMeasuredHeights] = (0, import_react3.useState)({});
+  const itemRefs = (0, import_react3.useRef)(/* @__PURE__ */ new Map());
+  const normalizedItems = (0, import_react3.useMemo)(() => {
+    if (items) return items;
+    if (!children) return [];
+    return import_react3.default.Children.toArray(children).map((child, index) => {
+      var _a;
+      if (import_react3.default.isValidElement(child)) {
+        const key = (_a = child.key) != null ? _a : `masonry-item-${index}`;
+        return {
+          key,
+          children: child
+        };
+      }
+      return {
+        key: `masonry-item-${index}`,
+        children: child
+      };
+    });
+  }, [items, children]);
+  const currentBreakpoint = (0, import_react3.useMemo)(() => getBreakpoint(containerWidth), [containerWidth]);
+  const resolvedColumns = (0, import_react3.useMemo)(() => {
+    const count = resolveResponsiveValue(columns, currentBreakpoint, 3);
+    return Math.max(1, Math.floor(count));
+  }, [columns, currentBreakpoint]);
+  const [horizontalGap, verticalGap] = (0, import_react3.useMemo)(
+    () => resolveGutter(gutter, currentBreakpoint),
+    [gutter, currentBreakpoint]
+  );
+  (0, import_react3.useEffect)(() => {
+    if (!rootRef.current) return;
+    const observer = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        const width = entry.contentRect.width;
+        if (width > 0) {
+          setContainerWidth(width);
+        }
+      }
+    });
+    observer.observe(rootRef.current);
+    return () => observer.disconnect();
+  }, []);
+  const measureItems = (0, import_react3.useCallback)(() => {
+    let hasChange = false;
+    const newHeights = {};
+    itemRefs.current.forEach((el, key) => {
+      if (el) {
+        const strKey = String(key);
+        const h = el.offsetHeight;
+        if (h > 0) {
+          newHeights[strKey] = h;
+          if (measuredHeights[strKey] !== h) {
+            hasChange = true;
+          }
+        }
+      }
+    });
+    if (hasChange) {
+      setMeasuredHeights((prev) => ({ ...prev, ...newHeights }));
+    }
+  }, [measuredHeights]);
+  (0, import_react3.useLayoutEffect)(() => {
+    const handle = requestAnimationFrame(() => {
+      measureItems();
+    });
+    return () => cancelAnimationFrame(handle);
+  }, [measureItems]);
+  (0, import_react3.useEffect)(() => {
+    if (!fresh) return;
+    const observer = new ResizeObserver(() => {
+      measureItems();
+    });
+    itemRefs.current.forEach((el) => {
+      if (el) observer.observe(el);
+    });
+    return () => observer.disconnect();
+  }, [fresh, measureItems, normalizedItems]);
+  const columnWidth = (0, import_react3.useMemo)(() => {
+    if (containerWidth <= 0) return 0;
+    const totalGap = (resolvedColumns - 1) * horizontalGap;
+    return Math.max(0, (containerWidth - totalGap) / resolvedColumns);
+  }, [containerWidth, resolvedColumns, horizontalGap]);
+  const { layoutItems, containerHeight, layoutChangeData } = (0, import_react3.useMemo)(() => {
+    const colHeights = new Array(resolvedColumns).fill(0);
+    const changeData = [];
+    const computedList = normalizedItems.map((item) => {
+      var _a, _b;
+      const h = (_b = (_a = item.height) != null ? _a : measuredHeights[String(item.key)]) != null ? _b : 0;
+      let targetCol = 0;
+      if (typeof item.column === "number" && item.column >= 0 && item.column < resolvedColumns) {
+        targetCol = Math.floor(item.column);
+      } else {
+        let minH = colHeights[0];
+        for (let i = 1; i < resolvedColumns; i++) {
+          if (colHeights[i] < minH) {
+            minH = colHeights[i];
+            targetCol = i;
+          }
+        }
+      }
+      const left = targetCol * (columnWidth + horizontalGap);
+      const top = colHeights[targetCol];
+      colHeights[targetCol] += h + (h > 0 ? verticalGap : 0);
+      changeData.push({ key: item.key, column: targetCol });
+      return {
+        item,
+        left,
+        top,
+        width: columnWidth,
+        height: h,
+        column: targetCol
+      };
+    });
+    const totalH = Math.max(0, ...colHeights);
+    return {
+      layoutItems: computedList,
+      containerHeight: totalH,
+      layoutChangeData: changeData
+    };
+  }, [normalizedItems, resolvedColumns, horizontalGap, verticalGap, columnWidth, measuredHeights]);
+  const prevLayoutRef = (0, import_react3.useRef)("");
+  (0, import_react3.useEffect)(() => {
+    const layoutKey = JSON.stringify(layoutChangeData);
+    if (layoutKey !== prevLayoutRef.current) {
+      prevLayoutRef.current = layoutKey;
+      onLayoutChange == null ? void 0 : onLayoutChange(layoutChangeData);
+    }
+  }, [layoutChangeData, onLayoutChange]);
+  const semanticClassNames = (0, import_react3.useMemo)(() => {
+    var _a;
+    if (typeof classNames === "function") {
+      return (_a = classNames({ props })) != null ? _a : {};
+    }
+    return classNames != null ? classNames : {};
+  }, [classNames, props]);
+  const semanticStyles = (0, import_react3.useMemo)(() => {
+    var _a;
+    if (typeof styles === "function") {
+      return (_a = styles({ props })) != null ? _a : {};
+    }
+    return styles != null ? styles : {};
+  }, [styles, props]);
+  return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(
+    "div",
+    {
+      ref: rootRef,
+      className: ["masonry_root", semanticClassNames.root, className].filter(Boolean).join(" "),
+      style: {
+        minHeight: containerHeight > 0 ? containerHeight : void 0,
+        height: containerHeight > 0 ? containerHeight : void 0,
+        ...semanticStyles.root,
+        ...style
+      },
+      children: layoutItems.map(({ item, left, top, width, height }) => {
+        var _a;
+        const content = (_a = item.children) != null ? _a : itemRender == null ? void 0 : itemRender(item);
+        return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(
+          "div",
+          {
+            ref: (node) => {
+              if (node) {
+                itemRefs.current.set(item.key, node);
+              } else {
+                itemRefs.current.delete(item.key);
+              }
+            },
+            className: ["masonry_item", semanticClassNames.item].filter(Boolean).join(" "),
+            style: {
+              width: containerWidth > 0 ? width : "100%",
+              height: height > 0 ? height : void 0,
+              transform: containerWidth > 0 ? `translate3d(${left}px, ${top}px, 0)` : void 0,
+              opacity: containerWidth > 0 ? 1 : 0,
+              ...semanticStyles.item
+            },
+            onLoad: measureItems,
+            children: content
+          },
+          item.key
+        );
+      })
+    }
+  );
+};
+var Masonry_default = Masonry;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CollapseBox,
   DisabledBox,
+  Masonry,
   Splitter
 });
 //# sourceMappingURL=index.cjs.map