simpleui 快速上手指南
有很多同學會誤解simpleui，認為下載、安裝simpleui后，啟動就可以直接使用。但是simpleui是在django的基礎上進行優化的，所以請先自行用命令行、IDE創建一個django項目，然后修改默認后台模板為simpleui
在開始入門之前，請花1分鍾了解下settings.py文件，
它在接下來的過程中尤為重要。
入門指引
進階指南
常見問題
創建一個django項目
Simple UI 地址: https://simpleui.72wo.com/docs/simpleui/
django官方中文教程https://docs.djangoproject.com/zh-hans/2.0/intro/tutorial01/
安裝simpleui
pip install django-simpleui
修改默認后台模板為simpleui
我們只需要在項目中的settings.py文件中加入一行simpleui即可。
舉個例子🌰：
# Application definition
INSTALLED_APPS = [
'simpleui',
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
...
]
如果關閉debug模式后,會出現靜態資源無法訪問，請查看克隆靜態文件到根目錄
克隆靜態文件到根目錄
熟悉django的同學會了解，django有個神奇的模式叫做debug模式，默認是開啟的，在settings.py中
# SECURITY WARNING: don't run with debug turned on in production!
DEBUG = True
關閉后可以有兩種辦法解決靜態資源無法訪問的情況
- 在settings.py中加入：
STATICFILES_DIRS = [
os.path.join(BASE_DIR, "static"),
]
- 克隆靜態資源到項目的靜態目錄，然后交由nginx處理
python3 manage.py collectstatic
如果克隆報錯提示找不到靜態目錄，請先在settings.py指定靜態目錄
STATIC_ROOT = os.path.join(BASE_DIR, "static")
啟動項目查看效果
在settings.py中成功加入simpleui后，運行命令：
python manage.py runserver 8000
瀏覽器中輸入：http://127.0.0.1:8000/admin
如果發現登錄頁和之前有所不同，那么就可以恭喜你，成功安裝simpleui！接下來開始享受simpleui吧。
如何下載這個模版
目前暫時無法下載模板，不過我們計划推出simple-admin，純html的模板，可以讓更多語言使用。
切換主題
目前simpleui 內置28個流行樣式風格的主題。后續隨着版本的更新，會加入更多的主題。
圖標說明
simpleui中顯示的圖標 可以參考fontawesome的圖標，只需要將完整的class名填入即可。
關閉登錄頁粒子動畫
在項目的settings.py中加入
SIMPLEUI_LOGIN_PARTICLES = False
粒子動畫默認開啟
默認主題
默認主題在settings.py中進行配置
# 指定simpleui默認的主題,指定一個文件名，相對路徑就從simpleui的theme目錄讀取
SIMPLEUI_DEFAULT_THEME = 'admin.lte.css'
主題列表：
取對應的file即可設置成默認主題
var SimpleuiThemes = [
{
text: "Default",
menu: 'rgb(48, 65, 86)',
logo: 'rgb(48, 65, 86)',
top: '#FFF'
},
{
text: "Simpleui-x",
menu: '#2c2e39',
logo: '#2c2e39',
top: '#FFF',
file: "simpleui.css"
},
{
text: "Element-UI",
file: "element.css",
top: '#447eff',
menu: '#FFf',
logo: '#FFF'
},
{
text: "layui",
file: "layui.css",
menu: '#393D49',
logo: '#23262E',
top: '#23262E'
}, {
text: "Ant Design Pro",
file: "ant.design.css",
menu: '#000b16',
logo: '#002140',
top: '#FFF'
}, {
text: "Admin LTE",
file: "admin.lte.css",
top: '#3c8dbc',
logo: '#3c8dbc',
menu: '#2b3539'
}, {
text: "Highdmin",
file: "highdmin.css",
top: '#02c0ce',
menu: '#e0e0e0',
logo: '#02c0ce'
}, {
text: "Aircraft",
file: "aircraft.css",
top: '-webkit-gradient(linear, left bottom, left top, color-stop(0, #4d5b76), color-stop(1, #6f80a1)) !important',
menu: '#e0e0e0',
logo: '-webkit-gradient(linear, left bottom, left top, color-stop(0, #4d5b76), color-stop(1, #6f80a1)) !important'
}, {
text: "Purple",
file: "purple.css",
top: '#FFF',
logo: '#FFF',
menu: '#3e4295'
}, {
text: "Gray",
file: "gray.css",
top: '#213a53',
logo: '#213a53',
menu: '#e0e0e0'
},
{
text: "Dark green",
file: "dark.green.css",
top: '#f3f3f4',
menu: '#283846',
logo: '#283846'
},
{
text: "Orange",
file: "orange.css",
top: 'linear-gradient(to right bottom, #da8342, #e45131)',
logo: 'linear-gradient(to right bottom, #da8342, #e45131)',
menu: '#FFF'
},
{
text: "Black",
file: "black.css",
top: "#333",
logo: "#333",
menu: '#FFF'
},
{
text: "Green",
file: "green.css",
top: '#19a97b',
logo: '#FFF',
menu: '#FFF'
},
{
text: "Light",
file: "light.css",
top: "#ebf1f5",
logo: "#ebf1f5",
menu: "#ebf1f5"
}, {
text: 'Enterprise blue',
file: 'e-blue.css',
top: '#3ba1df',
logo: '#3ba1df',
menu: '#FFF'
}, {
text: 'Enterprise blue pro',
file: 'e-blue-pro.css',
top: '#3ba1df',
logo: '#3ba1df',
menu: 'rgb(38, 50, 56)'
}, {
text: 'Enterprise green',
file: 'e-green.css',
top: '#27ad60',
logo: '#27ad60',
menu: '#FFF'
}, {
text: 'Enterprise green pro',
file: 'e-green-pro.css',
top: '#27ad60',
logo: '#27ad60',
menu: 'rgb(38, 50, 56)'
}, {
text: 'Enterprise red',
file: 'e-red.css',
top: '#c9333e',
logo: '#c9333e',
menu: '#FFF'
}, {
text: 'Enterprise red pro',
file: 'e-red-pro.css',
top: '#c9333e',
logo: '#c9333e',
menu: 'rgb(38, 50, 56)'
}, {
text: 'Enterprise purple',
file: 'e-purple.css',
top: '#8263b1',
logo: '#8263b1',
menu: '#FFF'
}, {
text: 'Enterprise purple pro',
file: 'e-purple-pro.css',
top: '#8263b1',
logo: '#8263b1',
menu: 'rgb(38, 50, 56)'
}, {
text: 'Enterprise black',
file: 'e-black.css',
top: '#1f2c39',
logo: '#1f2c39',
menu: '#FFF'
}, {
text: 'Enterprise black pro',
file: 'e-black-pro.css',
top: '#1f2c39',
logo: '#1f2c39',
menu: 'rgb(38, 50, 56)'
}, {
text: 'x-green',
file: 'x-green.css',
top: '#2F9688',
logo: '#2F9688',
menu: 'rgb(38, 50, 56)'
}, {
text: 'x-red',
file: 'x-red.css',
top: '#AA3130',
logo: 'rgb(38, 50, 56)',
menu: 'rgb(38, 50, 56)'
}, {
text: 'x-blue',
file: 'x-blue.css',
top: '#FFF',
logo: '#1E9FFF',
menu: 'rgb(38, 50, 56)'
}
]
自定義主題
在自定義主題之前，請先把simpleui的靜態資源克隆到根目錄。然后找到theme
theme.js 就是用於配置主題列表
按該文件中的格式配置即可
var SimpleuiThemes = [
{
"text": "Default"
},
{
"text": "Simpleui-x",
"file": "simpleui.css"
},
.....
]
在增加你的樣式之前，請先了解less如何使用。
這是admin.lte.less的例子
@import "base";
@primary: #2096c8 !important;
@color: white;
@menu-color: #8aa4af !important;
@menu-background: #2b3539 !important;
@menu-color-hover: #FFF;
@menu-background-hover: #1f272b;
@menu-title-color: #FFF;
@menu-title-background-color: #212c32;
@menu-title-color-hover: #FFF;
@menu-title-background-color-hover: #1f272b;
@navbar-color: #fff;
@navbar-background: #3c8dbc;
他將會編譯為admin.lte.css
需要安裝less
npm install less -g
lessc admin.lte.less>admin.lte.css
修改默認圖標
django內置的認證與授權以及關聯的用戶、組，都已經默認配置了一個圖標。后續自定義的app將會是默認圖標，需要自行在settings.py文件中進行配置
修改默認管理標題
因為simpleui使用的是admin的配置, 所以我們不能直接在settings中進行修改
方法一:
- 在每一個應用下的admin文件中添加:
from django.contrib import admin
admin.site.site_header = '五年后的我們' # 設置header
admin.site.site_title = '五年后的我們' # 設置title
admin.site.index_title = '五年后的我們'
from .models import Task
admin.site.register(Task)
修改默認首頁
simpleui內置了一個默認的首頁，只是由簡單的快捷導航與最近操作組成。
在自己項目的settings.py中加入：
- 首頁配置
SIMPLEUI_HOME_PAGE = 'https://www.baidu.com'
- 首頁標題
SIMPLEUI_HOME_TITLE = '百度一下你就知道'
- 首頁圖標,支持element-ui和fontawesome的圖標，參考https://fontawesome.com/icons圖標
SIMPLEUI_HOME_ICON = 'fa fa-user'
三項配置都是選填，不填都會有默認值。 圖標列表
修復首頁跳轉地址
首頁頂部首頁圖標默認跳轉地址為/，即根目錄。如果需要自定義，請在項目的settings.py中加入設置：
# 設置simpleui 點擊首頁圖標跳轉的地址
SIMPLEUI_INDEX = 'https://www.88cto.com'
可以設置相對與絕對路徑。該地址並無特殊之處，將會調用window.open直接打開該地址。
修改LOGO
- 自定義SIMPLEUI的Logo
SIMPLEUI_LOGO = 'https://avatars2.githubusercontent.com/u/13655483?s=60&v=4'
配置首頁模塊
首頁默認展示3個模塊，服務器信息、快速操作、最近動作，大家可以根據需要來顯示或者隱藏某些模塊。
服務器信息
隱藏：
SIMPLEUI_HOME_INFO = False
顯示：
SIMPLEUI_HOME_INFO = True
快速操作
隱藏：
SIMPLEUI_HOME_QUICK = False
顯示：
SIMPLEUI_HOME_QUICK = True
最近動作
隱藏：
SIMPLEUI_HOME_ACTION = False
顯示：
SIMPLEUI_HOME_ACTION = True
使用分析
默認開啟，統計分析信息只是為了更好的幫助simpleui改進，並不會讀取敏感信息。並且分析數據不會分享至任何第三方。
SIMPLEUI_ANALYSIS = False
| 值 | 說明 |
|---|---|
| True | 收集分析，一天只上報一次分析數據。默認為True |
| False | 不收集分析信息 |
菜單
自定義菜單
system_keep 保留系統菜單
該字段用於告訴simpleui，是否需要保留系統默認的菜單，默認為False，不保留。
如果改為True，自定義和系統菜單將會並存
menu_display 過濾顯示菜單和排序功能
該字段用於告訴simpleui，是否需要開啟過濾顯示菜單和排序功能。
默認可以不用填寫，缺省配置為默認排序，不對菜單進行過濾和排序。
開啟認為傳一個列表，如果列表為空，則什么也不顯示。列表中的每個元素要對應到menus里面的name字段
dynamic 開啟動態菜單功能
該字段用於告訴simpleui，是否需要開啟動態菜單功能。
默認可以不用填寫，缺省配置為False，不開啟動態菜單功能。
開啟為True，開啟后，每次用戶登陸都會刷新左側菜單配置。
需要注意的是：開啟后每次訪問admin都會重讀配置文件，所以會帶來額外的消耗。
menus說明
| 字段 | 說明 |
|---|---|
| name | 菜單名 |
| icon | 圖標，參考element-ui和fontawesome圖標 |
| url | 鏈接地址，絕對或者相對,如果存在models字段，將忽略url |
| models | 子菜單 |
例子
import time
SIMPLEUI_CONFIG = {
'system_keep': False,
'menu_display': ['Simpleui', '測試', '權限認證', '動態菜單測試'], # 開啟排序和過濾功能, 不填此字段為默認排序和全部顯示, 空列表[] 為全部不顯示.
'dynamic': True, # 設置是否開啟動態菜單, 默認為False. 如果開啟, 則會在每次用戶登陸時動態展示菜單內容
'menus': [{
'name': 'Simpleui',
'icon': 'fas fa-code',
'url': 'https://gitee.com/tompeppa/simpleui'
}, {
'app': 'auth',
'name': '權限認證',
'icon': 'fas fa-user-shield',
'models': [{
'name': '用戶',
'icon': 'fa fa-user',
'url': 'auth/user/'
}]
}, {
'name': '測試',
'icon': 'fa fa-file',
'models': [{
'name': 'Baidu',
'url': 'http://baidu.com',
'icon': 'far fa-surprise'
}, {
'name': '內網穿透',
'url': 'https://www.wezoz.com',
'icon': 'fab fa-github'
}]
}, {
'name': '動態菜單測試' ,
'icon': 'fa fa-desktop',
'models': [{
'name': time.time(),
'url': 'http://baidu.com',
'icon': 'far fa-surprise'
}]
}]
}
如果SIMPLEUI_CONFIG中存在menus字段，將會覆蓋系統默認菜單。並且menus中輸出的菜單不會受權限控制。
默認圖標
simpleui對所有菜單提供了一個默認的file圖標，是為了統一風格。也許你並不喜歡，你可以選擇關閉默認圖標
SIMPLEUI_DEFAULT_ICON = False
| 值 | 說明 |
|---|---|
| True | 開啟默認圖標，默認為True |
| False | 關閉默認圖標 |
自定義圖標
simpleui僅為系統默認模塊提供了圖標，如果要為其他模塊指定圖標，可以自定義配置。圖標參考請查閱：圖標說明
優先級：
自定義->系統配圖->默認圖標
注：simpleui 原則上不涉及代碼，所以采用setting方式。后續可考慮擴展Model的 Meta class 進行配置圖標
| 字段 | 說明 |
|---|---|
| name | 模塊名字，請注意不是model的命名，而是菜單欄上顯示的文本，因為model是可以重復的，會導致無法區分 |
| icon | 圖標 |
例子：
SIMPLEUI_ICON = {
'系統管理': 'fab fa-apple',
'員工管理': 'fas fa-user-tie'
}
修改模板
在simpleui的基礎上修改模板需要對django有一定了解
- 先把simpleui克隆到靜態目錄下，參考克隆靜態文件到根目錄
- 找到靜態目錄下的admin目錄，里面就是simpleui的模板，直接修改相關html頁面即可生效。
開發調試
如果想在simpleui的基礎上進行一些修改，可以參考以下步驟
-
安裝simpleui到項目中
-
找到simpleui的目錄，然后刪除
-
克隆simpleui源碼到本地
-
Linux、Unix、macOS環境下用軟連接的方式，把項目依賴包中的simpleui目錄指定到源碼的simpleui目錄
ln -s 源文件 目標文件 -
windows環境下請右鍵創建快捷方式
接下來就可以修改、發布simpleui了。如有疑問請加入QQ群：786576510
源碼安裝到本地
- 克隆源碼本地安裝
git clone https://github.com/newpanjing/simpleui
cd simpleui
python setup.py sdist install
后續步驟請參考修改默認后台模板為simpleui
重寫頁面
例如重寫首頁，在templates目錄中新建admin文件夾，然后添加index.html
如果選擇繼承方式，就只能采用block
代碼如下：
{% extends 'admin/index.html' %}
{% load static %}
{% block head %}
{{ block.super }}
..此處寫你的代碼
{% endblock %}
{% block script %}
{{ block.super }}
..此處寫你的代碼
{% endblock %}
如果是想全部重寫：
<html>
<head>
<title>完全自定義</title>
</head>
<body>
這里你是自定義的html代碼
</body>
</html>
頭部添加自定義代碼
{% extends 'admin/index.html' %}
{% load static %}
{% block head %}
{{ block.super }}
..此處寫你的代碼
{% endblock %}
底部添加自定義代碼
{% extends 'admin/index.html' %}
{% load static %}
{% block script %}
{{ block.super }}
..此處寫你的代碼
{% endblock %}
自定義按鈕
需要在2.1.2以上版本生效
django admin 默認提供了自定義按鈕的支持，但是樣式、圖標均不可自定義，simpleui在django admin 自定義action的基礎上增加了樣式、圖標、按鈕類型自定義。
代碼：
@admin.register(Employe)
class EmployeAdmin(admin.ModelAdmin):
list_display = ('id', 'name', 'gender', 'idCard', 'phone', 'birthday', 'department', 'enable', 'create_time')
# 增加自定義按鈕
actions = ['make_copy', 'custom_button']
def custom_button(self, request, queryset):
pass
# 顯示的文本，與django admin一致
custom_button.short_description = '測試按鈕'
# icon，參考element-ui icon與https://fontawesome.com
custom_button.icon = 'fas fa-audio-description'
# 指定element-ui的按鈕類型，參考https://element.eleme.cn/#/zh-CN/component/button
custom_button.type = 'danger'
# 給按鈕追加自定義的顏色
custom_button.style = 'color:black;'
def make_copy(self, request, queryset):
pass
make_copy.short_description = '復制員工'
該配置與原生admin兼容。
字段：
| 字段 | 說明 |
|---|---|
| icon | 按鈕圖標，參考https://element.eleme.cn/#/zh-CN/component/icon與https://fontawesome.com，把class 復制進來即可 |
| type | 按鈕類型，參考：https://element.eleme.cn/#/zh-CN/component/button |
| style | 自定義css樣式 |
| confirm | 彈出確認框，在3.4或以上版本中生效 |
- confirm 例子
def message_test(self, request, queryset):
messages.add_message(request, messages.SUCCESS, '操作成功123123123123')
# 給按鈕增加確認
message_test.confirm = '你是否執意要點擊這個按鈕？'
- 鏈接按鈕
在2.9或以上版本中生效
| 字段 | 說明 |
|---|---|
| action_type | 按鈕動作類型，0=當前頁內打開，1=新tab打開，2=瀏覽器tab打開 |
| action_url | 按鈕訪問鏈接 |
demo：
# 增加自定義按鈕
actions = ['custom_button']
def custom_button(self, request, queryset):
pass
# 顯示的文本，與django admin一致
custom_button.short_description = '測試按鈕'
# icon，參考element-ui icon與https://fontawesome.com
custom_button.icon = 'fas fa-audio-description'
# 指定element-ui的按鈕類型，參考https://element.eleme.cn/#/zh-CN/component/button
custom_button.type = 'danger'
# 給按鈕追加自定義的顏色
custom_button.style = 'color:black;'
# 鏈接按鈕，設置之后直接訪問該鏈接
# 3中打開方式
# action_type 0=當前頁內打開，1=新tab打開，2=瀏覽器tab打開
# 設置了action_type，不設置url，頁面內將報錯
# 設置成鏈接類型的按鈕后，custom_button方法將不會執行。
custom_button.action_type = 0
custom_button.action_url = 'http://www.baidu.com'
離線模式
在2.1.3或以上的版本中生效
在settings.py中加入
SIMPLEUI_STATIC_OFFLINE = True
指定simpleui 是否以脫機模式加載靜態資源，為True的時候將默認從本地讀取所有資源，即使沒有聯網一樣可以。適合內網項目
不填該項或者為False的時候，默認從第三方的cdn獲取
關閉Loading遮罩層
在2.1.5或以上的版本中生效
在settings.py中加入
SIMPLEUI_LOADING = False
True或None 默認顯示加載遮罩層，指定為False 不顯示遮罩層。默認顯示
admindoc
admindoc需要simpleui 3.3+ 版本
常見問題
settings.py 找不到
這個文件是在自己創建的django項目中，不是在simpleui中。如果你熟悉django就會明白，如果不熟悉請先學習django。[django中文文檔](https://docs.djangoproject.com/zh-hans/2.2/)
python版本問題
+ 該項目推薦使用python3，python2.x可能會不兼容
+ 使用源碼安裝時如果出錯，請指定python版本，python3 和 pip3
無法啟動
可能由於某些未知的問題，導致項目無法啟動，請不要放棄simpleui，你可以提issue，或者直接加入QQ群：786576510，我們將協助解決。
樣式正常加載顯示不正常
在win8 系統中 可能會遇到，css以及其他文件全部正常加載，但是顯示不正常。這是因為響應頭為application/x-css，而不是text/css，造成瀏覽器不正常解析。
解決辦法：
1.運行cmd： 輸入regedit 並回車
2.在注冊表HKEY_CLASSES_ROOT中找到.css 點擊.css文件夾 修改Content Type 為 text/css
參考連接：https://blog.csdn.net/sun754276603/article/details/46989965
其他更多問題，請提交issues給我們。