Marquee (跑马灯)

用于展示无限循环滚动的内容，支持图片和文本，基于 Swiper 实现【✅ 已发布】

场景:

视口:

加载中...

当前视口: 1920px × 600px场景: 混合内容轮播

打开链接

功能特性

✅ 无限循环 - 内容自动无缝循环滚动，无停顿感
✅ 双内容类型 - 支持图片（image）和文本（text）两种内容
✅ 自动播放 - 自动持续滚动，无需手动操作
✅ 方向控制 - 支持正向和反向滚动
✅ 速度可调 - 自定义滚动速度（默认3000ms）
✅ 响应式设计 - 移动端和桌面端自动调整高度和间距
✅ 禁用交互 - 禁止触摸和鼠标拖动，保持流畅滚动
✅ 曝光埋点 - 内置曝光追踪功能
✅ 富文本支持 - 文本内容支持 HTML 格式

Props 参数

MarqueeProps

Prop	类型	默认值	必需	说明
`data`	`MarqueeData`	-	✅	跑马灯数据配置对象
`className`	`string`	`''`	-	自定义根容器类名

MarqueeData 配置

参数	类型	默认值	必需	说明
`items`	`MarqueeItemData[]`	-	✅	跑马灯内容列表
`key`	`string`	-	-	Swiper 唯一标识
`reverseDirection`	`boolean`	`false`	-	是否反向滚动
`speed`	`number`	`3000`	-	滚动速度（毫秒）

MarqueeItemData 配置

参数	类型	必需	说明
`type`	`'image' \| 'text'`	✅	内容类型
`image`	`Img`	-	图片数据（type为image时必需）
`text`	`string`	-	文本内容（type为text时必需）
`id`	`string`	-	项目唯一标识

使用示例

最简示例


import { Marquee } from '@anker-in/headless-ui/biz'
import scenarios from './scenarios.json'
 
<Marquee
  data={{
    items: [
      {
        type: 'image',
        image: {
          url: 'https://images.unsplash.com/photo-1614292247047-a966dd17c2e3',
          alt: 'Brand Logo 1',
        },
      },
      {
        type: 'text',
        text: '100 Million<br />Global Customers',
      },
      {
        type: 'image',
        image: {
          url: 'https://images.unsplash.com/photo-1558618666-fcd25c85cd64',
          alt: 'Brand Logo 2',
        },
      },
    ],
  }}
/>

纯图片跑马灯


<Marquee
  data={{
    items: [
      {
        type: 'image',
        image: {
          url: 'https://images.unsplash.com/photo-1614292247047-a966dd17c2e3',
          alt: 'Partner Logo 1',
        },
      },
      {
        type: 'image',
        image: {
          url: 'https://images.unsplash.com/photo-1558618666-fcd25c85cd64',
          alt: 'Partner Logo 2',
        },
      },
      {
        type: 'image',
        image: {
          url: 'https://images.unsplash.com/photo-1609091839311-d5365f9ff1c5',
          alt: 'Partner Logo 3',
        },
      },
    ],
  }}
/>

纯文本跑马灯


<Marquee
  data={{
    items: [
      { type: 'text', text: '47%<br />R&D Employees' },
      { type: 'text', text: '100 Million<br />Global Customers' },
      { type: 'text', text: 'Pioneering in Charging<br />Technology for 12 Years' },
    ],
  }}
/>

图文混合跑马灯


<Marquee
  data={{
    items: [
      {
        type: 'image',
        image: {
          url: 'https://images.unsplash.com/photo-1565688534245-05d6b5be184a',
          alt: 'Award Icon',
        },
      },
      { type: 'text', text: 'Award Winning Brand' },
      {
        type: 'image',
        image: {
          url: 'https://images.unsplash.com/photo-1600783245777-2e60b4a4d2c5',
          alt: 'Global Icon',
        },
      },
      { type: 'text', text: 'Serving 100+ Countries' },
    ],
  }}
/>

反向滚动


<Marquee
  data={{
    reverseDirection: true,
    items: [
      { type: 'text', text: 'Trusted by Millions' },
      { type: 'text', text: 'Innovation Leader' },
      { type: 'text', text: 'Quality First' },
    ],
  }}
/>

自定义速度


<Marquee
  data={{
    speed: 5000, // 更慢的滚动速度
    items: brandLogos,
  }}
/>

响应式行为

断点说明

组件在不同设备上的尺寸调整：

断点	屏幕宽度	容器高度	图片宽度	项目间距
Mobile	< 1025px	48px	72px	24px
Laptop+	≥ 1025px	80px	120px	64px

滚动特性

速度：默认 3000ms（完整过渡时间）
延迟：无延迟（delay: 0），连续滚动
循环：内容自动复制3次，确保无缝循环
触摸：禁用触摸和鼠标拖动交互

设计规范

内容类型选择

图片类型 (type="image"):

适用场景：品牌Logo墙、合作伙伴、认证标志
推荐尺寸：120×80px（会自动适配容器）
格式：PNG/SVG（透明背景）
对齐方式：居中对齐

文本类型 (type="text"):

适用场景：数据展示、品牌口号、成就亮点
文字处理：支持 HTML 换行（<br>）
对齐方式：居中对齐
字体样式：中等字重，1.2 行高

性能建议

项目数量:

最少建议：3-4 个项目（确保视觉连续性）
最多建议：10-15 个项目（避免过长滚动）

图片优化:

使用压缩后的图片
推荐 WebP 格式
设置合适的 alt 文本

速度设置:

快速：2000-3000ms（信息密集场景）
中速：3000-5000ms（默认，推荐）
慢速：5000-8000ms（需要仔细查看内容）

无障碍性

图片替代文本

✅ 所有图片包含 alt 属性（通过 Img 类型强制）
✅ alt 文本应描述图片内容或品牌名称
✅ Logo图片使用品牌名称作为 alt

语义化标签

✅ 文本内容使用语义化标签
✅ 禁用触摸交互，避免意外中断滚动
✅ 颜色对比度符合标准

建议改进

⚠️ 添加 aria-label 描述跑马灯用途
⚠️ 添加 role="marquee" 语义角色
⚠️ 提供暂停按钮（可选）

性能优化

✅ Ref 转发 - 使用 React.forwardRef() 支持 ref 转发
✅ Ref 优化 - 使用 useImperativeHandle() 优化 ref 暴露
✅ 无缝循环 - 内容自动复制3次，确保无缝循环
✅ CSS 动画 - 使用 ease-linear，性能优于 JavaScript
✅ 图片懒加载 - 通过 Picture 组件实现
✅ 曝光埋点 - IntersectionObserver 实现高性能埋点

常见问题

为什么需要复制内容3次？

Swiper 的 loop 模式需要足够的 slides 才能实现无缝循环。组件自动复制内容3次（原始 + 2份副本），确保在任何项目数量下都能流畅循环。

如何调整滚动速度？

通过 speed 属性设置滚动速度（单位：毫秒）。数值越大，滚动越慢。默认3000ms适合大多数场景。


// 快速滚动
<Marquee data={{ speed: 2000, items: [...] }} />
 
// 慢速滚动
<Marquee data={{ speed: 6000, items: [...] }} />

可以暂停滚动吗？

默认不支持暂停。如需暂停功能，可以通过 ref 访问 Swiper 实例，调用 autoplay.stop() 和 autoplay.start() 方法。

为什么禁用触摸交互？

跑马灯通常用于展示而非交互。禁用触摸可以：

保持连续滚动，不被打断
避免用户误触
提供一致的视觉体验

图片和文本可以同时使用吗？

可以。items 数组中可以混合图片和文本类型，组件会自动渲染对应的内容。

文本内容支持哪些 HTML 标签？

文本内容通过 Text 组件渲染，支持常见的 HTML 标签（如 <br>, <strong>, <em> 等）。复杂样式建议使用 textClassName 自定义。

如何实现垂直滚动？

当前组件仅支持水平滚动（direction="horizontal"）。如需垂直滚动，需要修改源代码中的 direction 属性。

如何设置项目之间的间距？

间距根据屏幕尺寸自动调整：移动端 24px，桌面端 64px。如需自定义，可以通过 className 覆盖样式。

技术实现

基于 Swiper

组件基于 Swiper 实现，使用以下模块：

Autoplay: 自动播放功能
Loop: 无限循环功能

关键配置


{
  direction: 'horizontal',
  loop: true,
  autoplay: {
    delay: 0,
    disableOnInteraction: false,
    reverseDirection: false,
    pauseOnMouseEnter: false,
  },
  allowTouchMove: false,
  simulateTouch: false,
  slidesPerView: 'auto',
  speed: 3000,
}