更新记录

1.1.0（2026-11-02） 下载此版本

完善 UP Scanner 跨平台扫码能力，保留 up-scanner 插件标识与原有 content 结果字段。

• 补齐扫码类型筛选、扫码页相册选图及 onlyFromCamera 模式；Android 接入自动变焦和照明控制。
• 新增 App 三端与 Web 的 createQRCode，生成本地 PNG 二维码，支持中文与 emoji。
• 新增 Web 本地 ZXing 实现和小程序宿主扫码适配，明确不支持的平台或码制。
• 统一 result/content、scanType、charSet、rawData、path 和错误回调；修复并发、重复回调及监听器资源释放。
• 修复 Web 损坏图片等待、选图期间相机结果竞争和页面切换后摄像头未释放的问题。
• 更新示例、接入文档和平台限制说明。

验证说明：37 项自动化回归通过，H5/微信小程序/App CLI 编译通过，Android UTS→Kotlin 与原生 Kotlin 本地编译通过。iOS/鸿蒙原生编译及各端真机权限、相机、相册尚需验收；CLI 编译不代表 APK/IPA 已验收。不同平台码制和系统版本限制请参阅插件文档。

平台兼容性

UP Scanner

独立实现的 UTS 扫码插件，提供单码实时识别、扫码页相册选图、仅相机模式和二维码生成。插件 ID 保持 up-scanner，不依赖其他扫码插件或其商业授权。

能力与平台

以下为实现范围，不是所有设备都已实测的承诺。原生扫码需要自定义基座及真机验收。

不提供连续扫码、多码同时返回或嵌入式摄像头组件。照明按钮仅在设备支持时可用，autoZoom 仅 Android 生效。

安装

1. 将 up-scanner 目录放入项目 uni_modules。
2. 建议使用 HBuilderX 4.61+，原生混编至少需要 4.25，鸿蒙/uni-app x 的兼容基线按 4.61 配置。
3. Web 端在宿主项目根目录安装依赖（插件配置不能代替所有 CLI 工程的安装步骤）：

npm install @zxing/library@0.21.3

4. App 端重新制作自定义基座。Android 依赖由 app-android/config.json 声明，不需要用户额外安装商业扫码 SDK。

本仓库 CLI 示例使用固定版本的 uni-app Vue3 编译器；可运行的 Vue3 示例不等于 Vue2、nvue、uvue 或所有 uni-app x 版本已通过编译，这些使用方式需要按目标项目验证。

scanCode(options)

import { scanCode } from '@/uni_modules/up-scanner';

scanCode({
  scanType: ['qrCode', 'barCode'],
  onlyFromCamera: false,
  autoZoom: true,
  success: (res) => {
    console.log(res.result);  // 标准内容字段
    console.log(res.content); // 保留的旧字段，与 result 相同
    console.log(res.scanType);
  },
  fail: (error) => {
    if (error.errCode !== 10001) console.error(error.errMsg);
  },
  complete: () => {
    // 成功或失败后各调用一次
  }
});

参数

默认扫码页含“选择图片”入口，无需额外的识图 API。选图取消返回扫码页；无匹配码的图片在页内提示并允许重新选择。Web 单张图片限制 20MB；带 logo、模糊、过小或高密度码不保证能识别。

同一平台只允许一个扫码会话，重复调用报 10007。关闭、系统返回和取消不会当作成功；资源和锁在通知结果之前释放，允许在成功回调中开始下一次扫描。

码制

小程序原生接口通常只接受 qrCode、barCode、datamatrix、pdf417。精确一维码请求先转换为 barCode，成功后再次筛选；不符合请求报 10004，不能控制宿主页面持续扫描直到符合。Aztec 请求在小程序适配层返回 10005，不静默拓宽范围。iOS 的 UPC-A 由前缀为 0 的 EAN-13 规范化；明确请求 ean13 时保留 EAN-13。

结果

Android 与 ZXing 可提供原始字节，iOS/鸿蒙系统扫描通常不提供。不要假设任何引擎的 rawData 都等于文本的 UTF-8 编码。

createQRCode(options)

App 三端与 Web 可用。成功参数是图片地址字符串，不是 { src } 对象。

import { createQRCode } from '@/uni_modules/up-scanner';

createQRCode({
  content: 'UP Scanner 扫码示例',
  width: 300,
  height: 300,
  success: (src) => {
    // 可绑定到 <image :src="src" />
    console.log(src);
  },
  fail: (error) => console.error(error.errMsg),
  complete: () => {}
});

• content 必填且非空，保留原始空格，支持中文和 emoji。
• width、height 必填，均为 64–2048 的整数，单位 px。
• 黑码白底、M 级纠错、保留静区；矩形画布不拉伸码点。
• 内容太长或指定尺寸无法容纳时返回失败，避免返回不可识别的压缩图。
• 原生 PNG 放在应用临时/缓存目录，系统可能清理；需要长期保存时由业务复制到自己的目录。生成本身不写系统相册，不申请相册写入权限。
• Web 返回 data:image/png;base64,...，不上传内容、不依赖远程生成服务。
• 不支持 logo 覆盖、自定义颜色或普通条形码生成。

错误码

错误包含 errSubject: 'up-scanner'、errCode、带操作前缀的 errMsg。

权限与运行要求

Android

• API21+，插件声明 CAMERA；扫码页负责 Android 6+ 的运行时请求。
• 系统文档选择器仅授予所选图片的访问权，不申请 READ_EXTERNAL_STORAGE / READ_MEDIA_IMAGES 整库权限。
• 不要求 Google Play 服务在线下载识别模型，使用内置 ML Kit barcode-scanning 依赖。
• 摄像头不是安装硬件必选项；无摄像头设备扫码会报错，二维码生成仍可使用。

iOS

插件 Info.plist 声明：

• NSCameraUsageDescription
• NSPhotoLibraryUsageDescription（使用相册选择时）

只生成二维码不访问相机或相册。onlyFromCamera=true 不弹出相册选择器。系统或项目若覆盖隐私文案，需要保留相应键。

HarmonyOS

• 系统默认扫码页由 ScanKit 预授权相机，插件不额外申请应用 CAMERA 权限。
• 从可见页面的用户操作调用，不要从后台任务启动。
• 应用的 harmony-configs/build-profile.json5 中设置兼容版本 API12+；app-harmony/config.json 中不存在可用于替代应用配置的 minAPIVersion 字段。
• 鸿蒙系统页布局不可自定义；本插件不将系统页外观宣称为原创。

Web 与小程序

• Web 摄像头需 HTTPS/localhost 和浏览器授权；微信内置浏览器等环境受宿主策略限制。
• Web 非仅相机模式下，即使拒绝摄像头，仍可选图识别。页面隐藏、关闭、Escape 会结束会话并停止摄像头。
• 小程序权限和扫码 UI 由宿主控制；仅微信完成本仓库 CLI 编译，其他宿主需要自行验收。

验证与迁移

旧用法 res.content 和 datamatrix 继续可用。以前未生效的 scanType、autoZoom、onlyFromCamera 现在实际接入；请勿依赖旧版本“传入筛选但扫描所有码”的错误行为。本版保留 Android API21 基线，依赖 AAR 的最低版本已核实。

仓库测试运行命令、构建结论和真机验收清单见 验收说明。测试中的 SDK 边界替身用于验证桥接行为，不能代替 Kotlin/Swift/ArkTS 编译或相机真机测试。

技术与来源

• Android：Apache 2.0 的 CameraX/ZXing，ML Kit 按其 SDK 条款使用。
• Web：@zxing/library（Apache 2.0），由项目本地打包。
• iOS：Apple 系统框架；鸿蒙：Huawei 系统 ScanKit。
• 插件代码沿用仓库 MIT 声明；第三方组件使用各自许可证。

参考的是公开功能需求，没有使用参考插件的源码、品牌、组件标签或界面资源。本插件不采集或上传扫码内容，不自动打开识别到的链接。

1.1.0

补齐多码制筛选、相册入口、仅相机模式、Android 自动变焦、App/Web 二维码生成；规范结果和错误回调；增加 Web/小程序入口；修复平台硬编码及监听器泄漏；补全 CLI 示例和回归测试。