front-end/.cursor/rules/component-patterns.mdc

---
alwaysApply: false
---

### 组件开发模式

#### 通用组件设计原则
**组件职责单一**
- 每个组件只负责一个明确的功能
- 避免组件过于复杂，拆分成更小的子组件
- 组件应该是可复用的，不依赖特定的业务逻辑

**Props 设计规范**
```vue
<!-- components/UserCard.vue -->
<template>
  <view class="user-card" :class="{ 'user-card--disabled': disabled }">
    <image class="avatar" :src="avatar" mode="aspectFill" />
    <view class="info">
      <text class="name">{{ name }}</text>
      <text class="role">{{ role }}</text>
    </view>
    <view class="actions" v-if="showActions">
      <button @click="$emit('edit', user)">编辑</button>
      <button @click="$emit('delete', user)">删除</button>
    </view>
  </view>
</template>

<script>
export default {
  name: 'UserCard',
  props: {
    // 用户数据对象
    user: {
      type: Object,
      required: true,
      default: () => ({})
    },
    // 用户头像
    avatar: {
      type: String,
      default: '/static/images/default-avatar.png'
    },
    // 用户名称
    name: {
      type: String,
      required: true
    },
    // 用户角色
    role: {
      type: String,
      default: ''
    },
    // 是否显示操作按钮
    showActions: {
      type: Boolean,
      default: true
    },
    // 是否禁用
    disabled: {
      type: Boolean,
      default: false
    }
  },
  emits: ['edit', 'delete'],
  computed: {
    // 组件内部计算属性
    displayName() {
      return this.name || '未知用户'
    }
  }
}
</script>
```

#### 表单组件封装
**通用表单项组件**
```vue
<!-- components/FormItem.vue -->
<template>
  <view class="form-item" :class="{ 'form-item--error': hasError }">
    <view class="form-item__label" v-if="label">
      <text class="required" v-if="required">*</text>
      {{ label }}
    </view>
    <view class="form-item__content">
      <slot />
    </view>
    <view class="form-item__error" v-if="hasError">
      {{ errorMessage }}
    </view>
  </view>
</template>

<script>
export default {
  name: 'FormItem',
  props: {
    label: String,
    required: Boolean,
    error: String
  },
  computed: {
    hasError() {
      return !!this.error
    },
    errorMessage() {
      return this.error || ''
    }
  }
}
</script>

<style lang="scss" scoped>
.form-item {
  margin-bottom: 32rpx;
  
  &__label {
    font-size: 28rpx;
    color: #333;
    margin-bottom: 16rpx;
    
    .required {
      color: #ff4757;
    }
  }
  
  &__content {
    position: relative;
  }
  
  &__error {
    font-size: 24rpx;
    color: #ff4757;
    margin-top: 8rpx;
  }
  
  &--error {
    .form-item__content {
      border-color: #ff4757;
    }
  }
}
</style>
```

**输入框组件**
```vue
<!-- components/Input.vue -->
<template>
  <view class="input-wrapper">
    <input
      class="input"
      :type="type"
      :value="modelValue"
      :placeholder="placeholder"
      :disabled="disabled"
      :maxlength="maxlength"
      @input="handleInput"
      @blur="handleBlur"
      @focus="handleFocus"
    />
    <view class="input__clear" v-if="clearable && modelValue" @click="handleClear">
      <text class="iconfont icon-close"></text>
    </view>
  </view>
</template>

<script>
export default {
  name: 'Input',
  props: {
    modelValue: [String, Number],
    type: {
      type: String,
      default: 'text'
    },
    placeholder: String,
    disabled: Boolean,
    clearable: Boolean,
    maxlength: Number
  },
  emits: ['update:modelValue', 'focus', 'blur', 'clear'],
  methods: {
    handleInput(e) {
      this.$emit('update:modelValue', e.detail.value)
    },
    handleFocus(e) {
      this.$emit('focus', e)
    },
    handleBlur(e) {
      this.$emit('blur', e)
    },
    handleClear() {
      this.$emit('update:modelValue', '')
      this.$emit('clear')
    }
  }
}
</script>
```

#### 列表组件模式
**通用列表组件**
```vue
<!-- components/List.vue -->
<template>
  <view class="list">
    <!-- 加载状态 -->
    <view class="list__loading" v-if="loading">
      <text>加载中...</text>
    </view>
    
    <!-- 列表内容 -->
    <view class="list__content" v-else-if="list.length > 0">
      <view 
        class="list__item" 
        v-for="(item, index) in list" 
        :key="getItemKey(item, index)"
        @click="$emit('item-click', item, index)"
      >
        <slot :item="item" :index="index">
          <!-- 默认列表项渲染 -->
          <view class="default-item">{{ item.title || item.name }}</view>
        </slot>
      </view>
      
      <!-- 加载更多 -->
      <view class="list__load-more" v-if="hasMore" @click="$emit('load-more')">
        <text v-if="loadingMore">加载中...</text>
        <text v-else>点击加载更多</text>
      </view>
      
      <!-- 没有更多 -->
      <view class="list__no-more" v-else>
        <text>没有更多数据了</text>
      </view>
    </view>
    
    <!-- 空状态 -->
    <view class="list__empty" v-else>
      <slot name="empty">
        <view class="empty-default">
          <image src="/static/images/empty.png" mode="aspectFit" />
          <text>暂无数据</text>
        </view>
      </slot>
    </view>
    
    <!-- 错误状态 -->
    <view class="list__error" v-if="error" @click="$emit('retry')">
      <text>{{ error }}</text>
      <text>点击重试</text>
    </view>
  </view>
</template>

<script>
export default {
  name: 'List',
  props: {
    list: {
      type: Array,
      default: () => []
    },
    loading: Boolean,
    loadingMore: Boolean,
    hasMore: Boolean,
    error: String,
    itemKey: {
      type: String,
      default: 'id'
    }
  },
  emits: ['item-click', 'load-more', 'retry'],
  methods: {
    getItemKey(item, index) {
      return item[this.itemKey] || index
    }
  }
}
</script>
```

#### 弹窗组件模式
**通用弹窗组件**
```vue
<!-- components/Modal.vue -->
<template>
  <view class="modal" v-if="visible" @click="handleMaskClick">
    <view class="modal__content" @click.stop>
      <!-- 头部 -->
      <view class="modal__header" v-if="title || $slots.header">
        <slot name="header">
          <text class="modal__title">{{ title }}</text>
          <view class="modal__close" @click="handleClose">
            <text class="iconfont icon-close"></text>
          </view>
        </slot>
      </view>
      
      <!-- 内容 -->
      <view class="modal__body">
        <slot />
      </view>
      
      <!-- 底部 -->
      <view class="modal__footer" v-if="$slots.footer">
        <slot name="footer" />
      </view>
    </view>
  </view>
</template>

<script>
export default {
  name: 'Modal',
  props: {
    visible: Boolean,
    title: String,
    maskClosable: {
      type: Boolean,
      default: true
    }
  },
  emits: ['update:visible', 'close'],
  methods: {
    handleClose() {
      this.$emit('update:visible', false)
      this.$emit('close')
    },
    handleMaskClick() {
      if (this.maskClosable) {
        this.handleClose()
      }
    }
  }
}
</script>

<style lang="scss" scoped>
.modal {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background-color: rgba(0, 0, 0, 0.5);
  display: flex;
  align-items: center;
  justify-content: center;
  z-index: 1000;
  
  &__content {
    background-color: #fff;
    border-radius: 16rpx;
    min-width: 600rpx;
    max-width: 90%;
    max-height: 80%;
    overflow: hidden;
  }
  
  &__header {
    display: flex;
    align-items: center;
    justify-content: space-between;
    padding: 32rpx;
    border-bottom: 1px solid #eee;
  }
  
  &__title {
    font-size: 32rpx;
    font-weight: 500;
    color: #333;
  }
  
  &__close {
    width: 48rpx;
    height: 48rpx;
    display: flex;
    align-items: center;
    justify-content: center;
    color: #999;
  }
  
  &__body {
    padding: 32rpx;
  }
  
  &__footer {
    padding: 32rpx;
    border-top: 1px solid #eee;
  }
}
</style>
```

#### 业务组件示例
**订单卡片组件**
```vue
<!-- components/OrderCard.vue -->
<template>
  <view class="order-card" @click="$emit('click', order)">
    <view class="order-card__header">
      <text class="order-no">订单号：{{ order.orderNo }}</text>
      <text class="status" :class="`status--${order.status}`">
        {{ statusText }}
      </text>
    </view>
    
    <view class="order-card__content">
      <view class="products">
        <view 
          class="product-item" 
          v-for="product in order.products" 
          :key="product.id"
        >
          <image :src="product.image" mode="aspectFill" />
          <view class="product-info">
            <text class="name">{{ product.name }}</text>
            <text class="spec">{{ product.spec }}</text>
            <text class="price">¥{{ product.price }} × {{ product.quantity }}</text>
          </view>
        </view>
      </view>
    </view>
    
    <view class="order-card__footer">
      <text class="total">合计：¥{{ order.totalAmount }}</text>
      <view class="actions">
        <button 
          v-for="action in actions" 
          :key="action.type"
          class="action-btn"
          :class="`action-btn--${action.type}`"
          @click.stop="$emit('action', action.type, order)"
        >
          {{ action.label }}
        </button>
      </view>
    </view>
  </view>
</template>

<script>
export default {
  name: 'OrderCard',
  props: {
    order: {
      type: Object,
      required: true
    }
  },
  emits: ['click', 'action'],
  computed: {
    statusText() {
      const statusMap = {
        pending: '待付款',
        paid: '已付款',
        shipped: '已发货',
        delivered: '已送达',
        cancelled: '已取消'
      }
      return statusMap[this.order.status] || '未知状态'
    },
    actions() {
      const actionMap = {
        pending: [
          { type: 'pay', label: '去付款' },
          { type: 'cancel', label: '取消订单' }
        ],
        paid: [
          { type: 'remind', label: '提醒发货' }
        ],
        shipped: [
          { type: 'confirm', label: '确认收货' }
        ],
        delivered: [
          { type: 'review', label: '去评价' }
        ]
      }
      return actionMap[this.order.status] || []
    }
  }
}
</script>
```
### 组件开发模式

#### 通用组件设计原则
**组件职责单一**
- 每个组件只负责一个明确的功能
- 避免组件过于复杂，拆分成更小的子组件
- 组件应该是可复用的，不依赖特定的业务逻辑

**Props 设计规范**
```vue
<!-- components/UserCard.vue -->
<template>
  <view class="user-card" :class="{ 'user-card--disabled': disabled }">
    <image class="avatar" :src="avatar" mode="aspectFill" />
    <view class="info">
      <text class="name">{{ name }}</text>
      <text class="role">{{ role }}</text>
    </view>
    <view class="actions" v-if="showActions">
      <button @click="$emit('edit', user)">编辑</button>
      <button @click="$emit('delete', user)">删除</button>
    </view>
  </view>
</template>

<script>
export default {
  name: 'UserCard',
  props: {
    // 用户数据对象
    user: {
      type: Object,
      required: true,
      default: () => ({})
    },
    // 用户头像
    avatar: {
      type: String,
      default: '/static/images/default-avatar.png'
    },
    // 用户名称
    name: {
      type: String,
      required: true
    },
    // 用户角色
    role: {
      type: String,
      default: ''
    },
    // 是否显示操作按钮
    showActions: {
      type: Boolean,
      default: true
    },
    // 是否禁用
    disabled: {
      type: Boolean,
      default: false
    }
  },
  emits: ['edit', 'delete'],
  computed: {
    // 组件内部计算属性
    displayName() {
      return this.name || '未知用户'
    }
  }
}
</script>
```

#### 表单组件封装
**通用表单项组件**
```vue
<!-- components/FormItem.vue -->
<template>
  <view class="form-item" :class="{ 'form-item--error': hasError }">
    <view class="form-item__label" v-if="label">
      <text class="required" v-if="required">*</text>
      {{ label }}
    </view>
    <view class="form-item__content">
      <slot />
    </view>
    <view class="form-item__error" v-if="hasError">
      {{ errorMessage }}
    </view>
  </view>
</template>

<script>
export default {
  name: 'FormItem',
  props: {
    label: String,
    required: Boolean,
    error: String
  },
  computed: {
    hasError() {
      return !!this.error
    },
    errorMessage() {
      return this.error || ''
    }
  }
}
</script>

<style lang="scss" scoped>
.form-item {
  margin-bottom: 32rpx;
  
  &__label {
    font-size: 28rpx;
    color: #333;
    margin-bottom: 16rpx;
    
    .required {
      color: #ff4757;
    }
  }
  
  &__content {
    position: relative;
  }
  
  &__error {
    font-size: 24rpx;
    color: #ff4757;
    margin-top: 8rpx;
  }
  
  &--error {
    .form-item__content {
      border-color: #ff4757;
    }
  }
}
</style>
```

**输入框组件**
```vue
<!-- components/Input.vue -->
<template>
  <view class="input-wrapper">
    <input
      class="input"
      :type="type"
      :value="modelValue"
      :placeholder="placeholder"
      :disabled="disabled"
      :maxlength="maxlength"
      @input="handleInput"
      @blur="handleBlur"
      @focus="handleFocus"
    />
    <view class="input__clear" v-if="clearable && modelValue" @click="handleClear">
      <text class="iconfont icon-close"></text>
    </view>
  </view>
</template>

<script>
export default {
  name: 'Input',
  props: {
    modelValue: [String, Number],
    type: {
      type: String,
      default: 'text'
    },
    placeholder: String,
    disabled: Boolean,
    clearable: Boolean,
    maxlength: Number
  },
  emits: ['update:modelValue', 'focus', 'blur', 'clear'],
  methods: {
    handleInput(e) {
      this.$emit('update:modelValue', e.detail.value)
    },
    handleFocus(e) {
      this.$emit('focus', e)
    },
    handleBlur(e) {
      this.$emit('blur', e)
    },
    handleClear() {
      this.$emit('update:modelValue', '')
      this.$emit('clear')
    }
  }
}
</script>
```

#### 列表组件模式
**通用列表组件**
```vue
<!-- components/List.vue -->
<template>
  <view class="list">
    <!-- 加载状态 -->
    <view class="list__loading" v-if="loading">
      <text>加载中...</text>
    </view>
    
    <!-- 列表内容 -->
    <view class="list__content" v-else-if="list.length > 0">
      <view 
        class="list__item" 
        v-for="(item, index) in list" 
        :key="getItemKey(item, index)"
        @click="$emit('item-click', item, index)"
      >
        <slot :item="item" :index="index">
          <!-- 默认列表项渲染 -->
          <view class="default-item">{{ item.title || item.name }}</view>
        </slot>
      </view>
      
      <!-- 加载更多 -->
      <view class="list__load-more" v-if="hasMore" @click="$emit('load-more')">
        <text v-if="loadingMore">加载中...</text>
        <text v-else>点击加载更多</text>
      </view>
      
      <!-- 没有更多 -->
      <view class="list__no-more" v-else>
        <text>没有更多数据了</text>
      </view>
    </view>
    
    <!-- 空状态 -->
    <view class="list__empty" v-else>
      <slot name="empty">
        <view class="empty-default">
          <image src="/static/images/empty.png" mode="aspectFit" />
          <text>暂无数据</text>
        </view>
      </slot>
    </view>
    
    <!-- 错误状态 -->
    <view class="list__error" v-if="error" @click="$emit('retry')">
      <text>{{ error }}</text>
      <text>点击重试</text>
    </view>
  </view>
</template>

<script>
export default {
  name: 'List',
  props: {
    list: {
      type: Array,
      default: () => []
    },
    loading: Boolean,
    loadingMore: Boolean,
    hasMore: Boolean,
    error: String,
    itemKey: {
      type: String,
      default: 'id'
    }
  },
  emits: ['item-click', 'load-more', 'retry'],
  methods: {
    getItemKey(item, index) {
      return item[this.itemKey] || index
    }
  }
}
</script>
```

#### 弹窗组件模式
**通用弹窗组件**
```vue
<!-- components/Modal.vue -->
<template>
  <view class="modal" v-if="visible" @click="handleMaskClick">
    <view class="modal__content" @click.stop>
      <!-- 头部 -->
      <view class="modal__header" v-if="title || $slots.header">
        <slot name="header">
          <text class="modal__title">{{ title }}</text>
          <view class="modal__close" @click="handleClose">
            <text class="iconfont icon-close"></text>
          </view>
        </slot>
      </view>
      
      <!-- 内容 -->
      <view class="modal__body">
        <slot />
      </view>
      
      <!-- 底部 -->
      <view class="modal__footer" v-if="$slots.footer">
        <slot name="footer" />
      </view>
    </view>
  </view>
</template>

<script>
export default {
  name: 'Modal',
  props: {
    visible: Boolean,
    title: String,
    maskClosable: {
      type: Boolean,
      default: true
    }
  },
  emits: ['update:visible', 'close'],
  methods: {
    handleClose() {
      this.$emit('update:visible', false)
      this.$emit('close')
    },
    handleMaskClick() {
      if (this.maskClosable) {
        this.handleClose()
      }
    }
  }
}
</script>

<style lang="scss" scoped>
.modal {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background-color: rgba(0, 0, 0, 0.5);
  display: flex;
  align-items: center;
  justify-content: center;
  z-index: 1000;
  
  &__content {
    background-color: #fff;
    border-radius: 16rpx;
    min-width: 600rpx;
    max-width: 90%;
    max-height: 80%;
    overflow: hidden;
  }
  
  &__header {
    display: flex;
    align-items: center;
    justify-content: space-between;
    padding: 32rpx;
    border-bottom: 1px solid #eee;
  }
  
  &__title {
    font-size: 32rpx;
    font-weight: 500;
    color: #333;
  }
  
  &__close {
    width: 48rpx;
    height: 48rpx;
    display: flex;
    align-items: center;
    justify-content: center;
    color: #999;
  }
  
  &__body {
    padding: 32rpx;
  }
  
  &__footer {
    padding: 32rpx;
    border-top: 1px solid #eee;
  }
}
</style>
```

#### 业务组件示例
**订单卡片组件**
```vue
<!-- components/OrderCard.vue -->
<template>
  <view class="order-card" @click="$emit('click', order)">
    <view class="order-card__header">
      <text class="order-no">订单号：{{ order.orderNo }}</text>
      <text class="status" :class="`status--${order.status}`">
        {{ statusText }}
      </text>
    </view>
    
    <view class="order-card__content">
      <view class="products">
        <view 
          class="product-item" 
          v-for="product in order.products" 
          :key="product.id"
        >
          <image :src="product.image" mode="aspectFill" />
          <view class="product-info">
            <text class="name">{{ product.name }}</text>
            <text class="spec">{{ product.spec }}</text>
            <text class="price">¥{{ product.price }} × {{ product.quantity }}</text>
          </view>
        </view>
      </view>
    </view>
    
    <view class="order-card__footer">
      <text class="total">合计：¥{{ order.totalAmount }}</text>
      <view class="actions">
        <button 
          v-for="action in actions" 
          :key="action.type"
          class="action-btn"
          :class="`action-btn--${action.type}`"
          @click.stop="$emit('action', action.type, order)"
        >
          {{ action.label }}
        </button>
      </view>
    </view>
  </view>
</template>

<script>
export default {
  name: 'OrderCard',
  props: {
    order: {
      type: Object,
      required: true
    }
  },
  emits: ['click', 'action'],
  computed: {
    statusText() {
      const statusMap = {
        pending: '待付款',
        paid: '已付款',
        shipped: '已发货',
        delivered: '已送达',
        cancelled: '已取消'
      }
      return statusMap[this.order.status] || '未知状态'
    },
    actions() {
      const actionMap = {
        pending: [
          { type: 'pay', label: '去付款' },
          { type: 'cancel', label: '取消订单' }
        ],
        paid: [
          { type: 'remind', label: '提醒发货' }
        ],
        shipped: [
          { type: 'confirm', label: '确认收货' }
        ],
        delivered: [
          { type: 'review', label: '去评价' }
        ]
      }
      return actionMap[this.order.status] || []
    }
  }
}
</script>
```