二维码 qr-code

数据展示组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

给 value 就画码，版本按内容长度自动选；缺省 M 级纠错、4 个模块的静区

<script setup lang="ts">
import { XhQrCode } from "@xihan-ui/vue";
</script>

<template>
  <XhQrCode value="https://ui.xihanfun.com" />
</template>

纠错级别

L / M / Q / H 依次能容忍更多污损，同样的内容也因此占更多模块

L

M

Q

H

<script setup lang="ts">
import { XhQrCode } from "@xihan-ui/vue";

const levels = ["L", "M", "Q", "H"] as const;
const text = "https://ui.xihanfun.com/components/qr-code";
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 16px">
    <div v-for="level in levels" :key="level" style="display: grid; gap: 6px; justify-items: center">
      <XhQrCode :value="text" :level="level" :pixel-size="120" />
      <span style="font-size: 12px">{{ level }}</span>
    </div>
  </div>
</template>

边长与静区

pixelSize 是整块的像素边长；margin 的单位是模块数，静区含在里面不额外占地方

96px · 静区 4

144px · 静区 4

144px · 静区 0

<script setup lang="ts">
import { XhQrCode } from "@xihan-ui/vue";

const text = "https://ui.xihanfun.com";
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; align-items: end; gap: 16px">
    <div style="display: grid; gap: 6px; justify-items: center">
      <XhQrCode :value="text" :pixel-size="96" />
      <span style="font-size: 12px">96px · 静区 4</span>
    </div>
    <div style="display: grid; gap: 6px; justify-items: center">
      <XhQrCode :value="text" :pixel-size="144" />
      <span style="font-size: 12px">144px · 静区 4</span>
    </div>
    <!-- 静区归零后码面顶到边上；印刷或贴在深色底上时四周得自己再留白，否则扫不出来 -->
    <div style="display: grid; gap: 6px; justify-items: center">
      <XhQrCode :value="text" :pixel-size="144" :margin="0" />
      <span style="font-size: 12px">144px · 静区 0</span>
    </div>
  </div>
</template>

可及名字

缺省拿 value 当 aria-label；内容不是给人念的时候用 label 换一句人话

<script setup lang="ts">
import { ref } from "vue";
import { XhQrCode } from "@xihan-ui/vue";

const text = ref("https://ui.xihanfun.com");
</script>

<template>
  <div style="display: grid; gap: 12px; justify-items: start">
    <input
      v-model="text"
      type="text"
      aria-label="要编码的内容"
      style="inline-size: 320px; max-inline-size: 100%"
    />
    <!-- 内容清空时不画码，读屏也读不到这块 -->
    <XhQrCode :value="text" :pixel-size="140" label="曦寒 UI 文档站二维码" />
  </div>
</template>

码点形状

square / dot / rounded；三种形状的墨都盖住每个模块的格心，读码器按格心取样

square

dot

rounded

<script setup lang="ts">
import { XhQrCode } from "@xihan-ui/vue";

const shapes = ["square", "dot", "rounded"] as const;
const text = "https://ui.xihanfun.com/components/qr-code";
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 16px">
    <div
      v-for="shape in shapes"
      :key="shape"
      style="display: grid; gap: 6px; justify-items: center"
    >
      <!-- 时序图形与校正图形不跟着变形：它们是透视校正的几何基准 -->
      <XhQrCode :value="text" :module-shape="shape" :pixel-size="128" />
      <span style="font-size: 12px">{{ shape }}</span>
    </div>
  </div>
</template>

码眼形状

只作用于三个定位图形，7×7 的外环加内心结构保持不变，读码器靠它找码

square

rounded

dot + rounded

<script setup lang="ts">
import { XhQrCode } from "@xihan-ui/vue";

const shapes = ["square", "rounded"] as const;
const text = "https://ui.xihanfun.com/components/qr-code";
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 16px">
    <div
      v-for="shape in shapes"
      :key="shape"
      style="display: grid; gap: 6px; justify-items: center"
    >
      <XhQrCode :value="text" :eye-shape="shape" :pixel-size="128" />
      <span style="font-size: 12px">{{ shape }}</span>
    </div>
    <!-- 码点与码眼各挑各的，两条 path 分开出几何 -->
    <div style="display: grid; gap: 6px; justify-items: center">
      <XhQrCode :value="text" module-shape="dot" eye-shape="rounded" :pixel-size="128" />
      <span style="font-size: 12px">dot + rounded</span>
    </div>
  </div>
</template>

中心 logo

落位与尺寸由组件给出，那片模块先被底色挖空；放 logo 就把 level 提到 Q 或 H

Q 级 + logo

H 级 + 圆角

<script setup lang="ts">
import { XhQrCode, XhQrCodeLogo } from "@xihan-ui/vue";

const text = "https://ui.xihanfun.com";
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; align-items: end; gap: 16px">
    <div style="display: grid; gap: 6px; justify-items: center">
      <!-- 挖掉的那片等于人为污损，L / M 那点纠错余量赔不起 -->
      <XhQrCode :value="text" level="Q" :pixel-size="176" label="曦寒 UI 文档站二维码">
        <XhQrCodeLogo>
          <!-- 边长不超过整码的 1/5，写 100% 即铺满这块，溢出部分被它自己裁掉 -->
          <rect x="0" y="0" width="100%" height="100%" rx="1" fill="#0f172a" />
          <circle cx="50%" cy="50%" r="28%" fill="#ffffff" />
        </XhQrCodeLogo>
      </XhQrCode>
      <span style="font-size: 12px">Q 级 + logo</span>
    </div>
    <div style="display: grid; gap: 6px; justify-items: center">
      <XhQrCode :value="text" level="H" module-shape="rounded" eye-shape="rounded" :pixel-size="176" label="曦寒 UI 文档站二维码">
        <XhQrCodeLogo>
          <rect x="0" y="0" width="100%" height="100%" rx="1.5" fill="#1d4ed8" />
        </XhQrCodeLogo>
      </XhQrCode>
      <span style="font-size: 12px">H 级 + 圆角</span>
    </div>
  </div>
</template>

换色

颜色不是 props，写三个 CSS 变量即可：码点必须比底色深且对比要足，反相码一部分读码器不认

缺省

深蓝码点

暖底 + 独立码眼色

<script setup lang="ts">
import { XhQrCode } from "@xihan-ui/vue";

const text = "https://ui.xihanfun.com";
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 16px">
    <div style="display: grid; gap: 6px; justify-items: center">
      <XhQrCode :value="text" :pixel-size="128" />
      <span style="font-size: 12px">缺省</span>
    </div>
    <div style="display: grid; gap: 6px; justify-items: center">
      <!-- 只换码点色，码眼跟着走 -->
      <XhQrCode :value="text" :pixel-size="128" style="--xh-qr-code-fg: #1d4ed8" />
      <span style="font-size: 12px">深蓝码点</span>
    </div>
    <div style="display: grid; gap: 6px; justify-items: center">
      <!-- 码眼单独挑一个色，挖空矩形跟着底色走，两处必须一致 -->
      <XhQrCode
        :value="text"
        :pixel-size="128"
        eye-shape="rounded"
        style="--xh-qr-code-bg: #fff7ed; --xh-qr-code-fg: #431407; --xh-qr-code-eye-fg: #c2410c"
      />
      <span style="font-size: 12px">暖底 + 独立码眼色</span>
    </div>
  </div>
</template>

产物

层	值
自定义元素	<xh-qr-code>
Vue 组件	XhQrCode XhQrCodeLogo
状态机	无，connect 直接由 props 算属性
皮肤	@xihan-ui/styles/qr-code.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="qr-code"：root · logo

Props

属性	类型	必填	说明
eyeShape	QrEyeShape		码眼形状，缺省 square。时序图形与校正图形不受它影响，一律保持方块——它们是透视校正的几何基准。
label	string		可及名字，缺省用 value；给了全空白的名字等于没给。
level	QrLevel		纠错级别 L / M / Q / H，缺省 M。
logo	boolean		码面正中是否留一块给 logo。 留出来的那片模块会被底色盖住，对读码器而言等于人为污损：放 logo 就把 level 提到 Q 或 H， L 与 M 那点纠错余量赔不起这一块。损伤量见 logoDamage；超出所选级别的余量时 会往诊断通道报一条 qr-code.logo-damage 警告，码照画。
margin	number		静区宽度，单位是模块数，缺省 4；静区含在 viewBox 里，不占额外尺寸。
moduleShape	QrModuleShape		码点形状，缺省 square。
pixelSize	number		像素边长，缺省 160；写成根上的内联宽高。
value	string		要编码的内容，按 UTF-8 取字节走字节模式；空串不画码。

connect API

connect 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
modules	readonly (readonly boolean[])[]	模块矩阵，[行][列]，true = 深色；没画出码时是空数组。
version	number	实际用到的版本；没画出码时为 0。
count	number	每边模块数，不含静区；没画出码时为 0。
margin	number	解析后的静区宽度，单位是模块数。
viewBox	string	根的 viewBox，含静区。
path	string	除三个码眼以外的模块合成的那条 <path> 的 d；没画出码时是空串，此时不该生成 path 节点。 码眼永远不在这一条里，与形状无关。
eyePath	string	三个码眼合成的那条 <path> 的 d；没画出码时是空串，此时不该生成第二个 path 节点。 两条分开画与形状无关：码眼的颜色可以与码点不同，合成一条就没地方单独上色。
logoArea	QrCodeLogoArea | undefined	logo 的落位与挖空矩形；没留位时为 undefined。
logoDamage	QrCodeLogoDamage | undefined	挖空对码面造成的损伤；没留 logo 位时为 undefined。
state	QrCodeState	当前状态。
error	string | undefined	编码失败的原因；其余状态为 undefined。
label	string | undefined	解析后的可及名字；没给名字时为 undefined，此时根退出无障碍树。
getRootProps	() => T['element']
getLogoProps	() => T['element']	铺到 logo 部件上的落位；没留位时宽高都是 0，那块连同里面的图形一起不渲染。

键盘

规格出处：W3C APG

无键盘交互（不接收焦点，或焦点行为完全由原生元素提供）。