更新记录

1.2.1(2020-12-05)

  • 修复 用户管理 uni-forms 校验 switch 类型错误 bug
  • 登录页 token 失效后,重新登录 navigateTo -> redirect
  • 菜单管理增加提示

1.2.0(2020-12-04)

  • uni-id-roles 表内置 admin 角色,旧版 admin 升级到 admin1.2.0+ 版本需做向下兼容,在 uni-id-roles 表中添加如下一条记录:
    [{
    "role_id": "admin",
    "role_name": "超级管理员",
    "permission": [],
    "comment": "超级管理员拥有所有权限",
    "create_date": 0
    }]
  • 更新内置组件 uni-forms、uni-forms-item
  • 新增内置组件 uni-easyinput、uni-data-checkbox、uni-load-more
查看更多

云函数类插件通用教程

使用云函数类插件的前提是:使用HBuilderX 2.9+


uniCloud admin 基础框架

什么是 uniCloud admin

uniCloud admin 基础框架,是基于 uni-app 和 uniCloud 的应用后台管理框架。HBuilderX 2.9.5+ 支持,请更新到最新版本使用。

  • 它使用 uni-app 的宽屏适配,可自动适配 PC 宽屏和手机各端。了解宽屏适配
  • 它基于 uniCloud,是 serverless 的云开发。了解uniCloud
  • 它基于 uni-id,admin 框架使用的是 uni-id 的用户账户、权限系统。了解uni-id

内置的功能

  • 管理员账户初始化、登录、修改密码
  • 顶部 topWindow 的设置:比如 logo 更换、右上角部分链接更换。详见项目根目录的admin.config.js文件
  • 左侧 leftWindow 的菜单设置:菜单包括两类,一类是动态菜单,具备业务和权限功能;另一类是静态菜单,不会根据登录用户角色变化
  • 开发模式下的 debug 功能,帮助开发者及时发现报错和搜索错误信息,可在admin.config.js文件中配置

uniCloud admin 是一个框架,具体业务需要开发者自己开发或从插件市场导入相关插件

支持响应式布局

uniCloud admin 同时支持 PC 端 和移动端。

PC 端如下图:

pc

移动端如下图:

使用

创建

HBuilderX 2.9.5+版本新建 uni-app 项目,选择 uniCloud admin 项目模板,如下图

download-admin

创建完成后,可以跟随云服务空间初始化向导初始化项目,创建并绑定云服务空间

download-admin

运行

  1. 进入 admin 项目
  2. 在/cloudfunctions-aliyun/common/uni-id/config.json 文件中填写 passwordSecret 字段 (用于加密密码入库的密钥) 和 tokenSecret 字段 (为生成token需要的密钥)
  3. 右键 cloudfuntions 运行云服务空间初始化向导(如已创建并绑定云服务空间,则跳过此步)
  4. 点击工具栏的运行 -> 运行到浏览器
  5. 登录页面底部进入创建管理员页面(仅允许注册一次管理员账号)

注意:手机端报 request:fail,需要去云服务空间的跨域配置配置跨域域名,需带端口

目录结构

├── cloudfunctions              # 云函数
├── common
│   │── uni.css                 # 公共样式
│   └── uni-icons.css           # icon样式
├── components                  # 自定义组件
├── js_sdk                      # js sdk
├── pages                       # 页面
│   │── index                   # 首页
│   └── login                   # 登录页
├── static
├── store                       # vuex
├── windows
│   │── component               # 项目中使用的组件
│   │── leftWindow.vue          # 左侧窗口(菜单栏)
│   └── topWindow.vue           # 顶部窗口(导航栏)
├── admin.config.js             # 系统配置(配置导航,菜单等)
├── App.vue
├── main.js
├── mainfest.json
├── pages.json
├── postcss.config.js           # postcss 配置(浏览器兼容性)
└── uni.scss

登录页

首次使用,可以通过登录页面底部链接创建一个超级管理员(仅允许创建一次),该接口会判断系统里如果有admin角色的用户,就不再允许添加新的超级管理员。

注意:注册完毕后,建议从登录页面移除该链接

login

分栏窗体介绍

登录后我们会看到如下窗体, 窗体分为三个部分,topWindow 顶部窗口(导航栏),leftwindow 左侧窗口(菜单栏),右侧的内容主窗体

index

顶部窗口(导航栏)

顶部窗口默认在左侧展示系统Logo、右侧显示导航链接,效果如上图。展示内容可通过项目根目录下的admin.config.js文件进行配置,如下为示例:

# admin.config.js
export default {
  navBar: {// 顶部导航
    logo:"https://www.example.com/logo.png",//左侧 Logo
    links: [ // 右侧链接
      {
        text: "Admin框架文档",
        url: "https://uniapp.dcloud.net.cn/uniCloud/admin",
      },
      {
        text: "浏览更多Admin插件",
        url: "https://ext.dcloud.net.cn/?cat1=7&cat2=74",
      }
    ],
  },
};

顶部导航栏的样式,可通过项目根目录下的uni.scss进行自定义,如下:

# uni.scss
$top-window-bg-color: #fff; /* 背景色 */
$top-window-text-color: #999; /* 文字颜色 */

左侧窗口(菜单栏)

左侧窗口内主要是菜单,菜单包含静态菜单和动态菜单,支持无限层级嵌套,但建议层级不要超过三级

  • 静态菜单: 所有登录用户角色都能看到
  • 动态菜单: 根据角色的权限自动生成

    用户登录时,会根据用户的 角色 去查找其拥有的 权限 ,再根据 权限 去查找对应的 菜单

管理静态菜单

通过 admin.config.js 配置侧边栏内容,所有用户都能看到静态菜单。

export default {
  // 侧边栏
  sideBar: {
    // 配置静态菜单列表(放置在用户被授权的菜单列表下边)
    staticMenu: [
      {
        menu_id: "demo",
        name: "静态功能演示",
        icon: "uni-icons-list",
        children: [
          {
            menu_id: "icons",
            name: "图标",
            url: "/pages/demo/icons/icons",
          },
          {
            menu_id: "table",
            name: "表格",
            url: "/pages/demo/table/table",
          }
        ]
      },
    ],
  },
};
管理动态菜单

在云后台数据库的 opendb-admin-menus 表中管理菜单, 对菜单增删改查。如下图:

add-menu

菜单字段解释:

字段 类型 必填 描述
menu_id Object ID 菜单 Id
name String 菜单文字
icon String 菜单图标
url String 菜单对应的页面链接(只有没有子菜单的菜单项可以配置)
sort Integer 在同级菜单中的排序,数组越大越靠后
parent_id String 父级菜单 Id
permission Array 菜单权限(只有没有子菜单的菜单项可以配置)
enable Boolean 菜单状态:false 禁用 true 启用
create_date Timestamp 创建时间

添加菜单记录需要注意:

  • 无子菜单,则需 url 字段不能为空,该菜单才能在页面显示
  • 有子菜单,则需至少一个子菜单的 url 字段不能为空,该菜单才能在页面显示

例如,如需增加如下菜单:

订单管理                  # 父菜单
└── 手机                 # 子菜单

step 1:添加一条父菜单记录

菜单的 parent_id 字段为空, 即为一级菜单

{
  "menu_id": "order",
  "name": "订单管理",
  "icon": "uni-icons-cart-filled",
  "url": "",
  "sort": 2,
  "parent_id": "",
  "permission": [],
  "enable": true,
  "create_date": "1602662469396"
}

step 2:添加一条子菜单记录

将子菜单的 parent_id 指向父菜单的 menu_id即可,孙菜单就是将子菜单的 menu_id 当做父菜单

{
  "menu_id": "phone",
  "name": "手机",
  "icon": "uni-icons-phone",
  "url": "pages/phone",
  "sort": 3,
  "parent_id": "order",
  "permission": [],
  "enable": true,
  "create_date": "1602662469492"
}
侧边栏样式管理

通过 uni.scss 配置侧边栏样式

调整菜单颜色时,只需设置菜单背景色 $menu-bg-color,自行搭配文字前景色即可

$left-window-bg-color: #fff; /* 左侧窗口背景色 */
$menu-bg-color: #fff; /* 一级菜单背景色 */
$sub-menu-bg-color: darken($menu-bg-color, 8%); /* 二级以下菜单背景色 */
$menu-bg-color-hover: darken($menu-bg-color, 15%); /* 菜单 hover 背景颜色 */
$menu-text-color: #333; /* 菜单前景色 */
$menu-text-color-actived: #409eff; /* 菜单激活前景色 */

右侧窗口(内容主窗体)

右侧窗口是内容主窗体,和 uni-app 保持一致,用户登录后看到的第一个页面,默认是 pages 数组中第一项表示应用启动页。

如果想将自己开发的页面调到登录后首页,可在 page.json 调整。

icon 图标

admin 框架内置了一套icon图标,在静态功能演示-图标菜单中,点击图标即可复制图标的class定义,或者直接到common/uni-icons.css中查看定义,然后以如下方式使用:

<view class="uni-icons-gear"></view>

当然,你也可以使用三方icon库。以使用 elementUI 的图标为例,在 app.vue 中导入图标库的样式文件:

<style>
  /* 注意此处仅为 icon 使用示例,建议引入纯净图标库,避免增加不必要的 css */
  @import 'https://unpkg.com/element-ui/lib/theme-chalk/index.css';
</style>

在标签上使用图标的 class 名称,即:

<view class="el-icon-s-tools"></view>

用户-角色-权限

uniCloud admin 框架基于 uni-id,复用 uni-id 的用户、角色、权限系统,详见uni-id

需要注意的是,admin框架的动态菜单同样依赖uni-id的权限表(uni-id-permissions)。

菜单表(opendb-admin-menus)定义如下:

字段 类型 必填 描述
menu_id Object ID 菜单 Id
name String 菜单文字
icon String 菜单图标
url String 菜单对应的页面链接(只有没有子菜单的菜单项可以配置)
sort Integer 在同级菜单中的排序,数组越大越靠后
parent_id String 父级菜单 Id
permission Array 菜单权限(只有没有子菜单的菜单项可以配置)
enable Boolean 菜单状态:false 禁用 true 启用
create_date Timestamp 创建时间

admin 提供了两个内置方法,方便在页面中鉴定登录用户权限和角色:

方法 作用 入参 返回值
$hasPermission 鉴定登录用户是否具有某权限 String Boolean
$hasRole 鉴定登录用户是否具有某角色 String Boolean
<template>
  <view>
    <!-- 包含 user/add 权限的用户可以看到新增按钮 -->
    <button v-if="$hasPermission('USER_ADD')">新增</button>
    <!-- 包含 admin 角色的用户可以看到删除按钮 -->
    <button v-if="$hasRole('admin')">删除</button>
  </view>
</template>

新增页面

新增页面可以自己开发页面,也可以从插件市场下载插件。页面如需添加菜单,参见上文的菜单管理

开发页面不局限开发方式:

  • 可以新增普通的页面,在前端 callfunction,后台搭配云函数操作
  • 可以使用 uni-clientdb,在前端直接操作数据库,后台配置 db schema 进行权限和格式校验
  • 可以使用云函数单文件路由,在项目中默认包含了一个uni-cloud-router 的单文件路由,也可以使用插件市场的其他单文件路由

注意:在搭配云函数操作,controller 下的文件夹和文件,不要命名相同,例如:app/room 这个写法目前分辨不了 app 是文件 app.js,还是文件夹 app

自己开发页面

admin 中开发页面,和 uni-app 开发 vue 页面是一致的。

从插件市场下载插件,并注册到 admin 菜单

uniCloud admin 管理项目-权限管理插件为例

使用步骤:

  1. 插件市场导入插件
  2. 在 HBuilder X 2.9.5 中选择添加插件的项目
  3. 覆盖项目的 db_init.json 文件, 点击“确定覆盖”
  4. 在 db_init.json 文件上右键,点击“初始化云数据库”
  5. 刷新 admin 即可在菜单栏看到新增的菜单

---------------------------------- 分割线 ----------------------------------------

插件开发

我们不仅是插件的使用者,也可以是插件的开发者,那么如何开发一款插件呢?参考 DCloud 插件开发指南汇总 及其中的 admin 插件部分.

使用三方组件库

uniCloud admin 支持所有三方的 Vue UI 库,包括 elementUI 等非 uni-app 的 UI 库,但注意这些 for h5 的 ui 库只能在浏览器中使用,无法适配 App 和小程序,按如下操作。

以使用 element-ui 框架为例:

  1. 安装 UI 框架

    npm i element-ui -S

  2. 在 main.js 中引用

    import elementUI from "element-ui";
    import "element-ui/lib/theme-chalk/index.css";
    
    Vue.use(elementUI);

隐私、权限声明

1. 本插件需要申请的系统权限列表:

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

许可协议

Apache License Version 2.0, January 2004 http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

  1. Definitions.

    "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.

    "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.

    "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.

    "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.

    "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.

    "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.

    "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).

    "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.

    "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."

    "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.

  2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.

  3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.

  4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:

    (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and

    (b) You must cause any modified files to carry prominent notices stating that You changed the files; and

    (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and

    (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.

    You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.

  5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.

  6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.

  7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.

  8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.

  9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.

    END OF TERMS AND CONDITIONS

    APPENDIX: How to apply the Apache License to your work.

    To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.

    Copyright [yyyy] [name of copyright owner]

    Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

使用中有什么不明白的地方,就向插件作者提问吧~ 我要提问