MuYi.dev

Appearance

使用指南 ​

nuxtAdmin 基于 nuxt.js v3 版本开发，需要 node.js >= 18

快速开始 ​

bash
# 创建项目目录并进入
mkdir project
cd project

# 克隆 nuxtAdmin
git clone https://github.com/NMTuan/nuxtAdmin.git

# 安装依赖
# 或使用你习惯的工具，如： yarn pnpm bun
npm install

# 启动开发环境
npm run dev

提示：

npm run dev 是开发环境，修改代码后有热加载功能，方便调试，但页面加载速度有少许的慢。

npm run build && npm run preview 是打包+预览环境，页面加载速度快，但修改代码后需要重新执行命令。

打开浏览器，访问 http://localhost:3000 ，直接点击登录即可。一个完整的 nuxtAdmin 就算搭建起来了。

当前接口数据都来自 nuxtAdmin 本身，这得益于 nuxt 自带的 server 服务。如果你懂 node.js，可以在 /server 目录中写服务端逻辑，该服务使用的是 Nitro 。

但如果你想接入其它语言的后端，让我们继续。

接入后端 ​

要接入后端，至少需要 3 个非业务接口。

  • 登录鉴权 /auth/login
  • 登出 /auth/logout
  • 获取当前用户信息 /auth/me

按照以下格式返回数据即可完成后端的接入。完整内容请参考接口约定。

NOTE

如果你正在使用 laf 可以在函数市场找到接入示例。

json
// http://theBackendApiHost.com/api/v1/auth/login
{
    code: 200, message: "",
    data: {
        token: "the_token_string"
    }
}
json
// http://theBackendApiHost.com/api/v1/auth/logout
{
    code: 200, message: "",
    data: {}
}
json
// http://theBackendApiHost.com/api/v1/me/
{
    code: 200, message: "",
    data: {
        menu: [
            {label: "首页", key: "index", icon: "i-ri-home-3-line"}
        ],
        topbar: ["darkMode", "fullScreen", "i18n", {
            label: "退出",
            icon: "i-ri-logout-box-r-line",
            to: "/logout"
        }]
    }
}

然后修改 /nuxt.config.ts 文件引入这几个接口：

js
export default defineNuxtConfig({
    // ...
    auth: {
        baseURL: "http://theBackendApiHost.com/api/v1/",	// 接口地址及路径
        globalAppMiddleware: true,
        provider: {
            type: "local",
            endpoints: {
                signIn: { path: "/auth/login", method: "post" },	// 登录
                signOut: { path: "/auth/logout", method: "post" },	// 登出
                getSession: { path: "/me", method: "get" }	// 获取用户信息
            },
            token: {
                signInResponseTokenPointer: "/data/token",	// 登录接口返回数据中，“token”的位置
                maxAgeInSeconds: 60 * 60 * 24	// 超时时间
            },
            pages: {
                login: "/login"
            }
        }
    },
    //...
})

最后重启服务即可（npm run dev 模式下会自动重启）。

接入业务数据 ​

经过前面一系列的操作，我们完成了自有接口的接入。接下来，让我们把业务数据接进来。

基于下面的示例，让我们手摸手的完成整个数据接入。

示例：

我需要管理一批学生数据，需要列表展示相关字段，如：姓名、性别、身高、体重、所属年级。要有相关字段的查询能力，同时能对数据进行增删改操作。

1. 添加菜单 ​

要想在 nuxtAdmin 左侧增加新菜单，只需修改 /auth/me 接口中返回的 menu 数据即可。如：

json
{
    menu: [
        {	
            label: "学生管理",	
            value: "student"
        }	
    ]
}

刷新浏览器后就会发现，左侧菜单中增加了一级栏目： 学生管理 。

为满足大多数业务场景，nuxtAdmin 的菜单最多支持三级。下级菜单用关键字 children 定义。

二级菜单如下所示，三级菜单同理。

json
{
    menu: [
        {
            label: "学校管理",
            value: "school",
            children: [	
                { label: "学生管理", value: "student" },
                { label: "班级管理", value: "class" },
                { label: "年级管理", value: "grade" }
            ]
        }
    ]
}

2. 展示数据 ​

展示表格数据，需要用到 nuxtAdmin 提供的组件 dataTable。让我们回到刚刚添加的菜单数据，在其中声明一下渲染组件即可，如下：

json
{
    label: "学生管理",
    value: "student",
    component: "dataTable"
}

再次刷新浏览器，点击并进入 学生管理 页面，就会看到一个空的数据列表。

image-20240318113926008

此组件在加载时会自动 GET 请求同路径的后端接口，如： {接口地址}/{api}/student?page=1&limit=10 ，如果是上面二级菜单则会 GET 请求：{接口地址}/{api}/school/student?page=1&limit=10

接下来编写 student 后端接口，按以下格式返回数据即可。

json
{
    code: 200,
    message: "",
    data: {
        data: [
            {id: "1", name: "张三", sex: "1", height: "120", weight: "26", gradeId: "1"},
            {id: "2", name: "李四", sex: "1", height: "124", weight: "24", gradeId: "1"},
            {id: "2", name: "王五", sex: "2", height: "135", weight: "23", gradeId: "2"},
            {id: "2", name: "赵六", sex: "1", height: "135", weight: "29", gradeId: "2"}
        ],
        total: 4
    }
}

再次刷新浏览器，将会看到如下内容：

image-20240318134517380

数据出来了，但部分数据并不可读，让我们优化一下。依旧是修改 student 接口返回的数据格式，如下：

json
{
    code: 200,
    message: "",
    data: {
        data: [...],
        fields: [	
            {key: "id", label: "编号"},
            {key: "name", label: "姓名"},
            {key: "sex", label: "性别", component: "enum", items: [
            	{label: "男", value: "1"},
            	{label: "女", value: "2"},
            	{label: "未知", value: "0"}
            ]},
            {key: "height", label: "身高（cm）"},
            {key: "weight", label: "体重（kg）"},
            {key: "gradeId", label: "所在年级", component: "enum", items: [
                { label: "一年级", value: "1" },
                { label: "二年级", value: "2" },
                { label: "三年级", value: "3" }
            ]},
        ],
        total: 4
    }
}

image-20240318140824711

至此，一个列表的数据展示就完成了，接下来让我处理一下查询功能。

3. 查询 ​

查询是每个数据管理系统必不可少的功能。在 dataTable 组件中，查询分为 基础查询 、 高级查询 以及 固定条件过滤。

要开启基础查询，只需在 student 接口中返回 search 关键字及相关配置项即可，如下：

json
{
    code: 200,
    message: "",
    data: {
        data: [...],
        fields: [...],
        search: [	
            {
                key: "name",
                label: "姓名",
                placeholder: "请输入学生姓名"
            },
            {
                key: "sex",
                label: "性别",
                placeholder: "请选择学生性别",
                component: "select",
                options: [
                    {label: "男", value: "1"},
                    {label: "女", value: "2"},
                    {label: "未知", value: "0"}
                ]
            }
        ],
        total: 4
    }
}

image-20240318144826266

search 关键字内有几项，就会显示几个搜索条件，由于空间有限，基础搜索适用于一些常用搜索条件，更多搜索条件建议放到高级搜索中去。

要开启高级查询，只需在 student 接口中返回 advSearch 关键字及相关配置项即可，如下：

json
{
    code: 200,
    message: "",
    data: {
        data: [...],
        fields: [...],
        search: [...],
        advSearch: [	
			{ key: "name", label: "姓名" },
            {
                key: "sex",
                label: "性别",
                component: "select",
                options: [
                    { label: "男", value: "1" },
                    { label: "女", value: "2" },
                    { label: "未知", value: "0" }
                ]
            },
            { key: "height", label: "身高" },
            { key: "weight", label: "体重" },
            {
                key: "gradeId",
                label: "所在年级",
                component: "select",
                options: [
                    { label: "一年级", value: "1" },
                    { label: "二年级", value: "2" },
                    { label: "三年级", value: "3" }
                ]
            }
        ],
        total: 4
    }
}

image-20240318150122572

有了基础搜索和高级搜索，已经满足绝大数的使用场景了。但有时候会有一些常用的搜索条件比较复杂，每次手动输入就显得笨拙许多，所以 dataTable 还提供了 固定条件过滤 功能。只需在 student 接口中返回 filters 关键字及相关配置项即可，如下：

json
{
    code: 200,
    message: "",
    data: {
        data: [...],
        fields: [...],
        search: [...],
        advSearch: [...],
      	filters: [ 
            { label: "全部学生", query: {} },
            { label: "一年级女生", query: { sex: "2", groudId: "1" } },
            { label: "二年级男生", query: { sex: "1", groudId: "2" } }
        ],
        total: 4
    }
}

image-20240318153001261

至此，整个查询功能就做好了。

4. 增删改 ​

最后，让我们丰富一下 “增删改” 的功能。

这里需要回到最初 /auth/me 接口中返回的 menu 数据中，增加一些操作项，用关键字 actions 表示。另外，还要在 student 接口的 fields 中增加 “操作” 列。

json
{
    menu: [
        {
            label: "学生管理",
            value: "student",
            component: "dataTable",
            actions: [	
                {
                    label: "创建",
                    value: "create",
                    component: "form",
                    positions: ["top"]
                },
                {
                    label: "编辑",
                    value: "edit",
                    component: "form",
                    positions: ["row"],
                    query: ["id"]
                },
                {
                    label: "删除",
                    value: "delete",
                    component: "confirm",
                    message: "确定要删除此学生吗？",
                    positions: ["row"],
                    query: ["id"]
                }
            ]
        }
    ]
}
json
{
    code: 200,
    message: "",
    data: {
        data: [...],
        fields: [
            ...
            { label: "操作", component: "actions" }	
        ],
        total: 4
    }
}

image-20240318160245294

配置好后，功能就展示在页面上了，我们只需要按照各功能的约定，把返回的数据格式处理好即可。

创建 & 编辑 ​

创建和编辑操作都使用的 form 组件，该组件在加载的时候会自动 GET 请求同路径接口，如：

  • {GET接口地址}/{api}/student/create
  • {GET接口地址}/{api}/student/edit/id=3

这里，我们只需要按如下格式返回表单项及表单数据即可：

json
{
    code: 200,
    message: "",
    data: {
        fields: [
            { key: "name", label: "姓名" },
            {
                key: "sex",
                label: "性别",
                component: "select",
                options: [
                    { label: "男", value: "1" },
                    { label: "女", value: "2" },
                    { label: "未知", value: "0" }
                ]
            },
            { key: "height", label: "身高" },
            { key: "weight", label: "体重" },
            {
                key: "gradeId",
                label: "所在年级",
                component: "select",
                options: [
                    { label: "一年级", value: "1" },
                    { label: "二年级", value: "2" },
                    { label: "三年级", value: "3" }
                ]
            }
        ]
    }
}

提示：

这里的表单与搜索的表单使用的是同一个组件，所以配置是一致的。

它们大概是下面这个样子。如果你愿意，也可以改为右侧滑出的抽屉模式，详细配置看这里。

image-20240318164330568

提交表单也同样会 POST 请求同路径接口，如：

  • {POST接口地址}/{api}/student/create
  • {POST接口地址}/{api}/student/edit/id=3。

提交的数据如下：

json
// 创建操作
// request payload
{ name: "", sex: "", height: "", weight: "", gradeId: "" }

// 编辑操作
// query params
{ id: "" }
// request payload
{ name: "", sex: "", height: "", weight: "", gradeId: "" }
删除 ​

删除操作使用的 confirm 组件。该组件目前不会拉取任何接口数据，二次确认的文本内容在 actions 的 message 中配置。

image-20240318164913571

在点击“确认”按钮后，会 POST 请求同路径接口，如：{POST接口地址}/{api}/student/delete/?id=3。

提交的数据如下：

json
// query params
{ id: "" }

提示：

“创建”、“编辑”、“删除”操作完成后，列表数据会自动刷新。

至此，这个 “学生管理” 的功能就开发完成了。

提示：

/server 目录中有是 nuxtAdmin 自带的后端演示接口，自有接口完全接入后就可以删掉 /server 目录了。