xtf-index-list

组件说明

xtf-index-list 是索引列表组件，基于 xtf-index-bar 封装。通过数据驱动自动生成索引分组列表，支持自定义字段映射和单元格样式，适用于城市选择、联系人列表和分类导航等场景。

---

基础用法

1. 基础用法

通过 dataSource 传入分组数据：

<template>
  <xtf-index-list :data-source="cityList" height="100vh" clickable @item-click="onItemClick" />
</template>

<script>
export default {
  data() {
    return {
      cityList: [
        { name: 'A', items: [{ name: '安阳' }, { name: '鞍山' }] },
        { name: 'B', items: [{ name: '北京' }, { name: '保定' }] },
        { name: 'C', items: [{ name: '成都' }, { name: '重庆' }] }
      ]
    }
  },
  methods: {
    onItemClick(data) {
      console.log('选择城市:', data.item.name)
    }
  }
}
</script>

2. 自定义字段

通过 fieldNames 映射数据字段：

<template>
  <xtf-index-list
    :data-source="contactList"
    :field-names="{ title: 'label', desc: 'phone' }"
    height="100vh"
  />
</template>

<script>
export default {
  data() {
    return {
      contactList: [
        { name: 'A', items: [{ label: '安琪', phone: '138****1234' }] },
        { name: 'B', items: [{ label: '白雪', phone: '139****5678' }] }
      ]
    }
  }
}
</script>

3. 自定义列表项与索引事件

使用 item 插槽渲染业务字段，并监听列表项和侧栏索引事件：

<template>
  <xtf-index-list
    :data-source="groups"
    height="500rpx"
    clickable
    @item-click="onItem"
    @index-select="onIndex"
  >
    <template #item="{ item }">
      <view style="padding: 20rpx 24rpx">
        <text>{{ item.name }}</text>
        <text style="margin-left: 16rpx">{{ item.phone }}</text>
      </view>
    </template>
  </xtf-index-list>
</template>

<script>
export default {
  data() {
    return {
      groups: [
        { name: 'A', items: [{ name: '安琪', phone: '13800000000' }] },
        { name: 'B', items: [{ name: '白雪', phone: '13900000000' }] }
      ]
    }
  },
  methods: {
    onItem({ item }) {
      uni.showToast({ title: item.name, icon: 'none' })
    },
    onIndex({ name }) {
      console.log('切换索引：', name)
    }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
dataSource	Array	[]	分组数据	数据
indexList	Array	[]	索引字符列表	索引
height	String | Number	'100%'	滚动区域高度	布局
highlightColor	String	''	高亮颜色	样式
anchorTextColor	String	'secondary'	锚点文字颜色	样式
sticky	Boolean	true	是否吸顶	吸顶
clickable	Boolean	false	是否可点击	交互
fieldNames	Object	{ title: 'name', desc: '', icon: '', thumb: '' }	字段映射	数据
customClass	String	''	自定义类名	样式覆盖
customStyle	String | Object	''	自定义样式	动态样式覆盖
sidebarClass	String	''	侧栏自定义类名	侧栏
sidebarStyle	String | Object	''	侧栏自定义样式	侧栏
sidebarPadding	String | Number	''	侧栏内边距	侧栏
sidebarRadius	String | Number	''	侧栏圆角	侧栏
sidebarBackground	String	''	侧栏背景色	侧栏
sidebarBorder	String	''	侧栏边框	侧栏
sidebarShadow	String	''	侧栏阴影	侧栏
sidebarRight	String | Number	''	侧栏距右侧距离	侧栏
sidebarItemClass	String | Function	''	侧栏索引项类名；函数接收索引栏组件的参数	侧栏项
sidebarItemStyle	String | Object | Function	''	侧栏索引项样式；函数接收索引栏组件的参数	侧栏项
sidebarItemSize	String | Number	''	侧栏索引项尺寸	侧栏项
sidebarItemRadius	String | Number	''	侧栏索引项圆角	侧栏项
sidebarItemColor	String	''	侧栏索引项文字颜色	侧栏项
sidebarItemActiveColor	String	''	激活侧栏索引项文字颜色	侧栏项
sidebarItemActiveBackground	String	''	激活侧栏索引项背景色	侧栏项
sidebarItemActiveScale	String | Number	''	激活侧栏索引项缩放比例	侧栏项
toastClass	String	''	索引提示层类名	提示层
toastStyle	String | Object	''	索引提示层样式	提示层
toastSize	String | Number	''	索引提示层尺寸	提示层
toastRadius	String | Number	''	索引提示层圆角	提示层
toastBackground	String	''	索引提示层背景色	提示层
toastColor	String	''	索引提示层文字颜色	提示层
groupClass	String | Function	''	分组容器类名；函数接收 { group, groupIndex }	分组
groupGap	String | Number	8	分组底部间距	分组
groupPadding	String | Number | Object	''	分组内边距	分组
groupStyle	String | Object | Function	''	分组容器样式；函数接收 { group, groupIndex }	分组
anchorClass	String | Function	''	锚点类名；函数接收 { group, groupIndex }	锚点
anchorPadding	String | Number | Object	''	锚点内边距	锚点
anchorMargin	String | Number | Object	''	锚点外边距	锚点
anchorRadius	String | Number	''	锚点圆角	锚点
anchorBackground	String	''	锚点背景色	锚点
anchorBorder	String	''	锚点边框	锚点
anchorShadow	String	''	锚点阴影	锚点
anchorStyle	String | Object | Function	''	锚点样式；函数接收 { group, groupIndex }	锚点
cellClass	String | Function	''	单元格类名；函数接收 { group, item, index, groupIndex }	单元格
cellStyle	String | Object | Function	''	单元格样式；函数接收 { group, item, index, groupIndex }	单元格
itemClass	String | Function	''	列表项附加类名；与 cellClass 合并	列表项
itemStyle	String | Object | Function	''	列表项附加样式；与 cellStyle 合并	列表项
cellVariant	String	'soft'	单元格变体，可选 surface、soft、card、glass	单元格
cellTheme	String	'primary'	单元格主题，可选 primary、success、warning、danger、info	单元格
cellSize	String	'md'	单元格尺寸，可选 sm、md、lg	单元格
cellRadius	String | Number	''	单元格圆角	单元格
cellPaddingX	String | Number	''	单元格水平内边距	单元格
cellPaddingY	String | Number	''	单元格垂直内边距	单元格

---

事件

事件名称	触发时机	回调参数	参数说明
item-click	点击列表项时触发	({ group, item, index })	group 为分组名 String，另含项数据和索引
select	点击列表项时触发	({ group, item, index })	与 item-click 同时触发；group 为分组名 String
index-select	触摸侧栏索引时触发	({ index, name })	索引位置和字符

---

插槽

插槽名称	说明
item	自定义列表项内容

插槽示例

<template>
  <xtf-index-list :data-source="groups" height="500rpx" clickable>
    <template #item="{ item }">
      <view>
        <text>{{ item.name }}</text>
<text>{{ item.phone }}</text></view>
</template>

  </xtf-index-list>
</template>
<script>
export default {
  data() {
    return { groups: [{ name: 'A', items: [{ name: '安琪', phone: '13800000000' }] }] }
  }
}
</script>

方法

方法名	参数	返回值	说明
scrollTo	(index: String | Number)	-	委托 xtf-index-bar 滚动到指定索引

侧栏与提示层属性直接透传至 xtf-index-bar。group*、anchor* 的函数型值接收 { group, groupIndex }；cell*、item* 的函数型值接收 { group, item, index, groupIndex }。

---

主题说明

• 锚点使用 xtf-text 组件
• 列表项使用 xtf-cell 组件
• 底层使用 xtf-index-bar 组件

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖相关 CSS 变量。