# 页面视图开发

<!-- Copyright (c) 2021-2026 小蚂蚁云团队 版权所有 -->

:::tip 说明
页面视图位于 `src/views/` 目录，每个业务模块遵循 `index.vue`（列表页）+ `edit.vue`（编辑弹窗）+ `detail.vue`（详情弹窗）的标准模式，辅以 `columns.ts`（列定义）和 `querySchemas.ts`（搜索表单）配置文件。
:::

## 目录结构

```
src/views/
├── tool/
│ ├── example/
│ │ ├── index.vue       # 案例列表页
│ │ ├── edit.vue        # 案例编辑弹窗
│ │ ├── detail.vue      # 案例详情弹窗
│ │ ├── columns.ts      # 表格列定义
│ │ └── querySchemas.ts # 搜索表单定义
│ └── ...
└── ...
```

## 文件职责

| 文件 | 职责 | 说明 |
|------|------|------|
| `index.vue` | 列表页 | 搜索表单 + 工具栏 + BasicTable + 编辑弹窗引用 |
| `edit.vue` | 编辑弹窗 | a-modal + a-form，懒加载 |
| `detail.vue` | 详情弹窗 | a-modal 展示详情，懒加载 |
| `columns.ts` | 表格列定义 | 定列 dataIndex、title、customRender 函数等 |
| `querySchemas.ts` | 搜索表单定义 | FormSchema 数组，定义搜索字段 |

## index.vue 列表页

以案例管理为例，完整结构如下：

```vue
<template>
  <PageWrapper>
    <!-- 搜索表单卡片 -->
    <a-card :bordered="false" class="pt-3 mb-3 proCard">
      <BasicForm @register="register" @submit="handleSubmit" @reset="handleReset" />
    </a-card>

    <!-- 数据表格卡片 -->
    <a-card :bordered="false" class="proCard">
      <BasicTable
        :columns="columns"
        :request="loadDataTable"
        :row-key="(row) => row.id"
        ref="tableRef"
        :row-selection="{ onChange: onSelectionChange }"
        scroll-x="1200"
      >
        <template #tableTitle>
          <a-space>
            <a-button type="primary" @click="handleAdd" v-perm="['sys:example:add']">
              <template #icon><PlusOutlined /></template>
              添加案例
            </a-button>
            <a-button type="danger" @click="handleDelete()" :disabled="!selectionData.length" v-perm="['sys:example:batchDelete']">
              <template #icon><DeleteOutlined /></template>
              批量删除
            </a-button>
          </a-space>
        </template>
        <template #bodyCell="{ column, record }">
          <template v-if="column.key === 'action'">
            <a-space>
              <a-button type="primary" @click="handleEdit(record)" v-perm="['sys:example:update']">
                <template #icon><EditOutlined /></template>
                编辑
              </a-button>
              <a-button type="primary" @click="handleDetail(record)" v-perm="['sys:example:detail']">
                <template #icon><EyeOutlined /></template>
                详情
              </a-button>
              <a-button type="primary" danger @click="handleDelete(record)" v-perm="['sys:example:delete']">
                <template #icon><DeleteOutlined /></template>
                删除
              </a-button>
            </a-space>
          </template>
        </template>
      </BasicTable>
    </a-card>

    <!-- 编辑对话框组件 -->
    <editDialog v-if="editVisible" :id="currentId" v-model:visible="editVisible" @success="reloadTable('noRefresh')" />
    <!-- 查看详情对话框组件 -->
    <detailDialog v-if="detailVisible" :id="currentId" v-model:visible="detailVisible" @success="reloadTable('noRefresh')" />
  </PageWrapper>
</template>

<script lang="ts" setup>
  import { reactive, ref, nextTick, defineAsyncComponent } from 'vue';
  import { PlusOutlined, EditOutlined, DeleteOutlined, EyeOutlined } from '@ant-design/icons-vue';
  import { schemas } from './querySchemas';
  import { useForm } from '@/components/Form/index';
  import { getExamplePage, exampleDelete, exampleBatchDelete } from '@/api/tool/example';
  import { columns } from './columns';
  import { message, Modal } from 'ant-design-vue';

  const editDialog = defineAsyncComponent(() => import('./edit.vue'));
  const detailDialog = defineAsyncComponent(() => import('./detail.vue'));

  const currentId = ref(0);
  const editVisible = ref(false);
  const detailVisible = ref(false);
  const selectionData = ref([]);
  const tableRef = ref();

  const formParams = reactive({ name: '', type: '', status: '' });

  const loadDataTable = async (params: any) => {
    const result = await getExamplePage({ ...formParams, ...params });
    return result;
  };

  function reloadTable(noRefresh = '') {
    tableRef.value.reload(noRefresh ? {} : { pageNo: 1 });
  }

  const [register, {}] = useForm({
    rowProps: { gutter: [16, 0] },
    colProps: {
      xs: 24,
      sm: 24,
      md: 12,
      lg: 8,
      xl: 6,
    },
    labelCol: { span: 6, offset: 0 },
    schemas,
  });

  function handleSubmit(values: Recordable) {
    handleReset();
    for (const key in values) { formParams[key] = values[key]; }
    reloadTable();
  }

  function handleReset() {
    for (const key in formParams) { formParams[key] = ''; }
  }

  const handleAdd = async () => { currentId.value = 0; await nextTick(); editVisible.value = true; };
  const handleEdit = async (record: Recordable) => { currentId.value = record.id; await nextTick(); editVisible.value = true; };
  const handleDetail = async (record: Recordable) => { currentId.value = record.id; await nextTick(); detailVisible.value = true; };

  async function handleDelete(record: Recordable) {
    let ids = [];
    if (!record) {
      ids = selectionData.value.map(({ id }) => id);
      if (!ids.length) { message.warning('请选择要删除的数据'); return; }
    }
    Modal.confirm({
      title: '提示',
      content: '确定要删除选中的案例吗？',
      onOk: async () => {
        record ? await exampleDelete(record.id) : await exampleBatchDelete(ids);
        message.success('删除成功');
        reloadTable();
      },
    });
  }

  function onSelectionChange(selectedRowKeys, selectedRows) { selectionData.value = selectedRows; }
</script>
```

## columns.ts

```typescript
import { h } from 'vue';
import { Tag, Image } from 'ant-design-vue';

export const columns = [
  {
    title: 'ID',
    dataIndex: 'id',
    fixed: 'left',
    width: 50,
  },
  {
    title: '案例名称',
    dataIndex: 'name',
    width: 150,
  },
  {
    title: '案例图片',
    dataIndex: 'avatar',
    width: 150,
    customRender({ record }) {
      return record.avatar
        ? h(Image, { src: record.avatar, width: 48, height: 48, fit: 'cover', preview: true })
        : h('span', '-');
    },
  },
  {
    title: '案例类型',
    dataIndex: 'type',
    width: 100,
    customRender({ record }) {
      const statusMap = { 1: { text: '类型1', color: 'success' }, 2: { text: '类型2', color: 'error' }, 3: { text: '类型3', color: 'warning' }, 4: { text: '类型4', color: 'default' } };
      const status = statusMap[record.type];
      return h(Tag, { color: status?.color || 'default' }, { default: () => status?.text || record.type });
    },
  },
  {
    title: '案例状态',
    dataIndex: 'status',
    width: 100,
    customRender({ record }) {
      const statusMap = { 1: { text: '正常', color: 'success' }, 2: { text: '禁用', color: 'error' } };
      const status = statusMap[record.status];
      return h(Tag, { color: status?.color || 'default' }, { default: () => status?.text || record.status });
    },
  },
  {
    title: '排序',
    dataIndex: 'sort',
    width: 100,
  },
  {
    title: '创建人',
    dataIndex: 'createUser',
    width: 100,
  },
  {
    title: '创建时间',
    dataIndex: 'createTime',
    width: 180,
  },
  {
    title: '操作',
    fixed: 'right',
    dataIndex: 'action',
    key: 'action',
    width: 200,
  },
];
```

## querySchemas.ts

```typescript
import { FormSchema } from '@/components/Form/index';

export const schemas: FormSchema[] = [
  {
    name: 'name',
    component: 'Input',
    label: '案例名称',
    componentProps: { placeholder: '请输入案例名称', clearable: true, allowClear: true },
  },
  {
    name: 'type',
    component: 'Select',
    label: '案例类型',
    componentProps: {
      placeholder: '请输入案例类型',
      clearable: true,
      allowClear: true,
      options: [
        { label: '类型1', value: 1 },
        { label: '类型2', value: 2 },
        { label: '类型3', value: 3 },
        { label: '类型4', value: 4 },
      ],
    },
  },
  {
    name: 'status',
    component: 'Select',
    label: '案例状态',
    componentProps: {
      placeholder: '请输入案例状态',
      clearable: true,
      allowClear: true,
      options: [
        { label: '正常', value: 1 },
        { label: '禁用', value: 2 },
      ],
    },
  },
];
```

## 数据流

```
页面加载 → BasicForm 注册 → BasicTable request 触发 → loadDataTable → API → 渲染表格
用户搜索 → handleSubmit → 更新 formParams → reloadTable → 重新请求
用户新增 → handleAdd → currentId=0 → editVisible=true → edit.vue 加载 → 表单填写 → 提交
用户编辑 → handleEdit → currentId=id → editVisible=true → edit.vue 加载详情 → 修改 → 提交
用户删除 → Modal.confirm → API → reloadTable
```

:::tip 温馨提示
`columns.ts` 和 `querySchemas.ts` 独立为配置文件，便于维护和复用。`columns` 中的 `customRender` 函数使用 Vue 的 `h()` 创建虚拟 DOM，可实现任意复杂的自定义渲染。`querySchemas` 中的 `options` 硬编码或通过字典 API 动态获取。
:::

## 总结

页面视图遵循 `index.vue` + `edit.vue` + `detail.vue` + `columns.ts` + `querySchemas.ts` 标准模式。列表页使用 `BasicForm` 搜索 + `BasicTable` 展示数据 + `bodyCell` 插槽操作按钮，编辑弹窗使用 `defineAsyncComponent` 懒加载 + `useLockFn` 防重复提交。