MatchRankItem 榜单列表项

# MatchRankItem 榜单列表项

用于展示排行榜中的单个项目,支持动态列和固定列的组合展示。适用于各类排行榜、积分榜、成绩榜等场景。

# 特性

🏆 排名展示 - 前3名显示徽章图标,其余显示数字排名
📊 动态列配置 - 灵活配置显示列和对齐方式
🎨 主题定制 - 丰富的CSS变量支持主题定制
📱 横向滚动 - 支持横向滚动及滚动控制方法
🔧 插槽支持 - 支持自定义名称和列内容
⚡ 轻量高效 - 优化的代码结构,性能出色

# 适用场景

游戏排行榜展示
电竞比赛积分榜
在线考试成绩榜
活动参与人员列表

# 引入

import PressMatchRankItem from 'press-next/press-match-rank-item/press-match-rank-item';

# 代码演示

# 基础用法

<template>
  <PressMatchRankItem
    :rank="1"
    :avatar="avatarUrl"
    :name="'张三'"
    :phone="'138****1234'"
    :score="88"
  />
</template>

# 使用 dataObject 和 columns

通过 dataObject 传递数据对象,columns 定义列配置:

<template>
  <PressMatchRankItem
    :rank="1"
    :avatar="avatarUrl"
    :data-object="userData"
    :columns="columns"
  />
</template>

<script setup lang="ts">
const userData = {
  name: '张三',
  phone: '138****1234',
  score: 88,
  address: '广东省深圳市'
};

const columns = [
  { key: 'phone', width: '2rem', align: 'left' },
  { key: 'score', width: '1.5rem', align: 'center' },
  { key: 'address', width: '3rem', align: 'right' },
];
</script>

# 显示排名文字

设置 show-rank-text 显示"第x名"文字:

<template>
  <PressMatchRankItem
    :rank="1"
    :show-rank-text="true"
    :avatar="avatarUrl"
    :name="'张三'"
  />
</template>

# 自定义列内容

使用插槽自定义特定列的内容:

<template>
  <PressMatchRankItem
    :rank="1"
    :avatar="avatarUrl"
    :data-object="userData"
    :columns="columns"
  >
    <template #score="{ value }">
      <span style="color: red; font-weight: bold;">{{ value }}分</span>
    </template>
  </PressMatchRankItem>
</template>

# 横向滚动控制

<template>
  <PressMatchRankItem
    ref="rankItemRef"
    :rank="1"
    :avatar="avatarUrl"
    :data-object="userData"
  />
  <button @click="handleScrollRight">向右滚动</button>
  <button @click="handleScrollToLeft">滚动到最左侧</button>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const rankItemRef = ref();

const handleScrollRight = () => {
  rankItemRef.value.scrollRight(100, 'smooth');
};

const handleScrollToLeft = () => {
  rankItemRef.value.scrollToLeft('smooth');
};
</script>

# 自定义主题

<template>
  <PressMatchRankItem
    custom-class="my-custom-theme"
    :rank="1"
    :avatar="avatarUrl"
    :data-object="userData"
  />
</template>

<style>
.my-custom-theme {
  /* 背景和边框样式 */
  --pmri-rank-item-bg: linear-gradient(to right, #f5f5f5, #ffffff);
  --pmri-rank-item-radius: .16rem;
  
  /* 文字颜色 */
  --pmri-rank-value-color: #ff6b00;
  --pmri-name-color: #333333;
}
</style>

# API

# Props

参数	说明	类型	默认值
custom-class	自定义样式类	string	`''`
rank	排名	number	`1`
show-rank-text	是否显示排名文字(第x名)	boolean	`false`
avatar	头像 URL	string	`''`
name	名称	string	`''`
data-object	数据对象(包含所有自定义列数据)	_Record<string, string \	number>_
columns	列配置数组	ColumnConfig[]	`[]`

# ColumnConfig 类型定义

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

# Slots

名称	说明	参数
name	自定义名称展示	`{ value: string }`
[column.key]	自定义对应列的内容	`{ value: any }`

# Methods

组件通过 ref 暴露以下方法,用于控制横向滚动:

方法名	说明	参数	返回值
scrollTo	滚动到指定位置	`{ left?: number, behavior?: 'auto' \\\| 'smooth' }`	-
scrollToLeft	滚动到最左侧	`behavior?: 'auto' \\\| 'smooth'`	-
scrollToRight	滚动到最右侧	`behavior?: 'auto' \\\| 'smooth'`	-
scrollLeft	向左滚动指定距离	`distance?: number, behavior?: 'auto' \\\| 'smooth'`	-
scrollRight	向右滚动指定距离	`distance?: number, behavior?: 'auto' \\\| 'smooth'`	-
getScrollInfo	获取当前滚动信息	-	`{ scrollLeft, scrollWidth, clientWidth, maxScrollLeft, isAtStart, isAtEnd }`

# 注意事项

# 使用建议

排名徽章:前3名自动显示徽章图标,可通过CSS变量自定义徽章图片
列配置:建议设置合理的列宽度,避免内容溢出
横向滚动:当列内容较多时,组件会自动启用横向滚动
数据格式:dataObject 中的 name 字段会被作为名称显示,其他字段作为动态列
插槽自定义:可以通过插槽自定义任意列的展示内容
响应式适配:在小屏幕设备上,建议适当调整列宽度

# 性能优化

组件使用虚拟化节点减少DOM层级
样式使用CSS变量,便于动态主题切换
支持自定义插槽,灵活扩展功能
横向滚动使用原生 scrollTo API,性能优异

# 兼容性

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

# 主题定制

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

# 样式变量

# 间距系统 (Spacing)

名称	默认值	描述
--pmri-rank-item-margin	0 0 $spacing-xs 0	榜单项外边距
--pmri-rank-item-padding-tb	$spacing-md	榜单项上下内边距
--pmri-rank-item-padding-lr	$spacing-md	榜单项左右内边距
--pmri-rank-margin	0 $spacing-lg 0 0	排名区域右边距
--pmri-user-margin	0 $spacing-md 0 0	用户区域右边距
--pmri-avatar-margin	0 $spacing-xs 0 0	头像右边距
--pmri-column-margin	0 $spacing-md 0 0	列右边距
--pmri-phone-margin	0 $spacing-lg 0 0	手机号右边距
--pmri-score-margin	0 .24rem 0 0	分数右边距
--pmri-rank-badge-wrapper-gap	.04rem	排名标识间距

# 块状系统 (Box Model)

名称	默认值	描述
--pmri-rank-item-width	100%	榜单项宽度
--pmri-rank-item-height	1rem	榜单项最小高度
--pmri-rank-width	1rem	排名区域宽度
--pmri-rank-badge-width	.42rem	排名徽章宽度
--pmri-rank-badge-height	.5rem	排名徽章高度
--pmri-rank-value-width	.42rem	排名数字宽度
--pmri-rank-value-height	.5rem	排名数字高度
--pmri-avatar-size	.5rem	头像尺寸
--pmri-name-width	1.44rem	名称区域宽度
--pmri-column-width	auto	列宽度
--pmri-column-flex-shrink	0	列收缩值
--pmri-rank-item-overflow-x	auto	横向溢出处理
--pmri-rank-item-overflow-y	visible	纵向溢出处理

# 定位系统 (Positioning)

名称	默认值	描述
--pmri-rank-item-position	relative	榜单项定位方式
--pmri-rank-badge-position	relative	排名徽章定位方式

# 边框系统 (Border)

名称	默认值	描述
--pmri-rank-item-radius	$border-radius-xs	榜单项圆角
--pmri-rank-item-shadow	0 -1px 0 0 #e5e5e5 inset	榜单项阴影
--pmri-avatar-radius	$border-radius-circle	头像圆角

# 背景系统 (Background)

名称	默认值	描述
--pmri-rank-item-bg	$color-surface-default	榜单项背景色
--pmri-rank-badge-1	url(...)	第1名徽章图标
--pmri-rank-badge-2	url(...)	第2名徽章图标
--pmri-rank-badge-3	url(...)	第3名徽章图标
--pmri-rank-badge-background-repeat	no-repeat	徽章背景重复方式
--pmri-rank-badge-background-size	contain	徽章背景尺寸

# 文本系统 (Typography)

名称	默认值	描述
--pmri-rank-value-color	$color-text-primary	排名数字颜色
--pmri-rank-label-color	$color-text-primary	排名文字颜色
--pmri-name-color	$color-text-primary	名称颜色
--pmri-column-color	$color-text-primary	列文字颜色
--pmri-phone-color	$color-text-primary	手机号颜色
--pmri-score-color	$color-text-primary	分数颜色
--pmri-address-color	$color-text-secondary	地址颜色
--pmri-rank-value-font-family	inherit	排名数字字体
--pmri-rank-label-font-family	inherit	排名文字字体
--pmri-score-font-family	inherit	分数字体
--pmri-rank-value-font-size	$font-size-lg	排名数字字体大小
--pmri-rank-label-font-size	$font-size-sm	排名文字字体大小
--pmri-name-font-size	$font-size-sm	名称字体大小
--pmri-column-font-size	$font-size-sm	列字体大小
--pmri-phone-font-size	$font-size-sm	手机号字体大小
--pmri-score-font-size	$font-size-md	分数字体大小
--pmri-address-font-size	$font-size-sm	地址字体大小
--pmri-rank-value-font-weight	$font-weight-bold	排名数字字体粗细
--pmri-rank-label-font-weight	$font-weight-regular	排名文字字体粗细
--pmri-name-font-weight	$font-weight-regular	名称字体粗细
--pmri-column-font-weight	$font-weight-regular	列字体粗细
--pmri-phone-font-weight	$font-weight-regular	手机号字体粗细
--pmri-score-font-weight	$font-weight-regular	分数字体粗细
--pmri-address-font-weight	$font-weight-regular	地址字体粗细
--pmri-rank-value-text-align	center	排名数字对齐方式
--pmri-address-text-align	left	地址对齐方式

# 其他属性 (Others)

名称	默认值	描述
--pmri-avatar-object-fit	cover	头像填充方式

← MatchProtocalDialog MatchRankList →