更新记录

1.0.0（2026-07-09）

初始版本，授权后获取手机通讯录、获取当前地理位置信息

平台兼容性

uni-app(4.28)

uni-app x(4.18)

其他

获取手机通讯录和当前位置 UTS 插件

• 当前版本：1.0.0；
• 插件 ID：vutet-contact；
• 插件类型：uni_modules UTS 插件；
• 发布包：vutet-contact/vutet-contact_v1.0.0.zip；
• 支持读取手机通讯录联系人姓名和手机号；
• 支持获取当前经纬度，并返回地理位置解析字段；
• 支持检查并申请通讯录、定位权限；
• 支持打开应用权限设置页；
• 支持 App Android、App iOS、HarmonyOS。

接口

uni-app 使用示例

// 技术支持：***274472113
const contactModule = require("@/uni_modules/vutet-contact");

contactModule.getContacts({}, (res) => {
  console.log(res);

  if (!(res && (res.status === 200 || res.code === 0 || res.code === 200))) {
    uni.showToast({
      title: (res && (res.msg || res.message)) || "获取通讯录失败",
      icon: "none",
    });
    return;
  }

  const contacts = res.data || [];
  console.log("contacts:", contacts);
});

contactModule.getLocation({}, (res) => {
  console.log(res);

  if (!(res && (res.status === 200 || res.code === 200))) {
    uni.showToast({
      title: (res && (res.msg || res.message)) || "获取定位失败",
      icon: "none",
    });
    return;
  }

  const location = res.data || {};
  console.log("longitude:", location.longitude);
  console.log("latitude:", location.latitude);
  console.log("address:", location.address);
});

通讯录返回示例

{
  status: 200,
  code: 200,
  msg: "获取通讯录成功",
  message: "获取通讯录成功",
  type: "contacts",
  authorized: true,
  total: 2,
  data: [
    {
      name: "张三",
      familyName: "张",
      givenName: "三",
      phoneNumbers: ["***"],
      phone: "***"
    }
  ]
}

Android 兼容旧版字段，getContacts 成功时也可能返回：

{
  code: 0,
  message: "获取成功",
  data: [
    {
      name: "张三",
      phone: "***"
    }
  ]
}

定位返回示例

{
  status: 200,
  code: 200,
  msg: "获取定位成功",
  message: "获取定位成功",
  type: "location",
  authorized: true,
  data: {
    longitude: "121.473701",
    latitude: "31.230416",
    country: "中国",
    province: "上海市",
    city: "上海市",
    area: "黄浦区",
    street: "人民大道",
    address: "上海市黄浦区人民大道"
  }
}

检查权限

const contactModule = require("@/uni_modules/vutet-contact");

// 兼容旧接口，默认检查通讯录权限。
contactModule.checkPermission((res) => {
  console.log(res);
});

contactModule.checkPermissions({ type: "contacts" }, (res) => {
  console.log(res);
});

contactModule.checkPermissions({ type: "location" }, (res) => {
  console.log(res);
});

权限检查返回示例：

{
  status: 200,
  code: 200,
  msg: "已获得定位权限",
  message: "已获得定位权限",
  type: "location",
  authorized: true,
  needPermission: false,
  needSettings: false
}

如果首次没有权限，checkPermission、checkPermissions、getContacts、getLocation 都会尝试发起一次系统权限申请，并返回 needPermission: true。用户拒绝后再次调用通常不会再弹系统授权框，业务侧可根据 needSettings: true 引导用户调用 openSettings。

打开设置页

const contactModule = require("@/uni_modules/vutet-contact");

contactModule.openSettings((res) => {
  console.log(res);
});

权限说明

• Android 需要 android.permission.READ_CONTACTS、android.permission.ACCESS_FINE_LOCATION、android.permission.ACCESS_COARSE_LOCATION。
• iOS 需要 NSContactsUsageDescription、NSLocationWhenInUseUsageDescription。
• HarmonyOS 使用 ContactsKit、LocationKit、AbilityKit 相关系统能力。
• iOS 定位解析字段参考相册插件 parseLocation 的成熟字段格式：longitude、latitude、country、province、city、area、street、address。

打包说明

插件包按 UTS uni_modules 结构交付：

vutet-contact_v1.0.0.zip
└── vutet-contact/
    ├── package.json
    ├── readme.md
    ├── changelog.md
    └── utssdk/

问题反馈

插件可能存在的问题：

1. Android、iOS、HarmonyOS 返回字段存在平台差异，业务侧建议统一兼容 status/code 和 msg/message；
2. 部分系统或通讯录账号可能返回空姓名、空手机号；
3. 定位解析依赖系统服务，弱网或系统定位服务关闭时可能无法返回完整地址；
4. 联系 ***。