Press Next

# MatchRankList

Rank list component for displaying user ranking information with infinite scroll loading, horizontal scrolling and empty state support.

# Features

  • πŸ“Š Flexible Layout - Supports auto column adaptation and custom column configuration
  • πŸ”„ Infinite Scroll - Infinite scroll loading based on PressList component
  • ↔️ Horizontal Scroll - Auto-enabled horizontal scroll for multiple columns with programmatic control
  • 🎨 Theme Customization - Rich CSS variables for theme customization
  • πŸ“± Responsive Design - Adapts to different screen sizes
  • πŸ”§ Slot Support - Supports custom column content rendering

# Use Cases

  • E-sports competition leaderboards
  • Game score rankings
  • User achievement lists
  • Data statistics display

# Import

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

# Code Demo

# Basic Usage

Use dataObject to pass data, the component will automatically display all fields.

<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: 'Zhang San',
    dataObject: {
      phone: '18505556789',
      score: 15,
      address: 'Wangyu Internet Cafe Huashan Street',
    },
  },
  {
    rank: 2,
    showRankText: false,
    avatar: 'https://img.yzcdn.cn/vant/cat.jpeg',
    name: 'Li Si',
    dataObject: {
      phone: '13800138000',
      score: 12,
      address: 'Wangyu Internet Cafe Renmin Road',
    },
  },
]);

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

const handleLoadMore = () => {
  console.log('Load more data');
};

const handleItemClick = (item, index) => {
  console.log('Rank item clicked:', item, index);
};
</script>

# Using Column Configuration

Control which columns to display via columns property.

<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: 'Zhang San',
    dataObject: {
      phone: '18505556789',
      score: 100,
      address: 'Wangyu Internet Cafe Huashan Street',
      team: 'Red Team',
    },
  },
]);

// Display only phone, score, address columns
const columns = ref([
  { key: 'phone', visible: true },
  { key: 'score', visible: true },
  { key: 'address', visible: true },
]);
</script>

# Horizontal Scroll Control

The component provides rich scroll control methods.

<template>
  <div>
    <div class="controls">
      <button @click="scrollToStart">Scroll to Left</button>
      <button @click="scrollToEnd">Scroll to Right</button>
      <button @click="scrollLeft">Scroll Left</button>
      <button @click="scrollRight">Scroll Right</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>

# Custom Text

<template>
  <PressMatchRankList
    :list="rankList"
    :loading="loading"
    :finished="finished"
    empty-text="No ranking data available"
    finish-text="All rankings displayed"
    @load-more="handleLoadMore"
  />
</template>

# Empty State

<template>
  <PressMatchRankList
    :list="[]"
    empty-text="No data"
  />
</template>

# API

# Props

Attribute Description Type Default
list Rank data list RankItem[] []
columns Column configuration array ColumnConfig[] []
loading Whether in loading state boolean false
finished Whether loading finished boolean false
empty-text Empty state text string 'No data'
finish-text Finish loading text string 'No more'
image Empty state image URL string -
custom-class Custom CSS class string ''

# RankItem Data Structure

interface RankItem {
  rank: number; // Rank number
  showRankText?: boolean; // Whether to show "Rank X" text
  avatar: string; // Avatar URL
  name?: string; // User name
  dataObject?: Record<string, string | number>; // Data object with custom columns
}

# ColumnConfig Data Structure

interface ColumnConfig {
  key: string; // Column identifier, corresponds to field name in dataObject
  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
}

# Events

Event Description Parameters
load-more Triggered when scrolled to bottom for loading more data -
item-click Triggered when rank item clicked (item: RankItem, index: number)

# Methods

Use ref to get component instance and call instance methods.

Method Description Parameters Return
scrollTo Scroll to specified position { left: number, behavior?: 'auto' \| 'smooth' } -
scrollBy Scroll by specified distance { left: number, behavior?: 'auto' \| 'smooth' } -
scrollToStart Scroll to leftmost behavior?: 'auto' \| 'smooth' -
scrollToEnd Scroll to rightmost behavior?: 'auto' \| 'smooth' -
getScrollInfo Get current scroll information - ScrollInfo

# ScrollInfo Data Structure

interface ScrollInfo {
  scrollLeft: number; // Current horizontal scroll position
  scrollWidth: number; // Total content width
  clientWidth: number; // Visible area width
  maxScrollLeft: number; // Maximum scroll position
  isAtStart: boolean; // Whether at start position
  isAtEnd: boolean; // Whether at end position
}

# Notes

# Usage Guidelines

  1. Data Structure: Fields in dataObject are automatically rendered as columns, name field is displayed in user info column
  2. Column Config Priority: If both columns and dataObject are set, columns takes priority
  3. Horizontal Scroll: Auto-enabled when there are many columns, controlled by CSS variable --pmrl-container-overflow-x
  4. Loading State: Use loading and finished props for infinite scroll loading
  5. Empty State: Auto-displayed when list is empty
  6. Responsive: Adjust related size variables for small screen devices

# Performance Optimization

  • Component uses virtualized nodes to reduce DOM levels
  • List items use v-for and key for optimized rendering
  • Supports lazy loading for on-demand data
  • Horizontal scroll uses native capabilities for excellent performance

# Compatibility

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

# Theme Customization

The component provides the following CSS variables for custom styles. For usage, please refer to ConfigProvider component.

# Style Variables

# Box Model

Name Default Value Description
--pmrl-container-width 100% Container width
--pmrl-container-margin 0 Container margin
--pmrl-container-padding 0 Container padding

# Border

Name Default Value Description
--pmrl-container-radius 0 Container border radius

# Background

Name Default Value Description
--pmrl-container-bg $color-surface-default Container background color

# Others

Name Default Value Description
--pmrl-container-overflow-x auto Container horizontal overflow
--pmrl-container-overflow-y auto Container vertical overflow

← MatchResetPopup β†’