更新记录

1.1.4（2026-10-18）

• 修复二维码在鸿蒙端渲染失败。

1.1.3（2026-09-11）

• 优化二维码渲染性能；
• 完善文档说明。

1.1.2（2026-09-10）

• 修复蒸汽模式鸿蒙uts语法问题。

平台兼容性

uni-app x(4.83)

其他

umi-barcode-x

广告：

• 魔法上网35元/月，有需求的可以联系我(稳定，支持 Clash Verge)。
• 售卖CodeX账号，plus代充180元/月，有需求的可以联系我。
• 售卖Claude Code账号以及代充，有需求的可以联系我。
• vx: 781284440

二维码、条形码绘制组件。

• APP（HarmonyOS / Android / iOS）：系统原生生成码图（鸿蒙 ScanKit、Android ZXing、iOS CoreImage），以图片展示。
• 微信小程序、支付宝小程序、抖音小程序、元服务：canvas type="2d" 绘制。

注意事项

本插件含 UTS 原生实现，Android、iOS 真机运行必须打自定义基座（标准基座不含本插件原生代码，会出现找不到模块、生成失败或保存相册异常）。鸿蒙走原生编译，无需自定义基座。

切换 VDOM / vapor（蒸汽模式） 后，渲染与原生桥接方式会变，必须重新制作自定义基座再运行。只改源码热更新、或只改 manifest.json 里的 vapor 而不重打基座，Android / iOS 上仍会用旧基座里的原生侧，表现会错乱。

其它：

• Android 通过 utssdk/app-android/config.json 的 dependencies 引入 ZXing。更新依赖后必须重新制作并安装自定义基座；若出现 NoClassDefFoundError: com/google/zxing/EncodeHintType，请确认运行的是新基座，仅热更新源码无法补齐原生依赖。不要再手动放入 ZXing JAR，以免重复类冲突。
• 加密后的普通授权版只能从 @/uni_modules/umi-barcode-x 导入，不要写 utssdk/、common/ 内部路径。
• Android 保存相册不要给 WRITE_EXTERNAL_STORAGE 加 android:maxSdkVersion="28"，改权限后也需重新运行（自定义基座要重打）。
• Android 自定义事件载荷可能是 Map，不要直接读 e.path，见下方示例。

使用

easycom 自动引入：

<umi-barcode type="qrcode" value="https://uniapp.dcloud.net.cn/" :size="200" logo="/static/logo.png"></umi-barcode>
<umi-barcode type="barcode" format="code128" value="ABC-12345678" :width="280" :height="88"></umi-barcode>

也可调用原生生成 / 保存 API（仅 APP）。加密后的普通授权版只能从插件根目录导入，不要写 utssdk/、common/ 下的内部路径：

import { generateCode, saveCodeToAlbum, UmiBarcodeOkPayload, readAnyErrMsg } from '@/uni_modules/umi-barcode-x'

generateCode({
    content: 'hello',
    type: 'qrcode',
    width: 200,
    height: 200,
    logo: '/static/logo.png'
}).then((path : string) => {
    // path 为本地文件路径，可用于 image.src，或保存到相册
    saveCodeToAlbum(path).then((albumPath : string) => {
        uni.showToast({ title: '已保存到相册', icon: 'none' })
    })
})

组件绘制成功后会带上 path，也可直接保存。Android 上自定义事件参数是 Map，不要直接读 e.path：

function readEventPath(e : any) : string {
    if (e instanceof Map) {
        const raw = (e as Map<string, any>).get('path')
        if (raw == null) {
            return ''
        }
        return raw as string
    }
    const ok = e as UmiBarcodeOkEvent
    return ok.path
}
saveCodeToAlbum(readEventPath(e))

组件实例也可调用 download()（APP 内部走 saveCodeToAlbum；小程序 / 元服务会先导出 Canvas；Web 直接触发浏览器 PNG 下载，返回图片 data URL，成功表示已发起下载）：

const codeRef = ref<UmiBarcodeComponentPublicInstance | null>(null)
const inst = codeRef.value
if (inst != null) {
    const job = inst.download?.()
    if (job != null) {
        job.then((albumPath : string) : void => {})
    }
}

属性

事件

• success：绘制成功，{ width, height, path }（APP 上 path 为本地码图路径）
• fail：绘制失败，{ errMsg }

下载

APP 需相册写入权限（iOS NSPhotoLibraryAddUsageDescription，鸿蒙图库写入）。Android 在 manifest.json 的 app-android.distribute.permissions 声明存储权限，不要加 android:maxSdkVersion="28"，否则 saveImageToPhotosAlbum 会抛 IllegalArgumentException。

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

微信小程序不要在 app.json / manifest.json 的 permission 里写 scope.writePhotosAlbum，基础库会报「无效的 app.json permission」。相册写入只需在微信公众平台「用户隐私保护指引」中声明保存到相册；调用 saveImageToPhotosAlbum 时由微信弹授权。permission 目前只用于 scope.userLocation、scope.userLocationBackground、scope.userFuzzyLocation。

格式支持

Canvas 端 CODE128 仅支持 ASCII 32–127。