layuiAdmin std v1.x 【iframe版】开发者文档
题外
- 该文档适用于 layuiAdmin 专业版(单页面),阅读之前请务必确认是否与你使用的版本对应。
- 熟练掌握 layuiAdmin 的前提是熟练掌握 layui,因此除了本篇文档, layui 的文档 也是必不可少的存在。
- 看云上的文档
快速上手
部署
- 解压文件后,将 layuiAdmin 完整放置在任意目录
- 通过本地 web 服务器去访问 ./start/index.html 即可运行 Demo
由于 layuiAdmin 可采用前后端分离开发模式,因此你无需将其放置在你的服务端 MVC 框架中,你只需要给 layuiAdmin 主入口页面(我们也称之为:宿主页面)进行访问解析,它即可全权完成自身路由的跳转和视图的呈现,而数据层则完全通过服务端提供的异步接口来完成。
目录说明
- src/
layuiAdmin 源代码,通常用于开发环境(如本地),推荐你在本地开发时,将 ./start/index.html 中的 layui.css 和 layui.js 的引入路径由 dist 改为 src 目录。- src/controller/:存放 JS 业务模块,即对视图进行事件等交互性处理
- src/lib/:layuiAdmin 的核心模块,一般不推荐修改
- src/style/:存放样式,其中 admin.css是核心样式
- src/views/:存放视图文件。其中 layout.html 是整个框架结构的承载,一般不推荐做大量改动。
- src/config.js:layuiAdmin 的全局配置文件,可随意修改。
- src/index.js:layuiAdmin 的入口模块,一般不推荐修改
- dist/
通过 gulp 将 layuiAdmin src 目录的源代码进行构建后生成的目录(即:将 JS 和 CSS 文件进行了压缩等处理),通常用于线上环境。关于 gulp 的使用,下文也有介绍。 - start/
存放 layuiAdmin 的入口页面、模拟接口数据、layui
宿主页面
你所看到的 start/index.html 是我们提供好的宿主页面,它是整个单页面的承载,所有的界面都是在这一个页面中完成跳转和渲染的。事实上,宿主页面可以放在任何地方,但是要注意修改里面的
的 src 和 layui.config 中 base 的路径。
全局配置
当你已经顺利在本地预览了 layuiAdmin 后,你一定迫不及待关注更深层的结构。打开 src 目录,你将看到 config.js,里面存储着所有的默认配置。你可以按照实际需求选择性修改,下面是 layuiAdmin 默认提供的配置:
layui.define(['laytpl', 'layer', 'element', 'util'], function(exports){ exports('setter', { container: 'LAY_app' //容器ID ,base: layui.cache.base //记录layuiAdmin文件夹所在路径 ,views: layui.cache.base + 'views/' //视图所在目录 ,entry: 'index' //默认视图文件名 ,engine: '.html' //视图文件后缀名 ,pageTabs: false //是否开启页面选项卡功能。单页版不推荐开启 ,name: 'layuiAdmin Pro' ,tableName: 'layuiAdmin' //本地存储表名 ,MOD_NAME: 'admin' //模块事件名 ,debug: true //是否开启调试模式。如开启,接口异常时会抛出异常 URL 等信息 ,interceptor: false //是否开启未登入拦截 //自定义请求字段 ,request: { tokenName: 'access_token' //自动携带 token 的字段名。可设置 false 不携带。 } //自定义响应字段 ,response: { statusName: 'code' //数据状态的字段名称 ,statusCode: { ok: 0 //数据状态一切正常的状态码 ,logout: 1001 //登录状态失效的状态码 } ,msgName: 'msg' //状态信息的字段名称 ,dataName: 'data' //数据详情的字段名称 } //独立页面路由,可随意添加(无需写参数) ,indPage: [ '/user/login' //登入页 ,'/user/reg' //注册页 ,'/user/forget' //找回密码 ,'/template/tips/test' //独立页的一个测试 demo ] //扩展的第三方模块 ,extend: [ 'echarts', //echarts 核心包 'echartsTheme' //echarts 主题 ] //主题配置 ,theme: { //配色方案,如果用户未设置主题,第一个将作为默认 color: [{ main: '#20222A' //主题色 ,selected: '#009688' //选中色 ,logo: '' //logo区域背景色 ,header: '' //头部区域背景色 ,alias: 'default' //默认别名 }] //为了减少篇幅,更多主题此处不做列举,可直接参考 config.js //初始的颜色索引,对应上面的配色方案数组索引 //如果本地已经有主题色记录,则以本地记录为优先,除非清除 localStorage(步骤:F12呼出调试工具→Aplication→Local Storage→选中页面地址→layuiAdmin→再点上面的X) // 1.0 正式版开始新增 ,initColorIndex: 0 } }); });
侧边菜单
- 在 start/json/menu.js 文件中,我们放置了默认的侧边菜单数据,你可以去随意改动它。
- 如果你需要动态加载菜单,你需要将 views/layout.html 中的对应地址改成你的真实接口地址
侧边菜单最多可支持到三级。无论你采用静态的菜单还是动态的,菜单的数据格式都必须是一段合法的 JSON,且必须符合以下规范:
{
"code": 0 //状态码,key 名可以通过 config.js 去重新配置 ,"msg": "" //提示信息 ,"data": [{ //菜单数据,key名可以通过 config.js 去重新配置 "name": "component" //一级菜单名称(与视图的文件夹名称和路由路径对应) ,"title": "组件" //一级菜单标题 ,"icon": "layui-icon-component" //一级菜单图标样式 ,"jump": '' //自定义一级菜单路由地址,默认按照 name 解析。一旦设置,将优先按照 jump 设定的路由跳转 ,"spread": true //是否默认展子菜单(1.0.0-beta9 新增) ,"list": [{ //二级菜单 "name": "grid" //二级菜单名称(与视图的文件夹名称和路由路径对应) ,"title": "栅格" //二级菜单标题 ,"jump": '' //自定义二级菜单路由地址 ,"spread": true //是否默认展子菜单(1.0.0-beta9 新增) ,"list": [{ //三级菜单 "name": "list" //三级菜单名(与视图中最终的文件名和路由对应),如:component/grid/list ,"title": "等比例列表排列" //三级菜单标题 },{ "name": "mobile" ,"title": "按移动端排列" } }] }
TIPS:实际运用时,切勿出现上述中的注释,否则将不是合法的 JSON ,会出现解析错误。
需要注意的是以下几点:
- 当任意级菜单有子菜单,点击该菜单都只是收缩和展开操作,而并不会跳转,只有没有子菜单的菜单才被允许跳转。
- 菜单的路由地址默认是按照菜单层级的 name 来设定的。
我们假设一级菜单的 name 是:a,二级菜单的是:b,三级菜单的 name 是 c,那么:- 三级菜单最终的路由地址就是:
/a/b/c
- 如果二级菜单没有三级菜单,那么二级菜单就是最终路由,地址就是:
/a/b/
- 如果一级菜单没有二级菜单,那么一级菜单就是最终路由,地址就是:
/a/
- 三级菜单最终的路由地址就是:
- 但如果你设置了 参数 jump,那么就会优先读取 jump 设定的路由地址,如:
"jump": "/user/set"
路由
layuiAdmin 的路由是采用 location.hash
的机制,即路由地址是放在 ./#/
后面,并通过 layui 自带的方法:layui.router()
来进行解析。每一个路由都对应一个真实存在的视图文件,且路由地址和视图文件的路径是一致的(相对 views
目录)。因此,你不再需要通过配置服务端的路由去访问一个页面,也无需在 layuiAdmin 内部代码中去定义路由,而是直接通过 layuiAdmin 的前端路由去访问,即可匹配相应目录的视图,从而呈现出页面结果。
路由规则
./#/path1/path2/path3/key1=value1/key2=value2…
一个实际的示例:
./#/user/set
./#/user/set/uid=123/type=1#xxx(下面将以这个为例继续讲解)
当你需要对路由结构进行解析时,你只需要通过 layui 内置的方法 layui.router() 即可完成。如上面的路由解析出来的结果是:
{
path: ['user','set']
,search: {uid: 123, type: 1}
,href: 'user/set/uid=123/type=1'
,hash: 'xxx'
}
可以看到,不同的结构会自动归纳到相应的参数中,其中:
- path:存储的是路由的目录结构
- search:存储的是路由的参数部分
- href:存储的是 layuiAdmin 的完整路由地址
- hash:存储的是 layuiAdmin 自身的锚记,跟系统自带的 location.hash 有点类似
通过layui.router()
得到路由对象后,你就可以对页面进行个性化操作、异步参数传值等等。如:
//在 JS 中获取路由参数
var router = layui.router(); admin.req({ url: 'xxx' ,data: { uid: router.search.uid } });
<!-- 在动态模板中获取路由参数 -->