xtf-waterfall

组件说明

xtf-waterfall 是瀑布流布局组件，适用于商品流和图片流；可按预估或实测高度自动平衡列高。 核心能力以当前 xtf-waterfall.vue 源码为准。

---

基础用法

1. 基础用法

最小配置下即可完成常见业务交互：

<template>
  <xtf-waterfall :list="value" />
</template>

<script>
export default {
  data() {
    return {
      value: [
        { id: 1, title: '春季新品', meta: '限时活动', height: 180 },
        { id: 2, title: '会员专享', meta: '满减优惠', height: 240 }
      ]
    }
  },
  methods: {
    onEvent(payload) {
      console.log('组件事件', payload)
    }
  }
}
</script>

2. 核心交互

监听组件事件并维护页面状态：

<template>
  <xtf-waterfall :list="value" :columns="3" :column-gap="12" :item-gap="12" @item-click="onEvent" />
</template>

<script>
export default {
  data() {
    return {
      value: [
        { id: 1, title: '春季新品', meta: '限时活动', height: 180 },
        { id: 2, title: '会员专享', meta: '满减优惠', height: 240 }
      ]
    }
  },
  methods: {
    onEvent(payload) {
      console.log('组件事件', payload)
    }
  }
}
</script>

3. 进阶配置

组合布局、样式或插槽能力：

<template>
  <xtf-waterfall :list="value">
    <template #item="{ item, column }">
      <xtf-card :title="item.title" :desc="'第 ' + (column + 1) + ' 列'"
    /></template>
  </xtf-waterfall>
</template>

<script>
export default {
  data() {
    return {
      value: [
        { id: 1, title: '春季新品', meta: '限时活动', height: 180 },
        { id: 2, title: '会员专享', meta: '满减优惠', height: 240 }
      ]
    }
  },
  methods: {
    onEvent(payload) {
      console.log('组件事件', payload)
    }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
list	Array	函数返回值	控制组件的 list 行为。	按业务需要设置。
columns	[String, Number]	2	控制组件的 columns 行为。	按业务需要设置。
columnGap	[String, Number]	16	控制组件的 columnGap 行为。	按业务需要设置。
itemGap	[String, Number]	16	控制组件的 itemGap 行为。	按业务需要设置。
itemKey	String	'id'	控制组件的 itemKey 行为。	按业务需要设置。
heightKey	String	'height'	控制组件的 heightKey 行为。	按业务需要设置。
imageKey	String	'image'	控制组件的 imageKey 行为。	按业务需要设置。
titleKey	String	'title'	控制组件的 titleKey 行为。	按业务需要设置。
metaKey	String	'meta'	控制组件的 metaKey 行为。	按业务需要设置。
imageMode	String	'widthFix'	控制组件的 imageMode 行为。	按业务需要设置。
autoBalance	Boolean	true	控制组件的 autoBalance 行为。	按业务需要设置。
customClass	String	''	控制组件的 customClass 行为。	按业务需要设置。
customStyle	[String, Object]	''	控制组件的 customStyle 行为。	按业务需要设置。

数据项结构

字段	类型	默认值	说明
id/key	String | Number	index	稳定键；列表、轮播和瀑布流项目建议提供。
title/label/name	String	''	展示名称，具体读取字段见组件对应 prop。
disabled	Boolean	false	禁用可交互项目。

---

事件

事件名称	触发时机	回调参数	参数说明
item-click	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('item-click', ...) 为准。

事件使用示例

<template>
  <xtf-waterfall @item-click="onEvent" />
</template>
<script>
export default {
  methods: {
    onEvent(payload) {
      console.log('收到事件', payload)
    }
  }
}
</script>

---

插槽

插槽名	说明	作用域参数
item	自定义瀑布流项目内容。	item、index、column

---

方法

reflow()：重新测量并平衡列高。

使用示例：

this.$refs.waterfall.reflow()

---

主题说明

• var(--xtf-radius-md) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-color-fill) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-color-text) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-color-text-secondary) 参与组件的颜色、背景、边框或动效呈现。
• 视觉变体的可选值以 variant、theme、layout 等属性在源码中的分支为准。

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。