我最早做滚动字幕,其实是被一个特别土的运营需求逼的:公告栏要放一段平台通知,文案不长不短,放静态文本怕用户看不到,放弹窗又太打扰。当时查了一圈,发现uniapp里做滚动字幕的姿势五花八门——有人用swiper组件硬翻页,有人用CSS animation硬怼,还有人直接用定时器改偏移量。每种方案都能跑,但真放到多端环境里,坑一个接一个。
这篇文章就是来填坑的。我会从最基础的CSS transform方案讲起,跳到动态时长计算、无缝循环、真机适配这几个绕不开的点,最后给你一个可以直接抄进项目的通用组件。无论你是在做公告栏、跑马灯提示、歌词滚动还是资讯轮播,这套思路都能复用。内容适配小程序、H5和App三端,不需要你懂原生开发,有vue基础就能跟着走。
1. 滚动字幕的需求场景与方案选型心态
先说清楚什么是滚动字幕。它本质上是一段超长文本在有限宽度内循环平移,让用户能完整读完内容。最常见的形态是横向跑马灯,也就是文字从右往左持续移动,到末尾后重新开始。
这个需求在uniapp项目里出现的频率比你想的高很多。首页公告、支付成功页的活动提示、签到页的规则说明、信息流里的热点播报,全是滚动字幕的典型战场。很多开发者第一反应是:这个东西简单,不就是一个带动画的text标签吗?但真正动手后才会发现,难点从来不在动画本身,而在下面三个问题:
- 文案长度不固定,动画时长怎么配?
- 滚动到末尾后如何做到无缝衔接?
- 多端(小程序/H5/App)表现不一致怎么办?
先说方案选型的大方向。滚动字幕主流实现方式有三种:CSS animation、swiper组件、定时器修改偏移量。我直接给你结论:常规场景优先选CSS animation,原因后面会细说;swiper适合整屏切换的轮播,不适合连续平移的单条字幕;定时器方案能做到类似效果,但性能和流畅度在低端安卓机上会被CSS动画按在地上摩擦。
另外要提前给你们打个预防针:uniapp的滚动字幕在小程序端和H5端的实现逻辑是通用的,但真正的分水岭在文本宽度的获取方式上。小程序不允许直接操作DOM,你没法像H5那样挂个ref就能拿到元素宽度。这个核心差异直接决定你后续怎么写代码。
在开始写代码前,我还想纠正一个很多人会踩的坑:千万不要一上来就搜一个现成插件然后往项目里塞。滚动字幕的代码量撑死一百多行,你自己写一遍,后面适配需求变化(比如点击暂停、变速滚动、双行交替)会顺手得多。插件往往是黑盒,改一个样式都可能要翻半天源码。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心实现方案:CSS transform动画实现滚动字幕
2.1 为什么不用marquee标签
老一代人写网页可能见过<marquee>这个标签,它确实能实现滚动效果,但早就被标准淘汰了,uniapp里更不可能支持。在uniapp里跑滚动字幕,最靠谱的基础是transform: translateX()配合animation。
CSS动画的优势有三个:
- 流畅度高:transform的平移不会触发页面重排(reflow),性能开销小
- 代码精简:一个@keyframes就能搞定,不需要手动维护定时器
- 可控性强:动画的时长、延迟、循环次数、缓动函数全部可以用CSS属性控制
2.2 最基础的滚动字幕代码
这是最原始的版本,先跑通再说:
html复制<template>
<view class="scroll-container">
<view class="scroll-text" :style="animationStyle">
{{ text }}
</view>
</view>
</template>
<script>
export default {
data() {
return {
text: '这是一段测试文本,用来检验滚动字幕的效果',
animationStyle: ''
};
},
onReady() {
this.animationStyle = `animation: scrollMove 8s linear infinite;`;
}
};
</script>
<style scoped>
.scroll-container {
width: 100%;
overflow: hidden;
white-space: nowrap;
}
.scroll-text {
display: inline-block;
padding-left: 100%;
/* 动画名称、时长、线性运动、无限循环 */
animation: scrollMove 8s linear infinite;
}
@keyframes scrollMove {
0% {
transform: translateX(0);
}
100% {
transform: translateX(-100%);
}
}
</style>
这段代码的思路是:把滚动文本放在一个display: inline-block的容器里,初始padding-left: 100%让文本从容器右侧外部开始,动画播放时把文本向左平移自身的100%宽度——也就是刚好把整段文本移出左侧。
需要注意,translateX(-100%)移动的距离是元素自身宽度的100%,比如文本宽度是600rpx,它就会向左移600rpx。这个逻辑配合padding-left: 100%,就能形成"从右边进、从左边出"的效果。
但是,如果你直接复制这段代码跑起来,会发现滚动到末尾后会出现一段空窗期——文本完全消失,要等很久才从右边重新出现。这是因为你在padding-left: 100%的基础上又走了文本自身的宽度,中间有一段"空白平移"的时间。这个问题我们放到下一节解决。
2.3 关键参数:动画时长与文本长度的匹配
上面代码里的8s是写死的,真正项目里不能让用户觉得字幕走得忽快忽慢。这里有个简单的换算关系:动画时长 = 文本宽度 / 期望速度。
如果文本短、速度固定,但动画时长也写死,就会产生两种体验:
- 时长太短,文本滚动太快,用户没看清内容就没了。
- 时长太长,文本滚动太慢,用户等得不耐烦。
所以一般在封装组件时,会把duration作为props传进来,由业务方决定。但更智能的做法是提供一个"速度"参数,比如每秒滚动多少像素,然后根据文本宽度动态计算时长。
下一节我来讲怎么动态计算时长,这也是这个组件最核心的地方。
3. 动态计算动画时长与无缝循环的实现
3.1 获取文本实际宽度的姿势
动画时长要靠文本宽度算,那第一步就是拿到文本渲染后的宽度。这在H5端很简单,挂个ref用offsetWidth就行。但小程序端有他自己的一套API,叫uni.createSelectorQuery()。
看代码:
javascript复制getTextWidth() {
return new Promise((resolve) => {
const query = uni.createSelectorQuery().in(this);
query.select('.scroll-text').boundingClientRect((rect) => {
resolve(rect ? rect.width : 0);
}).ex
