更新记录

1.0.0（2026-09-10）

正式发布

平台兼容性

uni-app(5.25)

uni-app x(5.25)

其他

scan-kit

扫码界面模式

scan 的 viewMode 用于选择扫码界面：

scan({
  mode: 'single',
  viewMode: 'default', // default | custom
  success: (res) => console.log(res)
})

• default（默认）：使用 HMS Scan Kit 官方扫码 Activity，包含官方扫码框和相册入口。filterRegex 在该模式下会被忽略。
• custom：使用插件自定义扫码 Activity，支持 filterRegex、连续扫码和自定义交互。
• continuous 模式会自动使用 custom，因为 HMS 官方默认 Activity 是单次返回模式。
• 图册通过系统选图器授权的 URI 读取图片，无需预先申请全相册读取权限。自定义页支持 gallery: false 隐藏图册入口。
• image 模式始终使用官方相册扫码页面；如需过滤，请在结果回调中自行判断。

自定义模式还支持方法过滤。方法接收原始扫码文本，并通过插件导出的 resolveScanFilter(success, data?) 告知插件是否通过。插件不解析 data 中的任何字段，成功时将其原样放入结果的 data：

import { resolveScanFilter } from '@/uni_modules/scan-kit'

function filterCode(value) {
  if (value.startsWith('JD')) {
    resolveScanFilter(true, {
      carrier: 'JD',
      pieceCount: 1
    })
    return
  }
  resolveScanFilter(false)
}

scan({ mode: 'single', viewMode: 'custom', filter: filterCode, success: console.log })

成功回调中读取 res.value（始终是原始识别文本）和 res.data；连续扫码时读取 res.items[index].value 与 res.items[index].data。不要使用过滤方法的 return 值，也不要将回调函数作为过滤器参数传递：这两种方式都不能可靠跨越 JS/UTS 边界。

已有 getCodeByStr 时，将其 { success, data } 结果交给 resolve；原始识别文本仍会保留在成功回调的 res.value：

function filterCode(value) {
  const result = getCodeByStr(value)
  resolveScanFilter(result.success, result.data)
}

如果过滤逻辑需要异步处理，也可以不返回值，在过滤方法中调用解析函数：

function filterCode(value) {
  getCodeByStrAsync(value).then((data) => {
    resolveScanFilter(data != null, data)
  })
}

scan({ mode: 'single', viewMode: 'custom', filter: filterCode, success: console.log })

不论同步或异步，res.value 都保持原始识别文本；传入的 data 会原样出现在 res.data。

只需要判断是否通过时，调用 resolveScanFilter(true) 或 resolveScanFilter(false)。

filter 在官方默认 Activity 中会被忽略。兼容组件使用同名 filter 属性，事件 detail 会包含 value、format 和 data。

filter 和 filterRegex 同时配置时，以 filter 方法为准，filterRegex 会被忽略；只有未配置 filter 时才执行正则过滤。过滤方法可先从 URL 参数中提取业务单号，再返回标准化结果，这样 URL 和直接单号可以使用同一套去重逻辑。

兼容组件的宽高由外部样式控制，插件不会固定尺寸。例如：

<scan-kit-view
  style="width: 100%; height: 380rpx"
  :formats="['QR_CODE', 'CODE_128']"
  :filter="filterCode"
  @scan="onScan"
/>

过滤示例：

scan({
  mode: 'single',
  viewMode: 'custom',
  filterRegex: '^(SF|JD|DPK)'
})

获取扫码成功帧

returnImage 默认 false，开启后将 SDK 返回的识别帧保存为 JPEG 缓存文件，通过 res.image 返回 file:// 路径。连续扫码通过 res.items[index].image 返回每条记录的图片。可以直接用于 <image :src="res.image" /> 或 uni.previewImage。

scan({
  mode: 'single',
  returnImage: true,
  success: (res) => {
    if (res.image) uni.previewImage({ urls: [res.image] })
  }
})

HMS 官方默认 Activity 不支持开启成功帧返回，returnImage: true 会自动使用插件自定义界面；过滤规则仍按调用时的 viewMode 生效。需要方法过滤时请显式设置 viewMode: 'custom'。

嵌入式组件在创建时设置 :returnImage="true"，从 @scan 事件读取 image。该属性需在组件挂载前确定；切换时重新创建组件。

返回的是 SDK 提供的识别图片，不是包含扫码框和按钮的界面截图。SDK 未返回图片或缓存写入失败时不提供 image，文本识别仍正常返回。缓存文件可能被系统清理，需要长期保留时由业务方保存；方法过滤拒绝的候选图片会自动删除。

开发文档

UTS 语法 UTS API插件 UTS uni-app兼容模式组件 UTS 标准模式组件 Hello UTS