@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();