从零开始打造一个通用的 Vue 卡片组件

news2025/3/11 14:43:16

前言

大家好，最近在做项目的时候发现我们系统里到处都是各种卡片样式的 UI 元素，每次都要重写一遍真的很烦。于是我花了点时间，封装了一个通用的卡片组件，今天就来分享一下我的开发思路和实现过程。希望能对大家有所帮助！

需求分析

在开始写代码前，我先梳理了一下卡片组件的常见需求：

支持自定义标题、内容、底部操作区
可配置是否显示阴影、边框
支持加载状态
支持自定义样式
支持卡片展开/折叠功能
支持卡片的移除/关闭功能

组件设计

目录结构

|- CardComponent/
  |- index.vue         # 主组件文件
  |- CardHeader.vue    # 卡片头部组件
  |- CardContent.vue   # 卡片内容组件
  |- CardFooter.vue    # 卡片底部组件
  |- index.js          # 导出文件
  |- types.js          # TypeScript 类型定义
  |- style.scss        # 样式文件

实现代码

首先来看主组件 index.vue 的实现：

<template>
  <div 
    class="v-card" 
    :class="[
      `v-card--${shadow}-shadow`,
      { 
        'v-card--bordered': bordered,
        'is-loading': loading,
        'is-collapsed': !expanded
      }
    ]"
    :style="customStyle"
  >
    <!-- 加载状态遮罩 -->
    <div v-if="loading" class="v-card__loading-mask">
      <div class="v-card__loading-spinner"></div>
    </div>
    
    <!-- 卡片头部 -->
    <div v-if="$slots.header || title" class="v-card__header">
      <slot name="header">
        <div class="v-card__title">{{ title }}</div>
        <div v-if="collapsible" class="v-card__collapse-btn" @click="toggleExpand">
          <i :class="expanded ? 'icon-arrow-up' : 'icon-arrow-down'"></i>
        </div>
        <div v-if="closable" class="v-card__close-btn" @click="handleClose">
          <i class="icon-close"></i>
        </div>
      </slot>
    </div>
    
    <!-- 卡片内容 -->
    <div v-show="expanded" class="v-card__content">
      <slot></slot>
    </div>
    
    <!-- 卡片底部 -->
    <div v-if="$slots.footer && expanded" class="v-card__footer">
      <slot name="footer"></slot>
    </div>
  </div>
</template>

<script>
export default {
  name: 'VCard',
  
  props: {
    // 卡片标题
    title: {
      type: String,
      default: ''
    },
    // 阴影显示时机
    shadow: {
      type: String,
      default: 'always', // always, hover, never
      validator: value => ['always', 'hover', 'never'].includes(value)
    },
    // 是否有边框
    bordered: {
      type: Boolean,
      default: true
    },
    // 是否显示加载状态
    loading: {
      type: Boolean,
      default: false
    },
    // 自定义样式
    customStyle: {
      type: Object,
      default: () => ({})
    },
    // 是否可折叠
    collapsible: {
      type: Boolean,
      default: false
    },
    // 默认是否展开
    defaultExpanded: {
      type: Boolean,
      default: true
    },
    // 是否可关闭
    closable: {
      type: Boolean,
      default: false
    }
  },
  
  data() {
    return {
      expanded: this.defaultExpanded
    };
  },
  
  methods: {
    toggleExpand() {
      this.expanded = !this.expanded;
      this.$emit('collapse-change', this.expanded);
    },
    
    handleClose() {
      this.$emit('close');
    }
  }
};
</script>

<style lang="scss" scoped>
.v-card {
  position: relative;
  background-color: #fff;
  border-radius: 4px;
  overflow: hidden;
  transition: all 0.3s;
  
  &--always-shadow {
    box-shadow: 0 2px 12px 0 rgba(0, 0, 0, 0.1);
  }
  
  &--hover-shadow {
    &:hover {
      box-shadow: 0 2px 12px 0 rgba(0, 0, 0, 0.1);
    }
  }
  
  &--never-shadow {
    box-shadow: none;
  }
  
  &--bordered {
    border: 1px solid #ebeef5;
  }
  
  &__header {
    display: flex;
    align-items: center;
    padding: 18px 20px;
    border-bottom: 1px solid #ebeef5;
  }
  
  &__title {
    flex: 1;
    font-size: 16px;
    font-weight: bold;
    color: #303133;
  }
  
  &__collapse-btn,
  &__close-btn {
    margin-left: 10px;
    cursor: pointer;
    color: #909399;
    
    &:hover {
      color: #409EFF;
    }
  }
  
  &__content {
    padding: 20px;
  }
  
  &__footer {
    padding: 10px 20px;
    border-top: 1px solid #ebeef5;
  }
  
  &__loading-mask {
    position: absolute;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
    background-color: rgba(255, 255, 255, 0.7);
    z-index: 10;
    display: flex;
    align-items: center;
    justify-content: center;
  }
  
  &__loading-spinner {
    width: 30px;
    height: 30px;
    border: 2px solid #409EFF;
    border-radius: 50%;
    border-left-color: transparent;
    animation: spin 1s linear infinite;
  }
  
  &.is-loading {
    pointer-events: none;
  }
  
  &.is-collapsed {
    min-height: auto;
  }
}

@keyframes spin {
  0% { transform: rotate(0deg); }
  100% { transform: rotate(360deg); }
}
</style>

使用方法

基础用法

<template>
  <v-card title="我的卡片">
    这里是卡片内容
  </v-card>
</template>

<script>
import VCard from '@/components/CardComponent';

export default {
  components: {
    VCard
  }
}
</script>

自定义头部和底部

<template>
  <v-card>
    <template #header>
      <div class="custom-header">
        <h3>自定义标题</h3>
        <el-button size="small" type="primary">操作按钮</el-button>
      </div>
    </template>
    
    <p>这是卡片的主要内容区域</p>
    
    <template #footer>
      <div class="custom-footer">
        <el-button>取消</el-button>
        <el-button type="primary">确定</el-button>
      </div>
    </template>
  </v-card>
</template>

可折叠卡片

<template>
  <v-card 
    title="可折叠卡片" 
    :collapsible="true" 
    :default-expanded="false"
    @collapse-change="handleCollapseChange"
  >
    <p>这里是可以被折叠的内容</p>
  </v-card>
</template>

<script>
export default {
  methods: {
    handleCollapseChange(expanded) {
      console.log('卡片展开状态:', expanded);
    }
  }
}
</script>

加载状态

<template>
  <v-card title="加载中的卡片" :loading="isLoading">
    <p>这里是卡片内容</p>
  </v-card>
</template>

<script>
export default {
  data() {
    return {
      isLoading: true
    }
  },
  mounted() {
    // 模拟异步加载
    setTimeout(() => {
      this.isLoading = false;
    }, 2000);
  }
}
</script>

API 文档

Props

参数	说明	类型	可选值	默认值
title	卡片标题	String	—	‘’
shadow	设置阴影显示时机	String	always / hover / never	always
bordered	是否显示边框	Boolean	—	true
loading	是否显示加载状态	Boolean	—	false
customStyle	自定义样式	Object	—	{}
collapsible	是否可折叠	Boolean	—	false
defaultExpanded	默认是否展开	Boolean	—	true
closable	是否可关闭	Boolean	—	false