CpEditGrid 行编辑表格

对应旧系统费用录入类页面（GeorGrid + format 拼输入控件的模式）：工具栏新增一行 / 勾选删除，点击行内任意单元格，该行所有可编辑列同时放开编辑（无需逐格点击），输入中按 Tab 键按列顺序切换到下一个可编辑控件，支持 input / number / select / date / text 五种编辑器，options 支持按行返回（级联下拉），必填列表头带红星 + validate() 校验。编辑权限三级控制：row-disabled 整行禁用（如已提交行锁定）→ editable-fields 限定行内可编辑列 → 列配置 disabled（支持按行函数）。column-setting 开启工具栏列设置面板：搜索定位列、调整宽度、置顶 / 上移 / 下移 / 输入位置序号直接跳转，调整后触发 @column-change；column-setting-key 进一步把列顺序 / 宽度自动持久化到 localStorage，刷新页面后自动恢复。

费用录入

费用录入

点击行任意位置整行进入编辑，Tab 键依次切到下一列；新增行带 row-template 默认值并立即进入编辑；第二行预置 Locked 锁定（整行不可编辑，录入人列显示 🔒），勾选行可锁定/解锁；切换「仅金额+备注可编辑」后其余列自动禁用；点工具栏右侧「列设置」可搜索定位列、调宽、置顶/上移下移/跳转位置，column-setting-key 让调整结果刷新后依然保留；新行不填必填项时 validate() 报错。

<template>
  <div class="demo-col">
    <div class="demo-row">
      <el-button @click="check">validate() 必填校验</el-button>
      <el-button @click="toggleLock">锁定 / 解锁选中行</el-button>
      <el-radio-group v-model="mode" size="small">
        <el-radio-button value="all">全部列可编辑</el-radio-button>
        <el-radio-button value="limited">仅金额+备注可编辑</el-radio-button>
      </el-radio-group>
      <span class="demo-value">{{ msg }}</span>
    </div>
    <CpEditGrid
      ref="editRef"
      :columns="columns"
      :data="rows"
      :height="240"
      :row-disabled="(row) => !!row.Locked"
      :editable-fields="editableFields"
      column-setting-key="demo-fee-grid"
      :row-template="() => ({ Currency: 'CNY', Date: today, Creator: 'aetos' })"
      @cell-change="(row, f, v) => (msg = `${f} → ${v}`)"
      @column-change="(cols) => (msg = `列顺序: ${cols.map((c) => c.title).join(' / ')}`)"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
import dayjs from "dayjs";
import type { CpEditColumn } from "../../src/index";
import type CpEditGrid from "../../src/components/CpEditGrid.vue";

const editRef = ref<InstanceType<typeof CpEditGrid>>();
const msg = ref("");
const mode = ref<"all" | "limited">("all");
const today = dayjs().format("YYYY-MM-DD");

/** editableFields：限定行内可编辑的列；返回 null = 不限制 */
const editableFields = (row: Record<string, any>) =>
  mode.value === "limited" ? ["Amount", "Remark"] : null;

const columns: CpEditColumn[] = [
  {
    dataField: "ChargeCode",
    title: "费用名称",
    width: 150,
    editor: "select",
    required: true,
    options: [
      { label: "海运费", value: "OFT" },
      { label: "码头操作费", value: "THC" },
      { label: "报关费", value: "CDC" },
      { label: "拖车费", value: "TRK" },
    ],
  },
  {
    dataField: "Amount",
    title: "金额",
    width: 120,
    align: "right",
    editor: "number",
    required: true,
    format: (v) => (v == null ? "" : Number(v).toFixed(2)),
  },
  {
    dataField: "Currency",
    title: "币种",
    width: 130,
    editor: "select",
    options: [
      { label: "人民币 CNY", value: "CNY" },
      { label: "美元 USD", value: "USD" },
    ],
  },
  { dataField: "Date", title: "费用日期", width: 140, editor: "date" },
  {
    dataField: "Remark",
    title: "备注",
    editor: "input",
    placeholder: "输入备注",
  },
  {
    dataField: "Creator",
    title: "录入人",
    width: 90,
    editor: "text",
    align: "center",
    format: (v, row) => (row.Locked ? `${v} 🔒` : v),
  },
];

const rows = ref([
  {
    ChargeCode: "OFT",
    Amount: 12000,
    Currency: "USD",
    Date: today,
    Remark: "",
    Creator: "aetos",
  },
  {
    ChargeCode: "THC",
    Amount: 980,
    Currency: "CNY",
    Date: today,
    Remark: "预付",
    Creator: "aetos",
    Locked: true,
  },
]);

function check() {
  const invalid = editRef.value?.validate() ?? [];
  msg.value = invalid.length
    ? `第 ${[...new Set(invalid.map((i) => i.rowIndex + 1))].join(",")} 行有必填项未填`
    : "校验通过 ✓";
}

/** 切换勾选行的 Locked 标记：rowDisabled 按行判定后整行不可编辑 */
function toggleLock() {
  const selected = editRef.value?.tableRef?.getCheckboxRecords() ?? [];
  if (!selected.length) {
    msg.value = "先勾选要锁定/解锁的行";
    return;
  }
  for (const r of selected) r.Locked = !r.Locked;
  const locked = selected.filter((r) => r.Locked).length;
  msg.value = locked
    ? `已锁定 ${locked} 行（整行不可编辑）`
    : "已解锁选中行";
}
</script>

显示代码 ▼

autocomplete 编辑器：远程检索 + 多选回填 + 搜索弹窗

列配置 editor: "autocomplete" 即可把 CpAutoComplete 整个嵌进单元格， 通过 autocomplete 字段透传它的全套能力（load 远程检索、multiple 多选回填、dialog 搜索弹窗、columns 下拉列）。 远程模式下的并发守卫一并继承，行内边输边查同样不会被过期响应污染。

autocomplete 支持传函数按行返回，用于级联场景 —— 下例「船公司」列只列出本行起运港所属国家的船司。

autocomplete 编辑器

起运港走远程接口边输边查，并可点放大镜开表格弹窗；费用项多选回填为 THC,DOC 形态；船公司按本行起运港级联过滤。三列都在行编辑态内，Tab 可依次切换。

<template>
  <div class="demo-col">
    <CpEditGrid
      ref="gridRef"
      :columns="columns"
      :data="rows"
      :height="260"
      @cell-change="(row, f, v) => (lastChange = `${f} → ${v || '(空)'}`)"
    />
    <span class="demo-value">最近改动：{{ lastChange || "-" }}</span>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
import type { CpEditColumn } from "../../src/index";
import { searchPorts } from "../api/portApi";

const gridRef = ref();
const lastChange = ref("");

const rows = ref([
  { Pol: "CNSHA", Fee: "", Carrier: "", Amount: 1200 },
  { Pol: "", Fee: "", Carrier: "", Amount: 0 },
]);

const FEES = [
  { Code: "THC", Name: "码头操作费" },
  { Code: "DOC", Name: "文件费" },
  { Code: "ORC", Name: "原产地收货费" },
  { Code: "AMS", Name: "舱单费" },
  { Code: "VGM", Name: "称重费" },
];

const CARRIERS = [
  { Code: "COSCO", Name: "中远海运", Country: "CN" },
  { Code: "SITC", Name: "海丰国际", Country: "CN" },
  { Code: "MATSON", Name: "美森", Country: "US" },
  { Code: "APL", Name: "美国总统轮船", Country: "US" },
  { Code: "HPL", Name: "赫伯罗特", Country: "DE" },
];

const columns: CpEditColumn[] = [
  {
    dataField: "Pol",
    title: "起运港（远程检索）",
    width: 150,
    editor: "autocomplete",
    // 远程数据源：竞态守卫由组件内置，这里只管把 signal 交给请求库
    autocomplete: {
      load: (query, { signal }) => searchPorts(query, signal, "grid"),
      dialog: true,
      dialogTitle: "选择起运港",
      columns: [
        { field: "Code", title: "代码", width: 90 },
        { field: "Name", title: "港口" },
      ],
    },
  },
  {
    dataField: "Fee",
    title: "费用项（多选 + 弹窗）",
    width: 180,
    editor: "autocomplete",
    autocomplete: {
      options: FEES,
      multiple: true,
      dialog: true,
      dialogTitle: "选择费用项",
      columns: [
        { field: "Code", title: "代码", width: 80 },
        { field: "Name", title: "名称" },
      ],
    },
  },
  {
    dataField: "Carrier",
    title: "船公司（级联）",
    width: 150,
    editor: "autocomplete",
    // 按行返回配置：只给出本行起运港所属国家的船公司
    autocomplete: (row) => ({
      options: CARRIERS.filter(
        (c) => !row.Pol || c.Country === String(row.Pol).slice(0, 2),
      ),
      placeholder: row.Pol ? "" : "请先选起运港",
      columns: [
        { field: "Code", title: "代码", width: 80 },
        { field: "Name", title: "船公司" },
      ],
    }),
  },
  { dataField: "Amount", title: "金额", width: 90, editor: "number" },
];

</script>

显示代码 ▼

API

属性 Props

属性	说明	类型	默认值
columns *	—	CpEditColumn[]	必填
data	—	Record[]	—
height	—	number | string	300
row-height	—	number	36
show-toolbar	—	boolean	true
show-row-index	—	boolean	true
edit-mode	编辑模式：row = 点击行内任意单元格整行放开编辑，Tab 顺序切换（默认）； cell = 仅点击的单元格进入编辑	"row" | "cell"	"row"
row-disabled	整行不可编辑：布尔值全表生效，函数按行判断（如已提交行锁定， (row) => !!row.Locked）。被禁用的行点击不进入编辑态	boolean | TSParenthesizedType	—
editable-fields	限定行内可编辑的列（dataField 数组），不在列表中的可编辑列自动禁用； 数组或函数返回 null/undefined/空数组 = 全部可编辑。 列级更细的规则仍可用列配置 disabled（支持函数按行判断）	string[] | TSParenthesizedType	—
row-template	新增行的初始值模板	Function	—
column-setting	工具栏显示「列设置」按钮：面板内可搜索定位列、调宽、置顶/上移下移/跳转位置	boolean	—
column-setting-key	列设置持久化键：设置后自动把列顺序 / 宽度存到 localStorage， 下次打开同 key 的表格自动恢复；同时自动显示「列设置」按钮	string	—

事件 Events

事件	说明	回调参数
@cellChange	单元格值变更	(Record)
@add	—	(Record)
@remove	—	(Array)
@columnChange	列设置面板调整列顺序 / 宽度后触发（可用于持久化）	(Array)

方法 Expose

方法（ref 调用）	说明
addRow	—
removeSelected	—
setData	—
data	—
validate	—
tableRef	—

插槽 Slots

插槽	说明	作用域参数
toolbar	—	add-row, remove-selected
[dataField]	—	name, row, column
${[dataField]}-edit	—	name, row, column