# 页面视图开发

<!-- 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` | 编辑弹窗 | n-dialog + n-form，懒加载 |
| `detail.vue` | 详情弹窗 | n-dialog 展示详情，懒加载 |
| `columns.ts` | 表格列定义 | 定义列 key、title、render 函数等 |
| `querySchemas.ts` | 搜索表单定义 | FormSchema 数组，定义搜索字段 |

## index.vue 列表页

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

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

    <!-- 数据表格卡片 -->
    <n-card :bordered="false" class="proCard">
      <BasicTable
        :columns="columns"
        :request="loadDataTable"
        :row-key="(row) => row.id"
        ref="basicTableRef"
        :actionColumn="actionColumn"
        @update:checked-row-keys="onCheckedRow"
        :auto-scroll-x="true"
      >
        <!-- 表格顶部工具栏 -->
        <template #tableTitle>
          <n-space>
            <!-- 新增按钮 -->
            <n-button type="primary" @click="handleAdd" v-perm="['sys:example:add']">
              <template #icon>
                <n-icon>
                  <PlusOutlined />
                </n-icon>
              </template>
              添加案例
            </n-button>

            <!-- 批量删除按钮 -->
            <n-button
              type="error"
              @click="handleDelete()"
              :disabled="!rowKeys.length"
              v-perm="['sys:example:batchDelete']"
            >
              <template #icon>
                <n-icon>
                  <DeleteOutlined />
                </n-icon>
              </template>
              批量删除
            </n-button>
          </n-space>
        </template>
      </BasicTable>
    </n-card>

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

<script lang="ts" setup>
  import { h, nextTick, reactive, ref } from 'vue';
  import { useMessage, useDialog } from 'naive-ui';
  import { PlusOutlined, DeleteOutlined, EditOutlined, EyeOutlined } from '@vicons/antd';
  import { TableAction } from '@/components/Table';
  import { BasicForm, useForm } from '@/components/Form/index';
  import { getExamplePage, exampleDelete, exampleBatchDelete } from '@/api/tool/example';
  import { renderIcon } from '@/utils';

  import { columns } from './columns';
  import { schemas } from './querySchemas';

  // 动态导入编辑对话框组件
  import editDialog from './edit.vue';
  // 动态导入详情对话框组件
  import detailDialog from './detail.vue';

  // 消息提示和对话框
  const message = useMessage();
  const dialog = useDialog();

  // 表格引用
  const basicTableRef = ref();
  const editModalRef = ref();
  const detailModalRef = ref();

  // 响应式状态定义
  const currentId = ref(0); // 当前操作的ID
  const editVisible = ref(false); // 编辑对话框显示状态
  const detailVisible = ref(false); // 详情对话框显示状态
  const rowKeys = ref([]); // 表格选中行Key

  /**
   * 定义查询参数
   * 用于存储搜索表单的值
   */
  const formParams = reactive({
    name: '',
    type: '',
    status: '',
  });

  /**
   * 定义操作栏配置
   * 包含编辑、详情和删除按钮
   */
  const actionColumn = reactive({
    width: 280,
    title: '操作',
    align: 'center',
    key: 'action',
    fixed: 'right',
    render(record) {
      return h(TableAction as any, {
        style: 'button',
        actions: [
          {
            label: '编辑',
            icon: renderIcon(EditOutlined),
            type: 'info',
            onClick: handleEdit.bind(null, record),
            auth: ['sys:example:update'],
          },
          {
            label: '详情',
            icon: renderIcon(EyeOutlined),
            type: 'default',
            onClick: handleDetail.bind(null, record),
            auth: ['sys:example:detail'],
          },
          {
            label: '删除',
            icon: renderIcon(DeleteOutlined),
            type: 'error',
            onClick: handleDelete.bind(null, record),
            auth: ['sys:example:delete'],
          },
        ],
      });
    },
  });

  /**
   * 加载数据列表
   * @param params 分页参数
   * @returns 表格数据
   */
  const loadDataTable = async (params: any) => {
    // 清空选中行
    rowKeys.value = [];
    const result = await getExamplePage({ ...formParams, ...params });
    return result;
  };

  /**
   * 刷新表格数据
   * @param noRefresh 是否重置页码
   */
  function reloadTable(noRefresh = '') {
    basicTableRef.value.reload(noRefresh ? {} : { pageNo: 1 });
  }

  /**
   * 注册搜索表单
   * 配置表单布局和字段
   */
  const [register, {}] = useForm({
    gridProps: { cols: '1 s:1 m:2 l:3 xl:4 2xl:4' },
    labelWidth: 80,
    schemas,
  });

  /**
   * 提交搜索表单
   * @param values 表单值
   */
  function handleSubmit(values: Recordable) {
    for (const key in formParams) {
      formParams[key] = '';
    }
    for (const key in values) {
      formParams[key] = values[key];
    }
    reloadTable();
  }

  /**
   * 重置搜索表单
   */
  function handleReset(values: Recordable) {
    for (const key in formParams) {
      formParams[key] = '';
    }
    for (const key in values) {
      formParams[key] = values[key];
    }
    reloadTable();
  }

  /**
   * 表格选择项变化时的回调
   * @param keys 选中的key数组
   */
  function onCheckedRow(keys: (string | number)[]) {
    rowKeys.value = keys;
  }

  /**
   * 处理新增按钮点击
   */
  const handleAdd = async () => {
    currentId.value = 0;
    editVisible.value = true;
    await nextTick();
    editModalRef.value?.openModal();
  };

  /**
   * 处理编辑按钮点击
   * @param record 当前行数据
   */
  const handleEdit = async (record: Recordable) => {
    currentId.value = record.id;
    editVisible.value = true;
    await nextTick();
    editModalRef.value?.openModal();
  };

  /**
   * 处理详情按钮点击
   * @param record 当前行数据
   */
  const handleDetail = async (record: Recordable) => {
    currentId.value = record.id;
    detailVisible.value = true;
    await nextTick();
    detailModalRef.value?.openModal();
  };

  /**
   * 处理删除操作
   * @param record 当前行数据（可选，不传时表示批量删除）
   */
  async function handleDelete(record?: Recordable) {
    let ids = [];
    if (!record) {
      // 批量删除：获取选中行的ID
      ids = rowKeys.value;
      if (!ids.length) {
        message.warning('请选择要删除的数据');
        return;
      }
    }

    dialog.warning({
      title: '提示',
      content: '确定要删除选中的案例吗？',
      positiveText: '确定',
      negativeText: '取消',
      onPositiveClick: async () => {
        try {
          record ? await exampleDelete(record.id) : await exampleBatchDelete(ids);
          message.success('删除成功');
          reloadTable();
        } catch (error) {
          message.error('删除失败');
        }
      },
    });
  }
</script>
```

## columns.ts

```typescript
import { h } from 'vue';
import { NTag, NAvatar, NImage } from 'naive-ui';

/**
 * 表格列配置
 * 定义表格显示的列
 */
export const columns = [
  {
    type: 'selection', // 多选框列
    width: 50,
    fixed: 'left',
  },
  {
    title: 'ID',
    key: 'id',
    fixed: 'left',
    width: 50,
  },
  {
    title: '案例名称',
    key: 'name',
    width: 150,
    // 普通文本渲染（无需额外配置）
    ellipsis: {
      tooltip: true,
    },
  },
  {
    title: '案例图片',
    key: 'avatar',
    width: 150,
    // 图片渲染
    render(record) {
      return record.avatar
        ? h(NAvatar, {
            src: record.avatar,
            size: 48,
            shape: 'square',
            fit: 'cover',
            style: {
              borderRadius: '4px',
            },
          })
        : h('span', '-');
    },
  },
  {
    title: '案例类型',
    key: 'type',
    width: 100,
    // 选项标签渲染
    render(record) {
      const statusMap = {
        1: { text: '类型1', type: 'success' },
        2: { text: '类型2', type: 'error' },
        3: { text: '类型3', type: 'warning' },
        4: { text: '类型4', type: 'info' },
      };
      const status = statusMap[record.type];
      return h(
        NTag,
        {
          bordered: false,
          type: status?.type || 'info',
        },
        {
          default: () => status?.text || record.type,
        },
      );
    },
  },
  {
    title: '案例状态',
    key: 'status',
    width: 100,
    // 选项标签渲染
    render(record) {
      const statusMap = {
        1: { text: '正常', type: 'success' },
        2: { text: '禁用', type: 'error' },
      };
      const status = statusMap[record.status];
      return h(
        NTag,
        {
          bordered: false,
          type: status?.type || 'info',
        },
        {
          default: () => status?.text || record.status,
        },
      );
    },
  },
  {
    title: '排序',
    key: 'sort',
    width: 100,
    // 普通文本渲染（无需额外配置）
    ellipsis: {
      tooltip: true,
    },
  },
  {
    title: '创建人',
    key: 'createUser',
    width: 100,
  },
  {
    title: '创建时间',
    key: 'createTime',
    width: 180,
  },
];
```

## querySchemas.ts

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

/**
 * 查询表单配置
 * 定义搜索区域的表单项
 */
export const schemas: FormSchema[] = [
  {
    field: 'name',
    component: 'NInput',
    label: '案例名称',
    componentProps: {
      placeholder: '请输入案例名称',
      clearable: true,
      filterable: false,
    },
  },
  {
    field: 'type',
    component: 'NSelect',
    label: '案例类型',
    componentProps: {
      placeholder: '请输入案例类型',
      clearable: true,
      filterable: true,
      options: [
        {
          label: '类型1',
          value: 1,
        },
        {
          label: '类型2',
          value: 2,
        },
        {
          label: '类型3',
          value: 3,
        },
        {
          label: '类型4',
          value: 4,
        },
      ],
    },
  },
  {
    field: 'status',
    component: 'NSelect',
    label: '案例状态',
    componentProps: {
      placeholder: '请输入案例状态',
      clearable: true,
      filterable: 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 加载详情 → 修改 → 提交
用户删除 → dialog.warning → 确认 → API → reloadTable
```

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

## 总结

页面视图遵循 `index.vue` + `edit.vue` + `detail.vue` + `columns.ts` + `querySchemas.ts` 标准模式。列表页使用 `BasicForm` 搜索 + `BasicTable` 展示数据 + `TableAction` 操作按钮，编辑弹窗使用 `import` 直接导入 + `useLockFn` 防重复提交。消息提示使用 NaiveUI 的 `useMessage()`，确认对话框使用 `useDialog()`。