@xingzhijian/ltc-sub-table

@xingzhijian/ltc-sub-table

基于 Vue 3 与 Ant Design Vue 的可配置编辑子表组件。组件通过 fields 配置字段、控件、必填和正则校验，不固定业务字段；支持新增、删除、批量删除、合计、失焦校验以及父页面提交前校验。

当前包名使用 @xingzhijian scope。发布到你的 npm 账号或公司私有源前，请先在 package.json 中确认 name 与实际 scope 一致。

环境要求

• Vue >= 3.2.0 < 4.0.0
• Ant Design Vue >= 3.2.0 < 5.0.0
• 业务项目需自行完成 Ant Design Vue 的 app.use(Antd) 注册。

安装

pnpm add @xingzhijian/ltc-sub-table
# 或 npm install @xingzhijian/ltc-sub-table

引入

按需注册（推荐）

import { createApp } from 'vue';
import Antd from 'ant-design-vue';
import { PlanItemSubTable } from '@xingzhijian/ltc-sub-table';
import '@xingzhijian/ltc-sub-table/style.css';

const app = createApp(App);
app.use(Antd);
app.component('PlanItemSubTable', PlanItemSubTable);

全局安装

import Antd from 'ant-design-vue';
import LtcSubTable from '@xingzhijian/ltc-sub-table';
import '@xingzhijian/ltc-sub-table/style.css';

app.use(Antd);
app.use(LtcSubTable);

发布

pnpm install
pnpm run check
pnpm run build
npm login
npm publish --access public

dist/ 是发布产物；不要手工修改。若发布到公司私有 npm 源，请按公司要求配置 .npmrc 后执行发布命令。

组件说明

PlanItemSubTable

功能

• 支持 v-model:modelValue 双向绑定明细数据；
• 支持动态新增行、单行删除、批量删除选中行；
• 通过 fields 配置列标题、字段名、表单控件、默认值及必填规则，不再固定为计划日期、金额、备注；
• 内置 input、textarea、input-number、date-picker、select 五种表单控件；
• 通过 summaryField 配置需要累计的数值字段；未配置时仅展示明细条数；
• 支持 showIndex、showAction、disabled 等展示与操作控制；
• 通过 defineExpose 暴露 validate、getData、reset、addRow、removeSelected、calculateTotal。

字段配置

fields 是组件的核心配置，每项对应一列可编辑字段。

配置项	类型	说明
field	string	提交数据中的字段名。
label	string	表格列标题。
component	input / textarea / input-number / date-picker / select	表单控件类型。
required	boolean	是否必填；失焦和提交前调用 validate 时均会校验。
requiredMessage	string	自定义必填提示。
pattern	string / RegExp	非空时需匹配的正则表达式；失焦和提交时均会校验。
patternMessage	string	自定义正则校验失败提示。
width / align	number / string	列宽和对齐方式。
placeholder	string	输入提示；不传时组件自动生成。
defaultValue	unknown	新增空行的默认值。
disabled	boolean	是否禁用该字段。
options	{ label, value }[]	下拉框选项，仅 select 使用。
componentProps	Record<string, unknown>	透传控件属性，如 min、precision、allowClear。

暴露方法

父页面可通过 ref 调用子表实例方法，常用于主表提交前统一校验子表数据。

方法名	入参	返回值	说明
validate	-	Promise<boolean>	校验子表必填项和字段正则；校验通过返回 true，校验不通过会抛出包含 errorFields 的错误信息，并在表格内展示错误提示。
getData	syncModel?: boolean	Promise<SubTableRecord[]>	获取去除内部行标识后的明细数据；默认同步触发 modelValue 更新。
reset	-	void	重置子表为最小行数，并清空选中状态和错误信息。
addRow	row?: SubTableRecord	Promise<void>	手动新增一行，可传入默认行数据。
removeSelected	-	Promise<void>	删除当前选中的明细行。
calculateTotal	-	string	按 summaryField 重新计算并返回合计金额；未配置时返回 0.00。

使用示例

<template>
  <PlanItemSubTable
    ref="subTableRef"
    v-model:modelValue="detailList"
    title="付款计划"
    :fields="fields"
    summary-field="amount"
    :show-index="false"
    @totalChange="handleTotalChange"
  />
</template>

<script lang="ts" setup>
  import { ref } from 'vue';
  import { PlanItemSubTable, type PlanItemSubTableExpose, type SubTableFieldConfig, type SubTableRecord } from '@xingzhijian/ltc-sub-table';

  const fields: SubTableFieldConfig[] = [
    {
      field: 'payeeName',
      label: '收款方',
      component: 'input',
      required: true,
      componentProps: { allowClear: true },
    },
    {
      field: 'paymentDate',
      label: '付款日期',
      component: 'date-picker',
      required: true,
      componentProps: { valueFormat: 'YYYY-MM-DD' },
    },
    {
      field: 'amount',
      label: '付款金额',
      component: 'input-number',
      required: true,
      componentProps: { min: 0, precision: 2 },
    },
    {
      field: 'paymentMethod',
      label: '付款方式',
      component: 'select',
      required: true,
      options: [
        { label: '银行转账', value: 'bank' },
        { label: '现金', value: 'cash' },
      ],
    },
    {
      field: 'remark',
      label: '备注',
      component: 'textarea',
      componentProps: { autoSize: { minRows: 1, maxRows: 3 } },
    },
  ];

  const detailList = ref<SubTableRecord[]>([]);
  const subTableRef = ref<PlanItemSubTableExpose>();

  function handleTotalChange(total: string) {
    console.log('合计金额：', total);
  }

  async function handleSubmit() {
    // 主表提交前先校验子表，校验失败会自动在子表中展示错误信息。
    await subTableRef.value?.validate();
    const detailRows = await subTableRef.value?.getData();
    console.log('提交明细：', detailRows);
  }
</script>

存量计划明细兼容方式

原“计划日期、金额、备注”结构可使用内置的兼容字段工厂：

import { createPlanItemFields } from '@xingzhijian/ltc-sub-table';

const fields = createPlanItemFields();