xtf-grid

组件说明

xtf-grid 是宫格组件，用于展示等分网格布局。支持数据驱动和插槽模式、自定义列数、间距、图标/图片/文字组合、徽标、骨架屏和级联动画，适用于功能入口、分类导航和图片网格等场景。

---

基础用法

1. 数据驱动模式

通过 items 传入网格数据，通过 columns 设置列数：

<template>
  <xtf-grid :items="gridItems" :columns="4" icon-size="lg" clickable @item-click="onItemClick" />
</template>

<script>
export default {
  data() {
    return {
      gridItems: [
        { icon: 'home', title: '首页' },
        { icon: 'search', title: '搜索' },
        { icon: 'favorite', title: '收藏' },
        { icon: 'settings', title: '设置' },
        { icon: 'person', title: '我的' },
        { icon: 'notifications', title: '消息' },
        { icon: 'shopping_cart', title: '购物车' },
        { icon: 'history', title: '历史' }
      ]
    }
  },
  methods: {
    onItemClick(data) {
      console.log('点击:', data.item.title)
    }
  }
}
</script>

2. 插槽模式

使用 xtf-grid-item 自定义每一项内容：

<template>
  <xtf-grid :columns="3" clickable>
    <xtf-grid-item v-for="item in menuList" :key="item.title" :title="item.title" :icon="item.icon">
      <template #icon>
        <xtf-icon :name="item.icon" size="lg" theme="primary" variant="soft" />
      </template>
    </xtf-grid-item>
  </xtf-grid>
</template>

<script>
export default {
  data() {
    return {
      menuList: [
        { icon: 'receipt_long', title: '账单' },
        { icon: 'account_balance_wallet', title: '钱包' },
        { icon: 'local_atm', title: '提现' }
      ]
    }
  }
}
</script>

3. 带图片和描述

通过 items 中的 image 和 desc 字段展示图片网格：

<template>
  <xtf-grid :items="imageItems" :columns="2" variant="soft" item-radius="20" />
</template>

<script>
export default {
  data() {
    return {
      imageItems: [
        { image: '/static/product1.jpg', title: '商品A', desc: '¥99.00' },
        { image: '/static/product2.jpg', title: '商品B', desc: '¥199.00' }
      ]
    }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
items	Array	[]	网格数据	数据驱动
columns	String | Number	3	列数	布局
gap	String | Number	20	间距	布局
rowGap	String | Number	''	行间距	布局
columnGap	String | Number	''	列间距	布局
autoRows	String | Number	''	自动行高	布局
mediaRatio	String	''	媒体宽高比	媒体
padding	String | Number	0	外边距	布局
itemPadding	String | Number	24	项内边距	布局
itemRadius	String | Number	28	项圆角	样式
itemMinHeight	String | Number	0	项最小高度	布局
iconSize	String | Number	'lg'	图标尺寸	图标
mediaWidth	String | Number	''	媒体宽度	媒体
mediaHeight	String | Number	''	媒体高度	媒体
mediaRadius	String | Number	''	媒体圆角	媒体
imageWidth / imageHeight	String | Number	''	图片宽度/高度	图片尺寸
align	String	'center'	对齐方式	布局
contentAlign	String	'center'	内容对齐	布局
sectionTitle	String	''	分区标题	标题
sectionDesc	String	''	分区描述	描述
theme	String	'primary'	主题色	主题
variant	String	'soft'	变体样式	样式
border	Boolean	true	是否显示边框	边框
square	Boolean	false	是否方形	形状
activeEffect	String	'scale'	点击效果	交互
activeScale	String | Number	''	点击缩放比例	交互
activeShadow	String	''	点击阴影	交互
clickable	Boolean	false	是否可点击	交互
divider	Boolean	false	是否显示分割线	分割线
dividerInset	String | Number	0	分割线内缩	分割线
dividerColor	String	''	分割线颜色	分割线
emptyText	String	''	空状态文字	空状态
emptyDesc	String	''	空状态描述	空状态
emptyIcon	String	'grid_view'	空状态图标	空状态
emptyIconSize	String | Number	'lg'	空状态图标尺寸	空状态
cascade	Boolean	false	是否级联动画	动画
cascadeStep	String | Number	60	级联步进(ms)	动画
layout	String	'header'	布局模式	布局
customClass	String	''	自定义类名	样式覆盖
customStyle	String | Object	''	自定义样式	动态样式覆盖

---

事件

事件名称	触发时机	回调参数	参数说明
item-click	点击网格项时触发	({ item, index })	项数据和索引
click	点击网格项时触发	({ item, index })	与 item-click 同时触发

---

插槽

插槽名称	说明
default	插槽模式下的网格项
item	数据模式下的自定义项内容
icon	自定义图标
header	自定义头部
footer	自定义底部
badge	自定义徽标
section	自定义分区标题
empty	自定义空状态

插槽使用示例

<template>
  <xtf-grid :items="items" :columns="2" clickable @click="onClick" @item-click="onClick">
    <template #item="{ item }"><xtf-text :text="item.title + '（自定义内容）'" /></template>
    <template #empty><xtf-empty type="search" /></template>
  </xtf-grid>
</template>

<script>
export default {
  data() {
    return { items: [{ title: '账单' }, { title: '统计' }] }
  },
  methods: {
    onClick(payload) {
      console.log(payload)
    }
  }
}
</script>

---

主题说明

• 图标使用 xtf-icon 组件
• 文字使用 xtf-text 组件
• 徽标使用 xtf-badge 组件
• 支持 primary、success、warning、danger、info 主题色
• 支持 soft、surface、card、glass、plain 变体样式

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