Skip to Content
@anker-in/headless-ui 2.0 is released 🎉
业务组件🌟 通用组件次级横幅

SecondaryBanner (次级横幅)

用于二级页面的主要视觉区域，支持4种尺寸变体、响应式媒体和倒计时功能。【✅ 已发布】

加载中...
当前视口: 1920px × 600px场景: 基础尺寸双按钮横幅
打开链接

功能特性

  • ✅ 4种尺寸变体 - sm(筛选页)、base(默认)、lg(专题页)、xlg(活动通栏)，满足不同场景需求
  • ✅ 响应式媒体 - 支持PC/Pad/Mobile独立媒体资源，自动适配当前设备
  • ✅ 视频背景 - 支持视频背景，自动静音循环播放
  • ✅ 倒计时功能 - 支持活动倒计时，可配置时区和日期格式
  • ✅ 双按钮配置 - 支持主按钮和次级按钮，灵活满足不同交互需求
  • ✅ 品牌图标列表 - 支持显示品牌图标数组，增强品牌展示
  • ✅ 主题支持 - 支持亮色(light)和暗色(dark)两种主题
  • ✅ 语义化类名 - 支持8个语义化classNames自定义样式
  • ✅ 完整ARIA支持 - 使用语义化标签和ARIA属性，支持无障碍访问

Props 参数

SecondaryBannerProps

Prop类型默认值必需说明
dataSecondaryBannerData-✅SecondaryBanner数据配置对象
classNamestring''-自定义根容器类名
classNamesPartial<Record<SemanticName, string>>--语义化类名对象，支持8个部分的自定义样式

SecondaryBannerData 配置

参数类型默认值必需说明
titlestring-✅主标题文本，支持HTML
size'sm' | 'base' | 'lg' | 'xlg''base'-横幅尺寸变体
pcImageMedia--PC端图片或视频
padImageMedia--Pad端图片或视频
mobileImageMedia--移动端图片或视频
superTitlestring--上标题文本
subtitlestring--副标题文本
primaryButtonButtonConfig--主按钮配置
secondaryButtonButtonConfig--次级按钮配置
endDatestring--倒计时结束时间(ISO 8601格式)
endDate_tzstring--倒计时时区(如’Asia/Shanghai’)
dateFormatstring--倒计时日期格式(JSON字符串)
brandIconsImg[]--品牌图标数组
theme'light' | 'dark''light'-主题模式

Media 类型

interface Media {
  url: string        // 媒体资源URL
  alt: string        // 替代文本
  mimeType?: string  // MIME类型(如'video/mp4')
}

ButtonConfig 类型

interface ButtonConfig {
  text: string           // 按钮文本
  link?: string          // 跳转链接
  onClick?: () => void   // 点击回调
  ...ButtonProps         // Button组件的其他props
}

使用示例

最简示例

import { SecondaryBanner } from '@anker-in/headless-ui/biz'
 
<SecondaryBanner
  data={{
    title: 'New Collection',
    mobileImage: {
      url: 'https://images.unsplash.com/photo-...',
      alt: 'Collection banner',
    },
  }}
/>

基础横幅

<SecondaryBanner
  data={{
    title: 'Flash Sale',
    subtitle: 'Up to 50% Off',
    size: 'base',
    pcImage: {
      url: 'https://images.unsplash.com/photo-...',
      alt: 'Flash sale banner',
    },
    mobileImage: {
      url: 'https://images.unsplash.com/photo-...',
      alt: 'Flash sale banner mobile',
    },
    primaryButton: {
      text: 'Shop Now',
      link: '/sale',
    },
  }}
/>

带倒计时的活动横幅

<SecondaryBanner
  data={{
    title: 'Black Friday Sale',
    superTitle: 'Limited Time Offer',
    subtitle: 'Hurry! Sale Ends Soon',
    size: 'lg',
    endDate: '2025-11-30T23:59:59.000Z',
    endDate_tz: 'America/New_York',
    dateFormat: JSON.stringify({
      day: 'Days',
      hour: 'Hours',
      minute: 'Min',
      second: 'Sec',
    }),
    pcImage: {
      url: 'https://images.unsplash.com/photo-...',
      alt: 'Black Friday',
    },
    primaryButton: {
      text: 'Shop Now',
      link: '/black-friday',
    },
    secondaryButton: {
      text: 'Learn More',
      link: '/about-sale',
    },
  }}
/>

视频背景横幅

<SecondaryBanner
  data={{
    title: 'Experience the Future',
    size: 'xlg',
    pcImage: {
      url: 'https://cdn.example.com/hero-video.mp4',
      alt: 'Hero video',
      mimeType: 'video/mp4',
    },
    primaryButton: {
      text: 'Watch Demo',
      onClick: () => {
        console.log('Demo clicked')
      },
    },
  }}
/>

小尺寸(筛选页)

<SecondaryBanner
  data={{
    title: 'Power Banks Collection',
    subtitle: 'Find your perfect charging solution',
    size: 'sm',
    pcImage: {
      url: 'https://images.unsplash.com/photo-...',
      alt: 'Power banks',
    },
  }}
/>

尺寸变体说明

size: ‘sm’ (小尺寸 - 筛选页)

宽高比:

  • Mobile: 390×480 (390:480)
  • Tablet: 768×480 (768:480)
  • Laptop: 1024×400 (1024:400)
  • Desktop: 1440×384 (1440:384)
  • LG Desktop: 1920×480 (1920:480)

适用场景: 产品列表页、筛选页、分类页

size: ‘base’ (基础尺寸 - 默认)

宽高比:

  • Mobile: 390×660 (390:660)
  • Tablet: 768×660 (768:660)
  • Laptop: 1024×432 (1024:432)
  • Desktop: 1440×576 (1440:576)
  • LG Desktop: 1920×720 (1920:720)

适用场景: 通用二级页面、产品详情页

size: ‘lg’ (大尺寸 - 专题页)

宽高比:

  • Mobile: 390×660 (390:660)
  • Tablet: 768×660 (768:660)
  • Laptop: 1024×520 (1024:520)
  • Desktop: 1440×700 (1440:700)
  • LG Desktop: 1920×930 (1920:930)

适用场景: 品牌专题页、活动专题页

size: ‘xlg’ (超大尺寸 - 活动页通栏)

宽高比: 同 lg,但允许内容溢出

适用场景: 活动落地页、营销页面

响应式行为

内容定位

组件在不同断点下的内容定位：

断点定位方式水平边距垂直定位
Mobile顶部固定16pxtop: 48px
Tablet顶部固定32pxtop: 48px
Laptop+垂直居中64pxtop: 50% + transform
LG Desktop垂直居中calc(50%-832px)top: 50% + transform

文本尺寸

元素移动端平板桌面大屏
superTitle14px14px16px18px
title (base/sm)size=4size=4size=4size=4
title (lg/xlg)size=5size=5size=5size=5
subtitle14px14px16px18px

按钮组间距

  • 移动端/平板: mt-6 gap-2
  • 大屏: lg-desktop:mt-[32px] lg-desktop:gap-3

设计规范

尺寸选择指南

  • sm: 适合产品列表页、筛选页顶部横幅，内容简洁
  • base: 默认尺寸，适合大多数二级页面
  • lg: 适合品牌专题页、活动专题页，需要突出视觉冲击力
  • xlg: 适合活动落地页通栏设计，允许背景图延伸到容器外

媒体资源建议

图片要求:

  • PC: 推荐尺寸 1920×720px (根据size调整)
  • Pad: 推荐尺寸 768×660px
  • Mobile: 推荐尺寸 390×660px
  • 格式: JPG/PNG/WebP
  • 大小: 建议 < 500KB

视频要求:

  • 格式: MP4 (H.264编码)
  • 大小: 建议 < 5MB
  • 时长: 建议 10-30秒循环
  • 必须设置: mimeType: 'video/mp4'

倒计时配置

倒计时dateFormat使用JSON字符串格式:

dateFormat: JSON.stringify({
  day: 'Days',
  hour: 'Hours',
  minute: 'Min',
  second: 'Sec'
})

语义化 ClassNames 参数

SecondaryBanner组件支持语义化的classNames属性，允许你为组件的不同部分自定义样式：

参数名描述使用说明
root组件根容器用于自定义整个SecondaryBanner组件的外层样式
title主标题元素用于自定义主标题的样式
superTitle上标题元素用于自定义上标题的样式
subtitle副标题元素用于自定义副标题的样式
content内容容器用于自定义内容区域的布局和定位
buttonGroup按钮组容器用于自定义按钮组的布局和间距
primaryButton主按钮用于自定义主按钮的样式
secondaryButton次级按钮用于自定义次级按钮的样式

示例:

<SecondaryBanner
  data={{...}}
  classNames={{
    root: 'custom-banner',
    title: 'custom-title',
    superTitle: 'custom-super-title',
    subtitle: 'custom-subtitle',
    content: 'custom-content',
    buttonGroup: 'custom-button-group',
    primaryButton: 'custom-primary',
    secondaryButton: 'custom-secondary'
  }}
/>

无障碍性

ARIA 支持

  • ✅ 使用 &lt;section role="banner"&gt; 语义化标签
  • ✅ 自动生成唯一ID(useId())用于ARIA关联
  • ✅ 主标题使用 aria-labelledby 关联
  • ✅ 副标题和上标题使用 aria-describedby 关联
  • ✅ 倒计时使用 role="timer" 和 aria-label
  • ✅ 图标组使用 role="group" 和 aria-label="brand icons"
  • ✅ 按钮自动关联标题(aria-describedby={titleId})
  • ✅ 所有图片必须有 alt 属性

ARIA 结构示例

<section role="banner" aria-labelledby="banner-title" aria-describedby="banner-super banner-subtitle">
  <h1 id="banner-title">Main Title</h1>
  <p id="banner-super">Super Title</p>
  <p id="banner-subtitle">Subtitle</p>
  <div role="timer" aria-label="event countdown">...</div>
  <button aria-describedby="banner-title">Shop Now</button>
</section>

键盘导航

  • ✅ 所有按钮可通过键盘访问
  • ✅ Tab键切换焦点
  • ✅ Enter键触发按钮点击

性能优化

  • ✅ Ref转发 - 使用 React.forwardRef() 支持ref转发
  • ✅ 媒体懒加载 - 通过Media组件实现图片/视频懒加载
  • ✅ 视频优化 - 视频自动静音循环，减少资源消耗
  • ✅ 条件渲染 - 减少不必要的DOM节点
  • ✅ CVA优化 - 使用class-variance-authority优化类名计算

常见问题

如何只提供移动端图片,桌面端自动适配?

可以只提供 mobileImage,Media组件会自动将其作为fallback:

data={{
  mobileImage: { url: '...', alt: '...' }
  // pcImage和padImage为空时自动使用mobileImage
}}

倒计时的dateFormat如何配置?

使用JSON字符串格式:

dateFormat: JSON.stringify({
  day: 'Days',
  hour: 'Hours',
  minute: 'Min',
  second: 'Sec'
})

如何隐藏次级按钮?

不传 secondaryButton 或设置 text 为空:

data={{
  primaryButton: { text: 'Shop Now' }
  // 不传secondaryButton
}}

视频背景无法自动播放?

确保 mimeType 设置正确:

pcImage: {
  url: 'https://example.com/video.mp4',
  alt: 'Background video',
  mimeType: 'video/mp4'  // 必需
}

组件会自动设置 muted, loop, playsInline, autoPlay 属性。

xlg尺寸的overflow-visible作用?

xlg 尺寸允许内容溢出容器,适合活动页通栏设计,背景图可以延伸到容器外。

如何自定义倒计时样式?

倒计时使用 HeroBanner/Countdown 组件,可以通过全局CSS覆盖 .banner-countdown 类的样式。

按钮如何同时支持链接和点击事件?

两者可以同时配置:

primaryButton: {
  text: 'Shop Now',
  link: '/sale',           // 作为<a>标签的href
  onClick: () => {         // 点击时先触发onClick
    trackEvent('banner_click')
  }
}

相关资源

Last updated on
跑马灯标语