更新记录

1.0.0（2026-07-17） 下载此版本

• 首发：Vue3 条形码组件，兼容 App(vue) / H5 / 各小程序 / 鸿蒙
• 多码制：CODE128 / CODE39 / EAN / UPC / ITF / MSI / Codabar / Pharmacode
• 相对旧 jnpf-barcode / tki-barcode：
  • 修正 UPC 误映射 UPCE
  • 编码校验失败有明确错误与重试
  • v-model、内容变化自动重绘
  • 下方可读标签、复制、保存相册、卡片外观
  • 空状态 / 加载中 / 失败态插槽
  • 支付宝 canvas 条件编译；无多余 hideLoading
  • 去表单耦合，业务直接传值即可
  • 高清输出：按设备 pixelRatio 放大绘制并导出，条宽取整
• 新增 quality：high / medium / low 或自定义倍率 1~4
• 点击条码图支持全屏预览（preview 默认开启）；ref.preview() 可命令式打开
• 更清晰：默认 3~4 倍 物理像素整数绘制（去掉 ctx.scale，部分端更锐利）
• 默认条宽 3、高度 100；展示图 pixelated 减少插值发糊

平台兼容性

uni-app(3.8.0)

kex-barcode

跨端条形码生成组件（uni-app Vue3 / <script setup>）。
在 tki-barcode / JsBarcode 思路上重做：更易用、错误可感知、多端更稳，并修正原版 UPC 映射问题。

支持：H5 / App（vue 页）/ 微信小程序 / 支付宝小程序 / 其它小程序 / 鸿蒙。

请在 vue 页面使用（依赖 canvas，不支持 nvue）。

目录

1. 功能一览
2. 安装
3. 快速上手
4. 进阶用法
5. 支持的码制
6. Props
7. Events
8. 方法 ref
9. 插槽
10. 多端说明
11. 常见问题
12. 相对旧组件的提升
13. 注意事项
14. 版本

功能一览

安装

拷贝到业务项目：

你的项目/uni_modules/kex-barcode/

easycom 自动注册，页面直接写标签，无需 import。

要求：uni-app Vue3；App 使用 vue 页。

演示页：首页 → kex-barcode，或 /pages/demos/barcode/index。

快速上手

1. 最少代码

<template>
  <kex-barcode v-model="code" />
</template>

<script setup>
import { ref } from 'vue'
const code = ref('KEX20260717001')
</script>

2. 指定码制与样式

<template>
  <kex-barcode
    v-model="code"
    format="CODE128"
    :bar-width="2"
    :height="90"
    line-color="#1c1917"
    background="#ffffff"
    appearance="card"
  />
</template>

<script setup>
import { ref } from 'vue'
const code = ref('ABC-123456')
</script>

3. EAN-13 商品码

<!-- 内容需符合 EAN13 规则（12 位数字 + 校验或 13 位） -->
<kex-barcode v-model="ean" format="EAN13" :display-value="true" />

const ean = ref('6901234567892')

4. 带操作按钮（复制 / 保存相册）

<kex-barcode
  v-model="code"
  :show-actions="true"
  :copyable="true"
  :saveable="true"
/>

点击条码图默认会 全屏预览（preview 默认为 true）。

5. 关闭预览 / 改为点击复制

<!-- 不预览 -->
<kex-barcode v-model="code" :preview="false" />

<!-- 不预览，点击复制内容 -->
<kex-barcode v-model="code" :preview="false" :click-copy="true" />

进阶用法

内容变化自动刷新

默认 autoMake 为 true，改 v-model 即可重绘：

<template>
  <input v-model="code" placeholder="输入条码内容" />
  <kex-barcode v-model="code" />
</template>

手动触发重绘

<template>
  <kex-barcode ref="bcRef" :model-value="code" :auto-make="false" :load-make="false" />
  <button @click="bcRef.make()">生成</button>
</template>

<script setup>
import { ref } from 'vue'
const code = ref('HELLO')
const bcRef = ref(null)
</script>

自定义空 / 错状态

<kex-barcode v-model="code">
  <template #empty>
    <text>请先填写单号</text>
  </template>
  <template #error="{ message }">
    <text>生成失败：{{ message }}</text>
  </template>
</kex-barcode>

点击图片复制

需先关闭预览，否则点击会进入预览：

<kex-barcode v-model="code" :preview="false" :click-copy="true" @copy="onCopy" />

兼容旧 prop 名 val

<kex-barcode :val="staticText" format="code128" />

modelValue 优先；未传 v-model 时可用 val。

支持的码制

format 大小写不敏感，code128 / CODE128 均可。

Props

Events

方法 ref

bcRef.value.make()       // 重新生成
bcRef.value.clear()      // 清空展示
bcRef.value.copy()       // 复制内容
bcRef.value.save()       // 保存到相册
bcRef.value.preview()    // 全屏预览当前条码图
bcRef.value.getResult()  // 返回当前图片路径
bcRef.value.formats      // 支持的码制列表

插槽

多端说明

常见问题

1. 条码不显示？

• 确认 v-model / val 有内容
• EAN/UPC 等内容不符合规则会进失败态，看错误文案或点重试
• 重新编译（非仅热更新）

2. 条码看起来模糊？

默认已按屏幕像素比 3~4 倍 在物理像素上绘制。仍觉得糊可：

<kex-barcode v-model="code" :quality="4" :bar-width="4" :height="120" />

3. 保存到相册失败？

需用户授权相册权限；App 端失败时会尝试引导打开设置。

4. 和旧 jnpf-barcode 表单关联怎么迁？

旧组件用 dataType + formData + relationField 拼值。新组件只负责展示，在页面里自己拼好字符串再传入：

const code = computed(() => `${form.orderNo}${form.sku}`)

<kex-barcode v-model="code" />

5. 单位用 px 还是 rpx？

默认 unit="rpx"，与设计稿一致。若按物理像素精细控制，设 unit="px"。

相对旧组件的提升

注意事项

1. 仅 Vue3；工程 vueVersion: "3"。
2. 必须在 vue 页面使用 canvas。
3. 发布只需拷贝 uni_modules/kex-barcode。
4. 部分码制对内容校验严格，失败时请核对位数与字符集。

版本

见 changelog.md。当前文档对应 1.0.3。