IndexList 索引列表

IndexList 是一个索引列表组件，用于展示按首字母分组的数据，支持快速导航。

导入

import IndexList from '@/components/list/IndexList.vue';
import IndexBar from '@/components/nav/IndexBar.vue';

使用方法

基础用法

以下是一个基础的索引列表示例，支持按首字母分组和快速导航：

<template>
  <IndexList 
    :data="data"
    :groupDataBy="(item) => item.charAt(0)"
    :sortGroup="arr => arr.sort()"
    :innerStyle="{
      height: '80vh',
    }"
    @itemClick="handleItemClick"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import IndexList from '@/components/list/IndexList.vue';
import Toast from '@/components/feedback/Toast.vue';

const toast = ref();
const data = [
  'Robert Davis',
  'Sandra Allen',
  'Charles Davis',
  'Michael Brown',
  'Joseph Miller',
  'Carol Allen',
  // ...更多数据
];

function handleItemClick(item) {
  toast.info('点击了：' + item);
}
</script>

自定义渲染

IndexList 支持自定义列表项和分组标题的渲染，需要注意小程序和非小程序环境的差异处理：

<template>
  <IndexList 
    :data="data"
    :groupDataBy="(item) => item.charAt(0)"
    :sortGroup="arr => arr.sort()"
    :innerStyle="{
      height: '80vh',
    }"
  >
    <!-- #ifdef MP -->
    <template #list="{ visibleItems, className, itemStyle, onItemPress }">
      <view 
        v-for="(row, index) in visibleItems" 
        :key="row.key"
        :style="itemStyle"
        :class="className"
        @click="onItemPress(row.item, index)"
      > 
        <text :id="row.item.id" v-if="row.item.isHeader" style="height: 40rpx;background-color:#a71">
          Header {{ row.item.header }}
        </text>
        <view :id="row.item.id" v-else>
          <text :style="{ color: index % 2 === 0 ? 'red' : 'green' }">{{ row.item.data }}</text>
        </view>
      </view>
    </template>
    <!-- #endif -->

    <!-- #ifndef MP -->
    <template #header="{ header, id }">
      <text :id="id" style="height: 40rpx;background-color:#a71">
        Header {{ header }}
      </text>
    </template>
    <template #itemContent="{ item, index, id }">
      <view :id="id">
        <text>Index: {{index}}</text>
        <text :style="{ color: index % 2 === 0 ? 'red' : 'green' }">{{ item }}</text>
      </view>
    </template>
    <!-- #endif -->
  </IndexList>
</template>

单独使用 IndexBar

IndexBar 是 IndexList 的侧边滑动组件，也可以单独使用：

<template>
  <view>
    <text :style="{ fontSize: '40rpx' }">当前选中索引 {{ activeIndex }}</text>
    <IndexBar
      v-model:activeIndex="activeIndex"
      :data="dataIndex"
    />
  </view>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import IndexBar from '@/components/nav/IndexBar.vue';

const activeIndex = ref(-1);
const dataIndex = [
  'A', 'B', 'C', 'D', 'E', 'F', 'G', 
  'H', 'I', 'J', 'K', 'L', 'M'
];
</script>

API 参考

IndexList

索引列表组件。

Props

名称	说明	类型	必填	默认值
data	源数据数组	T[]	是	[]
dataKey	数据项的唯一键名，用于vue循环优化	string	否	undefined
dataDisplayProp	显示数据的属性名，为空则直接显示数据	string	否	undefined
colorProp	控制数据条目颜色的字段名称	string	否	undefined
disabledProp	控制是否禁用数据条目的字段名称	string	否	undefined
itemHeight	每个条目的高度（px）	number	否	40
headerHeight	分组标题的高度（px）	number	否	30
groupDataBy	数据分组的回调函数	(item: T) => string	是	-
sortGroup	分组排序的回调函数	(headers: string[]) => string[]	否	undefined
mode	列表选择模式：select（点击选择）、single-check（单选）、mulit-check（多选）	'select' | 'single-check' | 'mulit-check'	否	'select'
checkProps	选择框的自定义属性	CheckBoxDefaultButtonProps	否	{}
defaultSelect	默认选中的条目	any[]	否	[]
innerStyle	内部容器的自定义样式	ViewStyle	否	{}
groupStyle	分组标题的自定义样式	ViewStyle	否	{}
groupTextStyle	分组标题文字的自定义样式	TextStyle	否	{}
itemStyle	条目的自定义样式	ViewStyle	否	{}
textStyle	条目文字的自定义样式	TextStyle	否	{}
checkedItemStyle	选中的条目的自定义样式	ViewStyle	否	{}
checkedTextStyle	选中的条目文字的自定义样式	TextStyle	否	{}
emptyText	空数据时显示的文字	string	否	'暂无数据'

Slots

名称	说明	参数
list	自定义列表渲染（主要用于小程序环境）	{ visibleItems, className, itemStyle, onItemPress }
header	分组标题插槽（非小程序环境）	{ header, id }
item	列表项插槽（非小程序环境）	{ item, index, id }
itemContent	列表项内容插槽（非小程序环境）	{ item, index, id }
empty	空数据时的插槽
inner	内部插槽，用于放置额外内容	-

Events

名称	说明	参数
itemClick	点击列表项时触发	item: T, index: number
selectedItemChanged	选中项目改变时触发（仅在check模式下）	selectedItems: T[]

主题变量

名称	类型	默认值	说明
IndexedListBackgroundColor	string	white	索引列表背景色
IndexedListHeaderBackgroundColor	string	background.page	分组标题背景色
IndexedListHeaderPaddingVertical	number	0	分组标题垂直内边距
IndexedListHeaderPaddingHorizontal	number	30	分组标题水平内边距
IndexedListHeaderFontSize	number	24	分组标题字体大小
IndexedListHeaderColor	string	text.second	分组标题文字颜色
IndexedListItemPaddingHorizontal	number	30	列表项水平内边距
IndexedListItemFontSize	number	28	列表项字体大小
IndexedListItemBorderTopWidth	number	0	列表项顶部边框宽度
IndexedListItemBorderBottomWidth	number	2	列表项底部边框宽度
IndexedListItemBorderColor	string	border.cell	列表项边框颜色
IndexedListItemColor	string	text.content	列表项文字颜色
IndexedListItemBackgroundColor	string	white	列表项背景色
IndexedListItemCheckedTextFontSize	number	28	选中项文字字体大小
IndexedListItemCheckedTextFontWeight	string	bold	选中项文字字体粗细
IndexedListItemCheckedTextColor	string	primary	选中项文字颜色