layuiAdmin pro v1.x 【单页版】开发者文档
layuiAdmin pro v1.x 【單頁版】開發者文檔
layuiAdmin pro (單頁版)是完全基于 layui 架構而成的后臺管理模板系統,可以更輕松地實現前后端分離,它是 mvc 的簡化版,全面接管?視圖?和?頁面路由,并可自主完成數據渲染,服務端通常只負責數據接口,而前端只需專注視圖和事件交互,所有的頁面動作都是在一個宿主頁面中完成,因此這賦予了 layuiAdmin 單頁面應用開發的能力。
題外
- 該文檔適用于?layuiAdmin 專業版(單頁面),閱讀之前請務必確認是否與你使用的版本對應。
- 熟練掌握 layuiAdmin 的前提是熟練掌握 layui,因此除了本篇文檔,?layui 的文檔?也是必不可少的存在。
快速上手
部署
由于 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 的入口模塊,一般不推薦修改
?
?
宿主頁面
你所看到的?start/index.html?是我們提供好的宿主頁面,它是整個單頁面的承載,所有的界面都是在這一個頁面中完成跳轉和渲染的。事實上,宿主頁面可以放在任何地方,但是要注意修改里面的?<link>?<script>?的 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 是:a,二級菜單的是:b,三級菜單的 name 是?c,那么:
- 三級菜單最終的路由地址就是:/a/b/c
- 如果二級菜單沒有三級菜單,那么二級菜單就是最終路由,地址就是:/a/b/
- 如果一級菜單沒有二級菜單,那么一級菜單就是最終路由,地址就是:/a/
路由
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 } }); <!-- 在動態模板中獲取路由參數 --> <script type="text/html" template lay-url="./xxx/?uid={{ layui.router().search.uid }}"> … </script><!-- 或 --> <script type="text/html" template lay-url="./xxx/" lay-data="{uid:'{{ layui.router().search.uid }}'}"> … </script>路由跳轉
通過上文的路由規則,你已經大致清楚了 layuiAdmin 路由的基本原理和解析方法。那么如何完成路由的跳轉呢?
路由結尾
在路由結尾部分出現的?/?與不出現,是兩個完全不同的路由。比如下面這個:
讀取的視圖文件是:.views/user/set.html
讀取的視圖文件是:./views/user/set/index.html (TIPS:這里的?index.html?即是目錄下的默認主視圖,下文會有講解)
因此一定要注意結尾處的?/,避免視圖讀取錯誤。
視圖
這或許是你應用 layuiAdmin 時的主要焦點,在開發過程中,你的大部分精力都可能會聚焦在這里。它取代了服務端 MVC 架構中的?view?層,使得應用開發變得更具擴展性。因此如果你采用 layuiAdmin 的 SPA(單頁應用)模式,請務必要拋棄服務端渲染視圖的思想,讓頁面的控制權限重新回歸到前端吧!
views?目錄存放的正是視圖文件,你可以在該目錄添加任意的新目錄和新文件,通過對應的路由即可訪問。
注意:如果是單頁面模式,視圖文件通常是一段 HTML 碎片,而不能是一個完整的 html 代碼結構。
視圖與路由的關系
每一個視圖文件,都對應一個路由。其中?index.html?是默認文件(你也可以通過 config.js 去重新定義)。視圖文件的所在目錄決定了路由的訪問地址,如:
| ./views/user/index.html | /user/ |
| ./views/user.html | /user |
| ./views/user/set/index.html | /user/set/ |
| ./views/user/set.html | /user/set |
| ./views/user/set/base.html | /user/set/base |
通過上述的表格列舉的對應關系,可以總結出:
- 當視圖文件是 index.html,那么路由地址就是它的上級目錄(相對?views),以?/?結尾
- 當視圖文件不是 index.html,那么路由地址就是它的上級目錄+視圖文件名,不以?/?結尾
值得注意的是:路由路徑并非最多只能三級,它可以無限極。但對應的視圖也必須存放在相應的層級目錄下
視圖中加載 JS 模塊
在視圖文件中,除了寫 HTML,也可以寫 JavaScript 代碼。如:
<div id=“LAY-demo-hello”>Hello layuiAdmin</div> <script> layui.use('admin', function(){ var $ = layui.jquery; admin.popup({ content: $('#LAY-demo-hello').html() }); }); </script>如果該視圖對應的 JS 代碼量太大,我們更推薦你在?controller?目錄下新增一個業務模塊,并在視圖中直接 layui.use 去加載該模塊。下面以控制臺主頁?index.html?為例:
<div>html區域<div><script> //加載 controller 目錄下的對應模塊 /* 小貼士: 這里 console 模塊對應 的 console.js 并不會重復加載, 然而該頁面的視圖可能會重新插入到容器,那如何保證腳本能重新控制視圖呢?有兩種方式: 1): 借助 layui.factory 方法獲取 console 模塊的工廠(回調函數)給 layui.use 2): 直接在 layui.use 方法的回調中書寫業務代碼,即: layui.use('console', function(){ //同 console.js 中的 layui.define 回調中的代碼 });這里我們采用的是方式1。其它很多視圖中采用的其實都是方式2,因為更簡單些,也減少了一個請求數。*/ layui.use('console', layui.factory('console')); </script>當視圖被渲染后,layui.factory 返回的函數也會被執行,從而保證在不重復加載 JS 模塊文件的前提下,保證腳本能重復執行。
動態模板
layuiAdmin 的視圖是一個“動靜結合”的載體,除了常規的靜態模板,你當然還可以在視圖中存放動態模板,因此它可謂是焦點中的焦點。
定義模板
在視圖文件中,通過下述規則定義模板:
<script type="text/html" template> <!-- 動態模板碎片 --> </script>下面是一個簡單的例子:
<script type="text/html" template> 當前 layuiAdmin 的版本是:{{ layui.admin.v }} 路由地址:{{ layui.router().href }} </script>在不對動態模板設定數據接口地址的情況下,它能讀取到全局對象。但更多時候,一個動態模板應該是對應一個接口地址,如下所示:
<script type="text/html" template lay-url="接口地址"> 我叫:{{ d.data.username }} {{# if(d.data.sex === '男'){ }} 公的 {{# } else { }} 母的 {{# } }} </script>模板中的?d?對應的是你接口返回的 json 轉化后的一維對象,如:
{ "code": 0 ,"data": { "username": "賢心" ,"sex": "男" } }那么,上述動態模板最終輸出的結果就是:
我叫:賢心 公的模板基礎屬性
動態模板支持以下基礎屬性
- lay-url
用于綁定模板的數據接口地址,支持動態模板解析,如:
- lay-type
用于設定模板的接口請求類型(默認:get),如:
- lay-data
用于定義接口請求的參數,其值是一個 JavaScript object 對象,同樣支持動態模板解析,如:
-
lay-headers
用戶定義接口請求的 Request Headers 參數,用法與 lay-data 的完全類似,支持動態模板解析。 -
lay-done
接口請求完畢并完成視圖渲染的回調腳本,里面支持寫任意的 JavaScript 語句。事實上它是一個封閉的函數作用域,通過給 Function 實例返回的函數傳遞一個參數?d,用于得到接口返回的數據:
很多時候,你在動態模板中可能會放入一些類似于 layui 的 form 元素,而有些控件需要執行?form.render()?才會顯示,這時,你可以對 lay-done 賦值一個全局函數,如:
<script type="text/html" template lay-url="接口地址" lay-done="layui.data.done(d);"> <div class="layui-form" lay-filter="LAY-filter-demo-form"> <input type="checkbox" title="復選框"> </div> </script><!-- 注意:別看眼花了,下面可不是動態模板,而是 JS 腳本區域 --> <script> layui.data.done = function(d){ layui.use(['form'], function(){ var form = layui.form; form.render(null, 'LAY-filter-demo-form'); //渲染該模板下的動態表單 }); }; </script>TIPS:
- 如果模板渲染完畢需要處理過多的交互,我們強烈推薦你采用上述的方式定義一個全局函數賦值給 lay-done,會極大地減少維護成本。
- 無需擔心該全局函數的沖突問題,該函數是一次性的。其它頁面即便聲明了一個同樣的函數,也只是用于新的視圖,絲毫不會對之前的視圖造成任何影響。
- layui.data.done 中的?done?可以隨意命名,但需與 lay-done 的賦值對應上。
模板語法
動態模板基于 layui 的 laytpl 模塊,詳細語法可見:
http://www.layui.com/doc/modules/laytpl.html#syntax
登錄與接口鑒權
由于 layuiAdmin 接管了視圖層,所以不必避免可能會與服務端分開部署,這時你有必要了解一下 layuiAdmin 默認提供的:從?登錄?到?接口鑒權,再到?注銷?的整個流程。
登錄攔截器
進入登入頁面登入成功后,會在 localStorage 的本地表中寫入一個字段。如: access_token (名稱可以在 config.js 自定義)。攔截器判斷沒有 access_token 時,則會跳轉到登入頁。盡管可以通過偽造一個假的 access_token 繞過視圖層的攔截,但在請求接口時,會自動帶上 access_token,服務端應再次做一層校驗。
流程
如果是在其它場景請求的接口(如:table.render()),那么你需要獲取本地存儲的 token 復制給接口參數,如:
table.render({ elem: '#xxxx' ,url: 'url' ,where: { access_token: layui.data('layuiAdmin').access_token } })事實上,layuiAdmin 的所有 Ajax 請求都是采用?admin.req(options),它會自動傳遞?access_token,因此推薦你在 JS 執行 Ajax 請求時直接使用它。其中參數?options?和?$.ajax(options)?的參數完全一樣。
接口鑒權
我們推薦服務端遵循?JWT(JSON Web Token) 標準進行鑒權。對 JWT 不甚了解的同學,可以去搜索一些相關資料,會極大地增加應用的可擴展性。當然,你也可以直接采用傳統的 cookie / session 機制。
基礎方法
- config 模塊
你可以在任何地方通過?layui.setter?得到?config.js?中的配置信息
- admin 模塊
var admin = layui.admin;
-
admin.req(options)
Ajax 請求,用法同 $.ajax(options),只是該方法會進行錯誤處理和 token 的自動傳遞 -
admin.screen()
獲取屏幕類型,根據當前屏幕大小,返回 0 - 3 的值
0: 低于768px的屏幕
1:768px到992px之間的屏幕
2:992px到1200px之間的屏幕
3:高于1200px的屏幕 -
admin.exit()
清除本地 token,并跳轉到登入頁 -
admin.sideFlexible(status)
側邊伸縮。status 為 null:收縮;status為 “spread”:展開 -
admin.on(eventName, callback)
事件監聽,下文會有講解 -
admin.popup(options)
彈出一個 layuiAdmin 主題風格的 layer 層,參數 options 跟 layer.open(options) 完全相同 -
admin.popupRight(options)
在屏幕右側呼出一個面板層。options 同上。
-
admin.resize(callback)
窗口 resize 事件處理,我們推薦你使用該方法取代 jQuery 的 resize 事件,以避免多頁面標簽下可能存在的沖突。 -
admin.events
-
admin.events.refresh()
刷新當前右側區域 -
admin.events.closeThisTabs()
關閉當前標簽頁 -
admin.events.closeOtherTabs()
關閉其它標簽頁 -
admin.events.closeAllTabs()
關閉全部標簽頁
?
-
?
- view 模塊
var view = layui.view;
- view(id)
獲取指定容器,并返回一些視圖渲染的方法,如:
另外,render?方法支持動態傳參,以用于視圖內容接受。如:
admin.popup({ id: 'LAY-popup-test1' ,success: function(){ view(this.id).render('視圖文件所在路徑', { id: 123 //這里的 id 值你可以在一些事件中動態獲取(如 table 模塊的編輯) }); } })那么,在視圖文件中,你可以在動態模板中通過?{{ d.params.xxx }}?得到傳入的參數,如:
<script type="text/html" template lay-url="http://api.com?id={{ d.params.id }}"> 配置了接口的動態模板,且接口動態獲取了 render 傳入的參數:{{ d.params.id }} </script><script type="text/html" template> 也可以直接獲取:<input type="hidden" name="id" value="{{ d.params.id }}"> </script>駕馭好?view().render().done(callback)?對您的項目開發至關重要。
ID唯一性
如果你開啟了標簽頁功能,請務必注意 ID 的沖突,尤其是在你自己綁定事件的情況。ID 的命令可以遵循以下規則來規避沖突:
LAY-路由-任意名以消息中心頁面為例,假設它的路由為:/app/message/,那么 ID 應該命名為:
<button class="layui-btn" id="LAY-app-message-del">刪除</button>實用組件
Hover 提示層
通過對元素設置?lay-tips="提示內容"?來開啟一個 hover 提示,如:
<i class="layui-icon layui-icon-tips" lay-tips="要支持的噢" lay-offset="5"></i>其中?lay-offset?用于定于水平偏移距離(單位px),以調整箭頭讓其對準元素
事件監聽
- hash
監聽路由地址改變
- side
監聽側邊伸縮
兼容性
layuiAdmin 使用到了 layui 的柵格系統,而柵格則是基于瀏覽器的媒體查詢。ie8、9不支持。
所以要在宿主頁面(如 start/index.html )加上下面這段保證兼容:
緩存問題
由于單頁面版本的視圖文件和靜態資源模塊都是動態加載的,所以可能存在瀏覽器的本地緩存問題,事實上我們也考慮到這個,因此,為了避免改動后的文件未及時生效,你只需在入口頁面(默認為start/index.html)中,找到?layui.config?,修改其?version?的值即可。
我們推薦你分場景來更新緩存:
- 場景一:如果項目是在本地開發。你可以設置 version 為動態毫秒數,如:
- 場景二:如果項目是在線上運行。建議你手工更新?version,如:
升級事項
從官網更新資源包后,除了 src 和 dist 目錄需要注意一下,其它目錄和文件均可覆蓋,下面以 src 為例(dist 由于是 src 構建后生成的目錄,所以本質是和 src 一樣的)
src 目錄下可以直接覆蓋的有:
- src/lib/
- src/style/
- src/index.js
需要靈活調配的有:
- src/controller/
- src/views/
- src/config.js
如果沒有改動默認配置,事實上 config.js 也可以覆蓋升級
開發過程中,建議同時運行兩個 layuiAdmin 。一個是已經實際運用的,一個是 layuiAdmin 本身的 Demo。以便從 Demo 中獲取參考和提取示例。
源碼構建
當你在 src 目錄完成開發后,你可通過 gulp 對 src 源碼進行自動化構建,以生成用于線上環境的 dist 目錄。并在入口頁面中的?layui.config?的 base 參數指向 dist。
在資源包中根目錄下看到的 gulpfile.js 是 layuiAdmin 寫好的任務腳本,package.json 是任務配置文件,你只需按照以下步驟:
安裝完成后,后續只需直接執行命令:gulp?即可完成 src 到 dist 目錄的構建
關于版權
layuiAdmin 受國家計算機軟件著作權保護,未經官網正規渠道授權擅自公開產品源文件、以及直接對產品二次出售的,我們將追究相應的法律責任。
總結
以上是生活随笔為你收集整理的layuiAdmin pro v1.x 【单页版】开发者文档的全部內容,希望文章能夠幫你解決所遇到的問題。
- 上一篇: PHP汉字转拼音带声调
- 下一篇: hilbert C语言