BizIdCardInput 身份证号输入

18 位身份证号录入与实时校验：省份区划码（GB/T 2260 前两位）、出生日期合法性、ISO 7064 MOD 11-2 校验位三重校验；校验通过后自动派生出生日期、性别、周岁、省份标签，derive 事件可一键回填表单。实名认证、员工/客户档案、旅客登记、报销人信息等一切证件录入场景。

基础用法

1990-01-01男36 周岁北京市

试着改动任意一位数字：校验位不匹配会在输入框下方给出红色原因，后缀图标同步变红。

v-model 绑定原始号码；实时校验 + 派生标签 + derive 事件。

<script setup lang="ts">
/** 场景：员工档案录入——身份证号实时校验，校验通过自动派生出生日期 / 性别 / 年龄 / 省份 */
import { ref } from 'vue'
import { ElAlert } from 'element-plus'
import { BizIdCardInput } from 'vue3-ep-biz-lib'
import type { BizIdCardInfo } from 'vue3-ep-biz-lib'

const idCard = ref('110105199001010010')
const lastDerive = ref<BizIdCardInfo | null>(null)

const onDerive = (info: BizIdCardInfo): void => {
  lastDerive.value = info
}
</script>

<template>
  <div style="max-width: 420px">
    <BizIdCardInput v-model="idCard" @derive="onDerive" />

    <ElAlert
      v-if="lastDerive"
      style="margin-top: 12px"
      type="success"
      :closable="false"
      show-icon
      :title="`derive 事件：${lastDerive.birthDate} / ${lastDerive.gender} / ${lastDerive.age} 周岁 / ${lastDerive.province}`"
    />
    <p style="margin-top: 8px; font-size: 13px; color: var(--el-text-color-secondary)">
      试着改动任意一位数字：校验位不匹配会在输入框下方给出红色原因，后缀图标同步变红。
    </p>
  </div>
</template>

显示代码

表单提交校验

姓名

身份证号

expose validate() 在提交时兜底，返回完整校验结论与失败原因。

<script setup lang="ts">
/** 场景：实名认证表单——提交时 expose validate() 兜底校验，通过后才发起业务请求 */
import { ref } from 'vue'
import { ElButton, ElForm, ElFormItem, ElInput, ElMessage } from 'element-plus'
import { BizIdCardInput } from 'vue3-ep-biz-lib'
import type { BizIdCardInputInstance } from 'vue3-ep-biz-lib'

const inputRef = ref<BizIdCardInputInstance>()
const idCard = ref('')
const realName = ref('')

const submit = (): void => {
  if (!realName.value.trim()) {
    ElMessage.warning('请填写姓名')
    return
  }
  const result = inputRef.value?.validate()
  if (!result?.valid) {
    ElMessage.error(result?.message || '身份证号不正确')
    return
  }
  ElMessage.success('实名信息校验通过，提交成功')
}
</script>

<template>
  <div style="max-width: 480px">
    <ElForm label-width="90px">
      <ElFormItem label="姓名" required>
        <ElInput v-model="realName" placeholder="与证件一致" />
      </ElFormItem>
      <ElFormItem label="身份证号" required>
        <BizIdCardInput ref="inputRef" v-model="idCard" :show-info="false" />
      </ElFormItem>
      <ElFormItem>
        <ElButton type="primary" @click="submit">提交实名认证</ElButton>
      </ElFormItem>
    </ElForm>
  </div>
</template>

显示代码

历史存量容错

1990-01-01男36 周岁北京市

末位校验码故意填错仍可通过：结构（区划 / 生日）校验保留，校验位验证跳过

skip-checksum 跳过校验位验证（结构校验保留），用于迁移存量脏数据。

<script setup lang="ts">
/** 场景：历史存量数据迁移——旧系统录入的号码校验位缺失，skip-checksum 跳过校验位只做结构校验 */
import { ref } from 'vue'
import { ElAlert } from 'element-plus'
import { BizIdCardInput } from 'vue3-ep-biz-lib'

const idCard = ref('110105199001010019')
</script>

<template>
  <div style="max-width: 420px">
    <BizIdCardInput v-model="idCard" skip-checksum placeholder="存量数据，跳过校验位" />
    <ElAlert
      style="margin-top: 12px"
      type="info"
      :closable="false"
      show-icon
      title="末位校验码故意填错仍可通过：结构（区划 / 生日）校验保留，校验位验证跳过"
    />
  </div>
</template>

显示代码

只读回显

disabled 只读态：不可编辑、不渲染派生标签，常用于详情回显。

disabled + 关闭信息区，用于审批/详情页。

<script setup lang="ts">
/** 场景：客户档案回显——审批/详情页只读展示，关闭派生信息区 */
import { ref } from 'vue'
import { BizIdCardInput } from 'vue3-ep-biz-lib'

const idCard = ref('330106199507204004')
</script>

<template>
  <div style="max-width: 420px">
    <BizIdCardInput v-model="idCard" disabled :show-info="false" :show-error="false" />
    <p style="margin-top: 8px; font-size: 13px; color: var(--el-text-color-secondary)">
      disabled 只读态：不可编辑、不渲染派生标签，常用于详情回显。
    </p>
  </div>
</template>

显示代码

旅客入住登记（自动回填）

旅客姓名

身份证号

出生日期

性别

男女

derive 派生出生日期与性别，自动回填表单项。

<script setup lang="ts">
/** 场景：旅客入住登记——身份证 change 派生信息自动回填出生日期 / 性别表单项 */
import { ref } from 'vue'
import { ElButton, ElForm, ElFormItem, ElInput, ElMessage, ElDatePicker, ElRadioGroup, ElRadio } from 'element-plus'
import { BizIdCardInput } from 'vue3-ep-biz-lib'
import type { BizIdCardInfo } from 'vue3-ep-biz-lib'

const guestName = ref('')
const idCard = ref('')
const birthDate = ref('')
const gender = ref('')

const onDerive = (info: BizIdCardInfo): void => {
  birthDate.value = info.birthDate
  gender.value = info.gender
}

const submit = (): void => {
  ElMessage.success('登记完成')
}
</script>

<template>
  <div style="max-width: 520px">
    <ElForm label-width="90px">
      <ElFormItem label="旅客姓名">
        <ElInput v-model="guestName" placeholder="请输入姓名" />
      </ElFormItem>
      <ElFormItem label="身份证号">
        <BizIdCardInput v-model="idCard" :show-info="false" @derive="onDerive" />
      </ElFormItem>
      <ElFormItem label="出生日期">
        <ElDatePicker v-model="birthDate" type="date" value-format="YYYY-MM-DD" placeholder="由身份证自动带出" />
      </ElFormItem>
      <ElFormItem label="性别">
        <ElRadioGroup v-model="gender">
          <ElRadio value="男">男</ElRadio>
          <ElRadio value="女">女</ElRadio>
        </ElRadioGroup>
      </ElFormItem>
      <ElFormItem>
        <ElButton type="primary" @click="submit">办理入住</ElButton>
      </ElFormItem>
    </ElForm>
  </div>
</template>

显示代码

报销人批量核对

张三

李四

王五

存在未填证件，补齐后提交

多行录入状态汇总，一行一核。

<script setup lang="ts">
/** 场景：报销人信息批量核对——多行录入状态汇总，一行一核 */
import { computed, ref } from 'vue'
import { ElTag } from 'element-plus'
import { BizIdCardInput } from 'vue3-ep-biz-lib'

interface Row {
  id: number
  name: string
  idCard: string
}

const rows = ref<Row[]>([
  { id: 1, name: '张三', idCard: '110105199001010010' },
  { id: 2, name: '李四', idCard: '440524198301050025' },
  { id: 3, name: '王五', idCard: '' },
])

const allFilled = computed(() => rows.value.every((row) => row.idCard.length === 18))
</script>

<template>
  <div style="max-width: 520px">
    <div v-for="row in rows" :key="row.id" style="display: flex; align-items: flex-start; gap: 10px; margin-bottom: 14px">
      <span style="width: 3em; line-height: 32px; flex: none">{{ row.name }}</span>
      <BizIdCardInput v-model="row.idCard" :show-info="false" />
    </div>
    <ElTag :type="allFilled ? 'success' : 'warning'">
      {{ allFilled ? '三人证件信息齐全，可提交财务复核' : '存在未填证件，补齐后提交' }}
    </ElTag>
  </div>
</template>

显示代码

Props

属性名	类型	默认值	说明
model-value / v-model	string	''	原始号码（大写 X，自动过滤非法字符，上限 18 位）
placeholder	string	'请输入 18 位身份证号'	占位文案
disabled	boolean	false	只读
clearable	boolean	true	可清空
show-error	boolean	true	校验失败时在输入框下方展示原因
show-info	boolean	true	校验通过时展示派生信息标签
skip-checksum	boolean	false	跳过校验位验证（存量数据容错）

Events

事件名	参数	说明
update:model-value	(value: string)	输入更新（已规范化：去非法字符、大写 X）
change	(value: string, info: BizIdCardInfo)	值变化时携带完整解析结果
derive	(info: BizIdCardInfo)	校验通过时触发，携带派生信息（出生日期/性别/年龄/省份）
blur	(event: FocusEvent)	失焦

Expose

名称	类型	说明
validate	() => BizIdCardInfo	主动校验，返回 { id, valid, message, birthDate, gender, age, province }