Barcode 条形码
将 ASCII 内容或商品号码生成为一维条形码,使用 SVG 显示,支持导出 SVG、PNG、JPEG、WebP。
引入
import { NsBarcode } from '@ns/ui'
import type { BarcodeExpose, BarcodeFormat, BarcodeStatus } from '@ns/ui'
示例
基础用法
<script setup lang="ts">
import { NsBarcode } from '@ns/ui'
</script>
<template>
<NsBarcode value="NS2026111800001" />
</template>
七种格式
CODE128 支持 ASCII 0–127;CODE39 支持大写字母、数字及部分标点;其余格式只支持数字。
<script setup lang="ts">
import { NsBarcode, NsSpace } from '@ns/ui'
const items = [
{ format: 'CODE128', value: 'Hello-NsUI' },
{ format: 'EAN13', value: '690123456789' },
{ format: 'EAN8', value: '9638507' },
{ format: 'UPC', value: '03600029145' },
{ format: 'CODE39', value: 'NSUI-2026' },
{ format: 'ITF14', value: '1540014128876' },
{ format: 'ITF', value: '123456' }
] as const
</script>
<template>
<NsSpace wrap align="start" size="large">
<NsSpace v-for="item in items" :key="item.format" direction="vertical">
<span>{{ item.format }}</span>
<NsBarcode :format="item.format" :value="item.value" />
</NsSpace>
</NsSpace>
</template>
商品条码与校验位
EAN-13 接受 12 位或 13 位,EAN-8 接受 7 位或 8 位,UPC-A 接受 11 位或 12 位,ITF-14 接受 13 位或 14 位。少一位时自动补上 GS1 校验位;位数完整时核对末位。EAN、UPC 的文字按商品码分组,护线延伸到文字区。
<script setup lang="ts">
import { NsBarcode, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap align="start" size="large">
<NsSpace direction="vertical">
<span>12 位:自动补为 6901234567892</span>
<NsBarcode value="690123456789" format="EAN13" />
</NsSpace>
<NsSpace direction="vertical">
<span>13 位:核对校验位</span>
<NsBarcode value="6901234567892" format="EAN13" />
</NsSpace>
<NsSpace direction="vertical">
<span>末位错误</span>
<NsBarcode value="6901234567891" format="EAN13" />
</NsSpace>
</NsSpace>
</template>
条宽与条高
bar-width 是最窄模块的宽度,整张图宽度随内容和格式变化;height 只控制条高,不含留白与文字。
EAN、UPC 的分组文字字号不超过 bar-width 的 10 倍。条宽为 1 时,默认字号从 14 收小为 10,避免数字压到护线。
<script setup lang="ts">
import { NsBarcode, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<NsSpace wrap align="end">
<NsSpace v-for="width in [1, 2, 3]" :key="width" direction="vertical">
<span>bar-width={{ width }}</span>
<NsBarcode value="NS2026" :bar-width="width" />
</NsSpace>
<NsSpace direction="vertical">
<span>EAN-13 / bar-width=1</span>
<NsBarcode value="690123456789" format="EAN13" :bar-width="1" />
</NsSpace>
</NsSpace>
<NsSpace wrap align="end">
<NsSpace v-for="height in [40, 60, 80]" :key="height" direction="vertical">
<span>height={{ height }}</span>
<NsBarcode value="NS2026" :height="height" />
</NsSpace>
</NsSpace>
</NsSpace>
</template>
文字
text 只替换展示文字,不改变编码内容。自定义文字后取消商品码分组和护线加长。text="" 与 display-value="false" 都隐藏文字区。
<script setup lang="ts">
import { NsBarcode, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<NsSpace wrap align="start">
<NsSpace direction="vertical"
><span>display-value=true</span><NsBarcode value="NS2026"
/></NsSpace>
<NsSpace direction="vertical"
><span>display-value=false</span><NsBarcode value="NS2026" :display-value="false"
/></NsSpace>
<NsSpace direction="vertical"
><span>自定义文字</span><NsBarcode value="NS2026" text="订单 NS2026"
/></NsSpace>
<NsSpace direction="vertical"
><span>text 为空</span><NsBarcode value="NS2026" text=""
/></NsSpace>
</NsSpace>
<NsSpace wrap align="start">
<NsSpace v-for="size in [12, 14, 18]" :key="size" direction="vertical">
<span>font-size={{ size }}</span>
<NsBarcode value="NS2026" :font-size="size" />
</NsSpace>
</NsSpace>
<NsSpace wrap align="start">
<NsSpace v-for="margin in [2, 8]" :key="margin" direction="vertical">
<span>text-margin={{ margin }}</span>
<NsBarcode value="NS2026" :text-margin="margin" />
</NsSpace>
<NsSpace direction="vertical">
<span>font-family=serif</span>
<NsBarcode value="NS2026" font-family="serif" />
</NsSpace>
</NsSpace>
</NsSpace>
</template>
颜色
条与文字共用 color。默认黑条白底,暗色主题也保持该配色。透明底适合放在已有浅色背景上。
<script setup lang="ts">
import { NsBarcode, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap align="start" size="large">
<NsSpace direction="vertical"><span>默认黑白</span><NsBarcode value="NS2026" /></NsSpace>
<NsSpace direction="vertical"
><span>自定义颜色</span><NsBarcode value="NS2026" color="#14532d" background-color="#f0fdf4"
/></NsSpace>
<NsSpace direction="vertical"
><span>透明底</span><NsBarcode value="NS2026" background-color="transparent"
/></NsSpace>
</NsSpace>
</template>
留白与静区
左右留白取 padding 与格式规定静区中的较大值。即使关闭静区,商品码仍为条码外侧的数字预留位置。扫码时应保留足够静区。
<script setup lang="ts">
import { NsBarcode, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" fill size="large">
<NsSpace wrap align="start">
<NsSpace v-for="padding in [0, 10, 20]" :key="padding" direction="vertical">
<span>padding={{ padding }}</span>
<NsBarcode value="NS2026" :padding="padding" bordered />
</NsSpace>
</NsSpace>
<NsSpace wrap align="start">
<NsSpace direction="vertical"
><span>quiet-zone=true</span><NsBarcode value="NS2026" :padding="0" bordered
/></NsSpace>
<NsSpace direction="vertical"
><span>quiet-zone=false</span
><NsBarcode value="NS2026" :padding="0" :quiet-zone="false" bordered
/></NsSpace>
</NsSpace>
</NsSpace>
</template>
外框
<script setup lang="ts">
import { NsBarcode, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap>
<NsSpace direction="vertical"><span>bordered=false</span><NsBarcode value="NS2026" /></NsSpace>
<NsSpace direction="vertical"
><span>bordered=true</span><NsBarcode value="NS2026" bordered
/></NsSpace>
</NsSpace>
</template>
Code 39 校验符
checksum 为 Code 39 加入模 43 校验符,显示文字仍为原始内容。其他格式不受此属性影响。
<script setup lang="ts">
import { NsBarcode, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap>
<NsSpace direction="vertical"
><span>checksum=false</span><NsBarcode value="NSUI-2026" format="CODE39"
/></NsSpace>
<NsSpace direction="vertical"
><span>checksum=true</span><NsBarcode value="NSUI-2026" format="CODE39" checksum
/></NsSpace>
</NsSpace>
</template>
状态与刷新
<script setup lang="ts">
import { ref } from 'vue'
import { NsBarcode, NsMessage, NsRadio, NsRadioGroup, NsSpace } from '@ns/ui'
import type { BarcodeStatus } from '@ns/ui'
const status = ref<BarcodeStatus>('expired')
const refresh = () => {
status.value = 'active'
NsMessage.success('刷新请求已触发')
}
</script>
<template>
<NsSpace direction="vertical">
<NsRadioGroup v-model="status" type="button">
<NsRadio value="active">active</NsRadio>
<NsRadio value="loading">loading</NsRadio>
<NsRadio value="expired">expired</NsRadio>
</NsRadioGroup>
<NsBarcode value="NS2026" :status="status" @refresh="refresh" />
<NsBarcode
value="NS2026"
status="expired"
expired-text="订单已过期"
refresh-text="重新生成"
@refresh="refresh"
/>
</NsSpace>
</template>
自定义状态插槽
<script setup lang="ts">
import { NsBarcode, NsButton, NsMessage, NsSpace } from '@ns/ui'
const refresh = () => NsMessage.info('已请求重新获取条码')
</script>
<template>
<NsBarcode value="NS2026" status="expired" @refresh="refresh">
<template #status="{ status, refresh: requestRefresh }">
<NsSpace direction="vertical" align="center">
<span>{{ status === 'expired' ? '订单条码已失效' : '正在获取条码' }}</span>
<NsButton icon="refresh" size="small" @click="requestRefresh">重新获取</NsButton>
</NsSpace>
</template>
</NsBarcode>
</template>
实时校验
空内容保留固定 100 模块宽度的占位,不显示错误。非法内容显示格式提示,开发环境警告中包含具体原因。invalid-text 可以覆盖提示。
<script setup lang="ts">
import { ref } from 'vue'
import { NsBarcode, NsInput, NsSelect, NsSpace } from '@ns/ui'
import type { BarcodeFormat } from '@ns/ui'
const value = ref('690123456789')
const format = ref<BarcodeFormat>('EAN13')
const options = ['CODE128', 'EAN13', 'EAN8', 'UPC', 'CODE39', 'ITF14', 'ITF'].map((value) => ({
label: value,
value
}))
</script>
<template>
<NsSpace direction="vertical">
<NsSpace wrap>
<NsSelect v-model="format" :options="options" aria-label="条码格式" style="width: 160px" />
<NsInput v-model="value" aria-label="条码内容" style="width: 240px" />
</NsSpace>
<NsBarcode :value="value" :format="format" />
<NsBarcode value="abc" format="EAN13" invalid-text="请填写有效的商品号码" />
</NsSpace>
</template>
下载与 SVG 源码
下载包含底色、留白和文字,不包含外框、状态遮罩。位图导出等待页面字体加载完成。导出期间切换属性,当前导出仍使用调用时的内容和样式。
<script setup lang="ts">
import { ref } from 'vue'
import { NsBarcode, NsButton, NsMessage, NsSpace, NsTextarea } from '@ns/ui'
import type { BarcodeExpose } from '@ns/ui'
const barcode = ref<BarcodeExpose | null>(null)
const source = ref('')
const download = async (type: 'image/png' | 'image/svg+xml') => {
try {
const url = await barcode.value?.toDataURL(type, { scale: 3 })
if (!url) return
const link = document.createElement('a')
link.href = url
link.download = type === 'image/png' ? 'barcode.png' : 'barcode.svg'
link.click()
NsMessage.success('条码已导出')
} catch {
NsMessage.error('导出失败,请检查条码内容')
}
}
const showSource = () => {
source.value = barcode.value?.toSvgString() ?? ''
}
</script>
<template>
<NsSpace direction="vertical" fill>
<div><NsBarcode ref="barcode" value="690123456789" format="EAN13" /></div>
<NsSpace wrap>
<NsButton icon="download" @click="download('image/png')">下载 PNG</NsButton>
<NsButton icon="download" @click="download('image/svg+xml')">下载 SVG</NsButton>
<NsButton @click="showSource">显示 SVG 源码</NsButton>
</NsSpace>
<NsTextarea v-model="source" readonly :rows="4" aria-label="SVG 源码" />
</NsSpace>
</template>
读屏文字
默认读出完整号码,商品码包含补全的校验位。aria-label 优先于 alt;显式空串同样优先。
<script setup lang="ts">
import { NsBarcode, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap>
<NsBarcode value="NS2026" alt="订单号 NS2026" />
<NsBarcode value="NS2026" alt="订单号" aria-label="出库单 NS2026" />
</NsSpace>
</template>
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value | 编码内容,空值时显示占位 | string | '' |
| format | 编码格式 | BarcodeFormat | 'CODE128' |
| barWidth | 最窄模块宽度,px,必须为正数 | number | 2 |
| height | 条高,px,不含留白和文字,必须为正数 | number | 60 |
| padding | 四周留白,px;左右仍至少保留静区和外侧数字 | number | 10 |
| quietZone | 是否保留格式要求的最小静区 | boolean | true |
| color | 条与文字颜色 | string | '#000' |
| backgroundColor | 底色,含留白 | string | '#FFF' |
| displayValue | 是否显示文字 | boolean | true |
| text | 自定义展示文字,传入后取消商品文字分组 | string | undefined |
| fontSize | 字号,px,必须为正数;EAN、UPC 分组文字不超过 barWidth 的 10 倍,避免压到护线 | number | 14 |
| fontFamily | 文字字体,页面和导出共用 | string | 'monospace' |
| textMargin | 文字与条的间距,px | number | 4 |
| checksum | Code 39 是否加模 43 校验符 | boolean | false |
| bordered | 是否显示外框 | boolean | false |
| status | 当前状态 | BarcodeStatus | 'active' |
| expiredText | 过期提示,支持空串 | string | 随语言(中文:条形码已过期) |
| refreshText | 刷新按钮文字,支持空串 | string | 随语言(中文:点击刷新) |
| invalidText | 非法内容提示,支持空串 | string | 随语言并带格式名 |
| alt | 替代文字,默认读出完整号码 | string | undefined |
| ariaLabel / aria-label | 读屏文字,优先于 alt | string | undefined |
Events
| 事件 | 说明 | 参数 |
|---|---|---|
| refresh | 点击过期刷新按钮或调用状态插槽的 refresh | 无 |
Slots
| 插槽 | 说明 | 参数 |
|---|---|---|
| status | 自定义 loading / expired 遮罩 | { status: 'loading' | 'expired', refresh: () => void } |
方法
通过模板引用调用,类型为 BarcodeExpose。
| 方法 | 说明 | 签名 |
|---|---|---|
| toSvgString | 导出 SVG 源码;空内容或非法内容返回 '' | () => string |
| toDataURL | 导出图片;空内容或非法内容 reject,非法内容的错误名为 BarcodeValueError | (type?: BarcodeExportType, options?: BarcodeExportOptions) => Promise<string> |
类型
type BarcodeFormat = 'CODE128' | 'EAN13' | 'EAN8' | 'UPC' | 'CODE39' | 'ITF14' | 'ITF'
type BarcodeStatus = 'active' | 'loading' | 'expired'
type BarcodeExportType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/svg+xml'
interface BarcodeExportOptions {
/** 位图倍数,默认 2;SVG 不受影响 */
scale?: number
/** JPEG / WebP 质量,0 到 1 */
quality?: number
}
interface BarcodeExpose {
toDataURL: (type?: BarcodeExportType, options?: BarcodeExportOptions) => Promise<string>
toSvgString: () => string
}
同时导出 BarcodeProps、BarcodeEmits。
注意事项
- 扫码需深色条配浅色底,建议
bar-width不小于 1;不要关闭静区,除非外层已留足空白。窄容器会按比例缩小 SVG,应确认实际显示的条宽仍足够。 - 默认条码不随暗色主题反色;外框和遮罩跟随主题。
- 中文等非 ASCII 字符无法编码;需要编码中文时使用二维码。Code 128 不支持把 FNC 字符作为普通输入。
- EAN、UPC、ITF-14 自动补全或核对校验位;ITF 必须是偶数位数字,不自动加校验位。
- Code 39 只支持大写,可先调用
toUpperCase();支持的标点为- . 空格 $ / + %,不接受*。 - 自定义文字过长可能被 SVG 边界裁切,请减小
font-size或增大padding;组件不自动量文字宽度。 - 透明底导出 JPEG 时底色会变黑,请使用明确的浅色背景。
- 打印建议使用
toSvgString()或直接打印页面,避免位图放大失真。实际打印与手机扫码效果需按设备验证。 barWidth、height、fontSize非正数或非有限数时回退默认值;非法padding、textMargin按 0 处理,开发环境会警告。