一套面向通用电商网站的 响应式商品轮播 + 商品变体 + Quick Add 抽屉 前端组件。
项目使用原生 HTML、CSS、JavaScript 与本地 Swiper 构建，不依赖框架、不需要构建工具，重点解决商品列表中常见的 响应式展示、颜色变体切换、价格与库存同步、快速购买 等交互，同时为后续接入 WooCommerce 保留清晰的数据与事件边界。
这个项目不是完整商城，也不试图在商品卡片中复制商品详情页。
它更适合作为电商网站中的一个独立内容区块，用于：
- 首页精选商品
- 新品 / 热销商品
- 分类页推荐商品
- Related Products / You May Also Like
- 家居、服装、建材、家具、数码等不同商品类型
- WooCommerce 自定义主题或企业电商网站的前端组件
核心目标是：保持结构轻量、交互完整、方便复用，并为真实商品数据接入留出空间。
- 内容最大宽度：
1200px - 商品主图比例：
1:1 - 桌面端：4 个商品 / 屏
- 平板端：3 个商品 / 屏
- 手机端：2 个商品 / 屏
- 支持鼠标拖动与移动端触摸滑动
- 支持上一组 / 下一组导航
- Swiper CSS / JS 全部本地化，不依赖 CDN
- Sale / New 状态标签
- 商品名称与详情链接
- 原价 / 当前售价
- 颜色色卡与 Tooltip
- 当前色卡高亮
- 库存状态显示
- 桌面端 Hover 快捷操作
- 手机端固定触控操作区
点击色卡后可以同步更新：
- 商品主图
- 当前售价
- 原价
- 商品链接
- 库存状态
- Variation ID
- Quick Add 可用状态
色卡不只是视觉装饰，而是当前 Demo 中的 Variation 数据入口。
- 整个 Section 只创建 一个共享 Drawer
- 桌面端从右侧打开
- 手机端自动切换为底部 Bottom Sheet
- 自动继承当前商品与当前颜色状态
- Drawer 内切换颜色后同步回商品卡片
- 支持规格选择
- 支持数量增减与直接输入
- 缺货变体自动禁用加入购物车
- 提供完整商品详情入口
- 色卡使用
aria-label与aria-pressed - Drawer 支持
ESC关闭 - 支持点击遮罩关闭
- 打开 Drawer 后锁定背景滚动
- 关闭后恢复触发按钮焦点
- 提供基础焦点循环
- 支持
prefers-reduced-motion
| 视口宽度 | 每屏商品数 | 分组切换 | 商品间距 |
|---|---|---|---|
< 768px |
2 | 2 | 14px |
≥ 768px |
3 | 3 | 18px |
≥ 1024px |
4 | 4 | 20px |
商品图片始终保持：
aspect-ratio: 1 / 1;因此替换不同类型商品图片时，不需要重新计算卡片高度。
Product Card
│
├─ Current Variation
│ ├─ Image
│ ├─ Price
│ ├─ Stock
│ ├─ URL
│ └─ Variation ID
│
└─ Quick Add
│
↓
Shared Drawer
├─ Product
├─ Color
├─ Spec
├─ Quantity
└─ Add to Cart
所有商品共用一个 Drawer，而不是为每张商品卡片重复生成弹层。
这样可以减少 DOM 数量，也更适合以后商品数量增加或通过 WooCommerce 动态循环输出。
假设商品卡片当前选择：
浅胡桃
¥229.00
仅剩 6 件
Variation ID: 10102
点击 Quick Add 后，Drawer 会直接继承这一状态。
如果在 Drawer 中继续切换为其他颜色，商品卡片也会同步更新，并在关闭 Drawer 后保留最后一次选择。
项目没有维护两套独立的商品变体状态，从而避免出现：
商品卡片：颜色 A
Quick Add：颜色 B
这样的状态不一致问题。
当前项目使用色卡按钮上的 data-* 属性模拟真实商品变体：
<button
class="swatch"
data-image="images/product-01-02.svg"
data-name="浅胡桃"
data-price="¥229.00"
data-regular-price="¥279.00"
data-stock="low"
data-stock-text="仅剩 6 件"
data-url="..."
data-variation-id="10102"
aria-label="浅胡桃">
</button>主要字段：
| 字段 | 作用 |
|---|---|
data-image |
当前变体商品图片 |
data-name |
颜色 / 变体名称 |
data-price |
当前售价 |
data-regular-price |
原价 |
data-stock |
库存状态 |
data-stock-text |
库存提示文字 |
data-url |
当前商品 / 变体链接 |
data-variation-id |
Variation ID |
当前实现非常适合静态 Demo，也便于以后将这些数据替换为 WooCommerce 输出的真实 Variation 数据。
商品规格通过 .item 的 data-specs 提供，例如：
<article
class="swiper-slide item"
data-product-id="01"
data-specs="标准板|加宽板|长板">当前规格按钮主要用于演示通用 Quick Add UI。
需要注意：目前没有人为维护“颜色 × 规格”的完整 Variation 组合矩阵。
正式接入 WooCommerce 后，应直接读取 WooCommerce 已存在的 Variation 与 Attribute 数据，由真实变体关系决定：
颜色 × 尺寸 × 材质 × 其他属性
而不是继续维护一套静态组合表。
为了避免把 UI、Swiper 和未来的 WooCommerce 业务代码耦合在一起，当前项目预留了两个自定义事件。
当前商品变体发生变化时，由对应 .item 触发。
适合后续处理：
- SKU 更新
- 变体属性同步
- 库存校验
- Analytics
- WooCommerce Variation Adapter
点击 Drawer 中的“加入购物车”时，由 #section01 触发。
事件数据包含：
productId
variationId
color
spec
quantity
url
当前 Demo 只显示加入成功反馈，不会真正修改购物车。
后期可以在这里接入 WooCommerce AJAX Add to Cart。
推荐继续保持以下职责分离：
Swiper
└─ 只负责商品布局与滑动
Variation UI
└─ 负责图片 / 价格 / 库存 / 属性状态
Quick Add Drawer
└─ 负责快速选择与购买确认
WooCommerce Adapter
└─ 负责真实 Product / Variation / Cart 数据
- 使用 WooCommerce 商品循环输出
.item。 - 将商品主图、标题、价格与 URL 替换为真实商品数据。
- 读取 Variable Product 的 Variation 数据。
- 将真实变体数据映射到现有色卡 / 属性按钮。
- 使用真实
variation_id替代当前 Demo ID。 - 在
cart:add中接 WooCommerce AJAX Add to Cart。 - 加入成功后刷新 Mini Cart / Cart Fragments。
这种方式不需要修改 Swiper，也不需要重写 Drawer UI。
最外层固定使用：
<section id="section01">组件样式统一限定在：
#section01 ...内部类名尽量保持简短，例如：
.inner
.head
.slider
.item
.media
.pic
.info
.price
.colors
.drawer
.panel
如果后期需要在同一个页面复制多套组件，只需批量替换：
section01 → section02
即可形成新的独立 Section，降低与其他页面区块发生 CSS 冲突的概率。
responsive-product-carousel/
├── index.html
├── README.md
├── css/
│ ├── style.css
│ └── swiper-bundle.min.css
├── js/
│ ├── main.js
│ └── swiper-bundle.min.js
└── images/
└── product-*.svg
| 文件 | 作用 |
|---|---|
index.html |
商品卡片、Variation 数据与共享 Drawer 结构 |
css/style.css |
组件样式、响应式与 Drawer / Bottom Sheet |
js/main.js |
Swiper、变体同步、Drawer、数量与事件逻辑 |
swiper-bundle.* |
本地 Swiper 依赖 |
images/ |
Demo 商品与变体图片 |
项目不需要 npm、构建工具或本地服务器。
下载后直接打开：
index.html
即可预览。
如果需要迁移到其他项目，建议整体复制：
HTML Section
+ style.css 中对应 #section01 样式
+ main.js
+ Swiper 本地文件
然后替换商品数据与图片即可。
当前 Demo 使用 SVG 占位图。
正式项目中建议：
- 主图保持
1:1 - 同一商品不同颜色尽量保持统一拍摄角度
- 尽量统一背景、构图和留白
- JPG / WebP / AVIF 均可使用
- 图片本身无需强制裁成正方形，前端会通过
object-fit控制显示
对于服装、家具、家居、建材等不同商品类型，可以根据实际素材调整：
object-fit: cover;或：
object-fit: contain;这个项目刻意没有加入大型框架或复杂状态管理。
当前架构坚持几个原则：
- Swiper 只负责轮播
- 商品数据不写死在 Swiper 配置中
- 一个 Section 只使用一个共享 Drawer
- 商品卡片与 Drawer 使用同一 Variation 状态
- WooCommerce 逻辑通过 Adapter / Event 接入
- 不为了 Demo 提前模拟完整商城后端
因此后期即使商品数据来源发生变化，核心 UI 仍然可以继续复用。
本项目当前仍然是纯前端演示组件，以下功能尚未连接真实电商系统：
- 不读取真实商品数据库
- 不校验服务器端库存
- 不生成真实购物车记录
- 不处理登录用户购物车
- 不处理优惠券、税费、运费
- 不维护完整 WooCommerce Variation 矩阵
- 收藏 / 对比等按钮目前仅作为 UI 演示
这些内容应在真正接入 WooCommerce 时处理，而不是继续堆积在当前前端 Demo 中。
如果作为真实 WooCommerce 项目继续开发，建议优先级如下：
- WooCommerce Variation 数据接入
- AJAX Add to Cart
- Mini Cart / Cart Fragments 更新
- Variable Product 属性组合校验
- SKU 与库存信息同步
- Wishlist / Compare 等可选功能
不建议继续在 Quick Add Drawer 中加入长描述、评价、推荐商品或复杂 Gallery；这些内容更适合完整商品详情页。
HTML5
CSS3
Vanilla JavaScript
Swiper.js
无框架、无构建流程、无远程 CDN，适合直接学习、修改、迁移和二次开发。