xtf-linkui

Appearance

xtf-marquee ​

组件说明 ​

xtf-marquee 是跑马灯/滚动公告组件，用于展示持续滚动的公告、新闻、标签列表或弹幕。支持 continuous（持续滚动）/ step（步进切换）两种模式、left / right / up / down 四个方向、barrage（弹幕）、多行滚动、渐变/玻璃/霓虹/终端等十余种视觉变体，并支持按需暂停（按压/悬停）、单项点击、分隔符、前后缀等能力，是运营公告与信息流展示的核心组件。

基础用法 ​

1. 最简示例（单条文本） ​

通过 text 传入单条公告文字：

vue
<template>
  <view style="padding: 32rpx">
    <xtf-marquee text="欢迎使用 xtf-linkui 组件库！这是一条横向滚动的公告信息。" />
  </view>
</template>

2. 多条数据滚动 ​

通过 items 传入多条数据，支持对象数组（text / tag / meta 字段）：

vue
<template>
  <view style="padding: 32rpx">
    <xtf-marquee :items="news" variant="notice" />
  </view>
</template>

<script>
export default {
  data() {
    return {
      news: [
        { text: '双 11 大促开启，全场 5 折起', tag: '促销', meta: '2小时前' },
        { text: 'v2.0.0 版本发布，新增 12 个组件', tag: '更新', meta: '5小时前' },
        { text: '性能优化：列表渲染提升 40%', tag: '公告', meta: '昨天' },
        { text: '主题系统全新升级，支持暗黑模式', tag: '新功能', meta: '3天前' }
      ]
    }
  }
}
</script>

3. 步进模式 ​

通过 mode="step" 逐条切换，step-interval 控制间隔，配合 change 事件监听：

vue
<template>
  <view style="padding: 32rpx">
    <xtf-marquee
      :items="notices"
      mode="step"
      :step-interval="2500"
      variant="ticker"
      @change="onChange"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      notices: [
        { text: '今日签到奖励已发放', tag: '提醒' },
        { text: '你的订单已发货，注意查收', tag: '物流' },
        { text: '本周累计签到 5 天，获得积分', tag: '积分' }
      ]
    }
  },
  methods: {
    onChange(payload) {
      console.log('当前展示:', payload.item.text, '索引:', payload.index)
    }
  }
}
</script>

4. 垂直滚动 ​

通过 direction="up" 或 vertical 开启垂直滚动：

vue
<template>
  <view style="padding: 32rpx">
    <xtf-marquee
      :items="announcements"
      direction="up"
      variant="default"
      clickable
      @item-click="onItemClick"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      announcements: [
        { text: '关于系统维护的通知', tag: '公告' },
        { text: '新增企业认证功能', tag: '新功能' },
        { text: '本周五例行维护', tag: '提醒' }
      ]
    }
  },
  methods: {
    onItemClick(payload) {
      console.log('点击公告:', payload.item.text)
      uni.showToast({ title: payload.item.text, icon: 'none' })
    }
  }
}
</script>

5. 弹幕与多行 ​

通过 barrage 开启弹幕模式，通过 rows 控制行数：

vue
<template>
  <view style="padding: 32rpx">
    <xtf-marquee :items="danmu" barrage :rows="3" clickable @item-click="onItemClick" />
  </view>
</template>

<script>
export default {
  data() {
    return {
      danmu: [
        { text: '这段视频真棒！', tag: '用户A' },
        { text: '学到了，谢谢分享', tag: '用户B' },
        { text: '前排围观', tag: '用户C' },
        { text: '已三连支持', tag: '用户D' },
        { text: '收藏了慢慢看', tag: '用户E' }
      ]
    }
  },
  methods: {
    onItemClick(payload) {
      console.log('弹幕点击:', payload.item.text)
    }
  }
}
</script>

6. 前后缀与自定义插槽 ​

通过 label / icon 显示前缀徽标，通过 separator 设置分隔符，使用 item 插槽自定义单项：

vue
<template>
  <view style="padding: 32rpx">
    <xtf-marquee
      :items="tips"
      label="公告"
      icon="📢"
      separator="·"
      variant="soft"
      clickable
      @item-click="onItemClick"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      tips: [
        { text: '出行前请检查随身物品', meta: '重要' },
        { text: '雷雨天气注意安全', meta: '天气' },
        { text: '节假日出行请提前规划', meta: '提醒' }
      ]
    }
  },
  methods: {
    onItemClick(payload) {
      console.log('点击:', payload.item.text)
    }
  }
}
</script>

全部属性 ​

属性类型默认值作用描述适用范围
textString''单条滚动文本（无 items 时使用）单条公告
itemsArray[]滚动数据数组，支持对象（text / label / tag / meta / icon / accentColor）或字符串多条数据
speedString | Number48滚动速度控制快慢
directionString'left'滚动方向：'left' / 'right' / 'up' / 'down'方向控制
gapNumber48单项间隔（rpx）间距
pauseOnPressBooleantrue按压时暂停交互暂停
pauseOnHoverBooleanfalse悬停时暂停（H5）交互暂停
barrageBooleanfalse是否弹幕模式弹幕展示
variantString'default'视觉变体：'default' / 'notice' / 'pill' / 'soft' / 'glass' / 'neon' / 'ticker' / 'terminal' / 'barrage' / 'sunset' / 'spotlight' / 'minimal'换风格
modeString'continuous'模式：'continuous'（持续）/ 'step'（步进）切换模式
durationString | Number''单次循环时长（秒），设置后优先于 speed精确控制时长
autoplayBooleantrue是否自动播放启停控制
rowsNumber1显示行数（配合 barrage 使用）弹幕行数
verticalBooleanfalse是否垂直滚动（等价 direction="up"）垂直方向
rowGapNumber16多行间距行间距
itemHeightNumber88单项高度（步进/垂直模式）布局高度
iconString''前缀图标（emoji/字符）前缀徽标
labelString''前缀文字前缀徽标
separatorString''项间分隔符分隔展示
accentColorString''强调色自定义配色
itemClassString''单项自定义类名单项样式
itemStyleString | Object''单项自定义样式单项动态样式
stepIntervalNumber2800步进模式间隔（毫秒）步进节奏
stepDurationNumber420步进切换动画时长（毫秒）切换动画
clickableBooleanfalse单项是否可点击（触发 item-click）交互单项
customClassString''自定义类名样式覆盖
customStyleString | Object''自定义样式动态样式覆盖

items 数组每项支持的字段 ​

字段类型默认值说明
textString''主文本内容
labelString''徽标文字
tagString''标签文字（与 label 同效）
metaString''辅助元信息（时间/来源等）
iconString''单项图标
accentColorString''单项强调色
id / keyString | Numberindex唯一键（用于 v-for）

事件 ​

事件名称触发时机回调参数参数说明
click点击组件根区域时触发(payload: { mode, variant, items })组件模式、变体与当前数据
item-click点击单项时触发（clickable 为真）(payload: { item, index, raw })单项数据、索引、原始对象
change步进模式切换单项时触发(payload: { index, item, raw })新单项索引、数据、原始对象
cycle-end步进模式循环完一轮时触发(payload: { mode, variant })组件模式与变体
play-state-change播放/暂停状态变化时触发(payload: { playing, paused, reason })播放态、暂停态、原因（press / hover）

事件使用示例 ​

vue
<template>
  <view style="padding: 32rpx">
    <xtf-marquee
      :items="list"
      mode="step"
      clickable
      @item-click="onItemClick"
      @change="onChange"
      @cycle-end="onCycleEnd"
      @play-state-change="onPlayStateChange"
      @click="onRootClick"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      list: [
        { text: '第一条公告', tag: 'A' },
        { text: '第二条公告', tag: 'B' },
        { text: '第三条公告', tag: 'C' }
      ]
    }
  },
  methods: {
    onItemClick(payload) {
      console.log('单项点击:', payload.index, payload.item.text)
      uni.showToast({ title: payload.item.text, icon: 'none' })
    },
    onChange(payload) {
      console.log('切换:', payload.index, payload.item.text)
    },
    onCycleEnd(payload) {
      console.log('循环结束', payload.mode)
    },
    onPlayStateChange(payload) {
      console.log('播放状态:', payload.playing, '原因:', payload.reason)
    },
    onRootClick(payload) {
      console.log('根区域点击', payload.mode)
    }
  }
}
</script>

插槽 ​

插槽名称说明
default完全自定义滚动内容（替代内部列表渲染）
item自定义每个单项（作用域插槽，提供 item / index / rowIndex）
prefix前缀区域（默认展示 label / icon 徽标）
suffix后缀区域
separator自定义分隔符（作用域插槽）

插槽使用示例 ​

通过 item 作用域插槽自定义单项样式，结合 prefix / suffix 定制前后缀：

vue
<template>
  <view style="padding: 32rpx">
    <xtf-marquee :items="list" variant="default" clickable @item-click="onItemClick">
      <template #prefix>
        <xtf-tag text="NEW" theme="danger" shape="round" size="xs" style="margin-right: 12rpx" />
      </template>
      <template #item="{ item, index }">
        <view style="display: flex; align-items: center; gap: 12rpx; margin-right: 48rpx">
          <xtf-text :text="String(index + 1)" color="primary" bold />
          <xtf-text :text="item.text" />
          <xtf-tag :text="item.tag" theme="info" size="xxs" variant="light" shape="round" />
        </view>
      </template>
      <template #suffix>
        <xtf-text text="更多 >>" color="link" level="caption" style="margin-left: 12rpx" />
      </template>
    </xtf-marquee>
  </view>
</template>

<script>
export default {
  data() {
    return {
      list: [
        { text: '组件文档已更新', tag: '文档' },
        { text: '新增主题定制能力', tag: '主题' },
        { text: '性能大幅提升', tag: '优化' }
      ]
    }
  },
  methods: {
    onItemClick(payload) {
      console.log('点击:', payload.item.text)
    }
  }
}
</script>

主题说明 ​

  • 强调色使用 var(--xtf-marquee-accent)，单项强调色使用 var(--xtf-marquee-item-accent)
  • 项间距使用 var(--xtf-marquee-gap)，行间距使用 var(--xtf-marquee-row-gap)，步进高度使用 var(--xtf-marquee-step-height)
  • 各种 variant（notice / pill / glass / neon / ticker / terminal / barrage / sunset / spotlight）有独立背景、边框与阴影
  • 左右滚动使用 xtf-marquee-left / xtf-marquee-right，上下滚动使用 xtf-marquee-up / xtf-marquee-down 动画

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。

MIT Licensed

Copyright © 2026 xtf-linkui