Vue3通讯录：滑动索引+暗黑模式全适配

ContactList 通讯录页面 - 技术集成文档

下载地址：https://ext.dcloud.net.cn/plugin?id=26704

1. 简介

本页面是一个基于 Vue 3 (Options API) 和 UniApp 开发的通用通讯录组件。它实现了主流 APP 的联系人交互体验，包括右侧悬浮索引栏（支持点击与滑动定位）、顶部吸顶搜索框、分组列表渲染以及暗黑模式（Dark Mode）的完美适配。

该页面设计为无外部重量级依赖（No Lo-Dash, No TypeScript），使用原生 JavaScript 逻辑实现，确保在 App（Android/iOS）、H5 和微信小程序端的性能与兼容性。

2. 功能特性

🔍 实时搜索：支持按姓名或电话号码实时过滤联系人，包含防抖或即时响应逻辑。
🔤 字母索引导航：
点击跳转：点击右侧 A-Z 字母，列表自动滚动到对应锚点。
滑动触控：支持手指在索引栏上滑动（TouchMove），列表实时跟随滚动，并伴有中间的大字母提示弹窗（Toast）。
📱 电话拨打：点击电话图标直接调用系统拨号盘。
🌗 暗黑模式适配：基于 CSS 变量（CSS Custom Properties）实现，自动跟随系统主题切换深色/浅色 UI。
🖼️ 智能头像 ：集成 ui-avatars 生成方案，无头像用户自动展示基于名字首字母的文字头像。
⚙️ 平台兼容：适配 iPhone X+ 底部安全区域，兼容 Android 10+ 及 iOS 12+。

3. 目录结构与依赖

文件结构

text 复制代码

pages/
└── index/
    └── index.vue      # 核心页面文件

依赖说明

uni-ui (uni-icons) : 页面使用了 uni-icons 组件用于展示搜索和电话图标。
如果项目中未安装 uni-ui，请将 <uni-icons> 标签替换为 image 标签或 SVG 代码。

4. 数据结构规范

页面依赖 sourceData 数组进行渲染。在对接后端 API 时，请确保数据映射为以下格式：

javascript 复制代码

// 示例数据模型
[
  {
    "id": 1,                // 唯一标识 (String | Number)
    "name": "艾伦",          // 姓名 (String)
    "phone": "13800138001", // 电话号码 (String)
    "tag": "家人"            // [可选] 标签，如 VIP、家人等 (String)
  },
  // ... 其他联系人
]

注意：当前的 processData 方法内部包含了一个简易的"首字母映射逻辑"仅用于演示。正式上线时，建议由后端接口直接返回拼音首字母字段（如 initial: 'A'），或者在前端引入 pinyin 库进行转换。

5. 核心逻辑解析

5.1. 索引栏滑动定位 (TouchMove)

为了实现类似微信通讯录的滑动效果，而不是单纯的点击跳转，我们使用了原生的 Touch 事件：

初始化 ：在 onReady 中使用 uni.createSelectorQuery 获取索引栏（.index-bar）在页面中的 top 坐标和总高度，计算出单个字母的高度 itemHeight。
滑动计算：

javascript 复制代码

// 计算公式
let index = Math.floor((e.touches[0].clientY - this.boxTop) / this.itemHeight);

通过触摸点的 Y 坐标减去索引栏顶部的偏移，除以单字符高度，得出当前手指所在的字母索引。

防抖与反馈 ：仅当计算出的 currentLetter 发生变化时，才更新 scroll-into-view 的 ID，并触发震动反馈（uni.vibrateShort）。

5.2. 暗黑模式 (Dark Mode)

放弃了传统的 JS 监听方案，采用 CSS 变量结合媒体查询，性能最佳且无闪烁：

css 复制代码

/* 定义变量 */
:root {
  --bg-color: #F8F8F8; /* 浅色背景 */
}

/* 媒体查询覆盖 */
@media (prefers-color-scheme: dark) {
  :root {
    --bg-color: #121212; /* 深色背景 */
  }
}

/* 使用变量 */
.page-container {
  background-color: var(--bg-color);
}

5.3. 滚动跳转

使用 scroll-view 组件的 :scroll-into-view 属性。

ID 命名规则 ：由于 HTML ID 不能以数字开头，我们将 ID 格式化为 index-A, index-B 等。

6. 兼容性说明

平台	版本要求	测试结果	备注
Android	10.0+	✅ 通过	表现流畅，CSS 变量支持良好
iOS	12.0+	✅ 通过	底部 Safe Area 适配正常
H5	Chrome/Safari	✅ 通过	完美支持 Sticky 吸顶效果
微信小程序	基础库 2.x+	✅ 通过	`scroll-view` 高度需准确计算

特殊适配点

iPhone 安全区域 ：
底部增加了 .safe-area-bottom 垫片类，利用 env(safe-area-inset-bottom) 确保最后一行数据不被底部横条遮挡。
图片加载 ：
使用了 lazy-load 属性，且头像源为 ui-avatars.com（纯文本生成图），避免了某些 Android 机型加载大图产生的卡顿，同时解决了无头像显示的尴尬。

7. 二次开发指南

如何更换图标库？

搜索代码中的 <uni-icons>。如果您的项目使用 iconfont 或图片：

html 复制代码

<uni-icons type="search" size="18"></uni-icons>

<image src="/static/search.png" class="icon-search" />

打印日志调试

代码中预留了关键动作的 Console Log，正式发布时可全局搜索 console.log 进行移除或封装：

正在搜索: [Keyword]
点击了联系人: [Object]
尝试拨打电话: [Number]