更新记录

1.0.1（2026-02-21）

优化源码授权

1.0.0（2026-02-21）

平台兼容性

uni-app(3.6.17)

其他

通讯录选择器组件 xtf-contact-picker

📱 简介

一个简洁的通讯录选择器组件，打开系统通讯录选择联系人，返回原始数据。只做一件事：选择联系人并返回，所有业务逻辑（重复判断、数据过滤）都由使用方处理。

💰 价格说明

✨ 功能特点

• ✅ 打开系统通讯录选择联系人 - Android系统原生界面
• ✅ 搜索过滤 - 支持按姓名、电话实时搜索
• ✅ 返回原始数据 - 电话是啥就是啥，不做任何格式化处理
• ✅ 自动权限处理 - 自动请求通讯录权限
• ✅ 自定义触发按钮 - 支持插槽自定义样式
• ✅ 轻量级 - 无额外依赖，开箱即用

📋 平台兼容性

⚠️ 注意：iOS端暂未真机测试，基于plus.contacts实现理论可用。如遇问题请在评论区反馈。

🚀 快速上手

1. 购买导入

购买后可在HBuilderX中直接导入，或下载ZIP解压到 uni_modules 目录。

2. 配置权限

在 manifest.json 中配置通讯录权限：

{
  "app-plus": {
    "distribute": {
      "android": {
        "permissions": [
          "<uses-permission android:name=\"android.permission.READ_CONTACTS\"/>"
        ]
      },
      "ios": {
        "plist": {
          "NSContactsUsageDescription": "需要访问通讯录以选择联系人"
        }
      }
    }
  }
}

3. 在页面中使用

<template>
  <view>
    <!-- 基础用法 -->
    <xtf-contact-picker @onSelect="handleSelect" />

    <!-- 自定义触发按钮 -->
    <xtf-contact-picker @onSelect="handleSelect">
      <template #trigger>
        <button class="my-btn">📱 从通讯录选择</button>
      </template>
    </xtf-contact-picker>
  </view>
</template>

<script>
import xtfContactPicker from '@/uni_modules/xtf-contact-picker/components/xtf-contact-picker/xtf-contact-picker.vue'

export default {
  components: { xtfContactPicker },
  methods: {
    handleSelect(contact) {
      console.log('选择的联系人:', contact)  // 返回原始数据
      // 业务逻辑：检查重复、添加等由您自己处理
      // 例如：
      // if (this.contacts.some(c => c.phone === contact.phone)) {
      //   uni.showToast({ title: '联系人已存在', icon: 'none' })
      //   return
      // }
      // this.contacts.push({ id: Date.now(), ...contact })
    }
  }
}
</script>

📚 API文档

Props

Events

Methods

Slots

🔐 权限说明

• Android：android.permission.READ_CONTACTS
• iOS：NSContactsUsageDescription

组件已内置权限请求逻辑，无需额外代码。

⚠️ 注意事项

1. 平台限制：仅支持App平台（Android已测试，iOS理论支持）
2. 数据处理：插件不做任何电话格式化，返回原始数据，所有业务逻辑由使用方处理
3. 重复判断：插件不判断联系人是否已存在，需在使用方自行处理
4. 提示控制：插件内部无任何toast提示，所有提示由使用方控制

❓ 常见问题

Q：iOS能用吗？
A：基于plus.contacts API实现，理论可用。暂未真机测试，欢迎反馈。

Q：电话会格式化吗？
A：不会，返回原始电话格式，是啥就是啥。

Q：会提示选择成功吗？
A：不会，插件内部没有任何提示，您可以在父页面按需提示。

📝 更新日志

1.0.0 (2026-02-21)

• 🎉 首次发布
• ✨ 支持Android系统通讯录选择
• 🔍 支持搜索过滤
• 🔐 自动权限处理
• 🎨 支持自定义触发按钮

📞 联系作者

• 邮箱：您的邮箱@example.com
• 评论区：可直接留言反馈