Category (Category)

用于展示产品分类，支持响应式设计和多种布局形式。【✅ 已发布】

场景:

视口:

加载中...

当前视口: 1920px × 600px场景: 默认6列布局

打开链接

功能特性

✅ 响应式设计 - PC 端轮播展示，移动端适配不同数量的卡片布局
✅ 形状切换 - 支持方形（square）和圆形（round）两种卡片样式
✅ 智能布局 - 根据分类数量自动调整移动端布局（≤5个为首项放大，>5个为紧凑列表）
✅ 轮播功能 - 内置 Swiper 滑动功能，支持无限循环
✅ 悬停效果 - PC 端卡片悬停时自动缩放和背景变化
✅ 曝光埋点 - 内置曝光追踪功能，自动上报用户浏览行为
✅ 点击追踪 - 自动追踪用户点击行为和位置信息
✅ 主题支持 - 支持亮色（light）和暗色（dark）两种主题
✅ 可选标题 - 支持显示组件标题

Props 参数

CategoryProps

Prop	类型	默认值	必需	说明
`data`	`CategoryData`	-	✅	分类数据配置对象
`className`	`string`	`''`	-	自定义根容器类名
`event`	`CategoryEvent`	-	-	事件回调对象
`buildData`	`BuildData`	-	-	构建时的额外数据
`key`	`string`	-	-	React key 属性

CategoryData 配置

参数	类型	默认值	必需	说明
`products`	`CategoryItem[]`	-	✅	分类列表数据
`isShowSelect`	`boolean`	-	✅	是否显示选中状态（用于控制显示 products 还是 productData）
`productData`	`CategoryItem[]`	`[]`	-	备用分类列表（当 isShowSelect 为 false 时使用）
`shape`	`'round' \| 'square'`	`'square'`	-	卡片形状
`title`	`string`	-	-	组件标题
`theme`	`'light' \| 'dark'`	`'light'`	-	主题模式

CategoryItem 配置

参数	类型	必需	说明
`name`	`string`	✅	分类名称
`image`	`Img`	✅	分类图片
`link`	`string`	-	分类链接地址

CategoryEvent 配置

参数	类型	说明
`primaryButton`	`(data: any, index: number) => void`	点击分类卡片的回调函数

使用示例

最简示例


import { Category } from '@anker-in/headless-ui/biz'
 
<Category
  data={{
    isShowSelect: true,
    productData: [],
    products: [
      {
        name: 'Power Banks',
        image: {
          url: 'https://images.unsplash.com/photo-1...',
          alt: 'Power Banks',
        },
        link: '/collections/power-banks',
      },
      {
        name: 'Chargers',
        image: {
          url: 'https://images.unsplash.com/photo-2...',
          alt: 'Chargers',
        },
        link: '/collections/chargers',
      },
      {
        name: 'Cables',
        image: {
          url: 'https://images.unsplash.com/photo-3...',
          alt: 'Cables',
        },
        link: '/collections/cables',
      },
    ],
  }}
/>

基础圆形卡片


<Category
  data={{
    isShowSelect: true,
    productData: [],
    shape: 'round',
    products: [
      {
        name: 'Power Banks',
        image: {
          url: 'https://images.unsplash.com/photo-...',
          alt: 'Power Banks',
        },
        link: '/collections/power-banks',
      },
      {
        name: 'Chargers',
        image: {
          url: 'https://images.unsplash.com/photo-...',
          alt: 'Chargers',
        },
        link: '/collections/chargers',
      },
    ],
  }}
/>

带标题的分类展示


<Category
  data={{
    title: 'Shop by Category',
    isShowSelect: true,
    productData: [],
    shape: 'round',
    products: categories,
    theme: 'light',
  }}
/>

带点击事件


<Category
  data={{
    isShowSelect: true,
    productData: [],
    products: categories,
  }}
  event={{
    primaryButton: (data, index) => {
      console.log('Clicked category:', data.name, 'at position:', index)
      // 自定义导航逻辑
      router.push(data.link)
    },
  }}
/>

暗色主题


<Category
  data={{
    title: 'Browse Categories',
    isShowSelect: true,
    productData: [],
    shape: 'round',
    products: categories,
    theme: 'dark',
  }}
  className="bg-gray-900 py-16"
/>

响应式行为

断点说明

组件在不同设备上有不同的展示方式：

断点	屏幕宽度	展示方式	卡片尺寸
Mobile	< 768px	垂直布局/分页轮播	根据数量自适应
Tablet	≥ 768px	水平轮播	167×120 (图72×72)
Laptop	≥ 1025px	水平轮播	212×144 (图88×88)
Desktop	≥ 1440px	水平轮播	205×192 (图116×116)
LG Desktop	≥ 1920px	水平轮播	264×240 (图146×146)

移动端智能布局

根据分类数量自动选择最佳布局：

≤5 个分类：首项放大布局（2列网格，第一项占2行）
>5 个分类：紧凑列表布局（单列，每页3个，支持轮播）

这种智能布局确保在不同数量的分类下都能保持最佳的用户体验。

设计规范

卡片样式

方形卡片 (shape="square")：适合正式、商务场景，线条硬朗
圆形卡片 (shape="round")：适合时尚、年轻化场景，视觉柔和

主题选择

亮色主题 (theme="light")：用于浅色背景页面，文字为深色
暗色主题 (theme="dark")：用于深色背景页面，文字为浅色

图片要求

推荐尺寸：200×200px
格式：PNG/JPG/WebP
背景：透明或纯色，便于适配不同主题
内容：产品或分类代表图，清晰可辨

文案要求

分类名称：简短精炼，建议不超过10个字符
命名规范：使用用户熟悉的分类术语
语言一致：保持所有分类名称的语言风格一致

无障碍性

图片替代文本

✅ 所有图片包含 alt 属性（通过 Img 类型强制）
✅ alt 文本应准确描述分类内容
✅ 装饰性图片使用空 alt 属性

链接可访问性

✅ 链接包含 aria-label 属性
✅ 链接文本清晰描述目标页面
✅ 支持键盘导航（Tab 键访问）

语义化标签

✅ 卡片标题使用语义化标签（h3）
✅ 使用 <nav> 标签包裹导航列表
✅ 轮播控件可键盘操作

视觉反馈

✅ 悬停状态有明确的视觉反馈
✅ 焦点状态清晰可见
✅ 激活状态与其他状态区分明显

性能优化

✅ 组件优化 - 使用 React.memo() 优化子组件渲染
✅ 图片懒加载 - 通过 Picture 组件实现图片懒加载
✅ 曝光埋点 - 使用 IntersectionObserver 实现高性能曝光埋点
✅ 避免重渲染 - 合理使用 React 优化技巧，避免不必要的重渲染

常见问题

为什么需要同时提供 products 和 productData？

isShowSelect 用于控制显示哪组数据，这在需要动态切换分类数据时很有用（如基于用户选择的筛选条件）。通常情况下，只需要设置 products 并将 isShowSelect 设为 true，productData 可以留空。

移动端为什么有两种布局？

当分类数量 ≤5 个时，采用首项放大布局，让用户更容易看到主要分类；当分类数量 >5 个时，采用紧凑列表布局，提高浏览效率。这种设计基于用户体验研究，能够在不同场景下提供最佳的浏览体验。

如何禁用轮播功能？

轮播是内置功能，无法直接禁用。如果分类数量较少（≤4个），轮播会自动隐藏导航按钮。这是基于用户体验的设计决策，确保界面简洁。

卡片点击事件如何处理？

组件默认使用 <a> 标签进行导航。你可以通过 event.primaryButton 回调自定义点击行为，例如：


event={{
  primaryButton: (data, index) => {
    // 自定义逻辑，如埋点上报
    trackClick('category', data.name, index)
    // 然后导航
    router.push(data.link)
  }
}}

如何自定义卡片样式？

使用 className prop 传入自定义类名，组件支持 Tailwind CSS 样式覆盖。例如：


className="bg-gradient-to-r from-blue-50 to-purple-50 py-12"