后台界面开发
校对日期:2026-11-16。适用于社区版及全部商业版。
后端接口写好之后,要让功能出现在后台(控制台)里,需要在 ujcms-ui-console 中写接口函数、列表页和表单,再登记路由、菜单文字和权限。 本文接着后端功能开发,仍以源码自带的示例功能(Example,菜单名 示例管理)为例。 开发服务器的启动方式和 src 的目录说明见源码结构与分层,Node.js 与 pnpm 的安装见 Node.js 与 pnpm 安装。
一、要写和要改的文件
下表的路径都在 ujcms-ui-console/ 之下:
| 内容 | 文件 | 示例功能中对应的部分 |
|---|---|---|
| 接口函数 | api/ | queryExamplePage、queryExample、createExample、updateExample、deleteExample |
| 列表页、表单 | views/、views/ | 整个文件 |
| 界面文字 | locales/zh-cn/ 和 locales/en/ 下的 interaction.、menu.json、log.json | example.*、menu.、log.example* |
| 路由与菜单 | router/index.ts | /interaction 分组里 path: 'example' 的一段(默认被注释) |
| 权限树、操作日志名称 | data.ts | getPermsTreeData() 里 example.key 的节点(默认被注释),logModules、logNames 里的 example 条目 |
api、views 和 locales 都按左侧菜单的分组分文件:内容 是 content,互动 是 interaction,用户 是 user, 配置 是 config,系统 是 system。自己的功能放进哪个分组,就写在哪一组文件里。
示例功能的界面与 内容 → 标签管理 是同一种结构,下面的截图取自标签管理:

二、接口函数
每个后台接口对应一个函数。示例功能的五个:
import axios from '@/utils/request';
export const queryExamplePage = async (params?: Record<string, any>): Promise<any> => (await axios.get('/backend/ext/example', { params })).data;
export const queryExample = async (id: string): Promise<any> => (await axios.get(`/backend/ext/example/${id}`)).data;
export const createExample = async (data: Record<string, any>): Promise<any> => (await axios.post('/backend/ext/example', data)).data;
export const updateExample = async (data: Record<string, any>): Promise<any> => (await axios.post('/backend/ext/example?_method=put', data)).data;
export const deleteExample = async (data: string[]): Promise<any> => (await axios.post('/backend/ext/example?_method=delete', data)).data;- 从
@/utils/request引入的axios已经配置好:地址前面自动加/api,请求头自动带上登录令牌、当前站点和界面语言, 出错时统一弹出提示。所以函数里的地址从/backend写起,调用处一般不用自己处理错误。 - 修改和删除用
POST加地址参数_method=put、_method=delete发出,后端按PUT、DELETE处理。 - ID 一律用字符串(
string):后端的主键是 64 位整数,超出 JavaScript 数字的安全范围,接口里以字符串传递。
三、列表页
ExampleList.vue 由四部分组成,从上到下与截图一一对应。
查询表单。 query-form 里每个 query-item 是一个查询项,name 就是发给后端的查询参数名:
<query-form :params="params" @search="handleSearch" @reset="() => handleReset()">
<query-item :label="$t('example.name')" name="Q_Contains_name"></query-item>
<query-item :label="$t('example.height')" name="Q_GE_height_Int,Q_LE_height_Int" type="number"></query-item>
<query-item :label="$t('example.birthday')" name="Q_GE_birthday_DateTime,Q_LE_birthday_DateTime" type="datetime"></query-item>
</query-form>Q_Contains_name 表示“名称包含”,Q_GE_ 用逗号隔开的两个参数表示一个范围(大于等于、小于等于)。 后端的列表接口会接收所有 Q_ 开头的参数,所以增加查询项只改界面,不用改后端。
工具栏。 按钮用 perm() 判断权限,没有权限时置灰:
<el-button type="primary" :disabled="perm('example:create')" :icon="Plus" @click="() => handleAdd()">{{ $t('add') }}</el-button>perm 来自 @/stores/,当前用户没有这个权限码时返回 true,正好绑定到 :disabled。
表格。 el-table 的列放在 <column-list name= 里,工具栏上的 <column-setting name=(齿轮图标) 让操作员选择显示哪些列;列上写 display="none" 表示默认不显示(如 ID 列)。列上的 sortable= 配合 @sort-change 把排序交给后端,参数是 Q_OrderBy,如 name_desc。
取数与分页。 取数函数把查询表单、排序和分页参数合在一起调用接口,返回值里 content 是当前页的数据,page. 是总数:
const fetchData = async () => {
loading.value = true;
try {
const {
content,
page: { totalElements },
} = await queryExamplePage({ ...toParams(params.value), Q_OrderBy: sort.value, page: currentPage.value, pageSize: pageSize.value });
data.value = content;
total.value = Number(totalElements);
} finally {
loading.value = false;
}
};
onMounted(fetchData);四、表单
新增和编辑共用一个对话框,由通用组件 DialogForm(src/)完成加载、保存、删除、 上一条 / 下一条和未保存提示,ExampleForm.vue 只需要告诉它用哪几个接口函数,并写出表单项:
<dialog-form
v-model:values="values"
:name="$t('menu.interaction.example')"
:query-bean="queryExample"
:create-bean="createExample"
:update-bean="updateExample"
:delete-bean="deleteExample"
:bean-id="beanId"
:bean-ids="beanIds"
:focus="focus"
:init-values="() => ({ enabled: true })"
:to-values="(bean) => ({ ...bean })"
:model-value="modelValue"
perms="example"
@update:model-value="(event) => $emit('update:modelValue', event)"
@finished="() => $emit('finished')"
>
<template #default="{}">
<el-form-item prop="name" :rules="{ required: true, message: () => $t('v.required') }">
<template #label><label-tip message="example.name" /></template>
<el-input ref="focus" v-model="values.name" maxlength="30"></el-input>
</el-form-item>
<el-form-item prop="height">
<template #label><label-tip message="example.height" help /></template>
<el-input-number v-model="values.height" :min="1" :max="500" />
</el-form-item>
</template>
</dialog-form>init-values是新增时的初始值,to-values把接口返回的对象转换成表单的值。perms="example"是权限码的前缀:组件用example:create、example:update、example:delete决定保存、新增、删除按钮是否可用。bean-id是当前编辑的 ID(新增时为空),bean-ids是列表当前页的全部 ID,供上一条 / 下一条使用。label-tip显示表单项的名称,message是文字的键;加上help会在名称后显示问号图标,鼠标移上去显示键为example.的说明。height. tooltip maxlength与后端实体类上的@Length保持一致。
五、界面文字
界面上的文字不直接写在页面里,而是写在 src/ 的 JSON 文件中,页面里用 $t('键') 引用。示例功能用到的三处:
"menu.interaction.example": "示例管理","example.name": "名称",
"example.height": "身高",
"example.height.tooltip": "单位:cm(厘米)","log.example": "示例管理",
"log.example.create": "新增示例",分别在 menu.json(菜单名)、interaction.(字段名和提示)和 log.json(操作日志里的模块名和动作名)。
src/locales/en/ 下有同名的文件,是英文界面的文字。运行时只装载当前语言的文件,所以新增的键两种语言都要加, 否则切换到英文时界面上显示的是键名。新建 JSON 文件时,要在两个目录各自的 index.ts 里引入。
六、路由与菜单
在 src/ 里,把路由加到所属分组的 children 中。示例功能在 /interaction(互动)分组:
{
path: 'example',
name: 'ExampleList',
component: () => import('@/views/interaction/ExampleList.vue'),
meta: { title: 'menu.interaction.example', requiresPermission: 'example:page' },
},- 左侧菜单直接由这个文件生成:分组的顺序、分组内各项的顺序都与文件里的顺序相同,不需要另外配置菜单。
meta.title是菜单名的键,对应menu.json。meta.是进入这个界面需要的权限码。当前用户没有它时,菜单项不显示,直接输入地址也进不去。 按惯例用requiresPermission <资源>:page,它只在界面这一侧使用,后端没有对应的接口。- 分组本身不用单独授权:分组里只要有一项可见,分组就显示。
- 界面的地址是
/cp/。#/ interaction/ example
七、权限树
权限码要登记在 src/data.ts 的 getPermsTreeData() 里,才会出现在角色的权限设置中。示例功能的节点:
{
label: t('menu.interaction.example'),
key: 'example.key',
perms: ['example:page', 'example:list'],
children: [
{ label: t('list'), key: 'example:page' },
{ label: t('add'), key: 'example:create', perms: ['example:create'] },
{ label: t('edit'), key: 'example:update', perms: ['example:update', 'example:show'] },
{ label: t('delete'), key: 'example:delete', perms: ['example:delete'] },
],
},它在 用户 → 角色管理 的 权限设置 → 功能权限 里显示成一个可以展开的节点,子节点是各个操作 (下图是标签管理的节点,结构相同):

perms是勾选这个节点后保存到角色上的权限码;key是树节点的标识,打开权限设置时,界面按角色已有的权限码去勾选key相同的节点。 所以子节点的key用它自己的权限码(example:create);“列表”子节点没有perms,key用上一层带的example:page。 有子节点的节点则用不是权限码的key(惯例是<资源>.key),它的勾选状态由子节点决定。- 功能节点(第一层)的
perms写打开这个界面就需要的权限码:路由的example:page和列表接口的example:list。 界面打开时还要调用别的功能的接口(比如下拉框要取栏目列表)时,把那些接口的权限码也写进来。勾选任何一个子节点,都会带上这一层的权限码。 - 子节点的
perms写这个操作要调用的全部接口的权限码:编辑要先读取单条数据,所以是example:update加example:show。 - 后端
@PreAuthorize里的每个权限码、路由requiresPermission里的每个权限码,都必须出现在某个节点的perms里; 不在树里的权限码无法授予角色,只有开启了 全部功能权限 的角色能用。 - 节点放在哪个分组下,与路由所在的菜单分组保持一致。
加好节点并重新构建后台界面后,到 用户 → 角色管理 给需要的角色勾选新节点并保存,该角色的用户重新打开后台后就能看到菜单。
八、操作日志的名称
后端 @OperationLog(module = "example", operation = "create") 记录的是代号。要让操作日志里显示中文名称、并能按模块和动作筛选, 在三处登记:
src/data.ts的logModules数组里加模块代号'example';src/data.ts的logNames数组里加'example.、create' 'example.、update' 'example.;delete' log.json里加log.example、log.等键(见“界面文字”一节)。example. create
操作日志的查询界面(日志 → 操作日志)是商业版基础版的功能,社区版可以省略这一步。
九、启用示例功能与构建
示例功能的界面文件、接口函数、界面文字和日志名称都已经写好,只有路由和权限树节点被注释。想看它的实际效果:
- 按后端功能开发的“示例功能”一节恢复后端三个 Controller 的注解,重新启动后端。
- 取消
src/里router/ index.ts path: 'example'一段和src/data.ts里example.key节点的注释。 - 用开发服务器(
pnpm --dir ujcms-ui-console dev)打开后台,互动 分组的末尾出现 示例管理。
开发完成后,在源码根目录执行下面的命令,把后台界面构建到 ujcms-starter/。构建会先做 TypeScript 类型检查,有类型错误时构建失败:
pnpm --dir ujcms-ui-console build:starter十、常见问题
- 路由加了,菜单里却没有。 当前用户没有路由上
requiresPermission指定的权限码:权限码没有登记到权限树,或者登记了但角色没有勾选。 开启了 全部功能权限 的角色不受影响,用这样的账号可以先确认界面本身是否正常。 - 按钮是灰的,或者点击后提示 403。 按钮上
perm()判断的权限码、接口上@PreAuthorize的权限码,没有包含在角色勾选的节点里。 检查权限树中对应子节点的perms是否写全。 - 界面上显示
example.name这样的键名。 当前语言的 JSON 文件里没有这个键,见“界面文字”一节。