发送短信/拨打电话/获取联系人能力 UTS 插件（cz-sms）发送短信/拨打电话/获取联系人能力 UTS 插件（cz-

发送短信/拨打电话/获取联系人能力 UTS 插件（cz-sms）

介绍

提供短信、电话、邮件、SIM 卡信息、通话状态、短信列表、通话记录、联系人读取等常用系统能力。
支持 uni-app / uni-app x 的 App 平台接入，当前已包含 Android、iOS、HarmonyOS NEXT 三端实现。
不同平台系统开放能力差异较大，尤其是 iOS 与 HarmonyOS NEXT 对隐式短信、系统短信读取、通话记录读取等能力限制较多，使用前请先查看本文档中的平台支持说明。

平台支持说明

能力	Android	iOS	HarmonyOS NEXT	说明
显式发送短信 `sendVisibleSms`	支持	支持	支持	打开系统短信界面并预填号码与内容
隐式发送短信 `sendHiddenSms`	支持	不支持	不支持	Android 支持后台发送，iOS 与 Harmony 当前实现直接返回不支持
显式发送邮件 `sendVisibleEmail`	支持	支持	支持	打开系统邮件应用并预填内容
注册短信监听 `registerSmsListener`	支持	不支持	不支持	iOS 与 HarmonyOS NEXT 第三方应用受系统限制
取消短信监听 `unregisterSmsListener`	支持	兼容返回	兼容返回	iOS 与 Harmony 为兼容接口返回
获取 SIM 卡信息 `getSimInfo`	支持	不支持	不支持	Android 可返回双卡信息；iOS / Harmony 当前实现直接返回不支持
显式拨打电话 `makeVisibleCall`	支持	支持	支持	打开拨号界面或系统电话应用
隐式拨打电话 `makeHiddenCall`	支持	不支持	不支持	Android 支持直接呼出；iOS / Harmony 当前实现直接返回不支持
注册电话监听 `registerCallListener`	支持	支持	支持	三端当前均为系统整体通话状态监听，不是精确双卡分别监听
取消电话监听 `unregisterCallListener`	支持	支持	支持	取消已注册的通话状态监听
获取通话记录 `getCallLogs`	支持	不支持	不支持	仅 Android 可读取系统通话记录
获取短信列表 `getSmsList`	支持	不支持	不支持	仅 Android 可读取系统短信列表
获取联系人列表 `getContacts`	支持	支持	支持	三端均支持读取联系人

API说明

方法名称	参数	返回参数	说明
sendVisibleSms	`SendVisibleSmsParams`	`ResponseEntity`	显式发送短信，打开系统短信界面
sendHiddenSms	`SendHiddenSmsParams`	`ResponseEntity`	隐式发送短信，Android 支持按 `subId` 发送
sendVisibleEmail	`SendVisibleEmailParams`	`ResponseEntity`	显式发送邮件，打开系统邮件界面
registerSmsListener	`SmsListenParams`	`ResponseEntity`	注册短信监听，仅 Android 支持真实短信监听
unregisterSmsListener	无	`boolean`	取消短信监听
getSimInfo	`GetSimInfoParams`	`ResponseEntity`	获取双卡信息、默认语音卡、默认短信卡
makeVisibleCall	`MakeVisibleCallParams`	`ResponseEntity`	显式拨号，打开拨号界面
makeHiddenCall	`MakeHiddenCallParams`	`ResponseEntity`	隐式拨号，Android 可按 `subId` 直接呼出
registerCallListener	`CallListenParams`	`ResponseEntity`	注册电话状态监听
unregisterCallListener	无	`boolean`	取消电话状态监听
getCallLogs	`GetCallLogsParams`	`ResponseEntity`	获取通话记录，仅 Android 支持
getSmsList	`GetSmsListParams`	`ResponseEntity`	获取短信列表，仅 Android 支持
getContacts	`GetContactsParams`	`ResponseEntity`	获取联系人列表

插件试用

APK下载

参数与返回结构说明

ResponseEntity

type ResponseEntity = {
  success: boolean // 是否成功
  data?: any | null // 返回数据，不同 API 对应不同结构
  message?: string | null // 提示信息或错误信息
}

SendVisibleSmsParams

type SendVisibleSmsParams = {
  phone: string // 手机号码
  message: string // 短信内容
  completeListener?: (res: ResponseEntity) => void // 结果回调
}

SendHiddenSmsParams

type SendHiddenSmsParams = {
  phone: string // 手机号码
  message: string // 短信内容
  subId: number | null // 卡槽索引 0 或 1，Android 发隐式短信时使用
  completeListener?: (res: ResponseEntity) => void // 结果回调
}

SendVisibleEmailParams

type SendVisibleEmailParams = {
  emails: string[] // 收件人邮箱列表
  title: string // 邮件标题
  message: string // 邮件正文
  completeListener?: (res: ResponseEntity) => void // 结果回调
}

SmsBMessage

type SmsBMessage = {
  sender: string | null // 发件人号码
  body: string | null // 短信正文
  timestamp: number | null // 短信时间戳（毫秒）
  emailBody: string | null // 邮件网关正文
  emailFrom: string | null // 邮件网关发件人
  indexOnIcc: number | null // ICC 索引
  indexOnSim: number | null // SIM 索引
  protocolIdentifier: number | null // 协议标识符
  pseudoSubject: string | null // 伪主题
  serviceCenterAddress: string | null // 短信中心地址
  status: number | null // 短信状态
  statusOnIcc: number | null // ICC 状态
  isCphsMwiMessage: boolean | null // 是否 CPHS 语音邮件通知
  isEmail: boolean | null // 是否来自邮件网关
  isMWIClearMessage: boolean | null // 是否清除语音邮件通知
  isMWISetMessage: boolean | null // 是否设置语音邮件通知
  isMwiDontStore: boolean | null // 语音邮件通知是否不存储
  isReplace: boolean | null // 是否为替换短信
  isReplyPathPresent: boolean | null // 是否存在回复路径
  isStatusReportMessage: boolean | null // 是否状态报告短信
}

SimCardInfo / DualSimResult

type SimCardInfo = {
  slotIndex: number | null // 卡槽索引 0 或 1
  subId: number | null // 订阅 ID，Android 发隐式短信时可用
  carrierName: string | null // 运营商名称
  phoneNumber: string | null // 手机号码，部分运营商可能为空
  displayName: string | null // 系统显示名称
  defaultVoice: boolean | null // 是否默认通话卡
  defaultSms: boolean | null // 是否默认短信卡
}

type DualSimResult = {
  isDualSim: boolean // 是否双卡
  simCount: number // SIM 卡数量
  simCards: SimCardInfo[] // SIM 卡列表
}

CallStateMessage

type CallStateMessage = {
  state: "ringing" | "offhook" | "idle" // 响铃 / 通话中 / 空闲
  phoneNumber: string | null | undefined // 号码，部分状态或平台可能为空
  slotIndex: number | null // 卡槽索引 0 或 1，部分平台仅为兼容字段
}

说明：

Android 当前电话监听监听的是系统整体通话状态，不是精确按某个 SIM 卡单独监听。
iOS 当前通话监听不返回号码，也不支持区分具体 SIM 卡。
HarmonyOS NEXT 当前同样不是精确双卡分别监听。

CallLogRecord

type CallLogRecord = {
  phoneNumber: string | null // 通话号码
  callType: "incoming" | "outgoing" | "missed" | "rejected" | "blocked" | "unknown" // 通话类型
  duration: number | null // 通话时长，单位秒
  timestamp: number | null // 通话时间戳（毫秒）
  name: string | null // 联系人姓名
}

SmsRecord

type SmsRecord = {
  id: string | null // 短信 ID
  threadId: string | null // 会话 ID
  phone: string | null // 对方号码
  body: string | null // 短信正文
  timestamp: number // 时间戳（毫秒）
  smsType: "inbox" | "sent" | "draft" | "outbox" | "failed" | "queued" | "unknown" // 短信类型
  isRead: boolean // 是否已读
}

ContactRecord

type ContactPhone = {
  number: string | null // 电话号码
  phoneType: string | null // 号码类型，如 mobile / home / work
}

type ContactRecord = {
  id: string | null // 联系人 ID
  name: string | null // 联系人姓名
  phones: ContactPhone[] | null // 电话列表
  photoUri: string | undefined | null // 头像 URI
  starred: boolean // 是否星标联系人
}

插件试用

建议先在真机环境验证以下能力：

Android：显式短信、隐式短信、SIM 卡信息、电话监听、通话记录、短信列表、联系人。
iOS：显式短信、显式邮件、显式拨号、通话监听、联系人。
HarmonyOS NEXT：显式短信、显式邮件、显式拨号、通话监听、联系人。

VUE代码调用示例

<script>
import {
  sendVisibleSms,
  sendHiddenSms,
  sendVisibleEmail,
  registerCallListener,
  unregisterCallListener,
  getSimInfo,
  makeVisibleCall,
  makeHiddenCall,
  getCallLogs,
  getSmsList,
  getContacts
} from "@/uni_modules/cz-sms"

export default {
  methods: {
    testSendVisibleSms() {
      sendVisibleSms({
        phone: "13800138000",
        message: "这是一条测试短信",
        completeListener: (res) => {
          console.log("sendVisibleSms", res)
        }
      })
    },

    testSendHiddenSms() {
      sendHiddenSms({
        phone: "13800138000",
        message: "这是一条后台发送短信测试",
        subId: null,
        completeListener: (res) => {
          console.log("sendHiddenSms", res)
        }
      })
    },

    testSendVisibleEmail() {
      sendVisibleEmail({
        emails: ["test@example.com"],
        title: "邮件标题",
        message: "邮件正文内容",
        completeListener: (res) => {
          console.log("sendVisibleEmail", res)
        }
      })
    },

    testGetSimInfo() {
      getSimInfo({
        completeListener: (res) => {
          console.log("getSimInfo", res)
        }
      })
    },

    testMakeVisibleCall() {
      makeVisibleCall({
        phone: "13800138000",
        completeListener: (res) => {
          console.log("makeVisibleCall", res)
        }
      })
    },

    testMakeHiddenCall() {
      makeHiddenCall({
        phone: "13800138000",
        subId: null,
        completeListener: (res) => {
          console.log("makeHiddenCall", res)
        }
      })
    },

    testRegisterCallListener() {
      registerCallListener({
        callListener: (res) => {
          console.log("call state", res)
        },
        completeListener: (res) => {
          console.log("registerCallListener", res)
        }
      })
    },

    testUnregisterCallListener() {
      let success = unregisterCallListener()
      console.log("unregisterCallListener", success)
    },

    testGetCallLogs() {
      getCallLogs({
        completeListener: (res) => {
          console.log("getCallLogs", res)
        }
      })
    },

    testGetSmsList() {
      getSmsList({
        phone: null,
        completeListener: (res) => {
          console.log("getSmsList", res)
        }
      })
    },

    testGetContacts() {
      getContacts({
        keyword: "张",
        completeListener: (res) => {
          console.log("getContacts", res)
        }
      })
    }
  }
}
</script>

各能力说明

显式发送短信

Android：通过系统短信应用发送，支持预填号码与正文。
iOS：通过 MFMessageComposeViewController 打开短信发送界面。
HarmonyOS NEXT：通过系统短信界面拉起发送。

隐式发送短信

Android：支持后台发送，可通过 subId 指定订阅卡发送。
iOS：系统不支持第三方应用隐式发送短信。
HarmonyOS NEXT：当前实现返回不支持。

获取 SIM 信息

Android：支持获取卡槽索引、订阅 ID、运营商名称、号码、默认语音卡、默认短信卡。
iOS：不开放真实 SIM 信息。
HarmonyOS NEXT：当前第三方应用场景下不支持。

电话监听

Android：当前是系统整体通话状态监听，不是按 subId 分别监听。
iOS：当前是系统整体通话状态监听，不支持区分双卡。
HarmonyOS NEXT：当前是系统整体/默认电话状态监听，不支持真正的多卡分别监听。

通话记录 / 短信列表

Android：支持读取系统通话记录和短信列表。
iOS：系统不开放给第三方应用。
HarmonyOS NEXT：当前第三方应用场景下不支持。

联系人

Android：支持读取联系人名称和号码。
iOS：支持读取联系人，需要在 info.plist 配置 NSContactsUsageDescription。
HarmonyOS NEXT：支持读取联系人，需要声明 READ_CONTACTS 权限。

用到的权限

Android

插件内已声明以下权限，见 utssdk/app-android/AndroidManifest.xml：

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.SEND_SMS" />
<uses-permission android:name="android.permission.READ_SMS" />
<uses-permission android:name="android.permission.RECEIVE_SMS" />
<uses-permission android:name="android.permission.CALL_PHONE" />
<uses-permission android:name="android.permission.READ_CALL_LOG" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.READ_PHONE_NUMBERS" />

iOS

当前插件已配置：

<key>NSContactsUsageDescription</key>
<string>用于读取通讯录联系人信息</string>

HarmonyOS NEXT

插件当前默认不会自动声明鸿蒙权限，HarmonyOS NEXT 当前实际已落地并建议配置的权限主要只有联系人读取：

 "requestPermissions": [
      {
        "name": "ohos.permission.READ_CONTACTS",
        "reason": "$string:permission_read_contacts_reason",
        "usedScene": {
          "when": "inuse"
        }
      }
    ]

对应 resources/base/element/string.json 可以这样配置：

{
  "string": [
    {
      "name": "permission_read_contacts_reason",
      "value": "用于读取联系人姓名、号码和头像信息"
    }
  ]
}

说明：

Harmony 当前 getContacts 会在运行时申请 ohos.permission.READ_CONTACTS，如果没有在 module.json5 中声明，对应能力将无法正常使用，此权限需要专门向华为申请，详情请看受限开放权限。
sendVisibleSms、sendVisibleEmail、makeVisibleCall 当前实现走的是拉起系统应用，不依赖系统层权限。
getSimInfo、sendHiddenSms、makeHiddenCall、getCallLogs、getSmsList 在当前 Harmony 实现中本身就是不支持或直接返回失败，因此文档中不再把这些权限当作当前版本的必配项。

注意事项

Android 某些厂商系统存在权限已授予但实际能力仍受限的情况，例如小米系统可能出现“有权限但不返回信息”的兼容性问题，需在应用权限设置里关闭"空白通行证"。
Android 的 sendHiddenSms 与 makeHiddenCall 依赖系统权限与 ROM 行为，不同厂商兼容性可能存在差异。
iOS 对隐式短信、系统短信读取、系统通话记录读取、真实 SIM 信息获取均有限制，这是系统层限制。
HarmonyOS NEXT 对第三方应用开放能力限制较严格，隐式短信、隐式拨号、短信监听、短信列表、通话记录、SIM 信息等能力当前实现为不支持或受限。