MatchRankList 排行榜列表

排行榜列表组件，用于展示用户排名信息，支持无限滚动加载、横向滚动和空状态显示。

特性

• 📊 灵活布局 - 支持自动列数适配和自定义列配置
• 🔄 无限滚动 - 基于 PressList 组件实现无限滚动加载
• ↔️ 横向滚动 - 多列时自动启用横向滚动，支持编程控制
• 🎨 主题定制 - 丰富的CSS变量支持主题定制
• 📱 响应式设计 - 适配不同屏幕尺寸
• 🔧 插槽支持 - 支持自定义列内容渲染

适用场景

• 电竞比赛排行榜
• 游戏积分榜
• 用户成绩榜单
• 数据统计展示

引入

import PressMatchRankList from 'press-next/press-match-rank-list/press-match-rank-list';

代码演示

基础用法

使用 dataObject 传递数据，组件会自动展示所有字段。

<template>
  <PressMatchRankList
    :list="rankList"
    :loading="loading"
    :finished="finished"
    @load-more="handleLoadMore"
    @item-click="handleItemClick"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import PressMatchRankList from 'press-next/press-match-rank-list/press-match-rank-list';

const rankList = ref([
  {
    rank: 1,
    showRankText: true,
    avatar: 'https://img.yzcdn.cn/vant/cat.jpeg',
    name: '张三',
    dataObject: {
      phone: '18505556789',
      score: 15,
      address: '网鱼网吧华山街店',
    },
  },
  {
    rank: 2,
    showRankText: false,
    avatar: 'https://img.yzcdn.cn/vant/cat.jpeg',
    name: '李四',
    dataObject: {
      phone: '13800138000',
      score: 12,
      address: '网鱼网吧人民路店',
    },
  },
]);

const loading = ref(false);
const finished = ref(false);

const handleLoadMore = () => {
  console.log('加载更多数据');
};

const handleItemClick = (item, index) => {
  console.log('点击排名项:', item, index);
};
</script>

使用列配置

通过 columns 属性控制显示哪些列。

<template>
  <PressMatchRankList
    :list="rankList"
    :columns="columns"
    :finished="true"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import PressMatchRankList from 'press-next/press-match-rank-list/press-match-rank-list';

const rankList = ref([
  {
    rank: 1,
    avatar: 'https://img.yzcdn.cn/vant/cat.jpeg',
    name: '张三',
    dataObject: {
      phone: '18505556789',
      score: 100,
      address: '网鱼网吧华山街店',
      team: '红队',
    },
  },
]);

// 只显示 phone, score, address 三列
const columns = ref([
  { key: 'phone', visible: true },
  { key: 'score', visible: true },
  { key: 'address', visible: true },
]);
</script>

横向滚动控制

组件提供了丰富的滚动控制方法。

<template>
  <div>
    <div class="controls">
      <button @click="scrollToStart">滚动到最左</button>
      <button @click="scrollToEnd">滚动到最右</button>
      <button @click="scrollLeft">向左滚动</button>
      <button @click="scrollRight">向右滚动</button>
    </div>
    
    <PressMatchRankList
      ref="rankListRef"
      :list="rankList"
      :finished="true"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import PressMatchRankList from 'press-next/press-match-rank-list/press-match-rank-list';

const rankListRef = ref();

const scrollToStart = () => {
  rankListRef.value?.scrollToStart();
};

const scrollToEnd = () => {
  rankListRef.value?.scrollToEnd();
};

const scrollLeft = () => {
  rankListRef.value?.scrollBy({ left: -200 });
};

const scrollRight = () => {
  rankListRef.value?.scrollBy({ left: 200 });
};
</script>

自定义文本

<template>
  <PressMatchRankList
    :list="rankList"
    :loading="loading"
    :finished="finished"
    empty-text="暂无排行榜数据"
    finish-text="已显示全部排名"
    @load-more="handleLoadMore"
  />
</template>

空状态

<template>
  <PressMatchRankList
    :list="[]"
    empty-text="暂无数据"
  />
</template>

API

Props

参数	说明	类型	默认值
list	排行榜数据列表	RankItem[]	[]
columns	列配置数组，控制显示哪些列	ColumnConfig[]	[]
loading	是否处于加载状态	boolean	false
finished	是否已加载完成	boolean	false
empty-text	空状态提示文本	string	'暂无数据'
finish-text	加载完成提示文本	string	'没有更多了'
image	空状态图片URL	string	-
custom-class	自定义样式类	string	''

RankItem 数据结构

interface RankItem {
  rank: number; // 排名
  showRankText?: boolean; // 是否显示"第X名"文字
  avatar: string; // 头像地址
  name?: string; // 用户名称
  dataObject?: Record<string, string | number>; // 数据对象，包含自定义列数据
}

ColumnConfig 数据结构

interface ColumnConfig {
  key: string; // 列标识，对应 dataObject 中的字段名
  visible?: boolean; // 是否可见，默认 true
  width?: string; // 列宽度，如 '1.5rem', 'auto'
  minWidth?: string; // 最小宽度，如 '1rem'
  align?: 'left' | 'center' | 'right'; // 文本对齐方式，默认 left
}

Events

事件名	说明	回调参数
load-more	滚动到底部时触发，用于加载更多数据	-
item-click	点击排名项时触发	(item: RankItem, index: number)

Methods

通过 ref 可以获取到组件实例并调用实例方法。

方法名	说明	参数	返回值
scrollTo	滚动到指定位置	{ left: number, behavior?: 'auto' \| 'smooth' }	-
scrollBy	滚动指定距离	{ left: number, behavior?: 'auto' \| 'smooth' }	-
scrollToStart	滚动到最左侧	behavior?: 'auto' \| 'smooth'	-
scrollToEnd	滚动到最右侧	behavior?: 'auto' \| 'smooth'	-
getScrollInfo	获取当前滚动信息	-	ScrollInfo

ScrollInfo 数据结构

interface ScrollInfo {
  scrollLeft: number; // 当前横向滚动位置
  scrollWidth: number; // 内容总宽度
  clientWidth: number; // 可视区域宽度
  maxScrollLeft: number; // 最大滚动位置
  isAtStart: boolean; // 是否在起始位置
  isAtEnd: boolean; // 是否在结束位置
}

注意事项

使用建议

1. 数据结构：dataObject 中的字段会自动渲染为列，name 字段会显示在用户信息列中
2. 列配置优先级：如果同时设置了 columns 和 dataObject，优先使用 columns 配置
3. 横向滚动：当列数较多时会自动启用横向滚动，可通过CSS变量 --pmrl-container-overflow-x 控制
4. 加载状态：配合 loading 和 finished 属性实现无限滚动加载
5. 空状态：当 list 为空时自动显示空状态
6. 响应式：建议在小屏幕设备上适当调整相关尺寸变量

性能优化

• 组件使用虚拟化节点减少DOM层级
• 列表项使用 v-for 和 key 优化渲染性能
• 支持懒加载，按需加载数据
• 横向滚动使用原生能力，性能优异

兼容性

• 支持 Vue 3.0+
• 兼容现代浏览器（Chrome 60+, Firefox 60+, Safari 12+）
• 支持微信小程序、支付宝小程序等平台

主题定制

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

样式变量

盒模型 (Box Model)

名称	默认值	描述
--pmrl-container-width	100%	容器宽度
--pmrl-container-margin	0	容器外边距
--pmrl-container-padding	0	容器内边距

边框 (Border)

名称	默认值	描述
--pmrl-container-radius	0	容器圆角

背景 (Background)

名称	默认值	描述
--pmrl-container-bg	$color-surface-default	容器背景色

其他 (Others)

名称	默认值	描述
--pmrl-container-overflow-x	auto	容器横向溢出处理
--pmrl-container-overflow-y	auto	容器纵向溢出处理