sunadmin-core
TypeScript icon, indicating that this package has built-in type declarations

1.0.15 • Public • Published

SunAdmin 后台管理系统前端框架

一句命令即可安装完整的后台管理系统前端框架!

介绍

SunAdmin Admin UI 是一个基于 Vue 3 和 Element Plus 开发的通用后台管理系统前端框架,旨在提供一套完整的后台管理界面解决方案,帮助开发者快速搭建专业的管理后台。

开发目的

  • 一句命令安装:通过简单的 npm/pnpm 命令即可获得完整后台框架
  • 零侵入性:作为独立的 npm 包,对宿主项目无任何侵入性
  • 便捷更新:版本更新只需更改依赖版本号,无需修改现有代码
  • 避免依赖冲突:使用 peerDependencies 设计,避免重复依赖安装
  • 提供开箱即用的后台管理界面
  • 减少重复开发常见后台功能的工作量
  • 统一管理后台的界面风格与交互体验
  • 与 SunAdmin 后端框架无缝集成,形成完整解决方案

为什么开发成独立的包?

  • 便于安装:一句命令即可完成安装,无需复杂配置
  • 无侵入性:作为独立包引入,不会污染宿主项目的代码结构
  • 便捷更新:只需修改版本号即可获取最新功能和安全修复
  • 跨项目复用:可在多个项目中使用相同的管理界面
  • 统一维护:集中维护一套代码,确保各项目使用相同标准
  • 避免依赖冲突:通过 peerDependencies 设计,让宿主项目管理依赖版本

技术栈

  • Vue 3: 渐进式 JavaScript 框架
  • TypeScript: 类型安全的 JavaScript 超集
  • Element Plus: 基于 Vue 3 的组件库
  • Pinia: Vue 的状态管理库
  • Vue Router: Vue.js 的官方路由
  • Axios: 基于 Promise 的 HTTP 客户端
  • Vite: 现代前端构建工具

起步

安装

只需一句命令,即可拥有完整的后台管理系统前端框架!

1. 安装依赖

由于采用了 peerDependencies 设计,您需要先安装必要的依赖:

# 使用 npm
npm install vue@^3.4.29 element-plus@^2.7.7 @element-plus/icons-vue@^2.3.1 pinia@^3.0.3 pinia-plugin-persistedstate@^4.2.0 vue-router@^4.3.3 axios@^1.7.2

# 使用 pnpm
pnpm add vue@^3.4.29 element-plus@^2.7.7 @element-plus/icons-vue@^2.3.1 pinia@^3.0.3 pinia-plugin-persistedstate@^4.2.0 vue-router@^4.3.3 axios@^1.7.2

2. 安装 SunAdmin

# 使用 npm
npm install @sunjinglong/sunadmin-admin-ui

# 使用 pnpm
pnpm add @sunjinglong/sunadmin-admin-ui

基础配置

由于新的设计架构,您需要在宿主项目中自行配置第三方库:

main.js 配置示例

import { createApp } from "vue";
import App from "./App.vue";

// 手动配置第三方库
import ElementPlus from "element-plus";
import "element-plus/dist/index.css";
import zhCn from "element-plus/dist/locale/zh-cn.mjs";
import * as ElementPlusIconsVue from "@element-plus/icons-vue";

import { createRouter, createWebHistory } from "vue-router";
import { createPinia } from "pinia";
import piniaPluginPersistedstate from "pinia-plugin-persistedstate";

// 导入 SunAdmin
import SunAdminUI from "@sunjinglong/sunadmin-admin-ui";
import "@sunjinglong/sunadmin-admin-ui/dist/style.css";

const app = createApp(App);

// 1. 配置 Element Plus
app.use(ElementPlus, { locale: zhCn });

// 2. 注册 Element Plus Icons
for (const [key, component] of Object.entries(ElementPlusIconsVue)) {
    app.component(key, component);
}

// 3. 配置 Pinia
const pinia = createPinia();
pinia.use(piniaPluginPersistedstate);
app.use(pinia);

// 4. 配置路由
const router = createRouter({
    history: createWebHistory(),
    routes: [
        // 您的自定义路由
    ],
});
app.use(router);

// 5. 配置 SunAdmin
app.use(SunAdminUI, {
    apiConfig: {
        baseURL: "http://your-api-domain.com/sunAdmin", // 后端API基础地址
        timeout: 60000, // 请求超时时间
        wsUrl: "ws://xxxx",
    },
});

app.mount("#app");

与后端集成

SunAdmin 前端框架设计为与 sunjinglong/sunadmin-server 后端框架无缝集成,一句命令即可拥有高性能后端。

请阅读后端仓库中的使用文档

后端 API 格式要求

响应格式:

{
    "code": 200,
    "message": "操作成功",
    "data": {}
}

认证方式:

  • 使用 Bearer Token 认证
  • Token 通过请求头 Authorization: Bearer {token} 传递

封装列表

用户认证与权限管理

  • 登录页面与认证流程
  • 基于角色的权限控制
  • 动态菜单权限
  • Token 自动刷新
  • 用户信息管理

布局与导航

  • 响应式侧边栏
  • 面包屑导航
  • 标签页导航
  • 自适应布局
  • 主题定制

数据管理页面

  • 管理员账号管理
  • 角色权限管理
  • 菜单管理
  • 数据字典管理
  • 附件管理
  • 定时任务管理

WebSocket 实时通信

  • 自动连接与重连
  • 消息订阅与发布
  • 实时通知
  • 用户在线状态

通用组件

  • 页面容器组件
  • 搜索卡片组件
  • 表单构建器
  • 图标选择器
  • 图片选择器
  • 附件选择器

二开文档

创建页面

  • 在你的项目 pages 目录中创建页面 vue 文件,例: src/test.vue
  • 在 main.js 中加载 sunadmin 的时候传入路由配置
app.use(SunAdminCore,{
    apiConfig: {....api配置信息},
    //layoutRoutes中的路由页面将在系统框架内显示
    layoutRoutes: [
      //该数组中加入你的路由地址
        {
            path: '/test',
            component: () => import('./pages/test.vue')
        }
    ],
    outsideRoutes:[
      {
        path:'/其他不需要再框架内显示的页面'
      }
    ]
})
  • 最后需要在后台 - 运维 - 菜单权限 - 新增 - 菜单类型(页面路由) - 路由地址(/test), 将菜单路由信息提交到服务区,该步骤请保证你已经安装了后端服务,具体请参阅sunadmin 配套后端服务安装方式,一条命令即可安装
  • 刷新页面后会即可在后台看到菜单

使用 ElementPlus 相关 api

sunadmin 包内已经安装了 ElementPlus 组件库,用户宿主项目中无需重复安装

import { ElMessage,ElMessageBox, ...其他api } from "@sunjinglong/sunadmin-admin-ui";
ElMessage.info("信息提示");
ElMessage.error("错误提示");

使用 pinia

sunadmin 中已经导入并加载了 pinia, 用户在宿主项目中无需安装和导入 pinia

import { defineStore } from "@sunjinglong/sunadmin-admin-ui";
export const useAccountStore = defineStore("account", {
    state: () => {
        return {
            test: "",
        };
    },
});

路由实例 router 的使用

npm 包内已经创建了路由实例,并且导出了该实例,宿主项目中无需引入并创建路由实例

  • 如果是 vue 组合式 api 风格,那么请直接使用 vue 原生的 useRouter()钩子来获取当前的路由实例(推荐);
// 组合式api风格,在宿主项目中
import { useRouter } from "vue-router";
// 在setup函数或组件中
const router = useRouter();
// 使用路由
router.push("/dashboard");
  • 如果使用的不是组合式 api 风格,那么请使用 vue 原生的 this.$router 来访问路由实例 (推荐)
// 选项式API组件
export default {
    methods: {
        navigateTo(path) {
            this.$router.push(path);
        },
        goBack() {
            this.$router.go(-1);
        },
    },
    mounted() {
        // 在生命周期钩子中使用
        console.log(this.$router.currentRoute.value);
    },
};
  • 如果需要在组件外或者特殊需求下获取 sunadmin 包内创建的路由实例,那么请使用 sunadmin 导出的 router(一般很少遇到这种场景)
import { router } from "@sunjinglong/sunadmin-admin-ui";
router.push("/some-path");

HTTP 请求

sunadmin 包内已经自行使用 axios 封装了网络请求方法,导出了 get,post,del,service(axios 实例)

请求返回拦截处理原则是:当接口 http 状态码为 200,且业务数据中 response.code 为 200,那么认为该接口成功。否则一律按照接口异常处理,返回 Promise.reject,走 catch。

import { get, post } from "@sunjinglong/sunadmin-admin-ui";

// GET 请求
http.get("请求地址(会自动拼接host)", {'请求数据对象'})
    .then((response) => {
        console.log(response.data);
    })
    .catch((err) => {
        console.error(err.message);
    });

// POST 请求
http.post("/api/users", { name: "John", email: "john@example.com" }).then((response) => {
    console.log(response.data);
});

// DELETE 请求
http.del("/api/users/1").then((response) => {
    console.log(response.data);
});

WebSocket 管理

主动订阅 ws 消息

import { wsManager } from "@sunjinglong/sunadmin-admin-ui";
//消息订阅 (一般在页面组件create的时候订阅),返回销毁方法
this.wsHandle = wsManager.addMessageHandler((data) => {
    console.log("收到ws消息");
});
//记得在合适时机取消订阅(一般在页面组件销毁beforeUnmount)
this.wsHandle();

sunadmin 包内可用的 pinia 状态实例

后台管理员登录信息

import { useAccountStore } from "@sunjinglong/sunadmin-admin-ui";
// 账户状态
const accountStore = useAccountStore();
属性:
  • 自行打印 accountStore 查看
  • isLogin 可判断当前登录状态,是一个 getters 属性
方法:
  • loginOut() 退出登录
  • accountOffLine() 强制踢出某管理员下线

日期工具

import { formatFriendlyTime } from "@sunjinglong/sunadmin-admin-ui";

友好时间显示

  • formatFriendlyTime(dateTime: string | number | Date | null | undefined)

判断两个日志是否为同一天

  • isSameDay(date1: Date, date2: Date)

业务初始化

import { initBusiness, cleanupBusiness, reinitBusiness } from "@sunjinglong/sunadmin-admin-ui";

// 初始化业务逻辑
initBusiness();

// 清理业务资源
cleanupBusiness();

// 重新初始化业务逻辑
reinitBusiness();

自定义开发

扩展组件

您可以通过导入并扩展 SunAdmin 的组件来创建自定义组件:

<template>
    <PageViewContainer title="自定义页面">
        <!-- 自定义内容 -->
    </PageViewContainer>
</template>

<script setup>
import { PageViewContainer } from "@sunjinglong/sunadmin-admin-ui";
</script>

相关链接

许可证

SunAdmin Admin UI 使用 MIT 许可证,详见 LICENSE 文件。

Package Sidebar

Install

npm i sunadmin-core

Weekly Downloads

31

Version

1.0.15

License

MIT

Unpacked Size

1.4 MB

Total Files

12

Last publish

Collaborators

  • sunjinglong