接口约定

注意：

nuxtAdmin 是一个约定式的程序，可能无法直接融入你的项目。需要你依照约定修改现有 api，或单独开发一套 api。

标准格式

所有接口统一按照以下格式返回数据：

json

{
    code: 200,
    message: "",
    data: {}
}

字段	数据类型	含义
code	number	状态码，正常为200，其它请自定义。
message	string	状态消息，留空时页面无动作；如有内容，会在右上角弹出内容。
data	object	数据主体，各接口返回的实际数据内容。

建议：

返回的数据中，简单数据类型的数据统一使用 string 类型，不要使用 number 类型。特别是表单项，经过组件处理后，最终会以 string 类型被提交。

获取数据统一会发起 GET 请求。请求参数由 query 及 params 两个配置项配置。例如：

// params query
{ id: '', state: '3'}	// {query: ['id'], params: {state: '3'}}

提交数据统一会发起 POST 请求。

这里使用的是 nuxt-auth 模块，它支持本地登录、第三方服务商授权登录、及其它自定义的登录方式，你可以在这里读到它的所有内容。

在 nuxtAdmin 中，仅使用了本地登录的模式，即标准的 jwt 鉴权模式。

登录页面会 POST 提交以下数据到接口，同时也需要接口按标准返回所需数据。

json

// post 提交
{
    username: "",
    password: "",
    keep_login: false
}

json

// 返回数据
{
    code: 200, message:"",
    data: {
        token: "the_token_string"
    }
}

目前只用到了 token 一个数据。如果你无法返回 data.token ，也根据你的数据格式进行修改，查看相关配置。

登陆成功后，所有请求都会自动携带 token 信息。

json

// request headers
{
    "Authorization": "Bearer the_token_string"
}

登出 /auth/logout

json

{
    code: 200, message: "",
    data: {}
}

这个没什么好说的，处理好后端逻辑即可。前端会自动清理本地保存的 token 信息，并跳转到登录页面。

用户信息 /auth/me

这个接口是整个 nuxtAdmin 项目的核心，当前登录用户所有的权限功能都在这里返回，整个平台将基于这个数据进行构建。基本数据格式如下：

json

{
    code: 200, message: "",
    data: {
        menu: [],
        topbar: [],
        notice: ""
    }
}

字段	数据类型	含义	备注
menu	object[]	定义左侧菜单及各功能模块	见下文
topbar	(string \| object)[]	定义右上角区域内容	见下文
notice	string	消息数的接口地址。留空或不返回，则不开启消息数的功能。	如：`/auth/notice`

这部分是页面左侧菜单及各功能模块的配置数据。基本数据格式如下：

json

[
    {
        label: "", 
        value: "", 
        icon: "", 
        component: "", 
        fetchType: "", 
        fetchUrl: "",
        actions: [],
        children: []
    }
]

字段	数据类型	含义	备注
key	string	字段名	此栏目的key，也用于 url 中当前栏目的地址
label	string	名称	在页面中显示的名称
icon	string	图标的 class 值	支持icones的所有图标，命名格式为：`i-{collection_name}-{icon_name}` 如： `i-ri-notification-3-line`
component	string	内置组件的名称	组件不同呈现的页面不同，具体有哪些组件可参考内置组件
fetchType	string	组件加载时拉取数据的方式	默认为 `GET`
fetchUrl	string	组件加载时拉取数据的接口地址	默认与当前栏目所在路径相同。
children	array	当前栏目的子栏目	见下文
actions	array	当前栏目的操作项	见下文
hidden	boolean	在侧边菜单栏中隐藏当前栏目	默认 false。此配置只影响侧边菜单。

children

数据格式与上面的相同，不再重复说明。

为满足大多数业务场景，nuxtAdmin 的菜单最多支持三级。也就是 children 还能再有一个 children。

actions

这里把没有独立 url 地址的，以弹窗（或侧边滑出）等形式出现的操作归为页内操作。基本数据格式如下：

字段	数据类型	含义	备注
key	string	字段名	此操作的 key
label	string	名称	在页面上显示的名称
title	string	对话框的左上角的标题	如未配置 title 窗体标题会显示当前 label
icon	string	图标的 class 值	支持icones的所有图标，命名格式为：`i-{collection_name}-{icon_name}` 如： `i-ri-notification-3-line`
component	string	内置组件的名称	组件不同呈现的效果不同，具体可参考操作级组件
showType	string	组件的展示方式	默认为 `modal` 弹窗；如果设置为 `slideover` 则为右侧滑出。
fetchType	string	组件加载时拉取数据的方式	默认为 `GET`
fetchUrl	string	组件加载时拉取数据的接口地址	默认值为与当前栏目所在路径+此操作的 key。如：`/student/delete`
submitUrl	string	组件提交数据的地址	默认值同 fetchUrl ，但会以 `POST` 方式提交。
query	array	fetchUrl 及 submitUrl 的 GET 参数	这里只提供 key，组件会自动匹配操作项数据中的 value。如： `['id']`
params	object	fetchUrl 及 submitUrl 的额外参数	这里提供的参数都是固定值的，如： `{ref: 'baidu.com'}`

这部分是页面右上角内容的配置数据，如下图所示：

基本数据格式如下：

json

[
    {label: "", icon: "", image: "", to: "", type: "", dropDown: []}
]

字段	数据类型	含义	备注
label	string	文本内容
icon	string	图标的 class 值	支持icones的所有图标，命名格式为：`i-{collection_name}-{icon_name}` 如： `i-ri-notification-3-line`
image	string	图片地址	常用于显示用户头像
to	string	程序内部路径或外部 url	内部路径： `/logout` 注意：这里一定是当前用户有权限的地址外部 url ： `https://www.baidu.com`
component	string	内置了一些功能组件	`darkMode` 深色模式与浅色模式的切换 `fullScreen` 浏览器全屏与非全屏的切换 `i18n` 多国语言的切换，具体配置看这里
activeIcon	string	激活状态下图标的 class 值	darkMode、fullScreen 可设置此项
dropDown	array	下拉菜单	见下文
noticeKey	string	绑定消息数接口返回的 key	如需显示消息数，则需要使用此字段，保证此字段的值与“接口”返回的key相同即可。

内置组件也可以配置 label、icon 等信息。如果不需要任何配置也可简写为一个 string。如：

json

[
    {label: "设置"， '/config'},
    {type: "darkMode", icon: "x", activeIcon: "x"},	// 自定义图标
    'fullScreen',	// 无配置的简写
    {label: '退出', '/logout'}
]

如需下拉菜单，可配置此项，基本格式如下：

json

[
    {label: "", icon: "", to: ""}
]

字段	数据类型	含义	备注
label	string	文本内容
icon	string	图标的 class 值	支持icones的所有图标，命名格式为：`i-{collection_name}-{icon_name}` 如： `i-ri-notification-3-line`
to	string	程序内部路径或外部 url	内部路径： `/logout` 注意：这里一定是当前用户有权限的地址外部 url ： `https://www.baidu.com`

提示：

dropDown 还支持二维数组 [[{},{}], [{},{}]]。每组菜单之间将会显示一条分割线，如上图中 profile 与 exit 之间。

消息数 /auth/notice

什么是消息数？比如：站内信、新消息等，通常会以小红点的形式展现在页面上，这些功能的通知是如何及时显示在页面上的？这里使用了比较简单（简陋）的方式，每次路由切换时，请求消息数接口并处理返回的数据，此功能基于 Nuxt middleware 实现。

此接口返回数据格式如下：

json

{
    code: 200, message: "",
    data: {
        key1: 0,
        key2: {
            count: 0,
            color: ""
        }
    }
}

字段	数据类型	含义	备注
key	string \| object	消息数	值如果是string，则表示消息数。值如果是object，则 count 为消息数， color 为背景色，默认颜色为配置的主色调。

key1 key2 为实际业务中自定义的 key，确保需要显示消息数的地方 noticeKey 的值与此 key 相同即可。

注意：

如果消息数是1，则以小红点的形式显示；如果大于1，则会显示实际值。

nuxtAdmin

压感时钟

无压书签

接口约定

标准格式

登出 /auth/logout

用户信息 /auth/me

menu

children

actions

topbar

消息数 /auth/notice

接口约定 ​

标准格式 ​

登录 /auth/login ​

登出 /auth/logout ​

用户信息 /auth/me ​

menu ​

children ​

actions ​

topbar ​

dropDown ​

消息数 /auth/notice ​

接口约定

标准格式

登录 /auth/login

登出 /auth/logout

用户信息 /auth/me

menu

children

actions

topbar

dropDown

消息数 /auth/notice