admiral
v5.9.7
嘗試現場演示
Admiral 是一個用於在 React 中建立後台的前端框架。它提供了開箱即用的元件和工具，使管理介面的開發變得簡單又快速。
用？由 dev.family 提供
要求：
安裝 Admiral 有多種選項：
要使用 npx，請確保您有Node.js
npx create-admiral-app@latest當您在控制台中輸入此命令時，您將看到 2 個安裝選項：
如果您選擇“在 Express.js 上安裝帶有後端設定的範本”，您將在 Express.js 上安裝帶有後端的完全自訂範本。
詳細的安裝和啟動說明
所有環境變數都會自動設定。如果您想手動配置它們，請轉到專案資料夾並打開.env。從一開始你就會有 1 個 CRUD -用戶。要找到他們，請透過 - admiral/src/crud/users/index.tsx
如果您選擇“安裝範本而不使用後端設定”，您將僅在 admiral 資料夾中透過 CRUD- Users獲得 Admiral 的前端 shell。要找到它，請通過 - admiral/src/crud/users/index.tsx 。若要使用您的後端，請閱讀文檔
Admiral 的位址為 http://localhost:3000。如果連接埠 3000 繁忙，則會選擇任何其他空閒連接埠。
在控制台中你會看到類似這樣的內容
Port 3000 is in use, trying another one...
vite v2.9.15 dev server running at:
> Local: http://localhost:3001/
> Network: http://192.168.100.82:3001/
ready in 459ms.每個範例中都有詳細的安裝和啟動說明。
開啟瀏覽器並造訪 http://localhost:3000。
是的，沒錯。您可以克隆此存儲庫並輸入以下命令：
yarn
yarn dev然後造訪http://localhost:3000。現在您可以使用具有模擬數據的海軍上將。
App.tsx 檔案是應用程式的入口點。這是庫初始化的地方以及元件渲染的地方Admin 。
import React from 'react'
import { Admin , createRoutesFrom , OAuthProvidersEnum } from '../admiral'
import Menu from './config/menu'
import dataProvider from './dataProvider'
import authProvider from './authProvider'
const apiUrl = '/api'
// import all pages from pages folder and create routes
const Routes = createRoutesFrom ( import . meta . globEager ( '../pages/**/*' ) )
function App ( ) {
return (
< Admin
dataProvider = { dataProvider ( apiUrl ) }
authProvider = { authProvider ( apiUrl ) }
menu = { Menu }
oauthProviders = { [
OAuthProvidersEnum . Google ,
OAuthProvidersEnum . Github ,
OAuthProvidersEnum . Jira ,
] }
>
< Routes />
</ Admin >
)
}
export default App系統中授權的主要契約是介面AuthProvider 。
export interface AuthProvider {
login : ( params : any ) => Promise < any >
logout : ( params : any ) => Promise < void | false | string >
checkAuth : ( params : any ) => Promise < void >
getIdentity : ( ) => Promise < UserIdentity >
oauthLogin ?: ( provider : OAuthProvidersEnum ) => Promise < { redirect : string } >
oauthCallback ?: ( provider : OAuthProvidersEnum , data : string ) => Promise < any >
[ key : string ] : any
}實作範例 介面本身可以根據您的喜好進行定制，但尊重它提供的契約很重要。詳細合約說明
我們來看看基本的實作方法：
| 方法 | 姓名 | 描述 | 參數 | 傳回值 |
|---|---|---|---|---|
| 登入 | 使用者認證 | 向/api/login發出 POST 請求，並將token欄位儲存在 localStorage 中，以供後續請求使用 | params - 包含username和password的對象 | 具有token欄位的物件和具有email和name欄位的user對象 |
| 註銷 | 用戶登出 | 向/api/logout發出 POST 請求並從 localStorage 中刪除token字段 | void | |
| 檢查驗證 | 使用者授權檢查 | 向/api/checkAuth發出 GET 請求並檢查令牌有效性，需要狀態代碼 - 200。 | 不記名token | 狀態碼200 |
| 取得身份 | 接收用戶數據 | 向/api/getIdentity發出 GET 請求並傳回包含使用者資料的對象 | 不記名token | 具有email和name欄位的物件user |
| 登入 | 透過 OAuth 授權 | 向/api/auth/social-login/${provider}發出 GET 請求並傳回帶有redirect欄位的對象，該物件用於重定向 | provider - OAuth 提供者 | 具有字段redirect的對象 |
| oauth回調 | 透過OAuth回調授權 | 向/api/auth/social-login/${provider}/callback發出 POST 請求，並將token欄位儲存在 localStorage 中，以在進一步的請求中使用 | provider - OAuth 提供者， data - 從存在token欄位的 OAuth 提供者接收的數據 | 帶有字段token對象 |
處理資料的主要合約代表介面DataProvider 。
export interface DataProvider {
getList : (
resource : string ,
params : Partial < GetListParams > ,
) => Promise < GetListResult < RecordType > >
reorderList : ( resource : string , params : ReorderParams ) => Promise < void >
getOne : ( resource : string , params : GetOneParams ) => Promise < GetOneResult < RecordType > >
getCreateFormData : ( resource : string ) => Promise < GetFormDataResult < RecordType > >
getFiltersFormData : (
resource : string ,
urlState ?: Record < string , any > ,
) => Promise < GetFiltersFormDataResult >
create : ( resource : string , params : CreateParams ) => Promise < CreateResult < RecordType > >
getUpdateFormData : (
resource : string ,
params : GetOneParams ,
) => Promise < GetFormDataResult < RecordType > >
update : ( resource : string , params : UpdateParams ) => Promise < UpdateResult < RecordType > >
deleteOne : ( resource : string , params : DeleteParams ) => Promise < DeleteResult < RecordType > >
[ key : string ] : any
}實施範例 詳細的合約描述
我們來看看基本的實作方法：
| 方法 | 姓名 | 描述 | 參數 |
|---|---|---|---|
| 取得列表 | 取得實體列表 | 向/api/${resource}發出 GET 請求並傳回一個對象，其中包含要在List元件中使用的數據 | resource - 資源名稱， params - 帶有查詢參數的對象 |
| 重新排序列表 | 更改實體的順序 | 向/api/${resource}/reorder發出 POST 請求並傳回一個對象，其中包含要在List元件中使用的數據 | resource - 資源名稱， params - 帶有查詢參數的對象 |
| 得到一個 | 取得實體 | 向/api/${resource}/${id}發出 GET 請求並傳回一個對象，其中包含要在Show元件中使用的數據 | resource - 資源名稱， id - 實體識別符 |
| 取得建立表單數據 | 取得實體建立表單的資料（Select、AjaxSelect） | 向/api/${resource}/create發出 GET 請求並傳回一個對象，其中包含要在Create元件中使用的數據 | resource -資源名稱 |
| 取得篩選器表單數據 | 接收過濾器數據 | 向/api/${resource}/filters發出 GET 請求並傳回一個對象，其中包含要在Filters組件中使用的數據 | resource - 資源名稱， urlState - 帶有要在元件Filters中使用的 url 參數的對象 |
| 創造 | 建立實體 | 向/api/${resource}發出 POST 請求並傳回一個對象，其中包含要在元件Create中使用的數據 | resource - 資源名稱， params - 實體資料對象 |
| 取得更新表單數據 | 取得實體編輯表單的資料（Select、AjaxSelect） | 向/api/${resource}/${id}/update發出 GET 請求並傳回一個對象，其中包含要在元件Edit中使用的數據 | resource - 資源名稱， id - 實體識別符 |
| 更新 | 更新實體 | 向/api/${resource}/${id}發出 POST 請求並傳回一個對象，其中包含要在元件Edit中使用的數據 | resource - 資源名稱， id - 實體標識符， params - 實體資料對象 |
| 刪除 | 刪除實體 | 向/api/${resource}/${id}發出 DELETE 請求並傳回一個對象，其中包含要在元件Delete中使用的數據 | resource - 資源名稱， id - 實體識別符 |
詢問：
http://localhost/admin/users?page=1&perPage=10&filter%5Bid%5D=1結果：
{
"items" : [
{
"id" : 1 ,
"name" : " Dev family " ,
"email" : " [email protected] " ,
"role" : " Administrator " ,
"created_at" : " 2023-05-05 14:17:51 "
}
],
"meta" : {
"current_page" : 1 ,
"from" : 1 ,
"last_page" : 1 ,
"per_page" : 10 ,
"to" : 1 ,
"total" : 1
}
}詢問：
http://localhost/admin/users/1/update?id=1結果：
{
"data" : {
"id" : 1 ,
"name" : " Dev family " ,
"email" : " [email protected] " ,
"role_id" : 1
},
"values" : {
"role_id" : [
{
"label" : " Administrator " ,
"value" : 1
}
]
}
}❗注意：我們利用 HTTP 狀態碼 422 Unprocessable Entity 來處理驗證錯誤。
{
"errors" : {
"name" : [ " Field 'name' is invalid. " ],
"email" : [ " Field 'email' is invalid. " ]
},
"message" : " Validation failed "
}分頁與getList方法一起使用。您可以將page和perPage參數傳遞給getList方法，它將傳回帶有items和meta欄位的PaginationResult物件。
過濾器與getList方法一起使用。您可以將filter[$field]參數傳遞給getList方法，它將傳回帶有items和meta欄位的PaginationResult物件。
使用getList方法進行排序。您可以將sort[$field]參數傳遞給getList方法，它將傳回帶有items和meta欄位的PaginationResult物件。
Admiral 有一個基於檔案系統的路由器。
頁面是從頁面目錄中的 .js、.jsx、.ts 或 .tsx 檔案匯出的 React 元件。當檔案新增到頁面目錄時，它會自動作為路由使用。 React-router-dom 幕後使用。
路由器會自動將名為index的檔案路由到目錄的根目錄。
pages/index.ts → / pages/users/index.ts → /users
路由器支援嵌套檔案。如果您建立嵌套資料夾結構，檔案仍將以相同的方式自動路由。
pages/users/create.ts → /users/create
要匹配動態段，可以使用括號語法。這允許您匹配命名參數。
pages/users/[id].ts → /users/:id (/users/42)
該元件是您的管理面板中最重要的元件。有了它，您可以設定應用程式的基本設定和配置，例如：導航、標誌、向伺服器請求的 api、api 授權、本地化、主題等。
使用範例：
< Admin
dataProvider = { dataProvider ( apiUrl ) }
authProvider = { authProvider ( apiUrl ) }
menu = { Menu }
oauthProviders = { [
OAuthProvidersEnum . Google ,
OAuthProvidersEnum . Github ,
OAuthProvidersEnum . Jira ,
] }
>
< Routes />
</ Admin >該組件接受以下屬性：
選單
在這裡您可以自訂您的導航。您應該使用我們套件中的特殊元件：Menu、MenuItemLink、SubMenu。您可以在這裡找到一個範例。
標識
您可以變更旁邊導覽列中顯示的徽標。此屬性接受 svg、JSX 元件或 svg 格式檔案的連結。
登入標誌
您可以變更授權表中顯示的徽標。此屬性接受 svg、JSX 元件或 svg 格式檔案的連結。
旁白內容
使用此工具，您可以將必要的內容新增至連結下方的旁側導覽列。你必須透過ReactNode。
數據提供者
處理資料的主要合約。您可以在我們的文件中獲取更多資訊。
授權提供者
系統中授權的主合約。您可以在我們的文件中獲取更多資訊。
主題預設
您可以為您的應用程式自訂顏色主題。您可以在我們的文件中獲取更多資訊。
語言環境
管理面板的本地化方案，您可以使用 useLocaleProvider 掛鉤來取得。您可以在此處找到該方案的範例。
oauthProviders
使用此道具進行 OAuth 授權。使用來自 admiral 的 OAuthProvidersEnum 枚舉在陣列中傳遞所需提供者的名稱。
基本應用程式 URL
新增道具以更改應用程式的基本路徑。
選單是具有以下結構的物件數組：
import { Menu , SubMenu , MenuItemLink } from '../../admiral'
const CustomMenu = ( ) => {
return (
< Menu >
< MenuItemLink icon = "FiCircle" name = "First Menu Item" to = "/first" />
< SubMenu icon = "FiCircle" name = "Second Menu Item" >
< MenuItemLink icon = "FiCircle" name = "Sub Menu Item" to = "/second" />
</ SubMenu >
</ Menu >
)
}
export default CustomMenu我們的應用程式使用 React hooks。您可以在 React 元件內的應用程式中的任何位置使用它們。這些是您可以使用的鉤子：
此鉤子可讓您接收和管理導覽列的狀態
import { useNav } from '@devfamily/admiral'
const { collapsed , toggleCollapsed , visible , toggle , open , close } = useNav ( )此掛鉤可讓您取得表單值並管理表單的狀態。此鉤子可以在 createCRUD 函數配置中的“form”中使用的元件中使用。
import { useForm } from '@devfamily/admiral'
const {
values ,
options ,
errors ,
setErrors ,
setValues ,
setOptions ,
isSubmitting ,
isFetching ,
locale ,
} = useForm ( )此掛鉤允許您接收和管理主題的狀態。
import { useTheme } from '@devfamily/admiral'
const { themeName , setTheme } = useTheme ( )一個鉤子，允許您取得透過呼叫 AuthProvider.getIdentity() 所獲得的狀態
import { useGetIdentty } from '@devfamily/admiral'
const { identity , loading , loaded , error } = useGetIdentty ( )Admiral 中使用的圖示來自 React Icons。
ThemeProvider 在底層使用 @consta/uikit 主題組件。
您可以使用themePresets屬性將預設傳遞給Admin元件：
import React from 'react'
import { Admin , createRoutesFrom } from '../admiral'
import Menu from './config/menu'
import dataProvider from './dataProvider'
import authProvider from './authProvider'
import themeLight from './theme/presets/themeLight'
import themeDark from './theme/presets/themeDark'
const apiUrl = '/api'
const Routes = createRoutesFrom ( import . meta . globEager ( '../pages/**/*' ) )
function App ( ) {
return (
< Admin
dataProvider = { dataProvider ( apiUrl ) }
authProvider = { authProvider ( apiUrl ) }
menu = { Menu }
themePresets = { { light : themeLight , dark : themeDark } }
>
< Routes />
</ Admin >
)
} 建立預設目錄。在每個修飾符的 make 資料夾中 - 與主題組件中的相同。
建立 CSS 檔案。在帶有修飾符的資料夾中放置負責這些修飾符的 CSS 檔案。
你會得到類似的東西：
presets/
_color/
_Theme_color_themeDark.css
_Theme_color_themeLight.css
_control/
_Theme_control_themeLight.css
_font/
_Theme_font_themeLight.css
_size/
_Theme_size_themeLight.css
_space/
_Theme_space_themeLight.css
_shadow/
_Theme_shadow_themeLight.css
themeLight.ts
themeDark.ts
配置 CSS 檔案中的變數。
建立預設檔案（themeLight、themeDark）。
匯入您要使用的 CSS 檔案。
建立預設物件。指定在預設中使用哪些修飾符的哪些值（即 CSS 檔案）。你會得到類似的東西：
// in presets/themeLight.ts
import './_color/_Theme_color_themeLight.css'
import './_color/_Theme_color_themeDark.css'
import './_control/_Theme_control_themeLight.css'
import './_font/_Theme_font_themeLight.css'
import './_size/_Theme_size_themeLight.css'
import './_space/_Theme_space_themeLight.css'
import './_shadow/_Theme_shadow_themeLight.css'
export default {
color : {
primary : 'themeLight' ,
accent : 'themeDark' ,
invert : 'themeDark' ,
} ,
control : 'themeLight' ,
font : 'themeLight' ,
size : 'themeLight' ,
space : 'themeLight' ,
shadow : 'themeLight' ,
}將您的預設傳遞給Admin元件，如上例所示。
❗注意：postcss 外掛程式用於 admiral 預設範例中的顏色轉換。如果你想重現，請設定 postcss 和 postcss-color-mod-function 外掛。
如果您想參與 Admiral 的開發，請將儲存庫進行分叉，進行所需的變更並發送拉取請求。我們很樂意考慮您的建議！
該庫是根據 MIT 許可證分發的。
如果您有任何疑問，請透過以下方式與我們聯絡：[email protected] 我們很高興收到您的回饋！
