Files
aibridge/docs/codedev/02-frontend-pattern.md
2026-05-18 09:28:15 +08:00

9.3 KiB
Raw Permalink Blame History

前端扩展开发模式

基于 views/extend 示例的 Vue 3 + TypeScript 前端开发指南 源码分析时间:2026-04-01


一、前端目录结构

web/apps/jnpf-web-apps-main/src/
├── views/extend/              # 扩展示例
│   ├── barCode/              # 条形码
│   ├── importAndExport/       # 导入导出 ★
│   ├── tableDemo/            # 表格示例 ★
│   └── ...
└── api/extend/              # API 接口定义
    ├── employee.ts
    ├── table.ts
    └── ...

二、API 接口定义

2.1 API 文件模板

// #/api/extend/xxx.ts
import { defHttp } from '#/api/request';

enum Api {
  Prefix = '/api/extend/Xxx',  // 后端接口路径
}

// 获取列表
export function getXxxList(data) {
  return defHttp.get({ url: Api.Prefix, data });
}

// 获取详情
export function getInfo(id) {
  return defHttp.get({ url: `${Api.Prefix}/${id}` });
}

// 创建
export function createXxx(data) {
  return defHttp.post({ url: Api.Prefix, data });
}

// 更新
export function updateXxx(data: { id }) {
  return defHttp.put({ url: `${Api.Prefix}/${data.id}`, data });
}

// 删除
export function delXxx(id) {
  return defHttp.delete({ url: `${Api.Prefix}/${id}` });
}

// 导出Excel
export function exportExcel(data) {
  return defHttp.get({ url: `${Api.Prefix}/ExportData`, data });
}

// 导入预览
export function importPreview(data) {
  return defHttp.get({ url: `${Api.Prefix}/ImportPreview`, data });
}

// 导入数据
export function importData(data) {
  return defHttp.post({ url: `${Api.Prefix}/ImportData`, data });
}

2.2 HTTP 方法对应

操作 前端方法 后端注解
获取列表 defHttp.get({ url: Prefix, data }) @GetMapping
获取详情 defHttp.get({ url: ${Prefix}/${id} }) @GetMapping("/{id}")
创建 defHttp.post({ url: Prefix, data }) @PostMapping
更新 defHttp.put({ url: ${Prefix}/${id}, data }) @PutMapping("/{id}")
删除 defHttp.delete({ url: ${Prefix}/${id} }) @DeleteMapping("/{id}")

三、Vue 组件模式

3.1 基础列表页面(使用 useVxeTable)

<script lang="ts" setup>
import type { BasicColumn } from '@jnpf/ui/vxeTable';
import { useMessage } from '@jnpf/hooks';
import { BasicVxeTable, useVxeTable } from '@jnpf/ui/vxeTable';
import { getXxxList, delXxx } from '#/api/extend/xxx';

defineOptions({ name: 'ExtendXxxDemo' });

const { createMessage, createConfirm } = useMessage();

// 列表列定义
const columns: BasicColumn[] = [
  { title: '字段1', dataIndex: 'field1', width: 120 },
  { title: '字段2', dataIndex: 'field2', width: 120 },
  { title: '创建时间', dataIndex: 'creatorTime', width: 150, format: 'date|YYYY-MM-DD' },
];

// 使用 useVxeTable
const [registerTable, { reload, getSelectRows }] = useVxeTable({
  api: getXxxList,           // 数据接口
  columns,                    // 列定义
  useSearchForm: true,        // 启用搜索表单
  formConfig: {               // 搜索表单配置
    schemas: [
      {
        field: 'keyword',
        label: '关键词',
        component: 'Input',
        componentProps: { placeholder: '请输入' }
      }
    ]
  },
  rowSelection: { type: 'checkbox' },  // 多选
});

// 操作按钮
function getTableActions(record): ActionItem[] {
  return [
    { label: '编辑', onClick: handleEdit.bind(null, record) },
    { label: '删除', color: 'error', modelConfirm: { onOk: handleDel.bind(null, record.id) } }
  ];
}

// 编辑
function handleEdit(record) {
  // 打开编辑弹窗
}

// 删除
function handleDel(id) {
  delXxx(id).then(res => {
    createMessage.success(res.msg);
    reload();
  });
}
</script>

<template>
  <BasicVxeTable @register="registerTable">
    <template #tableTitle>
      <a-button type="primary" @click="handleAdd">新增</a-button>
    </template>
    <template #action="{ record }">
      <TableAction :actions="getTableActions(record)" />
    </template>
  </BasicVxeTable>
</template>

3.2 搜索表单配置

function getFormConfig(): Partial<FormProps> {
  return {
    schemas: [
      {
        field: 'field1',
        label: '字段1',
        component: 'Input',
        componentProps: { placeholder: '请输入' }
      },
      {
        field: 'field2',
        label: '字段2',
        component: 'Select',
        componentProps: {
          placeholder: '请选择',
          options: [
            { id: 1, fullName: '选项1' },
            { id: 2, fullName: '选项2' }
          ]
        }
      }
    ]
  };
}

3.3 列配置

const columns: BasicColumn[] = [
  { title: '序号', dataIndex: 'index', width: 60, customRender: ({ index }) => index + 1 },
  { title: '编码', dataIndex: 'code', width: 150, fixed: 'left' },
  { title: '名称', dataIndex: 'name', minWidth: 150 },
  { title: '金额', dataIndex: 'amount', width: 120, format: 'money' },
  { title: '日期', dataIndex: 'date', width: 120, format: 'date|YYYY-MM-DD' },
  { title: '状态', dataIndex: 'status', width: 80, slots: { default: 'status' } },
  { title: '操作', dataIndex: 'action', width: 150, fixed: 'right' },
];

3.4 弹窗表单

<script lang="ts" setup>
import { useModal } from '@jnpf/ui/modal';
import { BasicModal } from '@jnpf/ui/modal';

const [registerModal, { openModal, closeModal }] = useModal();

// 打开弹窗
function handleAdd() {
  openModal(true, { id: null });
}

// 提交
function handleSubmit() {
  const data = { /* 表单数据 */ };
  createXxx(data).then(res => {
    createMessage.success(res.msg);
    closeModal();
    emit('reload');
  });
}
</script>

<template>
  <BasicModal @register="registerModal" title="标题" @ok="handleSubmit">
    <!-- 表单内容 -->
  </BasicModal>
</template>

四、useVxeTable 钩子

4.1 核心方法

const [registerTable, {
  reload,              // 刷新数据
  setColumns,          // 设置列
  getSelectRows,      // 获取选中行
  clearSelectedRowKeys, // 清空选择
  getFetchParams,     // 获取查询参数
}] = useVxeTable(options);

4.2 常用配置

const options = {
  api: getList,                 // 数据接口(必填)
  columns,                      // 列定义(必填)
  useSearchForm: true,          // 是否显示搜索表单
  formConfig,                   // 搜索表单配置
  rowSelection: { type: 'checkbox' },  // 行选择
  pagination: { pageSize: 20 }, // 分页配置
  afterFetch: (data) => {       // 数据处理钩子
    return data.map(item => ({
      ...item,
      // 处理数据
    }));
  },
};

五、主子表模式(参考 saleOrder)

<script lang="ts" setup>
// 主表
const [registerTable, { reload, getSelectRows }] = useVxeTable({
  api: getOrderList,
  columns: mainColumns,
  rowClick: ({ record }) => {
    // 点击主表行加载子表数据
    state.activeId = record.id;
    getProductEntry(record.id).then(res => {
      state.productList = res.data.list;
    });
  }
});

// 子表
const [registerProductTable] = useVxeTable({
  columns: productColumns,
  useSearchForm: false,
  pagination: false,
});
</script>

<template>
  <div class="h-full">
    <!-- 主表 -->
    <BasicVxeTable @register="registerTable" />
    <!-- 子表 -->
    <div class="footer">
      <BasicVxeTable @register="registerProductTable" :data-source="productList" />
    </div>
  </div>
</template>

六、导入导出模式(参考 importAndExport)

6.1 导出组件

<script lang="ts" setup>
import { useModal } from '@jnpf/ui/modal';
import { exportExcel } from '#/api/extend/xxx';
import { downloadByUrl } from '@jnpf/utils';

const [registerModal, { openModal }] = useModal();

function handleExport() {
  openModal(true, { listQuery: getFetchParams() });
}

function handleSubmit() {
  const query = {
    ...listQuery.value,
    selectKey: checkedList.value.join(','),
  };
  exportExcel(query).then(res => {
    downloadByUrl({ url: res.data.url });
    closeModal();
  });
}
</script>

6.2 导入组件

<script lang="ts" setup>
import { importData, importPreview } from '#/api/extend/xxx';

function handleFileChange({ file }) {
  if (file.response?.code === 200) {
    state.fileName = file.response.data.name;
  }
}

function handlePreview() {
  importPreview({ fileName: state.fileName }).then(res => {
    state.list = res.data.dataRow || [];
  });
}

function handleImport() {
  importData({ list: state.list }).then(res => {
    // 处理结果
  });
}
</script>

七、常用组件

组件 引入 用途
BasicVxeTable @jnpf/ui/vxeTable 高级表格
useVxeTable @jnpf/ui/vxeTable 表格状态管理
TableAction @jnpf/ui/vxeTable 表格操作按钮
BasicModal @jnpf/ui/modal 弹窗
useModal @jnpf/ui/modal 弹窗状态管理
useMessage @jnpf/hooks 消息提示
usePopup @jnpf/ui/popup 弹出页面
downloadByUrl @jnpf/utils 文件下载

八、关键配置

配置 说明
API 路径前缀 /api/extend/Xxx
组件 name ExtendXxxDemo
表格列配置 BasicColumn[]
搜索表单 formConfig.schemas
操作按钮 getTableActions()