01-说明文档.md 6.7 KB

说明文档

一、业务项目目录

从 mode 模板复制一份就是业务项目,结构如下。★ 是日常要动的目录。

业务项目/
├─ index.html                    # 只改了 title 注入,一般不动
├─ vite.config.js                # 端口、代理、别名、dedupe(见 05-工具配置文档)
├─ .env / .env.development / .env.production
├─ src/
│  ├─ main.js                    # 入口:注册基座 + 页面 glob,不动
│  ├─ App.vue                    # 根组件,不动
│  ├─ assets/main.less           # 全局样式变量,可按需加
│  ├─ config/
│  │  ├─ web-config.js           # 运行时可改的配置(会被打进 config.json)
│  │  └─ app-config.js           # 构建期配置:覆盖登录页/首页、静态路由、语言包
│  ├─ router/page-entries.js     # 老项目兼容用的页面登记表,新项目留空
│  ├─ locales/components/i18n.js # 公共词条(按钮名等),靠基座 components 命名空间兜底
│  ├─ api/                       ★ 接口层,按后端模块建文件
│  └─ views/                     ★ 页面层
│     └─ <模块>/<页面>/index.vue
└─ refresh-mode.ps1 / refresh-build.ps1   # 基座更新后重新拉依赖再起服务

二、页面怎么被路由到

启动链路:main.js 用 import.meta.glob('@/views/**/*.vue') 收集所有页面 → 交给基座 → 基座按后端菜单的 hrefs 去匹配页面文件。

匹配规则:把菜单的 hrefs 和 glob 出来的 key 一起转小写,找包含 /<hrefs>/index.vue 的那一项。

菜单 hrefs 页面必须放的路径
position src/views/任意模块/position/index.vue
basicData/position src/views/basicData/position/index.vue
system/user src/views/system/user/index.vue

要点:

  • 只有 index.vue 参与匹配。同目录下的 form.vue、view.vue、components/*.vue 由 index.vue 自己 import,不要指望被路由到。
  • 后端只给一段(如 position)时,任意模块下叫 position 的目录都能命中;给全路径时目录层级必须一致。
  • 大小写不敏感,但建议目录名和 hrefs 完全一致。

不依赖后端菜单的固定页面

在 src/config/app-config.js 的 staticRoutes 里配:

export default {
  staticRoutes: [
    {
      path: '/developmentProcess',
      name: 'developmentProcess',
      layout: false, // false = 不带侧边栏和头部,独立整页
      component: () => import('@/views/static/page/DevelopmentProcess.vue'),
      meta: { title: '开发流程', public: true, hidden: true }
    }
  ]
}

public: true 免登录,hidden: true 不进侧边菜单。

三、页面文件怎么组织

一个业务模块推荐这样放:

src/views/<模块>/<页面>/
├─ index.vue        # 列表页,被路由到
├─ form.vue         # 弹窗表单 / 新增编辑页,index.vue import
├─ view.vue         # 详情页
├─ components/      # 本页面私有子组件
└─ i18n.js          # 本模块词条(可选)

页面上的 name 用 defineOptions({ name: 'XxxList' }) 显式声明,方便 keep-alive 和调试。

四、国际化

基座按目录自动分配命名空间:views/<模块>/i18n.js → 命名空间 <模块>。

// src/views/position/i18n.js
export default {
  岗位名称: 'Position Name',
  请输入岗位名称: 'Please enter position name'
}

页面里二选一:

// 写法一:setup 里拿到 $l(推荐,模板和脚本都能用)
const { $l } = window.useI18n('position')
<!-- 写法二:模板里直接用全局 $l,命名空间按当前页面目录自动推断 -->
<a-button>{{ $l('添加') }}</a-button>

规则:

  • 词条 key 就是中文原文,值是对应英文。没配英文时英文环境会显示中文,不会空白。
  • 按钮、通用提示(添加/删除/保存/操作成功)基座已内置,不用自己配。
  • $l('中文') 里的中文必须是字面量,不要拼变量,否则切语言不生效。

五、按钮级权限

后端返回的 button_code 与指令值整体相等才通过。

<!-- 无权限时元素被移出 DOM -->
<a-button v-action="'add'">添加</a-button>
<span v-action="'edit'"><a @click="edit(record)">修改</a></span>
// 或/且这类指令表达不了的场景,用函数
const canEdit = window.$utils.hasAction('edit') || window.$utils.hasAction('add')

列表工具栏按钮也会自动挂 v-action,key 就是按钮编码(add / remove / import / export)。

六、全局方法与工具

组件内用 this.$xxx,<script setup> 里用 window.$xxx。

方法 用途
$l(中文) 国际化
$message.success / warn / error / info 顶部轻提示
$notice.success({ message, description }) 右上角通知(带标题和描述)
$modal.confirm({ title, content, onOk }) 二次确认弹窗
$confirm({...}) 同 $modal.confirm
$push(path, query) 站内跳转(location.href,自动拼 VITE_APP_BASE_URL)
$open(path, query) 新标签页打开
$utils.http 请求实例(见 05-工具配置文档)
$utils.env 当前环境变量对象
$utils.hasAction(code) 按钮权限判断
$utils.uuid() 生成 uuid
$utils.isFunction / isArray / isString 类型判断
$utils.ls.get / set localStorage 封装
$icons 全部 antd 图标,$icons.PlusOutlined
window.useI18n(ns) 取当前命名空间的 $l

图标除了 $icons,也可以直接从 @ant-design/icons-vue 引入,基座已带该依赖:

import { PlusOutlined, CheckOutlined } from '@ant-design/icons-vue'

七、页面骨架怎么选

场景 骨架 说明
标准业务列表(标题 + 按钮 + 查询 + 表格 + 分页) s-list-layout 高度自适应,表格铺满剩余空间,一行代码不用写样式
列表里带左侧组织树 s-list-layout + #tree 插槽 插槽给了左侧树和拖拽分隔条
卡片列表 s-list-card-layout 同类 API,把表格换成卡片,用 #default 渲染卡片内容
弹窗里新增/编辑 s-modal + s-form 宽度默认 60vw,可全屏、可拖拽
独立的整页表单 s-form-layout + s-form 自带标题栏、底部保存/取消按钮、右侧锚点
抽屉里编辑 s-drawer + s-form 适合简单的单列表单
详情展示 s-form-layout + s-form(:disabled 全禁用)或 s-panel-layout —
嵌在标签页里的列表 s-filter-table-toolbar 无标题条,查询区 + 表格