BizEditableText 行内编辑文本

点击文本就地变输入框的轻量编辑原语：单击 / 双击 / 受控三种触发，Enter（多行为 Ctrl+Enter）或失焦提交、Esc 取消还原；同步 validator + 异步 asyncValidator 两段校验（异步期间输入框禁用转 loading、失败保持编辑态并行内报错）；空值占位引导补录、超长省略、textarea 多行与 number 数值形态。适用于详情页字段就地修改、卡片 / 看板列重命名、目录节点重命名、备注快速补录——避免「为改一个字段开一次弹窗」。

与相关组件的边界：BizEditableTable 面向整表批量行编辑（列配置驱动）；BizEditableText 面向单点轻量就地编辑（一个字段一处使用）。

基础用法

部门名称：

华东运营中心

点击文本进入编辑（自动聚焦全选）；Enter 或点击外部提交，Esc 取消还原。 当前值：华东运营中心

点击文本进入编辑（自动聚焦全选）；Enter 或点击外部提交，Esc 取消还原。

<script setup lang="ts">
/** 场景：基础点击编辑——单击进入、Enter/失焦提交、Esc 取消 */
import { ref } from 'vue'
import { BizEditableText } from 'vue3-ep-biz-lib'

const nickname = ref('华东运营中心')
</script>

<template>
  <el-space direction="vertical" size="large">
    <el-space>部门名称：<BizEditableText v-model="nickname" style="min-width: 220px" /></el-space>
    <p style="margin: 0; font-size: 13px; color: var(--el-text-color-secondary)">
      点击文本进入编辑（自动聚焦全选）；Enter 或点击外部提交，Esc 取消还原。
      当前值：<code>{{ nickname }}</code>
    </p>
  </el-space>
</template>

显示代码

双击触发

目录节点（单击选中 · 双击重命名）

选中

客户管理

选中

商机跟进

选中

合同归档

trigger="dblclick" 双击才进入编辑——列表 / 树形场景单击常用于选中行，避免误触。

<script setup lang="ts">
/** 场景：双击触发——避免列表场景误触（单击常用于选中行 / 打开详情） */
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { Folder } from '@element-plus/icons-vue'
import { BizEditableText } from 'vue3-ep-biz-lib'

const selected = ref(0)

const nodes = ref([
  { id: 1, name: '客户管理', depth: 0 },
  { id: 2, name: '商机跟进', depth: 1 },
  { id: 3, name: '合同归档', depth: 1 },
])

const onSelect = (id: number, name: string): void => {
  selected.value = id
  ElMessage.info(`单击选中「${name}」（双击才进入重命名）`)
}
</script>

<template>
  <el-card shadow="never" style="width: 380px">
    <template #header>目录节点（单击选中 · 双击重命名）</template>
    <el-space direction="vertical" alignment="flex-start" size="large" style="width: 100%">
      <el-space
        v-for="node in nodes"
        :key="node.id"
        :style="{ paddingLeft: `${node.depth * 20}px`, width: '100%' }"
      >
        <el-tag :type="selected === node.id ? 'primary' : 'info'" effect="plain" style="cursor: pointer" @click="onSelect(node.id, node.name)">
          <el-icon style="vertical-align: -2px"><Folder /></el-icon>
          {{ selected === node.id ? '已选中' : '选中' }}
        </el-tag>
        <BizEditableText v-model="node.name" trigger="dblclick" style="min-width: 170px" />
      </el-space>
    </el-space>
  </el-card>
</template>

显示代码

同步校验

客户名称：

张三

validator 返回字符串即错误文案（阻止提交、保持编辑态聚焦）；返回 true / undefined 通过。 试试清空或输入特殊字符。

validator 返回字符串即错误文案（阻止提交、保持编辑态）；返回 true / undefined 通过。

<script setup lang="ts">
/** 场景：同步校验——非空 / 长度规则，失败行内报错并保持编辑态 */
import { ref } from 'vue'
import { BizEditableText } from 'vue3-ep-biz-lib'

const name = ref('张三')

const validate = (value: string): true | string => {
  if (value === '') return '名称不能为空'
  if (value.length > 12) return `最多 12 个字符，当前 ${value.length} 个`
  if (!/^[\u4e00-\u9fa5A-Za-z0-9-_]+$/.test(value)) return '仅支持中文、字母、数字、中划线、下划线'
  return true
}
</script>

<template>
  <el-space direction="vertical" size="large">
    <el-space>客户名称：<BizEditableText v-model="name" :validator="validate" style="min-width: 240px" /></el-space>
    <p style="margin: 0; font-size: 13px; color: var(--el-text-color-secondary)">
      validator 返回字符串即错误文案（阻止提交、保持编辑态聚焦）；返回 true / undefined 通过。
      试试清空或输入特殊字符。
    </p>
  </el-space>
</template>

显示代码

异步校验 / 保存

分组名称：

华东大区一组

提交经 async-validator：进行中输入框禁用并转 loading；resolve 字符串为服务端错误文案（保持编辑）。 试试改成「华东大区二组」触发判重失败。

async-validator 承接服务端判重 / 保存接口：进行中防重复提交，resolve 字符串为服务端错误文案。

<script setup lang="ts">
/** 场景：异步校验/保存——loading 期间防重复提交，服务端判重失败保持编辑态 */
import { ref } from 'vue'
import { BizEditableText } from 'vue3-ep-biz-lib'

const groupName = ref('华东大区一组')
const existing = ['华东大区二组', '华北大区一组']

/** 模拟服务端判重接口（1s 延迟） */
const checkName = (value: string): Promise<true | string> =>
  new Promise((resolve) => {
    setTimeout(() => {
      resolve(existing.includes(value) ? `「${value}」已存在，请换一个` : true)
    }, 1000)
  })
</script>

<template>
  <el-space direction="vertical" size="large">
    <el-space>分组名称：<BizEditableText v-model="groupName" :async-validator="checkName" style="min-width: 260px" /></el-space>
    <p style="margin: 0; font-size: 13px; color: var(--el-text-color-secondary)">
      提交经 async-validator：进行中输入框禁用并转 loading；resolve 字符串为服务端错误文案（保持编辑）。
      试试改成「华东大区二组」触发判重失败。
    </p>
  </el-space>
</template>

显示代码

受控编辑态

看板列名

编辑态

2026 Q4 促销活动

trigger="manual" 时组件不响应点击，编辑态完全由 v-model:editing 外部控制—— 适合「整行统一进入编辑」等批量交互编排。

v-model:editing 外部驱动编辑态；trigger="manual" 时组件不响应点击，适合整行统一编辑的批量编排。

<script setup lang="ts">
/** 场景：受控编辑态——v-model:editing 由外部驱动（manual 模式配合按钮开关） */
import { ref } from 'vue'
import { BizEditableText } from 'vue3-ep-biz-lib'

const title = ref('2026 Q4 促销活动')
const editing = ref(false)
</script>

<template>
  <el-card shadow="never" style="width: 420px">
    <template #header>
      <el-space>看板列名 <el-switch v-model="editing" active-text="编辑态" /></el-space>
    </template>
    <BizEditableText v-model="title" v-model:editing="editing" trigger="manual" style="width: 100%" />
    <p style="margin: 12px 0 0; font-size: 13px; color: var(--el-text-color-secondary)">
      trigger="manual" 时组件不响应点击，编辑态完全由 <code>v-model:editing</code> 外部控制——
      适合「整行统一进入编辑」等批量交互编排。
    </p>
  </el-card>
</template>

显示代码

多行编辑

跟进备注（点击展开多行编辑）

客户强调交付窗口在 11 月中旬前，验收标准按合同附件二执行。

多行形态 Enter 换行、Ctrl+Enter 提交、Esc 取消；maxlength 开启字数统计（100 字）。

input-type="textarea" 多行形态：Enter 换行、Ctrl+Enter 提交，maxlength 开启字数统计。

<script setup lang="ts">
/** 场景：多行编辑——textarea 形态，Enter 换行、Ctrl+Enter 提交、字数限制 */
import { ref } from 'vue'
import { BizEditableText } from 'vue3-ep-biz-lib'

const remark = ref('客户强调交付窗口在 11 月中旬前，验收标准按合同附件二执行。')
</script>

<template>
  <el-card shadow="never" style="width: 520px">
    <template #header>跟进备注（点击展开多行编辑）</template>
    <BizEditableText
      v-model="remark"
      input-type="textarea"
      :rows="4"
      :maxlength="100"
      :ellipsis="false"
      empty-text="点击补充备注"
      style="width: 100%"
    />
    <p style="margin: 12px 0 0; font-size: 13px; color: var(--el-text-color-secondary)">
      多行形态 Enter 换行、<code>Ctrl+Enter</code> 提交、Esc 取消；maxlength 开启字数统计（100 字）。
    </p>
  </el-card>
</template>

显示代码

数值形态

库存余量：

86

排序权重：

5

number 形态内部用 ElInputNumber（无步进器）；v-model 仍为字符串，便于与后端 DTO 直连。

input-type="number" 内部为 ElInputNumber（无步进器）；v-model 保持字符串，便于与后端 DTO 直连。

<script setup lang="ts">
/** 场景：数值形态——ElInputNumber 编辑（金额 / 数量 / 排序权重），字符串落值 */
import { ref } from 'vue'
import { BizEditableText } from 'vue3-ep-biz-lib'

const stock = ref('86')
const weight = ref('5')

const validateWeight = (value: string): true | string => {
  if (value === '') return '权重不能为空'
  const num = Number(value)
  if (!Number.isInteger(num) || num < 1 || num > 9) return '权重为 1-9 的整数'
  return true
}
</script>

<template>
  <el-space direction="vertical" size="large">
    <el-space>库存余量：<BizEditableText v-model="stock" input-type="number" style="min-width: 140px" /></el-space>
    <el-space>排序权重：<BizEditableText v-model="weight" input-type="number" :validator="validateWeight" style="min-width: 140px" /></el-space>
    <p style="margin: 0; font-size: 13px; color: var(--el-text-color-secondary)">
      number 形态内部用 ElInputNumber（无步进器）；v-model 仍为字符串，便于与后端 DTO 直连。
    </p>
  </el-space>
</template>

显示代码

详情页字段组合

成员档案（点击字段就地修改）

职位	高级客户成功经理
手机号	13856781234 允许编辑
邮箱	zhangsan@example.com
办公地址	上海市徐汇区漕河泾开发区宜州路 188 号 B 座 12 层
兴趣爱好	点击补充

手机号默认只读（开关授权后可改）；地址开启超长省略（悬浮 title 看全文）；兴趣为空显示占位引导补录。

职位 / 手机号 / 邮箱 / 地址 / 兴趣多字段并排：只读授权开关、格式校验、空占位与超长省略的组合范式。

<script setup lang="ts">
/** 场景：详情页字段就地编辑组合——多字段并排 + 只读权限 + 空占位 + 超长省略 */
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { BizEditableText } from 'vue3-ep-biz-lib'

const profile = ref({
  title: '高级客户成功经理',
  phone: '13856781234',
  email: 'zhangsan@example.com',
  address: '上海市徐汇区漕河泾开发区宜州路 188 号 B 座 12 层',
  hobby: '',
})

const canEditPhone = ref(false)

const phoneValidator = (value: string): true | string =>
  /^1[3-9]\d{9}$/.test(value) ? true : '手机号格式不正确'

const onChange = (field: string, value: string): void => {
  ElMessage.success(`${field}已更新：${value}`)
}
</script>

<template>
  <el-card shadow="never" style="width: 560px">
    <template #header>成员档案（点击字段就地修改）</template>
    <el-descriptions :column="1" border>
      <el-descriptions-item label="职位">
        <BizEditableText v-model="profile.title" :ellipsis="true" style="max-width: 320px" @change="(v) => onChange('职位', v)" />
      </el-descriptions-item>
      <el-descriptions-item label="手机号">
        <el-space>
          <BizEditableText
            v-model="profile.phone"
            :disabled="!canEditPhone"
            :validator="phoneValidator"
            empty-text="未绑定"
            style="min-width: 160px"
            @change="(v) => onChange('手机号', v)"
          />
          <el-switch v-model="canEditPhone" size="small" active-text="允许编辑" />
        </el-space>
      </el-descriptions-item>
      <el-descriptions-item label="邮箱">
        <BizEditableText v-model="profile.email" :ellipsis="true" style="max-width: 320px" @change="(v) => onChange('邮箱', v)" />
      </el-descriptions-item>
      <el-descriptions-item label="办公地址">
        <BizEditableText
          v-model="profile.address"
          :ellipsis="true"
          style="max-width: 320px"
          @change="(v) => onChange('办公地址', v)"
        />
      </el-descriptions-item>
      <el-descriptions-item label="兴趣爱好">
        <BizEditableText v-model="profile.hobby" empty-text="点击补充" style="max-width: 320px" @change="(v) => onChange('兴趣爱好', v)" />
      </el-descriptions-item>
    </el-descriptions>
    <p style="margin: 12px 0 0; font-size: 13px; color: var(--el-text-color-secondary)">
      手机号默认只读（开关授权后可改）；地址开启超长省略（悬浮 title 看全文）；兴趣为空显示占位引导补录。
    </p>
  </el-card>
</template>

显示代码

Props

属性名	类型	默认值	说明
model-value / v-model	string	''	文本值（number 形态也以字符串落值）
trigger	'click' | 'dblclick' | 'manual'	'click'	进入编辑的触发方式；manual 仅响应受控 editing
editing / v-model:editing	boolean	—	受控编辑态（缺省组件自治）
empty-text	string	'点击编辑'	空值占位文案（弱化展示，仍可进入编辑）
input-type	'text' | 'textarea' | 'number'	'text'	编辑输入类型（number 为 ElInputNumber 无步进器）
rows	number	3	textarea 行数
maxlength	number	0	最大长度（0 不限制；text / textarea 生效，textarea 同步开启字数统计）
trim	boolean	true	提交前去除首尾空白
validator	(value: string) => true | string | undefined	—	同步校验：返回字符串为错误文案（阻止提交保持编辑态）
async-validator	(value: string) => Promise<true | string>	—	异步校验 / 保存（同步校验通过后执行；进行中防重复提交，reject 按保存失败处理）
disabled	boolean	false	只读（不进入编辑，hover 无编辑图标）
autofocus	boolean	true	进入编辑后自动聚焦（text 形态同时全选）
ellipsis	boolean	false	展示文本超长省略（单行 ellipsis + title 全文）
width	number	—	编辑框定宽 px（缺省 100% 随容器）

Events

事件名	参数	说明
update:model-value	(value: string)	提交通过后落值
update:editing	(value: boolean)	编辑态切换（进入 / 退出均触发）
change	(value: string, oldValue: string)	提交通过后触发（提交即触发，值可能未变化）
edit-start	—	进入编辑时触发
edit-cancel	(oldValue: string)	Esc 取消（或受控关闭）时触发

Expose

属性/方法	类型	说明
startEdit	() => void	进入编辑（manual 受控模式的编程入口）
cancelEdit	() => void	取消编辑并还原草稿
isEditing	() => boolean	当前是否编辑态