1. 应用基本信息配置

修改 .env 文件：

# 应用标题（浏览器标签页）
VITE_APP_TITLE=管理平台

# 应用简称（侧边栏顶部）
VITE_APP_SHORT_TITLE=管理平台

# 应用描述（登录页）
VITE_APP_DESCRIPTION=后台管理系统

# Logo 图标（PrimeIcons 图标名称）
# 图标参考：https://primereact.org/icons/
VITE_APP_LOGO_ICON=pi-briefcase

# 版本号
VITE_APP_VERSION=v1.0.0

# 版权所有者
VITE_APP_COPYRIGHT_OWNER=Your Company

# 开发服务器端口
VITE_PORT=7052

# API 代理目标地址
VITE_API_PROXY_TARGET=https://your-api-server.com

2. 菜单配置

修改 src/config/menu.ts：

export const menuConfig: MenuItem[] = [
  // 一级菜单（直接链接）
  {
    path: '/',
    label: '首页',
    icon: 'pi pi-home',
  },

  // 二级菜单（带子菜单）
  {
    label: '用户中心',           // 父菜单名称
    icon: 'pi pi-users',        // 父菜单图标
    // defaultOpen: true,       // 是否默认展开（可选）
    children: [                  // 子菜单数组
      {
        path: '/users',
        label: '用户管理',
        icon: 'pi pi-user',
        module: 'user',          // 模块名称（用于CrudPage）
      },
      {
        path: '/roles',
        label: '角色管理',
        icon: 'pi pi-shield',
      },
    ],
  },

  // 隐藏菜单（路由存在但不显示在侧边栏）
  {
    path: '/profile',
    label: '个人中心',
    icon: 'pi pi-user',
    hidden: true,
  },
];

MenuItem 配置项：

3. API 配置

修改 src/api/config.ts：

方式一：模块化配置（推荐）

// 配置模块基础路径，自动生成 CRUD 接口
export const API_MODULES: Record<string, ModuleApiConfig> = {
  // 用户模块
  user: {
    basePath: '/user',           // 基础路径
    listPath: '/list',           // 列表接口：GET /user/list
    addPath: '/add',             // 新增接口：POST /user/add
    updatePath: '/update',       // 修改接口：POST /user/update
    deletePath: '/delete',       // 删除接口：DELETE /user/delete/:id
    detailPath: '/detail',       // 详情接口：GET /user/detail/:id
  },

  // 自定义请求方法
  order: {
    basePath: '/order',
    listPath: '/list',
    deleteMethod: 'POST',        // 删除使用 POST 方法
  },
};

使用方式：

import { createModuleApi } from '@/api';

const userApi = createModuleApi('user');

// 获取列表
userApi.list({ page: 1, pageSize: 10 });

// 新增
userApi.add({ name: 'test', phone: '13800138000' });

// 修改
userApi.update({ id: 1, name: 'test2' });

// 删除
userApi.delete(1);

// 详情
userApi.detail(1);

方式二：自定义接口配置

export const CUSTOM_API = {
  auth: {
    login: { url: '/auth/login', method: 'POST', desc: '登录' },
    logout: { url: '/auth/logout', method: 'POST', desc: '退出' },
  },
  upload: {
    image: { url: '/upload/image', method: 'POST', desc: '上传图片' },
  },
};

4. 页面配置（CrudPage）

使用 CrudPage 组件自动生成 CRUD 页面：

<!-- src/pages/Users.svelte -->
<script lang="ts">
  import CrudPage from '@/components/CrudPage.svelte';
  import { defineModule } from '@/config/module';

  const config = defineModule({
    name: 'user',
    title: '用户管理',

    // API 配置
    api: {
      list: '/user/list',
      add: '/user/add',
      edit: '/user/update',
      delete: '/user/delete',
    },

    // 表格配置
    table: {
      rowKey: 'id',
      showSelection: true,        // 显示选择框
      showIndex: false,           // 显示序号
      actionWidth: 150,           // 操作列宽度
      columns: [
        { field: 'id', label: 'ID', width: 80 },
        { field: 'username', label: '用户名', width: 120 },
        { field: 'phone', label: '手机号', width: 130 },
        {
          field: 'status',
          label: '状态',
          width: 100,
          format: 'status',
          statusMap: {
            1: { label: '正常', color: 'success' },
            0: { label: '禁用', color: 'danger' },
          },
        },
        { field: 'createTime', label: '创建时间', width: 180 },
      ],
      actions: [
        { label: '编辑', type: 'primary' },
        { label: '删除', type: 'danger', confirm: '确定删除？' },
      ],
    },

    // 搜索配置
    search: {
      fields: [
        { field: 'username', label: '用户名', type: 'input', placeholder: '请输入' },
        { field: 'phone', label: '手机号', type: 'input' },
        {
          field: 'status',
          label: '状态',
          type: 'select',
          options: [
            { label: '全部', value: '' },
            { label: '正常', value: 1 },
            { label: '禁用', value: 0 },
          ],
        },
      ],
    },

    // 表单配置（新增/编辑）
    form: {
      width: 500,
      fields: [
        { field: 'username', label: '用户名', type: 'input', required: true },
        { field: 'phone', label: '手机号', type: 'input' },
        { field: 'email', label: '邮箱', type: 'input' },
        {
          field: 'status',
          label: '状态',
          type: 'select',
          defaultValue: 1,
          options: [
            { label: '正常', value: 1 },
            { label: '禁用', value: 0 },
          ],
        },
      ],
    },

    // 工具栏配置
    toolbar: {
      showAdd: true,
      addText: '新增用户',
      showExport: true,
      showRefresh: true,
    },
  });
</script>

<CrudPage {config} />

自动生成 CRUD 页面（核心功能）

本框架支持零代码自动生成完整的增删改查页面，只需配置菜单和模块即可。

工作原理

菜单配置 (menu.ts)  +  模块配置 (modules/xxx/config.ts)
                    ↓
              自动生成路由
                    ↓
              自动渲染 CrudPage
                    ↓
        完整的增删改查页面（列表、搜索、新增、编辑、删除）

快速添加新模块（3 步完成）

第 1 步：配置菜单

在 src/config/menu.ts 中添加菜单项，设置 module 属性：

// src/config/menu.ts
export const menuConfig: MenuItem[] = [
  // ... 其他菜单
  {
    label: '订单中心',
    icon: 'pi pi-shopping-cart',
    children: [
      {
        path: '/orders',
        label: '订单管理',
        icon: 'pi pi-list',
        module: 'order',  // 关键：指定模块名称
      },
    ],
  },
];

第 2 步：创建模块配置

创建 src/modules/order/config.ts：

// src/modules/order/config.ts
import { defineModule } from '../../config/module';
import type { ModuleConfig } from '../../config/module';

export interface Order {
  id: number;
  orderNo: string;
  customerName: string;
  amount: number;
  status: number;
  createTime: string;
}

export default defineModule<Order>({
  name: 'order',
  title: '订单管理',

  // API 接口配置
  api: {
    list: '/order/list',       // 列表接口
    add: '/order/add',         // 新增接口
    edit: '/order/update',     // 编辑接口
    delete: '/order/delete',   // 删除接口
  },

  // 表格配置
  table: {
    rowKey: 'id',
    showSelection: true,       // 显示复选框
    columns: [
      { field: 'id', label: 'ID', width: 80 },
      { field: 'orderNo', label: '订单号', minWidth: 150 },
      { field: 'customerName', label: '客户名称', minWidth: 120 },
      { field: 'amount', label: '金额', width: 100 },
      {
        field: 'status',
        label: '状态',
        width: 100,
        format: 'status',
        statusMap: {
          0: { label: '待付款', color: 'warning' },
          1: { label: '已付款', color: 'success' },
          2: { label: '已取消', color: 'danger' },
        },
      },
      { field: 'createTime', label: '创建时间', minWidth: 180 },
    ],
    actions: [
      { label: '编辑', type: 'primary', icon: 'pi pi-pencil' },
      { label: '删除', type: 'danger', icon: 'pi pi-trash', confirm: '确定删除该订单吗？' },
    ],
  },

  // 搜索表单配置
  search: {
    fields: [
      { field: 'orderNo', label: '订单号', type: 'input', placeholder: '请输入订单号' },
      { field: 'customerName', label: '客户名称', type: 'input', placeholder: '请输入客户名称' },
      {
        field: 'status',
        label: '状态',
        type: 'select',
        options: [
          { label: '待付款', value: 0 },
          { label: '已付款', value: 1 },
          { label: '已取消', value: 2 },
        ],
      },
    ],
  },

  // 新增/编辑表单配置
  form: {
    width: 500,
    fields: [
      { field: 'orderNo', label: '订单号', type: 'input', required: true },
      { field: 'customerName', label: '客户名称', type: 'input', required: true },
      { field: 'amount', label: '金额', type: 'number', required: true },
      {
        field: 'status',
        label: '状态',
        type: 'select',
        defaultValue: 0,
        options: [
          { label: '待付款', value: 0 },
          { label: '已付款', value: 1 },
          { label: '已取消', value: 2 },
        ],
      },
    ],
  },

  // 工具栏配置
  toolbar: {
    showAdd: true,
    addText: '新增订单',
    showExport: true,
    showRefresh: true,
  },
}) as ModuleConfig<Order>;

第 3 步：注册模块

在 src/modules/index.ts 中注册：

// src/modules/index.ts
import orderConfig from './order/config';

export const moduleConfigs: Record<string, ModuleConfig> = {
  // ... 其他模块
  order: orderConfig,
};

export { orderConfig };

完成！ 无需创建页面文件，无需配置路由，系统自动生成完整的增删改查页面。

自动生成的功能

配置项详解

表格列配置 (TableColumn)

{
  field: 'status',           // 字段名
  label: '状态',             // 列标题
  width: 100,                // 列宽度
  minWidth: 80,              // 最小宽度
  align: 'center',           // 对齐方式: left | center | right
  sortable: true,            // 是否可排序
  format: 'status',          // 格式化: status | datetime | date | money
  statusMap: {               // 状态映射（format 为 status 时）
    1: { label: '正常', color: 'success' },
    0: { label: '禁用', color: 'danger' },
  },
  // 自定义渲染函数（可选）
  render: (value, row) => value,
}

搜索字段配置 (SearchField)

{
  field: 'status',           // 字段名
  label: '状态',             // 标签
  type: 'select',            // 类型: input | select | date | dateRange | number
  placeholder: '请选择',     // 占位符
  options: [...],            // 选项（select 类型）
  defaultValue: '',          // 默认值
}

表单字段配置 (FormField)

{
  field: 'username',         // 字段名
  label: '用户名',           // 标签
  type: 'input',             // 类型: input | textarea | select | number | date | switch
  required: true,            // 是否必填
  placeholder: '请输入',     // 占位符
  defaultValue: '',          // 默认值
  disabled: false,           // 是否禁用
  maxLength: 50,             // 最大长度
  rows: 3,                   // 行数（textarea）
  tip: '提示信息',           // 提示文字
  options: [...],            // 选项（select 类型）
}

操作按钮配置 (ActionButton)

{
  label: '编辑',             // 按钮文字
  type: 'primary',           // 类型: primary | success | warning | danger
  icon: 'pi pi-pencil',      // 图标
  confirm: '确定删除？',     // 确认提示（有值则显示确认框）
  show: (row) => row.status === 0,  // 是否显示（函数或布尔值）
}

5. 路由配置（可选）

注意： 如果使用了 module 属性，路由会自动生成，无需手动配置。

只有自定义页面（不使用 CrudPage）才需要手动配置路由。

手动配置路由（自定义页面）：

// src/router/index.ts 的 customPages 中添加
import Dashboard from '../pages/Dashboard.svelte';
import Profile from '../pages/Profile.svelte';
import Settings from '../pages/Settings.svelte';
import YourCustomPage from '../pages/YourCustomPage.svelte';

const customPages: Record<string, any> = {
  '/': Dashboard,
  '/profile': Profile,
  '/settings': Settings,
  '/your-custom-page': YourCustomPage,  // 添加自定义页面
};

6. 权限配置

设置用户权限

import { usePermissionStore } from '@/store/usePermissionStore';

// 登录成功后设置权限
const { setPermissions } = usePermissionStore();
setPermissions([
  'user:view',
  'user:add',
  'user:edit',
  'user:delete',
  'order:view',
  // '*' 表示超级管理员
]);

权限控制组件

<script lang="ts">
  import Permission from '@/components/Permission.svelte';
</script>

<!-- 单个权限 -->
<Permission permission="user:add">
  <button>新增用户</button>
</Permission>

<!-- 多个权限（任一） -->
<Permission permission={['user:add', 'user:edit']} mode="any">
  <button>操作</button>
</Permission>

<!-- 多个权限（全部） -->
<Permission permission={['user:add', 'user:edit']} mode="all">
  <button>操作</button>
</Permission>

权限 Hook

import { usePermission } from '@/store/usePermissionStore';

const { hasPermission, hasRole } = usePermission();

if (hasPermission('user:add')) {
  // 有权限
}

7. 国际化配置

添加语言包

修改 src/locales/zh-CN.ts 和 src/locales/en-US.ts：

export default {
  common: {
    confirm: '确定',
    cancel: '取消',
    // ...
  },
  yourModule: {
    title: '你的模块',
    // ...
  },
};

使用翻译

<script lang="ts">
  import { useLocale } from '@/locales';

  const { t, locale, setLocale } = useLocale();
</script>

<!-- 获取翻译 -->
<span>{$t('common.confirm')}</span>

<!-- 带变量 -->
<span>{$t('table.total', { total: 100 })}</span>

<!-- 切换语言 -->
<button onclick={() => setLocale('en-US')}>切换到英文</button>

8. 主题配置

import { useSettingsStore } from '@/store/useSettingsStore';

const { theme, setTheme, primaryColor, setPrimaryColor } = useSettingsStore();

// 切换主题
setTheme('dark');   // 'light' | 'dark' | 'system'

// 切换主题色
setPrimaryColor('#409eff');

目录结构

src/
├── api/                    # API 配置和请求
│   ├── config.ts          # API 模块配置
│   ├── index.ts           # API 导出
│   ├── request.ts         # 请求封装
│   └── types.ts           # 类型定义
├── components/            # 通用组件
│   ├── CrudPage/         # CRUD 页面组件
│   ├── Table/            # 增强表格
│   ├── Charts/           # 图表组件
│   ├── Captcha/          # 验证码
│   ├── TagsView/         # 标签页
│   ├── Toast.tsx         # 消息提示
│   └── Modal.tsx         # 弹窗
├── config/               # 配置文件
│   ├── index.ts          # 配置导出
│   ├── menu.ts           # 菜单配置
│   └── module.ts         # 模块类型定义
├── layouts/              # 布局组件
│   ├── AdminLayout.svelte   # 管理后台布局
│   ├── Sidebar.svelte       # 侧边栏
│   └── Header.svelte        # 顶部导航
├── locales/              # 国际化
│   ├── index.ts          # 国际化配置
│   ├── zh-CN.ts          # 中文
│   └── en-US.ts          # 英文
├── pages/                # 页面组件
├── store/                # 状态管理
│   ├── useAuthStore.ts       # 认证状态
│   ├── useSettingsStore.ts   # 设置状态
│   └── usePermissionStore.ts # 权限状态
├── hooks/                # 自定义 Hooks
├── utils/                # 工具函数
├── App.tsx               # 应用入口
└── main.tsx              # 主入口

内置组件

图表组件

<script lang="ts">
  import LineChart from '@/components/Charts/LineChart.svelte';
  import BarChart from '@/components/Charts/BarChart.svelte';
  import PieChart from '@/components/Charts/PieChart.svelte';
  import ProgressBar from '@/components/Charts/ProgressBar.svelte';
  import CircleProgress from '@/components/Charts/CircleProgress.svelte';
  import StatCard from '@/components/Charts/StatCard.svelte';

  const data = [{ label: '周一', value: 100 }, { label: '周二', value: 200 }];
</script>

<!-- 折线图 -->
<LineChart {data} showArea smooth />

<!-- 柱状图 -->
<BarChart {data} showValue />

<!-- 饼图 -->
<PieChart {data} innerRadius={0.6} showLegend />

<!-- 进度条 -->
<ProgressBar value={75} color="#409eff" />

<!-- 环形进度 -->
<CircleProgress value={75} size={100} />

<!-- 统计卡片 -->
<StatCard
  title="用户数"
  value="1,234"
  icon="pi-users"
  trend={{ value: 12, isUp: true }}
/>

消息提示

<script lang="ts">
  import { toast } from '@/components/Toast';

  function handleSuccess() {
    toast.success('操作成功');
  }

  function handleError() {
    toast.error('操作失败');
  }

  function handleWarning() {
    toast.warning('警告信息');
  }

  function handleInfo() {
    toast.info('提示信息');
  }
</script>

确认弹窗

<script lang="ts">
  import { confirm } from '@/components/Modal';

  async function handleDelete() {
    const confirmed = await confirm({
      title: '删除确认',
      content: '确定要删除吗？',
      type: 'warning',
    });

    if (confirmed) {
      // 执行删除
    }
  }
</script>

1. 修改 .env 文件（应用名称、Logo、API地址）
2. 修改 src/config/menu.ts（菜单配置）
3. 修改 src/api/config.ts（API配置）
4. 创建页面组件（使用 CrudPage 或自定义）
5. 添加路由（src/App.tsx）
6. 修改国际化文件（如需要）
7. 配置权限（如需要）