MatchUserList 用户列表

# MatchUserList 用户列表

用户列表组件，支持灵活的按钮配置和操作，集成无限滚动加载和空状态显示。采用配置驱动设计，不固化业务状态。

# 特性

👥 灵活配置 - 通过按钮配置数组自由定义每个用户的操作按钮
📜 无限滚动 - 基于 PressList 组件，自动加载更多数据
🎯 统一事件 - 单一 button-click 事件处理所有按钮操作
🎨 主题定制 - 丰富的CSS变量支持主题定制
📱 空状态 - 内置空状态展示
⚡ 高性能 - 优化的列表渲染

# 适用场景

队伍成员管理列表
好友申请列表
用户审核列表
成员邀请列表
任何需要用户列表的场景

# 引入

import PressMatchUserList from 'press-next/press-match-user-list/press-match-user-list';

# 代码演示

# 基础用法

<template>
  <PressMatchUserList
    :list="userList"
    :loading="loading"
    :finished="finished"
    @button-click="handleButtonClick"
    @load-more="handleLoadMore"
  />
</template>

<script setup lang="ts">
import PressMatchUserList from 'press-next/press-match-user-list/press-match-user-list.vue';

const userList = [
  {
    userInfo: {
      avatar: 'https://img.yzcdn.cn/vant/cat.jpeg',
      name: '张三',
      tags: [
        { icon: 'https://example.com/icon.png', name: '王者荣耀' }
      ],
      id: '001'
    },
    buttons: [
      { key: 'ignore', text: '忽略', type: 'default' },
      { key: 'pass', text: '通过', type: 'primary' }
    ]
  }
];

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

// 统一处理按钮点击
const handleButtonClick = (button, userInfo, item, index) => {
  console.log('按钮点击:', button.key, '用户:', userInfo.name);
  
  switch (button.key) {
    case 'ignore':
      console.log('忽略用户');
      break;
    case 'pass':
      console.log('通过用户');
      break;
    case 'transfer':
      console.log('移交队长');
      break;
    case 'kick':
      console.log('踢出队伍');
      break;
  }
};

const handleLoadMore = () => {
  console.log('加载更多数据');
  // 加载数据逻辑
};
</script>

# 不同场景的按钮配置

<template>
  <PressMatchUserList
    :list="userList"
    @button-click="handleButtonClick"
  />
</template>

<script setup lang="ts">
const userList = [
  // 待审核用户
  {
    userInfo: {
      avatar: 'https://img.yzcdn.cn/vant/cat.jpeg',
      name: '待审核用户',
      id: '001'
    },
    buttons: [
      { key: 'ignore', text: '忽略', type: 'default' },
      { key: 'pass', text: '通过', type: 'primary' }
    ]
  },
  // 已通过用户
  {
    userInfo: {
      avatar: 'https://img.yzcdn.cn/vant/cat.jpeg',
      name: '已通过用户',
      id: '002'
    },
    buttons: [
      { key: 'passed', text: '已通过', type: 'default', disabled: true }
    ]
  },
  // 队伍管理
  {
    userInfo: {
      avatar: 'https://img.yzcdn.cn/vant/cat.jpeg',
      name: '队伍成员',
      id: '003'
    },
    buttons: [
      { key: 'transfer', text: '移交队长', type: 'default' },
      { key: 'kick', text: '踢出队伍', type: 'danger' }
    ]
  }
];

const handleButtonClick = (button, userInfo) => {
  console.log(`${button.text} - ${userInfo.name}`);
};
</script>

# 自定义文本和样式

<template>
  <PressMatchUserList
    :list="userList"
    :loading="loading"
    :finished="finished"
    empty-text="暂无用户信息"
    finish-text="已显示全部用户"
    custom-class="custom-user-list"
    @button-click="handleButtonClick"
    @load-more="handleLoadMore"
  />
</template>

<style>
.custom-user-list {
  --pmul-bg-color: #f5f5f5;
}
</style>

# API

# Props

参数	说明	类型	默认值
list	用户列表数据	UserListItem[]	`[]`
loading	是否处于加载状态	boolean	`false`
finished	是否已加载完成	boolean	`false`
empty-text	空状态文本	string	`'暂无数据'`
finish-text	加载完成文本	string	`'没有更多了'`
image	空状态图片	string	-
custom-class	自定义样式类	string	`''`

# UserListItem 数据结构

interface UserListItem {
  userInfo: UserInfo;      // 用户信息
  buttons: ButtonConfig[]; // 按钮配置列表
}

# UserInfo 数据结构

// 标签接口
interface Tag {
  icon?: string; // 标签图标(可选)
  name: string;  // 标签名称
}

// 用户信息接口
interface UserInfo {
  avatar?: string;       // 用户头像(可选)
  name: string;          // 用户名称
  tags?: Tag[];          // 标签列表(可选)
  description?: string;  // 用户描述(可选)
  id?: string;           // 用户ID(可选)
}

# ButtonConfig 数据结构

interface ButtonConfig {
  key: string;           // 按钮唯一标识
  text: string;          // 按钮文本
  type?: ButtonType;     // 按钮类型
  plain?: boolean;       // 是否朴素按钮
  size?: ButtonSize;     // 按钮尺寸
  openType?: string;     // 微信开放能力
  disabled?: boolean;    // 是否禁用
}

type ButtonType = 'primary' | 'default' | 'info' | 'warning' | 'danger';
type ButtonSize = 'normal' | 'large' | 'small' | 'mini';

# Events

事件名	说明	回调参数
load-more	滚动到底部时触发	-
button-click	点击按钮时触发	`(button: ButtonConfig, userInfo: UserInfo, item: UserListItem, index: number)`
image-error	头像加载失败时触发	`(userInfo: UserInfo, item: UserListItem, index: number)`

# 注意事项

# 使用建议

按钮配置：每个用户项可以配置不同的按钮，通过 buttons 数组灵活定义
事件处理：使用统一的 button-click 事件，根据 button.key 区分不同操作
加载更多：通过 loading 和 finished 属性控制加载状态
空状态：当列表为空时自动显示空状态组件
头像和标签：avatar 和 tags.icon 字段均为可选，不传则不显示对应内容

# 设计理念

本组件采用配置驱动的设计理念：

不固化业务状态：通过 buttons 配置数组自由定义操作
统一事件处理：单一 button-click 事件处理所有按钮操作
灵活扩展：可以随时添加、删除、修改按钮配置

# 性能优化

使用虚拟列表优化大量数据渲染
合理使用 finished 属性避免重复加载
图片懒加载提升首屏性能

# 兼容性

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

# 主题定制

# 样式变量

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

# 颜色系统 (Colors)

名称	默认值	描述
--pmul-bg-color	$color-surface-default	背景色

← MatchUserItem MatchWatchItem →