Press Next

# MatchRankItem

Display a single item in a ranking list, supporting a combination of dynamic and fixed columns. Suitable for various ranking lists, points lists, score lists and other scenarios.

# Features

  • πŸ† Rank Display - Top 3 show badge icons, others show numeric ranks
  • πŸ“Š Dynamic Column Config - Flexibly configure displayed columns and alignment
  • 🎨 Theme Customization - Rich CSS variables for theme customization
  • πŸ“± Horizontal Scroll - Support horizontal scrolling and scroll control methods
  • πŸ”§ Slot Support - Support custom name and column content
  • ⚑ Lightweight & Efficient - Optimized code structure with excellent performance

# Use Cases

  • Game leaderboard display
  • E-sports competition points table
  • Online exam scoreboard
  • Event participant list

# Import

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

# Code Demo

# Basic Usage

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

# Using dataObject and columns

Pass data object through dataObject, define column configuration through columns:

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

<script setup lang="ts">
const userData = {
  name: 'John Doe',
  phone: '138****1234',
  score: 88,
  address: 'Shenzhen, Guangdong'
};

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

Set show-rank-text to show "No.x" text:

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

# Custom Column Content

Use slots to customize the content of specific columns:

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

# Horizontal Scroll Control

<template>
  <PressMatchRankItem
    ref="rankItemRef"
    :rank="1"
    :avatar="avatarUrl"
    :data-object="userData"
  />
  <button @click="handleScrollRight">Scroll Right</button>
  <button @click="handleScrollToLeft">Scroll to Left</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>

# Custom Theme

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

<style>
.my-custom-theme {
  /* Background and border styles */
  --pmri-rank-item-bg: linear-gradient(to right, #f5f5f5, #ffffff);
  --pmri-rank-item-radius: .16rem;
  
  /* Text colors */
  --pmri-rank-value-color: #ff6b00;
  --pmri-name-color: #333333;
}
</style>

# API

# Props

Parameter Description Type Default
custom-class Custom style class string ''
rank Rank number number 1
show-rank-text Whether to show rank text (No.x) boolean false
avatar Avatar URL string ''
name Name string ''
data-object Data object (contains all custom column data) _Record<string, string \ number>_
columns Column configuration array ColumnConfig[] []

# ColumnConfig Type Definition

interface ColumnConfig {
  key: string;                           // Column identifier, corresponds to dataObject key
  visible?: boolean;                     // Whether visible, default true
  width?: string;                        // Column width, e.g. '1.5rem', 'auto'
  minWidth?: string;                     // Minimum width, e.g. '1rem'
  align?: 'left' | 'center' | 'right';   // Text alignment, default left
}

# Slots

Name Description Parameters
name Custom name display { value: string }
[column.key] Custom corresponding column content { value: any }

# Methods

Component exposes the following methods through ref for horizontal scroll control:

Method Description Parameters Return
scrollTo Scroll to specified position { left?: number, behavior?: 'auto' \\| 'smooth' } -
scrollToLeft Scroll to leftmost behavior?: 'auto' \\| 'smooth' -
scrollToRight Scroll to rightmost behavior?: 'auto' \\| 'smooth' -
scrollLeft Scroll left by distance distance?: number, behavior?: 'auto' \\| 'smooth' -
scrollRight Scroll right by distance distance?: number, behavior?: 'auto' \\| 'smooth' -
getScrollInfo Get current scroll info - { scrollLeft, scrollWidth, clientWidth, maxScrollLeft, isAtStart, isAtEnd }

# Notes

# Usage Recommendations

  1. Rank Badges: Top 3 automatically show badge icons, can customize badge images through CSS variables
  2. Column Configuration: Recommend setting reasonable column widths to avoid content overflow
  3. Horizontal Scroll: Component automatically enables horizontal scrolling when column content is excessive
  4. Data Format: name field in dataObject will be displayed as the name, other fields as dynamic columns
  5. Slot Customization: Can customize display content of any column through slots
  6. Responsive Adaptation: On small screen devices, recommend adjusting column widths appropriately

# Performance Optimization

  • Component uses virtual host to reduce DOM layers
  • Styles use CSS variables for easy dynamic theme switching
  • Support custom slots for flexible extension
  • Horizontal scrolling uses native scrollTo API with excellent performance

# Compatibility

  • Support Vue 3.0+
  • Compatible with modern browsers (Chrome 60+, Firefox 60+, Safari 12+)
  • Support WeChat Mini Program, Alipay Mini Program and other platforms

# Theme Customization

The component provides the following CSS variables for custom styling. Please refer to the ConfigProvider component for usage.

# Style Variables

# Spacing System

Name Default Description
--pmri-rank-item-margin 0 0 $spacing-xs 0 Rank item margin
--pmri-rank-item-padding-tb $spacing-md Rank item top/bottom padding
--pmri-rank-item-padding-lr $spacing-md Rank item left/right padding
--pmri-rank-margin 0 $spacing-lg 0 0 Rank area right margin
--pmri-user-margin 0 $spacing-md 0 0 User area right margin
--pmri-avatar-margin 0 $spacing-xs 0 0 Avatar right margin
--pmri-column-margin 0 $spacing-md 0 0 Column right margin
--pmri-phone-margin 0 $spacing-lg 0 0 Phone right margin
--pmri-score-margin 0 .24rem 0 0 Score right margin
--pmri-rank-badge-wrapper-gap .04rem Rank badge gap

# Box Model System

Name Default Description
--pmri-rank-item-width 100% Rank item width
--pmri-rank-item-height 1rem Rank item min height
--pmri-rank-width 1rem Rank area width
--pmri-rank-badge-width .42rem Rank badge width
--pmri-rank-badge-height .5rem Rank badge height
--pmri-rank-value-width .42rem Rank value width
--pmri-rank-value-height .5rem Rank value height
--pmri-avatar-size .5rem Avatar size
--pmri-name-width 1.44rem Name area width
--pmri-column-width auto Column width
--pmri-column-flex-shrink 0 Column flex shrink
--pmri-rank-item-overflow-x auto Horizontal overflow
--pmri-rank-item-overflow-y visible Vertical overflow

# Positioning System

Name Default Description
--pmri-rank-item-position relative Rank item position
--pmri-rank-badge-position relative Rank badge position

# Border System

Name Default Description
--pmri-rank-item-radius $border-radius-xs Rank item border radius
--pmri-rank-item-shadow 0 -1px 0 0 #e5e5e5 inset Rank item shadow
--pmri-avatar-radius $border-radius-circle Avatar border radius

# Background System

Name Default Description
--pmri-rank-item-bg $color-surface-default Rank item background
--pmri-rank-badge-1 url(...) Rank 1 badge icon
--pmri-rank-badge-2 url(...) Rank 2 badge icon
--pmri-rank-badge-3 url(...) Rank 3 badge icon
--pmri-rank-badge-background-repeat no-repeat Badge background repeat
--pmri-rank-badge-background-size contain Badge background size

# Typography System

Name Default Description
--pmri-rank-value-color $color-text-primary Rank value color
--pmri-rank-label-color $color-text-primary Rank label color
--pmri-name-color $color-text-primary Name color
--pmri-column-color $color-text-primary Column text color
--pmri-phone-color $color-text-primary Phone color
--pmri-score-color $color-text-primary Score color
--pmri-address-color $color-text-secondary Address color
--pmri-rank-value-font-family inherit Rank value font family
--pmri-rank-label-font-family inherit Rank label font family
--pmri-score-font-family inherit Score font family
--pmri-rank-value-font-size $font-size-lg Rank value font size
--pmri-rank-label-font-size $font-size-sm Rank label font size
--pmri-name-font-size $font-size-sm Name font size
--pmri-column-font-size $font-size-sm Column font size
--pmri-phone-font-size $font-size-sm Phone font size
--pmri-score-font-size $font-size-md Score font size
--pmri-address-font-size $font-size-sm Address font size
--pmri-rank-value-font-weight $font-weight-bold Rank value font weight
--pmri-rank-label-font-weight $font-weight-regular Rank label font weight
--pmri-name-font-weight $font-weight-regular Name font weight
--pmri-column-font-weight $font-weight-regular Column font weight
--pmri-phone-font-weight $font-weight-regular Phone font weight
--pmri-score-font-weight $font-weight-regular Score font weight
--pmri-address-font-weight $font-weight-regular Address font weight
--pmri-rank-value-text-align center Rank value text align
--pmri-address-text-align left Address text align

# Others

Name Default Description
--pmri-avatar-object-fit cover Avatar object fit

← MatchRankList β†’