BizCouponCard 优惠券

营销券卡片组件：满减 / 折扣 / 兑换三形态券卡（面额区 + 门槛 + 适用范围 + 生效期），五态自动派生（未开始 / 领取中 / 已领完 / 已结束 / 暂停发放，失效态灰化）、库存进度条（≥90% 变红）、临期红标（N 天内截止倒计提示）、每人限领校验（首领后「再领一张」、领满拦截）；本地领取或 claimRequest 远程扣减；claimable=false 只读营销位（自动发放权益展示）。适用于营销后台活动配置预览、会员中心领券中心、券核销对账等场景。

基础用法

领券中心

满减券¥50满 199 元可用

全场通用满减券领取中

限全品类（虚拟商品除外）

2026-10-21 ~ 2026-11-05

折扣券8.5折满 499 元可享

数码专场 8.5 折券领取中

限数码家电类目

2026-10-25 ~ 2026-11-02

兑换券兑换到店出示即可兑换

兑换券 · 芝士蛋糕领取中

限华东 32 家门店

2026-10-16 ~ 2026-11-15

三形态券卡片；「立即领取」本地入库（mineCount / claimed 递增）并提示。

<script setup lang="ts">
/** 基础用法：满减 / 折扣 / 兑换三形态券卡片，点击「立即领取」本地入库并提示 */
import { BizCouponCard } from 'vue3-ep-biz-lib'

const pad = (n: number) => String(n).padStart(2, '0')
const dayAt = (offset: number) => {
  const d = new Date()
  d.setDate(d.getDate() + offset)
  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
}
</script>

<template>
  <div style="max-width: 900px">
    <BizCouponCard
      :coupons="[
        { id: 'c1', kind: 'cash', title: '全场通用满减券', threshold: 199, amount: 50, scope: '限全品类（虚拟商品除外）', startAt: dayAt(-5), endAt: dayAt(10) },
        { id: 'c2', kind: 'discount', title: '数码专场 8.5 折券', threshold: 499, discount: 0.85, scope: '限数码家电类目', startAt: dayAt(-1), endAt: dayAt(7) },
        { id: 'c3', kind: 'gift', title: '兑换券 · 芝士蛋糕', giftText: '到店出示即可兑换', scope: '限华东 32 家门店', startAt: dayAt(-10), endAt: dayAt(20) },
      ]"
    />
  </div>
</template>

显示代码

三形态细节

领券中心

满减券¥10无门槛

新人无门槛券领取中

全品类可用

2026-10-26 ~ 2026-11-25

不与折扣券叠加

折扣券9折无门槛享折扣

会员日折扣券领取中

会员专属

2026-10-26 ~ 2026-11-10

可与满减叠加，上限 2 张

兑换券兑换双杯饮品 + 甜点一份

生日礼包兑换券领取中

生日当月可用

2026-10-26 起长期有效

无门槛满减、无门槛折扣、长期有效兑换券（无截止时间显示「长期有效」）；stack-note 展示叠加规则。

<script setup lang="ts">
/** 三形态细节：无门槛满减 / 无门槛折扣 / 门槛与叠加规则文案 */
import { BizCouponCard } from 'vue3-ep-biz-lib'

const pad = (n: number) => String(n).padStart(2, '0')
const dayAt = (offset: number) => {
  const d = new Date()
  d.setDate(d.getDate() + offset)
  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
}
</script>

<template>
  <div style="max-width: 900px">
    <BizCouponCard
      :show-progress="false"
      :coupons="[
        { id: 'k1', kind: 'cash', title: '新人无门槛券', amount: 10, scope: '全品类可用', startAt: dayAt(0), endAt: dayAt(30), stackNote: '不与折扣券叠加' },
        { id: 'k2', kind: 'discount', title: '会员日折扣券', discount: 0.9, scope: '会员专属', startAt: dayAt(0), endAt: dayAt(15), stackNote: '可与满减叠加，上限 2 张' },
        { id: 'k3', kind: 'gift', title: '生日礼包兑换券', giftText: '双杯饮品 + 甜点一份', scope: '生日当月可用', startAt: dayAt(0) },
      ]"
    />
  </div>
</template>

显示代码

每人限领

领券中心

满减券¥20满 99 元可用

限时满减券（限领 2 张）领取中

2026-10-25 ~ 2026-10-31

87%

已领 873 / 1000张

limitPerUser: 2：首领后按钮变「再领一张」、券卡显示已领张数，领满后拦截提示。

<script setup lang="ts">
/** 每人限领：limitPerUser=2，首领后按钮变「再领一张」，领满后拦截提示 */
import { BizCouponCard } from 'vue3-ep-biz-lib'

const pad = (n: number) => String(n).padStart(2, '0')
const dayAt = (offset: number) => {
  const d = new Date()
  d.setDate(d.getDate() + offset)
  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
}
</script>

<template>
  <div style="max-width: 640px">
    <BizCouponCard
      :coupons="[
        { id: 'l1', kind: 'cash', title: '限时满减券（限领 2 张）', threshold: 99, amount: 20, limitPerUser: 2, total: 1000, claimed: 873, startAt: dayAt(-1), endAt: dayAt(5) },
      ]"
    />
  </div>
</template>

显示代码

库存进度

领券中心

满减券¥80满 299 元可用

爆款券 · 库存告急领取中

2026-10-23 ~ 2026-11-01

94%

已领 1873 / 2000张

满减券¥30满 99 元可用

爆款券 · 已抢完已领完

2026-10-23 ~ 2026-11-01

100%

已领 500 / 500张

已领完

已领 90% 以上进度条变红；claimed >= total 派生「已领完」态，按钮区替换为状态文案。

<script setup lang="ts">
/** 库存进度：已领 90% 以上进度条变红；已领完的券按钮区显示「已领完」 */
import { BizCouponCard } from 'vue3-ep-biz-lib'

const pad = (n: number) => String(n).padStart(2, '0')
const dayAt = (offset: number) => {
  const d = new Date()
  d.setDate(d.getDate() + offset)
  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
}
</script>

<template>
  <div style="max-width: 760px">
    <BizCouponCard
      :coupons="[
        { id: 's1', kind: 'cash', title: '爆款券 · 库存告急', threshold: 299, amount: 80, total: 2000, claimed: 1873, startAt: dayAt(-3), endAt: dayAt(6) },
        { id: 's2', kind: 'cash', title: '爆款券 · 已抢完', threshold: 99, amount: 30, total: 500, claimed: 500, startAt: dayAt(-3), endAt: dayAt(6) },
      ]"
    />
  </div>
</template>

显示代码

生效期状态

领券中心

满减券¥60满 199 元可用

整点开抢券未开始

2026-10-27 ~ 2026-11-03

未开始

折扣券7折满 99 元可享

清仓折扣券领取中

2026-10-20 ~ 2026-10-28 （剩 2 天，抓紧使用）

满减券¥15满 99 元可用

历史满减券已结束

2026-09-26 ~ 2026-10-25

已结束

未开始（开抢时间在将来）/ 临期红标（剩 2 天）/ 已结束三态灰化对比。

<script setup lang="ts">
/** 生效期状态：未开始（明天 10 点开抢）/ 临期红标（剩 2 天）/ 已结束，三态灰化对比 */
import { BizCouponCard } from 'vue3-ep-biz-lib'

const pad = (n: number) => String(n).padStart(2, '0')
const dayAt = (offset: number, hour = 10) => {
  const d = new Date()
  d.setDate(d.getDate() + offset)
  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(hour)}:00:00`
}
</script>

<template>
  <div style="max-width: 760px">
    <BizCouponCard
      :coupons="[
        { id: 't1', kind: 'cash', title: '整点开抢券', threshold: 199, amount: 60, startAt: dayAt(1, 10), endAt: dayAt(8, 10) },
        { id: 't2', kind: 'discount', title: '清仓折扣券', discount: 0.7, threshold: 99, startAt: dayAt(-6), endAt: dayAt(2) },
        { id: 't3', kind: 'cash', title: '历史满减券', threshold: 99, amount: 15, startAt: dayAt(-30), endAt: dayAt(-1) },
      ]"
    />
  </div>
</template>

显示代码

远程领取

领券中心

满减券¥40满 199 元可用

云端券 A领取中

2026-10-26 ~ 2026-11-04

21%

已领 21 / 100张

满减券¥20满 99 元可用

云端券 B（服务端限量 3 张演示）领取中

2026-10-26 ~ 2026-11-04

3%

已领 3 / 100张

claim-request 服务端扣减（演示服务端限量），claim 事件流水回显；失败时本地不计数。

<script setup lang="ts">
/** 远程领取：claimRequest 提交（模拟服务端扣减库存），claim 事件流水回显 */
import { ref } from 'vue'
import { BizCouponCard } from 'vue3-ep-biz-lib'
import type { BizCoupon } from 'vue3-ep-biz-lib'

const pad = (n: number) => String(n).padStart(2, '0')
const dayAt = (offset: number) => {
  const d = new Date()
  d.setDate(d.getDate() + offset)
  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
}

const log = ref<string[]>([])

const claimRequest = (c: BizCoupon) =>
  new Promise<void>((resolve, reject) => {
    setTimeout(() => {
      if (c.id === 'rc2' && (c.claimed ?? 0) >= 3) reject(new Error('server limit'))
      else resolve()
    }, 500)
  })
</script>

<template>
  <div style="max-width: 760px">
    <BizCouponCard
      :coupons="[
        { id: 'rc1', kind: 'cash', title: '云端券 A', threshold: 199, amount: 40, total: 100, claimed: 21, startAt: dayAt(0), endAt: dayAt(9) },
        { id: 'rc2', kind: 'cash', title: '云端券 B（服务端限量 3 张演示）', threshold: 99, amount: 20, total: 100, claimed: 3, startAt: dayAt(0), endAt: dayAt(9) },
      ]"
      :claim-request="claimRequest"
      @claim="(p) => log.push(`${p.couponId} 累计 ${p.mineCount} 张`)"
    />
    <p v-if="log.length" style="margin: 12px 0 0; font-size: 13px; color: var(--el-text-color-secondary)">
      领取流水：{{ log.join(' ｜ ') }}
    </p>
  </div>
</template>

显示代码

暂停发放

领券中心

满减券¥60满 199 元可用

风控暂停的券（库存异常排查中）暂停发放

2026-10-25 ~ 2026-11-04

暂停发放

paused 置灰显示「暂停发放」，点击领取被拦截（风控 / 库存异常排查场景）。

<script setup lang="ts">
/** 暂停发放：paused 置灰并显示「暂停发放」，点击领取被拦截 */
import { BizCouponCard } from 'vue3-ep-biz-lib'

const pad = (n: number) => String(n).padStart(2, '0')
const dayAt = (offset: number) => {
  const d = new Date()
  d.setDate(d.getDate() + offset)
  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
}
</script>

<template>
  <div style="max-width: 640px">
    <BizCouponCard
      :coupons="[
        { id: 'p1', kind: 'cash', title: '风控暂停的券（库存异常排查中）', threshold: 199, amount: 60, paused: true, startAt: dayAt(-1), endAt: dayAt(9) },
      ]"
    />
  </div>
</template>

显示代码

只读营销位

会员权益 · 专属券

兑换券兑换每月 2 次

黑卡专属 · 免费洗车领取中

限绑定车牌

2026-10-26 ~ 2026-11-25

自动发放至券包

折扣券9.2折无门槛享折扣

黑卡专属 · 加油 9.2 折领取中

2026-10-26 起长期有效

自动发放至券包

claimable=false 隐藏领取按钮，action-extra 槽位改放权益说明（自动发放类券卡）。

<script setup lang="ts">
/** 只读营销位：claimable=false 隐藏领取按钮，action-custom 槽位放活动规则说明 */
import { BizCouponCard } from 'vue3-ep-biz-lib'

const pad = (n: number) => String(n).padStart(2, '0')
const dayAt = (offset: number) => {
  const d = new Date()
  d.setDate(d.getDate() + offset)
  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
}
</script>

<template>
  <div style="max-width: 760px">
    <BizCouponCard
      title="会员权益 · 专属券"
      :claimable="false"
      :coupons="[
        { id: 'ro1', kind: 'gift', title: '黑卡专属 · 免费洗车', giftText: '每月 2 次', scope: '限绑定车牌', startAt: dayAt(0), endAt: dayAt(30) },
        { id: 'ro2', kind: 'discount', title: '黑卡专属 · 加油 9.2 折', discount: 0.92, startAt: dayAt(0) },
      ]"
    >
      <template #action-extra="{ status }">
        <span style="font-size: 12px; color: var(--el-text-color-placeholder)">{{ status === 'running' ? '自动发放至券包' : '敬请期待' }}</span>
      </template>
    </BizCouponCard>
  </div>
</template>

显示代码

插槽

领券中心

满减券¥40满 199 元可用

可分享的满减券领取中

2026-10-26 ~ 2026-11-04

分享好友，双方各得 50 积分 →

header-extra 标题区追加操作；card-extra 券卡底部追加分享入口（作用域含 coupon 与派生状态）。

<script setup lang="ts">
/** 插槽：header-extra 标题区刷新按钮 + card-extra 券卡底部追加「分享赚积分」入口 */
import { ref } from 'vue'
import { BizCouponCard } from 'vue3-ep-biz-lib'
import { ElMessage } from 'element-plus'

const pad = (n: number) => String(n).padStart(2, '0')
const dayAt = (offset: number) => {
  const d = new Date()
  d.setDate(d.getDate() + offset)
  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
}

const count = ref(0)
</script>

<template>
  <div style="max-width: 760px">
    <BizCouponCard
      :coupons="[
        { id: 'sl1', kind: 'cash', title: '可分享的满减券', threshold: 199, amount: 40, startAt: dayAt(0), endAt: dayAt(9) },
      ]"
    >
      <template #header-extra>
        <el-button size="small" plain @click="count++; ElMessage.success('券列表已刷新')">刷新（{{ count }}）</el-button>
      </template>
      <template #card-extra="{ coupon }">
        <a style="font-size: 12px; color: var(--el-color-primary); cursor: pointer" @click="ElMessage.success(`分享 ${coupon.title} 成功`)">
          分享好友，双方各得 50 积分 →
        </a>
      </template>
    </BizCouponCard>
  </div>
</template>

显示代码

已领视角

我的券包 · 可再领

满减券¥8满 25 元可用

早餐满减券（已领 2/3）领取中

2026-10-24 ~ 2026-11-07

50%

已领 402 / 800张

已领 2 张

折扣券9折无门槛享折扣

午后咖啡 9 折（已领满）领取中

2026-10-24 ~ 2026-11-07

58%

已领 288 / 500张

已领 1 张

「我的券包」：mineCount>0 显示已领张数徽标，可再领 / 已领满两种按钮形态。

<script setup lang="ts">
/** 已领视角：mineCount>0 显示「已领 N 张」，首领后按钮文案变「再领一张」 */
import { BizCouponCard } from 'vue3-ep-biz-lib'

const pad = (n: number) => String(n).padStart(2, '0')
const dayAt = (offset: number) => {
  const d = new Date()
  d.setDate(d.getDate() + offset)
  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
}
</script>

<template>
  <div style="max-width: 760px">
    <BizCouponCard
      title="我的券包 · 可再领"
      :coupons="[
        { id: 'mc1', kind: 'cash', title: '早餐满减券（已领 2/3）', threshold: 25, amount: 8, limitPerUser: 3, mineCount: 2, total: 800, claimed: 402, startAt: dayAt(-2), endAt: dayAt(12) },
        { id: 'mc2', kind: 'discount', title: '午后咖啡 9 折（已领满）', discount: 0.9, limitPerUser: 1, mineCount: 1, total: 500, claimed: 288, startAt: dayAt(-2), endAt: dayAt(12) },
      ]"
    />
  </div>
</template>

显示代码

Props

属性名	类型	默认值	说明
title	string	'领券中心'	面板标题
coupons	BizCoupon[]	[]	券列表：{ id, kind, title, threshold?, amount?, discount?, giftText?, scope?, stackNote?, startAt?, endAt?, total?, claimed?, limitPerUser?, mineCount?, paused? }
claimable	boolean	true	允许领取操作；false 为只读营销位（配合 action-extra 槽位）
claim-request	(coupon) => Promise<void>	—	领取请求（远程模式，失败时本地不计数）
show-progress	boolean	true	展示库存进度条
expiring-days	number	3	临期提醒阈值（天）

Events

事件名	参数	说明
claim	(payload: BizCouponClaimPayload, coupon)	领取点击（先于 claimRequest 外抛）

Slots

插槽名	说明
header-extra	{ coupons } 标题区右侧追加
card-extra	{ coupon, status } 券卡信息区底部追加
action-extra	{ coupon, status } 仅 claimable=false 时渲染，替代领取按钮区

Expose

属性/方法	说明
reset	() => void 重置为 props.coupons 初始状态（本地模式）
statusOf	(couponId: string) => BizCouponStatus 指定券当前派生状态

口径说明

• 状态派生优先级：paused > 未开始（now < startAt）> 已结束（now > endAt）> 已领完（claimed ≥ total）> 领取中。
• 折扣展示：discount: 0.85 渲染为「8.5折」（×10 后最多一位小数）。
• 临期口径：仅「领取中」状态参与，剩余天数 = ⌈(endAt − now) / 天⌉，≤ expiring-days 红标提示。
• 限领口径：limitPerUser: 0 视为不限量；领取成功后 mineCount / claimed 同步 +1（远程模式在 request 成功后）。