更新记录

1.0.1（2026-08-28） 下载此版本

nl-sms-new 用于在 uni-app Android App 运行期间实时监听新收到的短信，并将短信转换成普通 JavaScript 对象返回给业务页面。

1.0.0（2025-08-05） 下载此版本

初版

平台兼容性

uni-app(4.76)

Android 实时短信监听

nl-sms-new 用于在 uni-app Android App 运行期间实时监听新收到的短信，并将短信转换成普通 JavaScript 对象返回给业务页面。

支持范围

• 支持 uni-app Vue 2、Vue 3、普通 Vue 页面和 nvue 页面。
• 仅支持 Android App。
• 不支持 iOS、HarmonyOS 原生应用、H5 和各类小程序。
• 依赖 HTML5 Plus 的 plus.android 能力。

配置 Android 权限

在项目的 manifest.json 中为 Android App 配置短信接收权限：

{
  "app-plus": {
    "distribute": {
      "android": {
        "permissions": [
          "<uses-permission android:name=\"android.permission.RECEIVE_SMS\"/>"
        ]
      }
    }
  }
}

插件只监听新收到的短信，不读取短信历史，因此不申请 READ_SMS。

新增原生权限后需要重新制作自定义基座或重新打包 APK，仅更新 WGT 无法添加 APK 中不存在的权限声明。

引入

import sms from '@/uni_modules/nl-sms-new/js_sdk/nl-sms-new.js'

也可以按需引入：

import {
  listen,
  startListening,
  stopListening,
  onMessage,
  offMessage
} from '@/uni_modules/nl-sms-new/js_sdk/nl-sms-new.js'

旧项目仍可从 nl-sms.js 引入，但建议逐步迁移到 js_sdk/nl-sms-new.js。

推荐用法

listen 会申请权限、启动监听并注册回调，成功后返回一个取消订阅函数。

import { listen } from '@/uni_modules/nl-sms-new/js_sdk/nl-sms-new.js'

export default {
  data() {
    return {
      stopSmsListen: null
    }
  },
  onShow() {
    listen(message => {
      console.log('收到短信', message)
    }, {
      onError: error => {
        console.error('短信监听失败', error.code, error.message)
      }
    }).then(unsubscribe => {
      this.stopSmsListen = unsubscribe
    }).catch(error => {
      console.error('启动失败', error)
    })
  },
  onHide() {
    if (this.stopSmsListen) {
      this.stopSmsListen()
      this.stopSmsListen = null
    }
  },
  onUnload() {
    if (this.stopSmsListen) {
      this.stopSmsListen()
      this.stopSmsListen = null
    }
  }
}

同一页面请避免在 onShow 中重复调用 listen 而不取消上一次订阅。

分步控制

需要统一管理监听器时，可以先订阅回调，再单独启动和停止底层监听。

import sms from '@/uni_modules/nl-sms-new/js_sdk/nl-sms-new.js'

const handleMessage = message => {
  console.log(message.address)
  console.log(message.body)
  console.log(message.dateTime)
}

sms.onMessage(handleMessage)

sms.startListening().then(status => {
  console.log('监听状态', status)
}).catch(error => {
  console.error(error.code, error.message)
})

// 页面销毁或不再需要监听时执行
sms.offMessage(handleMessage)
sms.stopListening()

短信数据格式

每次回调收到一个普通 JavaScript 对象：

{
  address: "10690000",
  body: "您的验证码是 123456",
  timestamp: 1787882400000,
  dateTime: "2026-08-28 10:00:00",
  serviceCenterAddress: "+8613800...",
  partsCount: 1
}

筛选短信

可以按发件号码、正文关键词或自定义函数进行筛选：

listen(message => {
  console.log('匹配到验证码短信', message)
}, {
  address: '1069',
  keyword: '验证码',
  filter: message => message.body.length < 500
})

三个条件同时设置时需要全部满足才会触发回调。

权限处理

主动申请权限

sms.requestPermissions().then(result => {
  console.log('权限已授予', result)
}).catch(error => {
  if (error.code === 'PERMISSION_DENIED_ALWAYS') {
    sms.openAppSettings()
  }
})

不自动弹出权限申请

sms.startListening({
  requestPermission: false
}).catch(error => {
  console.log(error.code, error.message)
})

API

isSupported()

判断当前运行环境是否为可用的 Android App 环境。

getStatus()

返回支持状态、监听状态、订阅者数量和权限状态。

requestPermissions(options)

申请实时接收短信所需的 RECEIVE_SMS 权限。

listen(handler, options)

推荐的快捷接口。订阅短信并启动监听，返回值为 Promise<unsubscribe>。

startListening(options)

启动底层短信广播监听。重复调用不会重复注册接收器。

stopListening(options)

停止底层监听。传入 { clearListeners: true } 可同时清除全部消息和错误回调。

onMessage(handler, options)

注册消息回调，立即返回取消订阅函数，但不会自动启动底层监听。

offMessage(handler)

移除指定消息回调；不传参数时移除全部消息回调。

onError(handler) 和 offError(handler)

注册或移除全局错误回调。

openAppSettings()

打开当前 App 的系统设置页面，用于处理权限被永久拒绝的情况。

常见错误码

注意事项

• 动态广播接收器只在 App 进程存活且插件已启动监听时有效，App 被系统彻底杀死后不能继续接收回调。
• 部分 Android 系统会限制后台进程和短信权限，请将 App 加入后台运行白名单并关闭过度省电限制。
• Android 应用市场可能对短信权限有严格审核要求，业务应仅申请真正需要的最小权限。
• 双卡设备返回的短信号码和短信中心信息由系统提供，不同厂商可能存在差异。
• 短信属于敏感数据，业务层应明确告知用户用途，并避免在控制台长期输出完整短信内容。