BizTemplateInput 模板变量输入

文案 + ${变量} 占位符的模板编辑器：工具栏「插入变量」下拉（按 group 聚类）点选在光标处插入 ${name}；失焦 / 预览时校验未注册变量与未闭合 ${（下方报错列出位置）；「预览」用 sample 示例值实时替换渲染（变量徽标高亮、未注册红色，纯前端不发请求）；已用变量计数、maxlength 字数统计。适用于短信 / 邮件 / 站内信模板、合同条款变量、审批提醒话术、打印模板——所有「文案 + 数据占位符」场景。

与相关组件的边界：BizMentionInput 面向 @ 提及具体人员（插入姓名，带人员候选弹层）；BizI18nInput 面向同一文案多语言录入；BizTemplateInput 面向插入数据占位符并校验 / 预览。

基础用法

52 / 500

已用 4 个变量

「插入变量」面板点选在光标处插入 ${变量}；工具栏实时统计已用变量数。

「插入变量」面板点选在光标处插入 ${变量}，工具栏实时统计已用变量数。

<script setup lang="ts">
/** 场景：基础用法——变量面板点选在光标处插入 ${变量} */
import { ref } from 'vue'
import { BizTemplateInput } from 'vue3-ep-biz-lib'
import type { BizTemplateVariable } from 'vue3-ep-biz-lib'

const template = ref('尊敬的${customer}，您预订的${room}将于${date}开放入住，凭${code}取房卡。')

const variables: BizTemplateVariable[] = [
  { name: 'customer', label: '客户姓名', sample: '张三' },
  { name: 'room', label: '房型', sample: '湖景大床房' },
  { name: 'date', label: '入住日期', sample: '11月8日' },
  { name: 'code', label: '取房码', sample: '8A6K' },
]
</script>

<template>
  <el-space direction="vertical" size="large" style="width: 560px">
    <BizTemplateInput v-model="template" :variables="variables" />
    <p style="margin: 0; font-size: 13px; color: var(--el-text-color-secondary)">
      「插入变量」面板点选在光标处插入 <code>${变量}</code>；工具栏实时统计已用变量数。
    </p>
  </el-space>
</template>

显示代码

分组变量

53 / 500

已用 4 个变量

变量定义 group 字段聚类展示，变量多的业务按域分组更易检索。

变量定义 group 字段聚类展示（订单 / 客户 / 系统），变量多的业务按域分组检索。

<script setup lang="ts">
/** 场景：分组变量——面板按 group 聚类（订单域 / 客户域 / 系统域） */
import { ref } from 'vue'
import { BizTemplateInput } from 'vue3-ep-biz-lib'
import type { BizTemplateVariable } from 'vue3-ep-biz-lib'

const template = ref('${customer}您好，订单${orderNo}（${amount}元）已发货，预计${eta}送达。')

const variables: BizTemplateVariable[] = [
  { name: 'orderNo', label: '订单号', sample: 'SO20261101001', group: '订单' },
  { name: 'amount', label: '订单金额', sample: '1,299.00', group: '订单' },
  { name: 'eta', label: '预计送达', sample: '11月4日', group: '订单' },
  { name: 'customer', label: '客户姓名', sample: '李静', group: '客户' },
  { name: 'phone', label: '客户手机', sample: '139****6666', group: '客户' },
  { name: 'nickname', label: '平台昵称', sample: '静观其变', group: '客户' },
  { name: 'brand', label: '平台品牌', sample: '云枢商城', group: '系统' },
  { name: 'hotline', label: '客服热线', sample: '400-666-8888', group: '系统' },
]
</script>

<template>
  <el-space direction="vertical" size="large" style="width: 560px">
    <BizTemplateInput v-model="template" :variables="variables" :rows="5" />
    <p style="margin: 0; font-size: 13px; color: var(--el-text-color-secondary)">
      变量定义 <code>group</code> 字段聚类展示，变量多的业务按域分组更易检索。
    </p>
  </el-space>
</template>

显示代码

校验未注册变量

40 / 500

已用 3 个变量 1 个未注册

${staff} 未在白名单：失焦即在下方报错并列出未注册变量；再手输一个未闭合的 ${name（缺 }）试试未闭合校验。

手输变量超出 variables 白名单，或 ${ 未闭合（缺 }），失焦即在下方报错。

<script setup lang="ts">
/** 场景：校验未注册变量——手输 ${xxx} 超出白名单 / 未闭合时失焦报错 */
import { ref } from 'vue'
import { BizTemplateInput } from 'vue3-ep-biz-lib'
import type { BizTemplateVariable } from 'vue3-ep-biz-lib'

const template = ref('您尾号${tail}的卡支出${amount}元，如有疑问联系${staff}。')

const variables: BizTemplateVariable[] = [
  { name: 'tail', label: '卡尾号', sample: '8821' },
  { name: 'amount', label: '支出金额', sample: '3,200.00' },
]
</script>

<template>
  <el-space direction="vertical" size="large" style="width: 560px">
    <BizTemplateInput v-model="template" :variables="variables" />
    <p style="margin: 0; font-size: 13px; color: var(--el-text-color-secondary)">
      <code>${staff}</code> 未在白名单：失焦即在下方报错并列出未注册变量；再手输一个未闭合的
      <code>${name</code>（缺 <code>}</code>）试试未闭合校验。
    </p>
  </el-space>
</template>

显示代码

实时预览

40 / 500

已用 3 个变量

点击「预览」切换渲染态：变量用 sample 示例值替换并徽标高亮（未注册变量红色提示）， 纯前端渲染不发请求。

「预览」切换渲染态：变量用 sample 示例值替换并徽标高亮（未注册红色），纯前端渲染。

<script setup lang="ts">
/** 场景：实时预览——sample 示例值替换渲染，变量徽标高亮、未注册红色 */
import { ref } from 'vue'
import { BizTemplateInput } from 'vue3-ep-biz-lib'
import type { BizTemplateVariable } from 'vue3-ep-biz-lib'

const template = ref('${user} 提交的《${doc}》等待您审批，单号 ${no}，请及时处理。')

const variables: BizTemplateVariable[] = [
  { name: 'user', label: '提交人', sample: '王强' },
  { name: 'doc', label: '单据名称', sample: '差旅报销单' },
  { name: 'no', label: '审批单号', sample: 'SP-20261106-0142' },
]
</script>

<template>
  <el-space direction="vertical" size="large" style="width: 560px">
    <BizTemplateInput v-model="template" :variables="variables" />
    <p style="margin: 0; font-size: 13px; color: var(--el-text-color-secondary)">
      点击「预览」切换渲染态：变量用 <code>sample</code> 示例值替换并徽标高亮（未注册变量红色提示），
      纯前端渲染不发请求。
    </p>
  </el-space>
</template>

显示代码

变量白名单收敛 + 字数限制

29 / 70

已用 1 个变量

maxlength 开启字数统计（短信按 70 字计费条数）；白名单仅两个变量，面板即选即插防止运营手输错变量名。

少量变量的场景面板即选即插防手错；maxlength 开启字数统计（短信 70 字计费口径）。

<script setup lang="ts">
/** 场景：变量白名单收敛 + 字数限制——少量变量、 maxlength 计费的短信场景 */
import { ref } from 'vue'
import { BizTemplateInput } from 'vue3-ep-biz-lib'
import type { BizTemplateVariable } from 'vue3-ep-biz-lib'

const template = ref('【云枢】验证码 ${code}，5 分钟内有效，请勿泄露。')

const variables: BizTemplateVariable[] = [
  { name: 'code', label: '验证码', sample: '482913' },
  { name: 'minutes', label: '有效分钟', sample: '5' },
]
</script>

<template>
  <el-space direction="vertical" size="large" style="width: 560px">
    <BizTemplateInput v-model="template" :variables="variables" :rows="3" :maxlength="70" />
    <p style="margin: 0; font-size: 13px; color: var(--el-text-color-secondary)">
      maxlength 开启字数统计（短信按 70 字计费条数）；白名单仅两个变量，面板即选即插防止运营手输错变量名。
    </p>
  </el-space>
</template>

显示代码

禁用与纯校验模式

禁用只读（协议模板不可改）

已用 2 个变量

toolbar=false（嵌入页面自有操作栏）

33 / 500

disabled 协议模板只读；toolbar=false 关闭工具栏（页面自带操作栏时仅保留文本域 + 校验）。

<script setup lang="ts">
/** 场景：禁用与纯校验模式——toolbar 关闭后仅文本域 + 失焦校验（嵌入自有工具栏的页面） */
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { BizTemplateInput } from 'vue3-ep-biz-lib'
import type { BizTemplateValidateResult, BizTemplateVariable } from 'vue3-ep-biz-lib'

const disabledTemplate = ref('${customer}的会员卡将于${expire}到期。')

const editableTemplate = ref('尊敬的${customer}，您的积分${points}即将清零。')

const variables: BizTemplateVariable[] = [
  { name: 'customer', label: '客户姓名', sample: '赵敏' },
  { name: 'expire', label: '到期日', sample: '2026-12-31' },
  { name: 'points', label: '积分', sample: '12,800' },
]

const onBlur = (result: BizTemplateValidateResult): void => {
  if (!result.valid) ElMessage.warning(result.message)
}
</script>

<template>
  <el-space direction="vertical" size="large" style="width: 560px">
    <el-card shadow="never">
      <template #header>禁用只读（协议模板不可改）</template>
      <BizTemplateInput v-model="disabledTemplate" :variables="variables" disabled />
    </el-card>
    <el-card shadow="never">
      <template #header>toolbar=false（嵌入页面自有操作栏）</template>
      <BizTemplateInput v-model="editableTemplate" :variables="variables" :toolbar="false" @blur="onBlur" />
    </el-card>
  </el-space>
</template>

显示代码

事件与 expose

38 / 500

已用 3 个变量

blur 携带完整校验结果 { valid, message, used }；expose validate() / getUsedVariables() / insertVariable()。

<script setup lang="ts">
/** 场景：事件与 expose——blur 校验结果面板 + validate()/getUsedVariables() 编程调用 */
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { BizTemplateInput } from 'vue3-ep-biz-lib'
import type { BizTemplateInputInstance, BizTemplateValidateResult, BizTemplateVariable } from 'vue3-ep-biz-lib'

const template = ref('会议提醒：${topic} 将于 ${time} 在 ${room} 举行。')
const lastResult = ref<BizTemplateValidateResult | null>(null)
const inputRef = ref<BizTemplateInputInstance>()

const variables: BizTemplateVariable[] = [
  { name: 'topic', label: '会议主题', sample: 'Q4 复盘' },
  { name: 'time', label: '会议时间', sample: '11月10日 14:00' },
  { name: 'room', label: '会议室', sample: '3F-致远厅' },
]

const onBlur = (result: BizTemplateValidateResult): void => {
  lastResult.value = result
}

const onValidate = (): void => {
  const result = inputRef.value?.validate()
  if (result === undefined) return
  lastResult.value = result
  if (result.valid) ElMessage.success(`校验通过，已用变量：${result.used.join('、')}`)
  else ElMessage.error(result.message)
}

const onShowUsed = (): void => {
  const used = inputRef.value?.getUsedVariables() ?? []
  ElMessage.info(`getUsedVariables()：${used.length > 0 ? used.join('、') : '（空）'}`)
}
</script>

<template>
  <el-space direction="vertical" size="large" style="width: 560px">
    <BizTemplateInput ref="inputRef" v-model="template" :variables="variables" @blur="onBlur" />
    <el-space>
      <el-button size="small" type="primary" @click="onValidate">validate() 校验</el-button>
      <el-button size="small" @click="onShowUsed">getUsedVariables()</el-button>
    </el-space>
    <el-alert v-if="lastResult" :closable="false" :type="lastResult.valid ? 'success' : 'error'" :title="`valid: ${lastResult.valid}`"
      :description="lastResult.valid ? `used: ${lastResult.used.join('、')}` : lastResult.message" />
  </el-space>
</template>

显示代码

短信模板实战

短信模板

55 字 · 1 条计费

55 / 200

已用 4 个变量

预览态确认示例值后再保存，避免变量拼错线上事故。

快递到件短信：变量插入 + 预览确认 + 70 字计费条数联动保存。

<script setup lang="ts">
/** 场景：短信模板实战——变量插入 + 预览 + 计费条数（70 字/条）联动 */
import { computed, ref } from 'vue'
import { ElMessage } from 'element-plus'
import { BizTemplateInput } from 'vue3-ep-biz-lib'
import type { BizTemplateVariable } from 'vue3-ep-biz-lib'

const template = ref('${name}您好，您的快递${waybill}已到${station}网点，凭取件码${pickup}领取。')

const variables: BizTemplateVariable[] = [
  { name: 'name', label: '收件人', sample: '张三', group: '收件' },
  { name: 'pickup', label: '取件码', sample: '6-2-4018', group: '收件' },
  { name: 'waybill', label: '运单号', sample: 'SF13988812345', group: '物流' },
  { name: 'station', label: '网点名', sample: '徐汇宜州路站', group: '物流' },
]

/** 短信计费：≤70 字 1 条，超出按 67 字/条累加 */
const segments = computed(() => {
  const len = template.value.length
  if (len === 0) return 0
  return len <= 70 ? 1 : Math.ceil(len / 67)
})

const onSave = (): void => {
  ElMessage.success(`模板已保存（${segments.value} 条计费）`)
}
</script>

<template>
  <el-card shadow="never" style="width: 620px">
    <template #header>
      <el-space>短信模板 <el-tag size="small" type="warning" effect="plain">{{ template.length }} 字 · {{ segments }} 条计费</el-tag></el-space>
    </template>
    <BizTemplateInput v-model="template" :variables="variables" :rows="4" :maxlength="200" />
    <el-space style="margin-top: 12px">
      <el-button type="primary" size="small" @click="onSave">保存模板</el-button>
      <span style="font-size: 13px; color: var(--el-text-color-secondary)">预览态确认示例值后再保存，避免变量拼错线上事故。</span>
    </el-space>
  </el-card>
</template>

显示代码

Props

属性名	类型	默认值	说明
model-value / v-model	string	''	模板文本（可含 ${变量} 占位符）
variables	BizTemplateVariable[]	[]	可用变量白名单（面板点选 + 校验 + 预览依据）
rows	number	4	文本域行数
placeholder	string	'请输入模板内容，可插入 ${变量}'	占位提示
disabled	boolean	false	禁用（工具栏同步禁用）
maxlength	number	500	字数上限（0 不限制），开启字数统计
show-error	boolean	true	校验失败时是否在下方展示原因
toolbar	boolean	true	是否显示工具栏（插入变量下拉 + 已用计数 + 预览切换）

BizTemplateVariable： { name: string; label?: string; sample?: string; group?: string }——name 变量名（插入 ${name}）、label 面板文案（缺省取 name）、sample 预览示例值（缺省取 name）、group 面板分组（缺省「常用变量」）。

Events

事件名	参数	说明
update:model-value	(value: string)	输入 / 插入变量后落值
change	(value: string)	输入 / 插入变量后触发
blur	(result: BizTemplateValidateResult)	失焦校验结果 { valid, message, used }

Expose

属性/方法	类型	说明
validate	() => BizTemplateValidateResult	触发校验，返回 { valid, message, used }（used 为去重按出现顺序的变量名）
getUsedVariables	() => string[]	当前使用的变量名列表
insertVariable	(name: string) => void	编程插入变量（等价面板点选，落光标处）