m2pool_web_frontend/mining-pool/src/components/README.md

# HorizontalBroadcast 横向滚动广播组件

一个功能完整的横向滚动广播通知栏组件，支持自动获取数据、鼠标交互、触摸交互等特性。

## 🚀 快速开始

### 基础用法

```vue
<template>
  <div>
    <!-- 最简单的用法，自动获取数据 -->
    <HorizontalBroadcast />
  </div>
</template>

<script>
import HorizontalBroadcast from '@/components/HorizontalBroadcast.vue'

export default {
  components: {
    HorizontalBroadcast
  }
}
</script>
```

## 📋 Props 属性

| 属性名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `broadcastData` | Array | `[]` | 广播数据，如果不传则自动获取 |
| `showTitle` | Boolean | `true` | 是否显示标题 |
| `showIcon` | Boolean | `true` | 是否显示图标 |
| `title` | String | `''` | 自定义标题，不传则使用国际化标题 |
| `scrollSpeed` | Number | `1` | 滚动速度（像素/步） |
| `scrollInterval` | Number | `50` | 滚动间隔（毫秒） |
| `autoFetch` | Boolean | `true` | 是否自动获取数据 |
| `lang` | String | `'zh'` | 获取数据的语言参数 |
| `minItems` | Number | `1` | 最小显示条数，少于此数不显示组件 |
| `height` | String | `'40px'` | 组件高度 |
| `clickable` | Boolean | `false` | 是否启用点击事件 |

## 📡 Events 事件

| 事件名 | 参数 | 说明 |
|--------|------|------|
| `data-loaded` | `data: Array` | 数据加载完成时触发 |
| `error` | `error: Error` | 发生错误时触发 |
| `item-click` | `item: Object` | 广播项被点击时触发（需要 `clickable=true`） |

## 🎯 使用示例

### 1. 自定义样式和行为

```vue
<template>
  <HorizontalBroadcast 
    :show-title="true"
    :show-icon="true"
    title="最新公告"
    height="50px"
    :scroll-speed="2"
    :scroll-interval="30"
    :clickable="true"
    @item-click="handleClick"
  />
</template>

<script>
export default {
  methods: {
    handleClick(item) {
      console.log('点击了:', item.content);
    }
  }
}
</script>
```

### 2. 使用外部数据

```vue
<template>
  <HorizontalBroadcast 
    :broadcast-data="customData"
    :auto-fetch="false"
    title="自定义消息"
    :clickable="true"
    @item-click="handleCustomClick"
  />
</template>

<script>
export default {
  data() {
    return {
      customData: [
        { id: '1', content: '第一条消息' },
        { id: '2', content: '第二条消息' },
        { id: '3', content: '第三条消息' }
      ]
    }
  },
  methods: {
    handleCustomClick(item) {
      this.$message.info(item.content);
    }
  }
}
</script>
```

### 3. 极简模式（无标题无图标）

```vue
<template>
  <HorizontalBroadcast 
    :show-title="false"
    :show-icon="false"
    height="35px"
    :scroll-speed="1.5"
  />
</template>
```

### 4. 错误处理

```vue
<template>
  <HorizontalBroadcast 
    @data-loaded="onDataLoaded"
    @error="onError"
  />
</template>

<script>
export default {
  methods: {
    onDataLoaded(data) {
      console.log('广播数据加载成功:', data);
    },
    onError(error) {
      console.error('广播组件出错:', error);
      this.$message.error('加载广播数据失败');
    }
  }
}
</script>
```

## 🎮 组件方法

通过 `ref` 访问组件实例，可以调用以下方法：

```vue
<template>
  <div>
    <HorizontalBroadcast ref="broadcast" />
    <button @click="refreshData">刷新数据</button>
    <button @click="togglePause">暂停/继续</button>
    <button @click="getStatus">获取状态</button>
  </div>
</template>

<script>
export default {
  methods: {
    // 刷新数据
    refreshData() {
      this.$refs.broadcast.refresh();
    },
    
    // 切换暂停状态
    togglePause() {
      this.$refs.broadcast.togglePause();
    },
    
    // 获取组件状态
    getStatus() {
      const status = this.$refs.broadcast.getStatus();
      console.log('组件状态:', status);
    }
  }
}
</script>
```

### 可用方法：

- `refresh()` - 刷新数据
- `togglePause()` - 切换暂停/继续状态
- `getStatus()` - 获取当前状态信息

## 🎨 样式定制

组件使用 scoped 样式，如需定制外观，可以通过以下方式：

### 1. 通过 Props 定制

```vue
<HorizontalBroadcast 
  height="60px"  <!-- 调整高度 -->
  title="自定义标题"  <!-- 自定义标题 -->
/>
```

### 2. 全局样式覆盖

```scss
// 在全局样式中
.horizontal-broadcast-container {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  
  .broadcast-title {
    color: white;
  }
  
  .horizontal-scroll-wrapper {
    background: rgba(255, 255, 255, 0.2);
    border: 1px solid rgba(255, 255, 255, 0.3);
  }
}
```

## 📱 移动端适配

组件已内置移动端适配：

- 自动调整字体大小和间距
- 支持触摸交互（触摸暂停，松开恢复）
- 响应式布局自适应

## 🔧 数据格式

广播数据应遵循以下格式：

```javascript
[
  {
    id: 'unique-id-1',        // 必需：唯一标识
    content: '广播内容...'    // 必需：显示内容
  },
  {
    id: 'unique-id-2',
    content: '另一条广播内容...'
  }
]
```

## 🌐 国际化支持

组件支持国际化，默认标题会使用 `this.$t('home.describeTitle')`。

如需自定义，可以：

```vue
<HorizontalBroadcast 
  :title="$t('custom.broadcast.title')"
/>
```

## ⚡ 性能优化

组件已内置以下性能优化：

- 使用 `will-change: transform` 启用硬件加速
- 智能的数据复制策略减少 DOM 操作
- 自动清理定时器防止内存泄漏
- 合理的滚动间隔和步进设置

## 🐛 常见问题

### Q: 为什么组件没有显示？

A: 检查以下几点：
1. 数据是否正确加载（通过 `@data-loaded` 事件检查）
2. `minItems` 设置是否过高
3. 是否有 CSS 冲突

### Q: 如何调整滚动速度？

A: 通过 `scrollSpeed` 和 `scrollInterval` 两个属性：
- `scrollSpeed`: 每次移动的像素数（越大越快）
- `scrollInterval`: 滚动间隔毫秒数（越小越快）

### Q: 点击事件不生效？

A: 确保设置了 `clickable="true"` 并监听 `@item-click` 事件。

## <20><> 许可证

MIT License