更新记录

1.0.1（2026-01-24） 下载此版本

新版本发布

平台兼容性

uni-app(3.8.1)

其他

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

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. 目录结构与依赖

文件结构

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

依赖说明

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

4. 数据结构规范

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

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

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

5. 核心逻辑解析

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

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

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

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

通过触摸点的 Y 坐标减去索引栏顶部的偏移，除以单字符高度，得出当前手指所在的字母索引。
3. **防抖与反馈**：仅当计算出的 `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. 兼容性说明

特殊适配点

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

7. 二次开发指南

如何更换图标库？

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

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

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

打印日志调试

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

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