List

概述

List 是一个 Vue 3 组件，用于显示一个可滚动的列表。该组件支持多种配置选项，如锁定状态、滚动条、初始位置等，并提供了丰富的事件处理机制。

引入

import { List } from 'sofast-extensions';

基本用法

<template>
  <List :items="items" :lock="false" :scroll="true" @handlerSelect="handleSelect" />
</template>

<script setup lang="ts">
import {List} from 'sofast-extensions';
import 'sofast-extensions/dist/style.css';

const items = [
  {icon: 'https://baidu.com/favicon.ico', name: '百度'},
  {icon: 'https://bilibili.com/favicon.ico', name: '哔哩哔哩'},
  {icon: 'https://www.douyin.com/favicon.ico', name: '抖音'},
  {icon: 'https://www.xiaohongshu.com/favicon.ico', name: '小红书'},
  {icon: 'https://www.toutiao.com/favicon.ico', name: '今日头条'},
];

const handleSelect = (item: SimpleItem) => {
  console.log('Selected item:', item);
};
</script>

以下为效果展示，按住 Ctrl + n 或者 Ctrl + p 或者箭头上下键即可上下移动，按住 enter 可以选择对应的选项，与如快的界面风格一致。

Props

属性名	类型	必须	默认值	描述
items	SimpleItem[]	✅	-	列表项数组。每个项包含 id, name, color, icon, type, others 等属性。
lock	boolean		false	是否锁定列表，锁定时无法通过点击或键盘导航选择项。
scroll	boolean		true	是否启用滚动条。
initialPos	number		0	初始选中的项索引。
iconSize	string		-	图标大小，默认为 21px。
title	string		-	列表标题。
pageSize	number		6	每页显示的项数。
handlerSelect	(item: SimpleItem) => void		-	选择项时的回调函数。
handlerImageError	(item: SimpleItem) => void		-	图片加载失败时的回调函数。
handlerEnter	(items: SimpleItem[], currentItem: number) => void		-	按下 Enter 键时的回调函数。
defaultIcon	string		-	默认图标路径。
id	HTMLAttributes['id']		-	列表的 ID。
class	HTMLAttributes['class']		-	列表的类名。
handlerSelect	(item: SimpleItem) => void		-	选择项时触发。
handlerImageError	(item: SimpleItem) => void		-	图片加载失败时触发。
handlerEnter	(items: SimpleItem[], currentItem: number) => void		-	按下 Enter 键时触发。
itemClass	(item: SimpleItem) => HTMLAttributes['class']	string		-
activeClass	sstring		-	item 激活时候的类名，如你想让 item 激活的时候有自己的过滤色，则可以使用这个属性
change	(item: SimpleItem, index: number) => void		-	item 变化时执行的回调
truncate	boolean		-	文字超过一行是否忽略

Slots

插槽名	描述
default	渲染每个列表项的内容（除了 icon和 name）。
currentItem	当前选中的项。

方法

方法名	返回类型	描述
jumpTo	void	跳转到指定索引的项。
getCurrentIndex	number	获取当前选中的项索引。
getItemHeight	number	获取列表项的高度。

示例代码

<template>
  <List :items="items" :lock="false" :scroll="true" @handlerSelect="handleSelect">
    <template #default="{ currentItem }">
      <div>
        <span>{{ currentItem.name }}</span>
        <span>{{ currentItem.color }}</span>
      </div>
    </template>
  </List>
</template>

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

const items = ref([
  { id: 1, name: 'Item 1', color: 'red' },
  { id: 2, name: 'Item 2', color: 'blue' },
  { id: 3, name: 'Item 3', color: 'green' }
]);

const handleSelect = (item: SimpleItem) => {
  console.log('Selected item:', item);
};
</script>

注意事项

• 列表项的高度会自动计算并应用到组件中。
• 键盘导航支持 Ctrl + n 和 Ctrl + p 以及 ArrowDown 和 ArrowUp 键。