HeroBanner (首屏横幅)

用于展示网站主要内容区域，支持倒计时、视频播放、多按钮配置和响应式设计。【✅ 已发布】

场景:

视口:

加载中...

当前视口: 1920px × 600px场景: 基础图片 Banner

打开链接

功能特性

✅ 响应式设计：支持 PC、Pad、Mobile 三端图片和视频适配，自动切换媒体资源
✅ 主题切换：支持亮色 (light) 和暗色 (dark) 两种主题风格
✅ 媒体支持：支持图片和视频背景，可按设备切换，支持视频自动播放和静音控制
✅ 倒计时功能：支持设置结束时间和时区，倒计时结束时自动隐藏
✅ GSAP 动画：内置滚动触发动画效果 (ScrollTrigger)，支持标题渐显和视差效果
✅ 视频模态框：支持原生视频和 YouTube 视频播放，点击按钮弹出模态框
✅ 双按钮配置：支持主按钮和次要按钮，次要按钮可配置为视频播放按钮
✅ 底部产品列表：支持显示产品特性标签列表 (caption)
✅ IntersectionObserver：智能视频播放控制，进入视口自动播放，离开时暂停
✅ 语义化样式：支持 7 个语义化 classNames 自定义样式，灵活控制每个部分

Props 参数

HeroBannerProps

Prop	类型	默认值	必需	说明
`data`	`HeroBannerData`	-	✅	HeroBanner 的数据对象
`className`	`string`	-	-	添加到根容器的自定义类名
`classNames`	`Partial<Record<HeroBannerSemanticName, string>>`	-	-	语义化类名对象，支持 7 个部分的自定义样式
`onPrimaryClick`	`(data: any, e: any) => void`	-	-	主按钮点击回调函数
`onSecondaryClick`	`(data: any, e: any) => void`	-	-	次要按钮点击回调函数

HeroBannerData 对象

参数	类型	默认值	必需	说明
`title`	`string`	-	✅	主标题，支持 HTML 标签（如 `<span>`）
`subtitle`	`string`	-	✅	副标题文本
`pcImage`	`Media`	-	✅	PC 端图片对象
`mobileImage`	`Media`	-	✅	移动端图片对象
`theme`	`'light' \| 'dark'`	`'light'`	-	主题风格
`size`	`'default' \| 'sm'`	`'default'`	-	尺寸大小，sm 适用于较小高度的横幅
`padImage`	`Media`	-	-	Pad 端图片对象，未设置时使用 pcImage
`pcVideo`	`Media`	-	-	PC 端视频对象
`padVideo`	`Media`	-	-	Pad 端视频对象
`mobileVideo`	`Media`	-	-	移动端视频对象
`isShowVideo`	`boolean`	`false`	-	是否显示视频背景
`primaryButton`	`PrimaryButtonConfig`	-	-	主按钮配置对象
`secondaryButton`	`SecondaryButtonConfig`	-	-	次要按钮配置对象
`endDate`	`string`	-	-	倒计时结束时间 (ISO 8601 格式)
`endDate_tz`	`string`	-	-	倒计时时区 (如 ‘Asia/Shanghai’)
`caption`	`Array<{title: string}>`	-	-	底部产品特性列表
`isShowTitle`	`boolean`	`true`	-	是否显示标题
`isCountdown`	`boolean`	`true`	-	是否启用倒计时

Media 类型


interface Media {
  url: string        // 媒体资源 URL
  alt: string        // 替代文本（用于无障碍访问）
  mimeType?: string  // MIME 类型（如 'image/jpeg', 'video/mp4'）
}

按钮配置

PrimaryButtonConfig：


{
  text: string       // 按钮文本
  link?: string      // 跳转链接
  ...ButtonProps     // Button 组件的其他 props（如 variant, size 等）
}

SecondaryButtonConfig：


{
  text?: string                  // 按钮文本
  link?: string                  // 跳转链接
  isShowPlayVideoButton?: boolean // 是否显示为视频播放按钮
  videoUrl?: Media               // 原生视频 URL（用于模态框）
  youtubeId?: string             // YouTube 视频 ID
  ...ButtonProps                 // Button 组件的其他 props
}

使用示例

最简示例


import { HeroBanner } from '@anker-in/headless-ui/biz'
import scenarios from './scenarios.json'
 
const data = {
  title: '欢迎来到我们的网站',
  subtitle: '探索最新的科技产品',
  theme: 'light',
  pcImage: {
    url: 'https://images.unsplash.com/photo-1...',
    alt: 'Hero banner background'
  },
  mobileImage: {
    url: 'https://images.unsplash.com/photo-2...',
    alt: 'Hero banner mobile background'
  },
}
 
<HeroBanner data={data} />

带倒计时和按钮


const data = {
  title: '新年特惠 <span>限时抢购</span>',
  subtitle: '全场最高优惠 50%',
  theme: 'dark',
  endDate: '2025-12-31T23:59:59.000Z',
  endDate_tz: 'Asia/Shanghai',
  pcImage: { url: '...', alt: '...' },
  mobileImage: { url: '...', alt: '...' },
  primaryButton: {
    text: '立即抢购',
    link: '/products',
    variant: 'primary',
    size: 'lg',
  },
  secondaryButton: {
    text: '了解详情',
    link: '/about',
    variant: 'outline',
  },
}
 
<HeroBanner data={data} />

带视频背景


const data = {
  title: '体验未来科技',
  subtitle: '智能生活从这里开始',
  pcImage: { url: '...', alt: '...' },
  mobileImage: { url: '...', alt: '...' },
  pcVideo: {
    url: 'https://example.com/video.mp4',
    alt: 'Product showcase video',
    mimeType: 'video/mp4',
  },
  isShowVideo: true, // 开启视频背景
  primaryButton: { text: '立即购买', link: '/shop' },
}
 
<HeroBanner data={data} />

自定义样式


<HeroBanner
  data={data}
  className="my-custom-banner"
  classNames={{
    root: 'min-h-[600px]',
    title: 'text-6xl font-bold',
    subtitle: 'text-xl opacity-90',
    buttonGroup: 'gap-6',
    primaryButton: 'shadow-lg hover:shadow-xl',
  }}
  onPrimaryClick={(data, e) => {
    console.log('Primary button clicked:', data)
    // 自定义点击处理逻辑
  }}
/>

语义化 ClassNames 参数

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

参数名	描述	使用说明
`root`	组件根容器	用于自定义整个 HeroBanner 组件的外层样式
`title`	主标题元素	用于自定义主标题的样式，如字体大小、颜色等
`subtitle`	副标题元素	用于自定义副标题的样式
`buttonGroup`	按钮组容器	用于自定义按钮组的布局和间距
`primaryButton`	主要按钮	用于自定义主要按钮的样式
`secondaryButton`	次要按钮	用于自定义次要按钮的样式
`captionGroup`	底部产品列表容器	用于自定义底部产品列表的布局样式

常见问题

如何切换主题？

通过 data.theme 属性设置主题，支持 'light'（亮色）和 'dark'（暗色）两种主题：


const data = {
  theme: 'dark', // 或 'light'
  // ...其他配置
}

倒计时结束后会发生什么？

当倒计时到达 endDate 设置的时间后，倒计时组件会自动隐藏。标题、副标题和按钮仍然正常显示。如需完全隐藏整个横幅，请在父组件中监听时间变化并控制渲染。

视频何时播放？

自动播放：当 isShowVideo: true 时，视频背景会在页面加载后自动播放（静音模式）
IntersectionObserver 控制：当横幅进入视口时播放，离开时暂停，节省资源
模态框视频：点击次要按钮（配置了 videoUrl 或 youtubeId）时弹出模态框播放

如何使用 YouTube 视频？

在 secondaryButton 中配置 youtubeId，点击按钮将打开 YouTube 视频模态框：


secondaryButton: {
  text: '观看视频',
  isShowPlayVideoButton: true,
  youtubeId: 'dQw4w9WgXcQ', // YouTube 视频 ID
}

如何自定义按钮样式？

使用 classNames 自定义按钮样式，或在按钮配置中传入 Button 组件的 props：


// 方法 1: 使用 classNames
classNames={{
  primaryButton: 'bg-red-500 hover:bg-red-600',
}}
 
// 方法 2: 在按钮配置中传入 props
primaryButton: {
  text: '立即购买',
  variant: 'primary',
  size: 'lg',
  className: 'shadow-2xl',
}

不同设备如何自动切换图片/视频？

组件会根据当前设备自动选择对应的媒体资源：

Mobile（<768px）: 使用 mobileImage 和 mobileVideo
Tablet（768px-1024px）: 使用 padImage 和 padVideo（未设置时回退到 pcImage/pcVideo）
Desktop（≥1025px）: 使用 pcImage 和 pcVideo

如何实现多个 Banner 堆叠？

将多个 HeroBanner 组件放在同一个父容器中，组件的 IntersectionObserver 会自动管理每个横幅的视频播放状态：


<div>
  <HeroBanner data={data1} />
  <HeroBanner data={data2} />
  <HeroBanner data={data3} />
</div>

点击事件如何处理？

使用 onPrimaryClick 和 onSecondaryClick 回调函数处理按钮点击事件：


<HeroBanner
  data={data}
  onPrimaryClick={(data, event) => {
    // data: 传入的 HeroBannerData 对象
    // event: 原生点击事件
    console.log('主按钮点击', data.primaryButton?.link)
    // 自定义处理逻辑（如数据埋点、跳转拦截等）
  }}
  onSecondaryClick={(data, event) => {
    console.log('次要按钮点击')
  }}
/>