sard-uniapp 1.20.2 → 1.21.0

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+# [1.21.0](https://github.com/sutras/sard-uniapp/compare/v1.20.2...v1.21.0) (2025-07-04)
+
+
+### Bug Fixes
+
+* upload组件修改beforeChoose，多返回一个参数sourceType，用于区分当前选择项 ([d440c7e](https://github.com/sutras/sard-uniapp/commit/d440c7e166db4987507e642bda8d3fb6aa2a4c9b))
+* 修复 fab 图标设置失败问题 ([da00f11](https://github.com/sutras/sard-uniapp/commit/da00f11ce8cd19ab712572d106ce94856739a228))
+
+
+### Features
+
+* list 新增隐藏边框属性 ([6fbab69](https://github.com/sutras/sard-uniapp/commit/6fbab69ad4e637bc1bb12dea360e12413e398c74))
+* upload组件选择前置允许配置 ([5f2a753](https://github.com/sutras/sard-uniapp/commit/5f2a7538f985a85226e52c19aa11699fa1c6aa9f))
+* 新增瀑布流组件 ([8da700b](https://github.com/sutras/sard-uniapp/commit/8da700b367a63725f074d4431ac72e26b3e64cae))
+
+
+
 ## [1.20.2](https://github.com/sutras/sard-uniapp/compare/v1.20.1...v1.20.2) (2025-07-02)
 
 

package/README.md

@@ -25,7 +25,7 @@
 
 ## 特性
 
-- 🧩 95+个高质量组件，覆盖移动端主流场景
+- 🧩 96+个高质量组件，覆盖移动端主流场景
 - 💪 支持一套代码同时开发 H5 / 小程序 / App
 - 🌿 支持按需引入和 `Tree Shaking`
 - 📖 详尽的文档和案例展示
@@ -49,7 +49,8 @@
 ### 前提条件
 
 - 确保 node >= 20
-- 建议使用 pnpm
+- 建议使用 pnpm 包管理器
+- 建议使用 vscode 编辑器
 
 ### 克隆仓库到本地
 

package/components/config/index.d.ts

@@ -479,6 +479,11 @@ export declare const defaultConfig: {
     uploadPreview: {
         status: UploadPreviewProps["status"];
     };
+    waterfall: {
+        columns: number;
+        columnGap: number;
+        rowGap: number;
+    };
 };
 export type ConfigOptions = typeof defaultConfig;
 export declare function setConfig(...optionsArgs: DeepPartial<ConfigOptions>[]): void;

package/components/config/index.js

@@ -433,6 +433,11 @@ export const defaultConfig = {
     uploadPreview: {
         status: 'pending',
     },
+    waterfall: {
+        columns: 2,
+        columnGap: 16,
+        rowGap: 16,
+    },
 };
 function extendProps(source, target) {
     Object.keys(target).forEach((key) => {

package/components/fab/README.md

@@ -60,6 +60,12 @@ import Fab from 'sard-uniapp/components/fab/fab.vue'
 
 @code('${DEMO_PATH}/fab/demo/NonItemList.vue')
 
+### 自定义图标
+
+使用 `icon` 和 `icon-family` 可自定义悬浮按钮图标。
+
+@code('${DEMO_PATH}/fab/demo/Icon.vue')
+
 ## API
 
 ### FabProps

package/components/fab/fab.vue

@@ -33,7 +33,7 @@
     </view>
     <view :class="itemEntryClass" @click="onItemEntryClick">
       <view :class="bem.e('item-btn')" :style="itemEntryBtnStyle">
-        <sar-icon family="sari" name="plus" />
+        <sar-icon :family="iconFamily || 'sari'" :name="icon || 'plus'" />
       </view>
     </view>
   </view>

package/components/list/README.md

@@ -32,15 +32,15 @@ import ListItem from 'sard-uniapp/components/list-item/list-item.vue'
 
 ### 图标
 
-设置`icon`属性或插槽可以在左边显示图标。
+设置 `icon` 属性或插槽可以在左边显示图标。
 
 @code('${DEMO_PATH}/list/demo/Icon.vue')
 
 ### 自定义内容
 
-列表项的`body`和`footer`默认平分水平空间，如果`footer`需要占据更多的空间，可以设置`body`不扩展。
+列表项的 `body` 和 `footer` 默认平分水平空间，如果 `footer` 需要占据更多的空间，可以设置 `body` 不扩展。
 
-`value`中的元素默认会向右边靠，如果有使用`footer`属性定义内容，则内容会纵向排列。
+`value` 中的元素默认会向右边靠，如果有使用 `footer` 属性定义内容，则内容会纵向排列。
 
 @code('${DEMO_PATH}/list/demo/Slot.vue')
 
@@ -52,22 +52,29 @@ import ListItem from 'sard-uniapp/components/list-item/list-item.vue'
 
 ### 卡片风格
 
-可以使用`card`属性让列表显示为卡片风格。
+可以使用 `card` 属性让列表显示为卡片风格。
 
 @code('${DEMO_PATH}/list/demo/Card.vue')
 
+### 隐藏边框 <sup>1.21.0+</sup>
+
+可以使用 `hide-border` 属性隐藏边框。
+
+@code('${DEMO_PATH}/list/demo/HideBorder.vue')
+
 ## API
 
 ### ListProps
 
-| 属性        | 描述           | 类型             | 默认值 |
-| ----------- | -------------- | ---------------- | ------ |
-| root-class  | 组件根元素类名 | string           | -      |
-| root-style  | 组件根元素样式 | StyleValue       | -      |
-| title       | 列表顶部标题   | string \| number | -      |
-| description | 列表底部描述   | string \| number | -      |
-| card        | 卡片风格       | boolean          | false  |
-| inlaid      | 嵌入式列表     | boolean          | false  |
+| 属性                           | 描述           | 类型             | 默认值 |
+| ------------------------------ | -------------- | ---------------- | ------ |
+| root-class                     | 组件根元素类名 | string           | -      |
+| root-style                     | 组件根元素样式 | StyleValue       | -      |
+| title                          | 列表顶部标题   | string \| number | -      |
+| description                    | 列表底部描述   | string \| number | -      |
+| card                           | 卡片风格       | boolean          | false  |
+| inlaid                         | 嵌入式列表     | boolean          | false  |
+| hide-border <sup>1.21.0+</sup> | 是否隐藏边框   | boolean          | false  |
 
 ### ListSlots
 

package/components/list/common.d.ts

@@ -1,4 +1,4 @@
-import { type StyleValue } from 'vue';
+import { InjectionKey, type StyleValue } from 'vue';
 export interface ListProps {
     rootStyle?: StyleValue;
     rootClass?: string;
@@ -6,6 +6,7 @@ export interface ListProps {
     description?: string | number;
     inlaid?: boolean;
     card?: boolean;
+    hideBorder?: boolean;
 }
 export interface ListSlots {
     default?(props: Record<string, never>): any;
@@ -40,3 +41,7 @@ export interface ListItemSlots {
     arrow?(props: Record<string, never>): any;
     icon?(props: Record<string, never>): any;
 }
+export interface ListContext {
+    hideBorder?: boolean;
+}
+export declare const listContextKey: InjectionKey<ListContext>;

package/components/list/common.js

@@ -1,2 +1,3 @@
 import { defaultConfig } from '../config';
 export const defaultListItemProps = defaultConfig.listItem;
+export const listContextKey = Symbol('list-context');

package/components/list/index.scss

@@ -24,6 +24,14 @@
     }
   }
 
+  @include m(borderless) {
+    @include e(content) {
+      &::before {
+        display: none;
+      }
+    }
+  }
+
   @include e(description) {
     @include universal;
     margin-left: var(--sar-list-description-margin-x);

package/components/list/list.vue

@@ -17,13 +17,14 @@
 
 <script>
 import { defineComponent as _defineComponent } from "vue";
-import { computed } from "vue";
+import { computed, provide, reactive, toRef } from "vue";
 import {
   classNames,
   stringifyStyle,
   isRenderVisible,
   createBem
 } from "../../utils";
+import { listContextKey } from "./common";
 /**
  * @property {string} rootClass 组件根元素类名，默认值：-。
  * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
@@ -31,6 +32,7 @@ import {
  * @property {string | number} description 列表底部描述，默认值：-。
  * @property {boolean} card 卡片风格，默认值：false。
  * @property {boolean} inlaid 嵌入式列表，默认值：false。
+ * @property {boolean} hideBorder 是否隐藏边框，默认值：false。
  */
 export default  _defineComponent({
   ...{
@@ -46,18 +48,26 @@ export default  _defineComponent({
     title: { type: [String, Number], required: false },
     description: { type: [String, Number], required: false },
     inlaid: { type: Boolean, required: false },
-    card: { type: Boolean, required: false }
+    card: { type: Boolean, required: false },
+    hideBorder: { type: Boolean, required: false }
   },
   setup(__props, { expose: __expose }) {
     __expose();
     const props = __props;
     const bem = createBem("list");
+    provide(
+      listContextKey,
+      reactive({
+        hideBorder: toRef(() => props.hideBorder)
+      })
+    );
     const listClass = computed(() => {
       return classNames(
         bem.b(),
         bem.m("card", props.card),
         bem.m("not-card", !props.card),
         bem.m("inlaid", props.inlaid),
+        bem.m("borderless", props.hideBorder),
         props.rootClass
       );
     });

package/components/list-item/index.scss

@@ -26,6 +26,12 @@
       right: var(--sar-list-item-padding-x);
     }
 
+    @include m(borderless) {
+      &::before {
+        display: none;
+      }
+    }
+
     &:first-child::before {
       display: none;
     }

package/components/list-item/list-item.vue

@@ -42,7 +42,7 @@
 
 <script>
 import { useSlots as _useSlots, mergeDefaults as _mergeDefaults, defineComponent as _defineComponent } from "vue";
-import { computed } from "vue";
+import { computed, inject } from "vue";
 import {
   classNames,
   stringifyStyle,
@@ -51,7 +51,8 @@ import {
 } from "../../utils";
 import SarIcon from "../icon/icon.vue";
 import {
-  defaultListItemProps
+  defaultListItemProps,
+  listContextKey
 } from "../list/common";
 /**
  * @property {string} rootClass 组件根元素类名，默认值：-。
@@ -100,6 +101,7 @@ export default  _defineComponent({
     const slots = _useSlots();
     const emit = __emit;
     const bem = createBem("list-item");
+    const context = inject(listContextKey);
     const onClick = (event) => {
       emit("click", event);
     };
@@ -108,10 +110,11 @@ export default  _defineComponent({
         bem.b(),
         bem.m("hover", props.hover),
         bem.m("custom", !!slots.default),
+        bem.m("borderless", context?.hideBorder),
         props.rootClass
       );
     });
-    const __returned__ = { props, slots, emit, bem, onClick, listItemClass, get stringifyStyle() {
+    const __returned__ = { props, slots, emit, bem, context, onClick, listItemClass, get stringifyStyle() {
       return stringifyStyle;
     }, get isRenderVisible() {
       return isRenderVisible;

package/components/locale/lang/en-US.js

@@ -91,7 +91,7 @@ export default {
         },
     },
     loadMore: {
-        incompleteText: 'Load more',
+        incompleteText: 'Click to load more',
         loadingText: 'Loading...',
         errorText: 'Request failed. Click to reload',
         completeText: 'No more',

package/components/locale/lang/zh-CN.js

@@ -91,7 +91,7 @@ export default {
         },
     },
     loadMore: {
-        incompleteText: '加载更多',
+        incompleteText: '点击加载更多',
         loadingText: '加载中...',
         completeText: '没有更多了',
         errorText: '请求失败，点击重新加载',

package/components/upload/README.md

@@ -43,7 +43,7 @@ import Upload from 'sard-uniapp/components/upload/upload.vue'
 
 ### 选择文件前置处理 <sup>1.19.2+</sup>
 
-通过传入 `beforeChoose` 函数可以在选择之前做处理，接受当前文件列表和 `next` 函数作参数，调用 `next(true)` 允许选择，调用 `next(false)` 不允许选择。
+通过传入 `beforeChoose` 函数可以在选择之前做处理，接受当前文件列表和 `next` 函数作参数，调用 `next(true)` 允许选择，调用 `next(false)` 不允许选择，也可传入一个配置对象自定义选择。
 
 @code('${DEMO_PATH}/upload/demo/BeforeChoose.vue')
 
@@ -87,28 +87,36 @@ import Upload from 'sard-uniapp/components/upload/upload.vue'
 
 ### UploadProps
 
-| 属性                             | 描述                                                                                                              | 类型                                                                   | 默认值                     |
-| -------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | -------------------------- |
-| root-class                       | 组件根元素类名                                                                                                    | string                                                                 | -                          |
-| root-style                       | 组件根元素样式                                                                                                    | StyleValue                                                             | -                          |
-| accept                           | 允许上传的文件类型                                                                                                | 'image' \| 'video'                                                     | 'image'                    |
-| multiple                         | 是否开启图片多选                                                                                                  | boolean                                                                | false                      |
-| source-type                      | 文件选择来源                                                                                                      | ('album' \| 'camera')[]                                                | ['album', 'camera']        |
-| size-type                        | 所选的图片的尺寸                                                                                                  | ('original' \| 'compressed')[]                                         | ['original', 'compressed'] |
-| max-duration                     | 拍摄视频最长拍摄时间，单位秒                                                                                      | number                                                                 | 60                         |
-| camera                           | 默认拉起的是前置或者后置摄像头。部分 Android 手机下由于系统 ROM 不支持无法生效                                    | 'back' \| 'front'                                                      | 'back'                     |
-| model-value (v-model)            | 已上传的文件列表                                                                                                  | UploadFileItem[]                                                       | -                          |
-| max-count                        | 文件上传数量限制                                                                                                  | number                                                                 | Number.MAX_SAFE_INTEGER    |
-| max-size                         | 文件大小限制，单位为 `byte`                                                                                       | number \| ((file: File) => boolean)                                    | Number.MAX_SAFE_INTEGER    |
-| over-size                        | 文件大小超过限制时触发                                                                                            | (fileItem: UploadFileItem \| UploadFileItem[]) => void                 | -                          |
-| disabled                         | 是否禁用文件上传                                                                                                  | boolean                                                                | false                      |
-| readonly                         | 是否将上传区域设置为只读状态                                                                                      | boolean                                                                | false                      |
-| before-choose <sup>1.19.2+</sup> | 文件选择前的回调，接受当前文件列表和 `next` 函数作参数，调用 `next(true)` 允许选择，调用 `next(false)` 不允许选择 | (fileList: UploadFileItem[], next: (allowed: boolean) => void) => void | -                          |
-| before-read                      | 文件读取前的回调，返回 false 可终止文件读取，支持返回 Promise                                                     | (file: File) => boolean \| Promise\<File>                              | -                          |
-| after-read                       | 文件读取完成后的回调                                                                                              | (fileItem: UploadFileItem \| UploadFileItem[]) => void                 | -                          |
-| removable                        | 是否可删除                                                                                                        | boolean                                                                | true                       |
-| before-remove                    | 文件删除前的回调，返回 false 可终止文件删除，支持返回 Promise                                                     | (index: number, fileItem: UploadFileItem) => boolean \| Promise\<any>  | -                          |
-| validate-event                   | 是否触发表单验证                                                                                                  | boolean                                                                | true                       |
+| 属性                             | 描述                                                                                                                                              | 类型                                                                                          | 默认值                     |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | -------------------------- |
+| root-class                       | 组件根元素类名                                                                                                                                    | string                                                                                        | -                          |
+| root-style                       | 组件根元素样式                                                                                                                                    | StyleValue                                                                                    | -                          |
+| accept                           | 允许上传的文件类型                                                                                                                                | 'image' \| 'video'                                                                            | 'image'                    |
+| multiple                         | 是否开启图片多选                                                                                                                                  | boolean                                                                                       | false                      |
+| source-type                      | 文件选择来源                                                                                                                                      | ('album' \| 'camera')[]                                                                       | ['album', 'camera']        |
+| size-type                        | 所选的图片的尺寸                                                                                                                                  | ('original' \| 'compressed')[]                                                                | ['original', 'compressed'] |
+| max-duration                     | 拍摄视频最长拍摄时间，单位秒                                                                                                                      | number                                                                                        | 60                         |
+| camera                           | 默认拉起的是前置或者后置摄像头。部分 Android 手机下由于系统 ROM 不支持无法生效                                                                    | 'back' \| 'front'                                                                             | 'back'                     |
+| model-value (v-model)            | 已上传的文件列表                                                                                                                                  | UploadFileItem[]                                                                              | -                          |
+| max-count                        | 文件上传数量限制                                                                                                                                  | number                                                                                        | Number.MAX_SAFE_INTEGER    |
+| max-size                         | 文件大小限制，单位为 `byte`                                                                                                                       | number \| ((file: File) => boolean)                                                           | Number.MAX_SAFE_INTEGER    |
+| over-size                        | 文件大小超过限制时触发                                                                                                                            | (fileItem: UploadFileItem \| UploadFileItem[]) => void                                        | -                          |
+| disabled                         | 是否禁用文件上传                                                                                                                                  | boolean                                                                                       | false                      |
+| readonly                         | 是否将上传区域设置为只读状态                                                                                                                      | boolean                                                                                       | false                      |
+| before-choose <sup>1.19.2+</sup> | 文件选择前的回调，接受当前文件列表和 `next` 函数作参数，调用 `next(true)` 允许选择，调用 `next(false)` 不允许选择，或者传入一个配置对象自定义选择 | (fileList: UploadFileItem[], next: (allowed: boolean \| UploadSelectOptions) => void) => void | -                          |
+| before-read                      | 文件读取前的回调，返回 false 可终止文件读取，支持返回 Promise                                                                                     | (file: File) => boolean \| Promise\<File>                                                     | -                          |
+| after-read                       | 文件读取完成后的回调                                                                                                                              | (fileItem: UploadFileItem \| UploadFileItem[]) => void                                        | -                          |
+| removable                        | 是否可删除                                                                                                                                        | boolean                                                                                       | true                       |
+| before-remove                    | 文件删除前的回调，返回 false 可终止文件删除，支持返回 Promise                                                                                     | (index: number, fileItem: UploadFileItem) => boolean \| Promise\<any>                         | -                          |
+| validate-event                   | 是否触发表单验证                                                                                                                                  | boolean                                                                                       | true                       |
+
+### UploadSelectOptions <sup>1.21.0+</sup>
+
+```ts
+interface UploadSelectOptions {
+  sourceType?: ('album' | 'camera')[]
+}
+```
 
 ### UploadSlots
 

package/components/upload/common.d.ts

@@ -20,6 +20,9 @@ export interface UploadFileItem {
     message?: string;
     [key: PropertyKey]: any;
 }
+export interface UploadSelectOptions {
+    sourceType?: ('album' | 'camera')[];
+}
 export interface UploadProps {
     rootStyle?: StyleValue;
     rootClass?: string;
@@ -35,7 +38,7 @@ export interface UploadProps {
     overSize?: (fileItem: UploadFileItem[]) => void;
     disabled?: boolean;
     readonly?: boolean;
-    beforeChoose?: (fileList: UploadFileItem[], next: (allowed: boolean) => void) => void;
+    beforeChoose?: (fileList: UploadFileItem[], next: (allowed: boolean | UploadSelectOptions) => void) => void;
     beforeRead?: (file: UploadFile) => boolean | Promise<UploadFile>;
     afterRead?: (fileItem: UploadFileItem) => void;
     removable?: boolean;

package/components/upload/upload.vue

@@ -69,7 +69,7 @@ import { useFormContext, useFormItemContext } from "../form/common";
  * @property {(fileItem: UploadFileItem | UploadFileItem[]) => void} overSize 文件大小超过限制时触发，默认值：-。
  * @property {boolean} disabled 是否禁用文件上传，默认值：false。
  * @property {boolean} readonly 是否将上传区域设置为只读状态，默认值：false。
- * @property {(fileList: UploadFileItem[], next: (allowed: boolean) => void) => void} beforeChoose 文件选择前的回调，接受当前文件列表和 `next` 函数作参数，调用 `next(true)` 允许选择，调用 `next(false)` 不允许选择，默认值：-。
+ * @property {(fileList: UploadFileItem[], next: (allowed: boolean | UploadSelectOptions) => void) => void} beforeChoose 文件选择前的回调，接受当前文件列表和 `next` 函数作参数，调用 `next(true)` 允许选择，调用 `next(false)` 不允许选择，或者传入一个配置对象自定义选择，默认值：-。
  * @property {(file: File) => boolean | Promise\<File>} beforeRead 文件读取前的回调，返回 false 可终止文件读取，支持返回 Promise，默认值：-。
  * @property {(fileItem: UploadFileItem | UploadFileItem[]) => void} afterRead 文件读取完成后的回调，默认值：-。
  * @property {boolean} removable 是否可删除，默认值：true。
@@ -233,12 +233,12 @@ export default  _defineComponent({
       if (isSelectPending || isDisabled.value || isReadonly.value || innerValue.value.length >= props.maxCount) {
         return;
       }
-      const next = () => {
+      const next = (options = {}) => {
         chooseMedia({
           mediaType: props.accept,
           count: props.multiple ? 9999 : 1,
           sizeType: props.sizeType,
-          sourceType: props.sourceType,
+          sourceType: options.sourceType || props.sourceType,
           maxDuration: props.maxDuration,
           camera: props.camera,
           success(result) {
@@ -264,7 +264,7 @@ export default  _defineComponent({
         props.beforeChoose?.(innerValue.value, (allowed) => {
           isSelectPending = false;
           if (allowed) {
-            next();
+            next(typeof allowed === "object" ? allowed : void 0);
           }
         });
       } else {

package/components/waterfall/README.md

@@ -0,0 +1,162 @@
+---
+nav: 组件
+title: Waterfall
+subtitle: 瀑布流
+group: 布局
+version: 1.21.0+
+---
+
+## 介绍
+
+按照元素高度自适应排列，形成参差不齐的多列布局。
+
+## 引入
+
+```ts
+import Waterfall from 'sard-uniapp/components/waterfall/waterfall.vue'
+```
+
+## 代码演示
+
+### 基础使用
+
+瀑布流布局是使用绝对定位实现的，每一项内容需放置在 `WaterfallItem` 组件里面以便控制其位置；可放置任意内容，并不限定为具体模板。
+
+如果里面包含图片或其他使其在挂载后仍然不确定高度的组件时，需在加载完后调用瀑布流项的 `load` 插槽中的 `onLoad` 回调，以便计算其渲染后的高度并进行准确定位。
+
+瀑布流会按照渲染的顺序逐一将加载好的瀑布流项渲染出来；如果后面比前面要先加载完，也得等前面加载完才能渲染。因此，如果前面有一张很大的图片需要很久才能加载完，则会堵塞后面的渲染。
+
+因此，一次性不要加载太多图片，图片的尺寸也要有所限制。
+
+瀑布流组件的 `load` 事件会在所有项都加载完后触发，可以用来处理加载状态。
+
+@code('${DEMO_PATH}/waterfall/demo/Basic.vue')
+
+`SimulatedImage.vue`
+
+@code('${DEMO_PATH}/waterfall/demo/SimulatedImage.vue')
+
+### 已知宽高
+
+如果接口已将图片宽高信息返回，可以使用 `WaterfallLoad` 组件处理 `onLoad` 回调，会在挂载时调用，无需等待图片加载完即可渲染，可极大提高用户体验。
+
+`WaterfallLoad` 会根据 `width`、`height` 属性计算占用的空间。
+
+@code('${DEMO_PATH}/waterfall/demo/KnownSize.vue')
+
+### 真实案例
+
+需同时监听 `image` 组件的 `load` 和 `error` 事件，确保 `onLoad` 回调函数能调用，无论图片加载成功或失败。
+
+@code('${DEMO_PATH}/waterfall/demo/TrueCase.vue')
+
+### 最大等待时间
+
+为了避免因图片太大导致渲染阻塞，`WaterfallLoad` 组件提供了 `max-wait` 属性，在超过等待时间后取自定义的宽高进行渲染，无需等待图片加载完；加载时间小于等待时间时，则取图片实际的宽高进行渲染。
+
+宽高只用于计算比例来进行等比缩放，而不是最终的展示尺寸。
+
+@code('${DEMO_PATH}/waterfall/demo/MaxWait.vue')
+
+### 大图
+
+可使用 `column-gap` 和 `row-gap` 设置瀑布流项的间隔大小，单位为 px。
+
+@code('${DEMO_PATH}/waterfall/demo/BigImage.vue')
+
+### 自定义列数
+
+可使用 `columns` 属性设置任意的列数。
+
+@code('${DEMO_PATH}/waterfall/demo/Columns.vue')
+
+### 结合下拉刷新与触底加载
+
+可配合 `LoadMore` 和 `PullDownRefresh` 组件实现数据动态增减。
+
+因瀑布流在数据加载完后仍需等待图片加载，因此提供了 `onLoad` 方法，传递到此方法中的函数会在图片加载完后调用，可用于取消加载状态。
+
+@code('${DEMO_PATH}/waterfall/demo/Dynamic.vue')
+
+## API
+
+### WaterfallProps
+
+| 属性       | 描述           | 类型       | 默认值 |
+| ---------- | -------------- | ---------- | ------ |
+| root-class | 组件根元素类名 | string     | -      |
+| root-style | 组件根元素样式 | StyleValue | -      |
+| columns    | 自定义列数     | number     | 2      |
+| column-gap | 列间距，单位px | number     | 16     |
+| row-gap    | 行间距，单位px | number     | 16     |
+
+### WaterfallSlots
+
+| 插槽    | 描述           | 属性 |
+| ------- | -------------- | ---- |
+| default | 自定义默认内容 | -    |
+
+### WaterfallEmits
+
+| 事件      | 描述                     | 类型       |
+| --------- | ------------------------ | ---------- |
+| load      | 所有瀑布流项加载完时触发 | () => void |
+| loadstart | 瀑布流项项开始加载时触发 | () => void |
+
+### WaterfallExpose
+
+| 属性   | 描述                             | 类型                          |
+| ------ | -------------------------------- | ----------------------------- |
+| reflow | 重新排版                         | () => void                    |
+| onLoad | 添加回调，会在所有项加载完时调用 | (handler: () => void) => void |
+
+### WaterfallItemProps
+
+| 属性       | 描述           | 类型       | 默认值 |
+| ---------- | -------------- | ---------- | ------ |
+| root-class | 组件根元素类名 | string     | -      |
+| root-style | 组件根元素样式 | StyleValue | -      |
+
+### WaterfallItemSlots
+
+| 插槽    | 描述           | 属性                                        |
+| ------- | -------------- | ------------------------------------------- |
+| default | 自定义默认内容 | { onLoad: () => void; columnWidth: number } |
+
+default 插槽属性说明：
+
+- `onLoad`: 图片加载完后（无论成功或失败）需要调用此方法。
+- `columnWidth`: 列宽。
+
+### WaterfallLoadProps
+
+| 属性       | 描述                 | 类型       | 默认值 |
+| ---------- | -------------------- | ---------- | ------ |
+| root-class | 组件根元素类名       | string     | -      |
+| root-style | 组件根元素样式       | StyleValue | -      |
+| max-wait   | 最大等待时间，单位ms | number     | 0      |
+| width      | 自定义宽度           | number     | 320    |
+| height     | 自定义高度           | number     | 240    |
+
+### WaterfallLoadSlots
+
+| 插槽    | 描述           | 属性                                                |
+| ------- | -------------- | --------------------------------------------------- |
+| default | 自定义默认内容 | { onLoad: (event: any) => void; overtime: boolean } |
+
+default 插槽属性说明：
+
+- `onLoad`: 图片加载完后（成功和失败）可以调用此方法，加载完时间比 `max-wait` 要大则超时。
+- `overtime`: 是否超时。
+
+### WaterfallEmits
+
+| 事件 | 描述                                     | 类型       |
+| ---- | ---------------------------------------- | ---------- |
+| load | 加载完时触发，无论是正常加载完，还是超时 | () => void |
+
+## 主题定制
+
+### CSS 变量
+
+@code('./variables.scss#variables')

package/components/waterfall/common.d.ts

@@ -0,0 +1,32 @@
+import { InjectionKey, type StyleValue } from 'vue';
+import { type WaterfallItemInfo } from '../waterfall-item/common';
+export interface WaterfallProps {
+    rootStyle?: StyleValue;
+    rootClass?: string;
+    columns?: number;
+    columnGap?: number;
+    rowGap?: number;
+}
+export declare const defaultWaterfallProps: {
+    columns: number;
+    columnGap: number;
+    rowGap: number;
+};
+export interface WaterfallSlots {
+    default?(props: Record<string, never>): any;
+}
+export interface WaterfallEmits {
+    (e: 'load'): void;
+    (e: 'loadstart'): void;
+}
+export interface WaterfallExpose {
+    reflow: () => void;
+    onLoad: (handler: () => void) => void;
+}
+export interface WaterfallContext {
+    columnWidth: number;
+    addItem: (item: WaterfallItemInfo) => void;
+    removeItem: (item: WaterfallItemInfo) => void;
+    onItemLoad: () => void;
+}
+export declare const waterfallContextKey: InjectionKey<WaterfallContext>;