@tanzhenxing/zx-barrage v1.0.1

zx-barrage 弹幕组件

zx-barrage 是一个用于在 uniapp 应用中实现弹幕效果的组件，支持 H5、小程序和 App 端。它允许开发者轻松地在视频或其他内容区域展示滚动的评论性字幕。

特性

• 跨平台兼容：专为 uniapp 设计，确保在 H5、小程序和 App 上的表现一致性。
• Vue3 Setup：使用 Vue 3 Composition API (setup 语法糖) 编写，代码更清晰易维护。
• 灵活配置：提供丰富的 props 来自定义弹幕的行为，如行数、速度、颜色、字体大小等。
• 事件支持：提供弹幕播放、暂停、结束等关键事件。
• 方法调用：可以通过 ref 获取组件实例，并调用 play、pause、add、clear 等方法控制弹幕。
• 动态添加：支持在运行时动态添加新的弹幕数据。
• 循环播放：可选支持弹幕循环播放。

使用方法

引入组件

<script setup>
import zxBarrage from '@/components/zx-barrage/zx-barrage.vue'; // 请根据实际路径调整
import { ref } from 'vue';

const barrageList = ref([
  { id: 1, text: '第一条弹幕' },
  { id: 2, text: 'Hello ZXUI!' },
]);

const barrageRef = ref(null);

const addBarrage = () => {
  const newText = `新弹幕 ${Date.now()}`;
  // 方式一：直接修改 v-model 绑定的数据
  // barrageList.value.push({ id: Date.now(), text: newText });
  // 方式二：通过 ref 调用 add 方法 (推荐，可以处理内部ID等)
  barrageRef.value?.add({ text: newText });
};

const play = () => {
  barrageRef.value?.play();
};

const pause = () => {
  barrageRef.value?.pause();
};
</script>

基础用法

<template>
  <view>
    <view style="width: 100%; height: 200px; background-color: #000;">
      <zx-barrage ref="barrageRef" v-model="barrageList">
        <!-- 这里可以放置视频播放器或其他背景内容 -->
        <view style="width:100%; height: 100%; display:flex; align-items:center; justify-content:center;">
          <text style="color: white;">视频区域</text>
        </view>
      </zx-barrage>
    </view>
    <button @click="addBarrage">发送弹幕</button>
    <button @click="play">播放</button>
    <button @click="pause">暂停</button>
  </view>
</template>

API

Props

v-model 数据项 (BarrageItem) 示例:

{
  id: 1, // 可选但强烈推荐，用于唯一标识，方便更新和删除
  text: '这是一条弹幕', // 必选，弹幕文字内容
  color: '#FF0000', // 可选，覆盖全局弹幕颜色
  fontSize: 20, // 可选，覆盖全局字体大小 (px)
  // ...可以添加其他自定义属性，这些属性会在事件回调中透传
}

Events

Methods

通过 ref 获取到组件实例后，可以调用以下方法：

注意事项

• 容器尺寸：zx-barrage 组件本身会撑满其父容器，请确保父容器具有明确的宽度和高度，以便弹幕轨道正确计算。
• 性能：同时显示大量弹幕可能会影响性能，尤其是在低端设备上。建议根据实际情况控制弹幕密度和数量。
• 文本宽度计算：在小程序等环境中，动态精确计算文本宽度有一定限制。组件内部采用估算方式，对于过长或特殊字体的弹幕，其飞行速度可能与预期略有差异。如果需要非常精确的控制，可以考虑在 BarrageItem 中传入预估的宽度。
• CSS动画：组件主要依赖 CSS transform 和 transition 实现动画。在部分老旧设备或特定小程序环境下，动画性能可能需要关注。

示例页面

更详细的用法请参考项目中的示例页面：src/pages/components/barrage/index.vue (路径可能根据您的项目结构有所不同)。