admiral
v5.9.7
Coba demo langsung
Admiral adalah kerangka frontend untuk membuat back office di React. Ini menyediakan komponen dan alat out-of-the-box yang membuat pengembangan antarmuka admin menjadi mudah dan cepat.
Dibuat dengan? oleh dev.family
Persyaratan:
Ada beberapa opsi untuk menginstal Admiral:
Untuk menggunakan npx, pastikan Anda memiliki Node.js
npx create-admiral-app@latestSaat Anda memasukkan perintah ini ke konsol, Anda akan melihat 2 opsi instalasi:
Jika Anda memilih " Instal templat dengan pengaturan backend di Express.js ", Anda akan menginstal templat yang sepenuhnya disesuaikan dengan backend di Express.js.
Petunjuk instalasi dan permulaan yang terperinci
Semua variabel lingkungan akan diatur secara otomatis. Jika Anda ingin mengonfigurasinya secara manual, buka folder proyek dan buka .env. Anda akan memiliki 1 CRUD dari awal - Users . Untuk menemukannya, lewati saja - admiral/src/crud/users/index.tsx
Jika Anda memilih " Instal template tanpa pengaturan backend ", Anda hanya mendapatkan shell frontend Admiral di folder admiral dengan CRUD - Users . Untuk menemukannya lewati saja - admiral/src/crud/users/index.tsx . Untuk menggunakan backend Anda, baca Dokumentasi
Laksamana tersedia di http://localhost:3000. Jika port 3000 sibuk, port bebas lainnya akan dipilih.
Di konsol Anda akan melihat sesuatu seperti ini
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.Petunjuk instalasi dan pengaktifan terperinci ada di setiap contoh.
Buka browser Anda dan buka http://localhost:3000.
Ya itu benar. Anda cukup mengkloning repositori ini dan memasukkan perintah berikut:
yarn
yarn devLalu pergi ke http://localhost:3000. Laksamana dengan data tiruan kini tersedia untuk Anda.
File App.tsx adalah titik masuk ke dalam aplikasi. Di sinilah perpustakaan diinisialisasi dan komponen dirender 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 Kontrak utama untuk otorisasi dalam sistem adalah antarmuka 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
}Contoh implementasi Antarmukanya sendiri dapat disesuaikan dengan keinginan Anda, namun penting untuk menghormati kontrak yang diberikannya. Deskripsi kontrak terperinci
Mari kita lihat metode dasar implementasinya:
| Metode | Nama | Keterangan | Parameter | Nilai kembalian |
|---|---|---|---|---|
| login | Otentikasi Pengguna | Membuat permintaan POST ke /api/login dan menyimpan bidang token di Penyimpanan lokal, yang digunakan dalam permintaan selanjutnya | params - objek dengan kolom username dan password | Objek dengan bidang token dan objek user dengan bidang email dan name |
| keluar | Keluar Pengguna | Membuat permintaan POST ke /api/logout dan menghapus bidang token dari Penyimpanan lokal | void | |
| periksaAuth | Pemeriksaan otorisasi pengguna | Membuat permintaan GET ke /api/checkAuth dan memeriksa validitas token, mengharapkan kode status - 200. Digunakan setiap kali API digunakan | token pembawa | Kode status 200 |
| dapatkan Identitas | Menerima data pengguna | Membuat permintaan GET ke /api/getIdentity dan mengembalikan objek dengan data pengguna | token pembawa | Objek user dengan bidang email dan name |
| oauthLogin | Otorisasi melalui OAuth | Membuat permintaan GET ke /api/auth/social-login/${provider} dan mengembalikan objek dengan bidang redirect , yang digunakan untuk pengalihan | provider - penyedia OAuth | Objek dengan bidang redirect |
| oauthCallback | Otorisasi panggilan balik melalui OAuth | Membuat permintaan POST ke /api/auth/social-login/${provider}/callback dan menyimpan bidang token di localStorage, yang digunakan dalam permintaan selanjutnya | provider - penyedia OAuth, data - data yang diterima dari penyedia OAuth tempat bidang token berada | Objek dengan token bidang |
Kontrak utama untuk bekerja dengan data mewakili antarmuka 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
}Contoh implementasi Deskripsi kontrak terperinci
Mari kita lihat metode dasar implementasinya:
| Metode | Nama | Keterangan | Parameter |
|---|---|---|---|
| dapatkanDaftar | Mendapatkan daftar entitas | Membuat permintaan GET ke /api/${resource} dan mengembalikan objek dengan data untuk digunakan dalam komponen List | resource - nama sumber daya, params - objek dengan parameter kueri |
| menyusun ulang Daftar | Mengubah urutan entitas | Membuat permintaan POST ke /api/${resource}/reorder dan mengembalikan objek dengan data untuk digunakan dalam komponen List | resource - nama sumber daya, params - objek dengan parameter kueri |
| dapatkanSatu | Memperoleh suatu entitas | Membuat permintaan GET ke /api/${resource}/${id} dan mengembalikan objek dengan data untuk digunakan dalam komponen Show | resource - nama sumber daya, id - pengidentifikasi entitas |
| dapatkanCreateFormData | Mendapatkan data untuk formulir pembuatan entitas (Pilih, AjaxSelect) | Membuat permintaan GET ke /api/${resource}/create dan mengembalikan objek dengan data untuk digunakan dalam komponen Create | resource - nama sumber daya |
| dapatkanFiltersFormData | Menerima data untuk filter | Membuat permintaan GET ke /api/${resource}/filters dan mengembalikan objek dengan data untuk digunakan dalam komponen Filters | resource - nama sumber daya, urlState - objek dengan parameter dari url yang akan digunakan dalam komponen Filters |
| membuat | Membuat Entitas | Membuat permintaan POST ke /api/${resource} dan mengembalikan objek dengan data untuk digunakan dalam komponen Create | resource - nama sumber daya, params - objek data entitas |
| dapatkanUpdateFormData | Mendapatkan data untuk formulir edit entitas (Pilih, AjaxSelect) | Membuat permintaan GET ke /api/${resource}/${id}/update dan mengembalikan objek dengan data untuk digunakan dalam komponen Edit | resource - nama sumber daya, id - pengidentifikasi entitas |
| memperbarui | Memperbarui suatu entitas | Membuat permintaan POST ke /api/${resource}/${id} dan mengembalikan objek dengan data yang akan digunakan dalam komponen Edit | resource - nama sumber daya, id - pengidentifikasi entitas, params - objek data entitas |
| menghapus | Menghapus Entitas | Membuat permintaan DELETE ke /api/${resource}/${id} dan mengembalikan objek dengan data untuk digunakan dalam komponen Delete | resource - nama sumber daya, id - pengidentifikasi entitas |
Pertanyaan:
http://localhost/admin/users?page=1&perPage=10&filter%5Bid%5D=1Hasil:
{
"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
}
}Pertanyaan:
http://localhost/admin/users/1/update?id=1Hasil:
{
"data" : {
"id" : 1 ,
"name" : " Dev family " ,
"email" : " [email protected] " ,
"role_id" : 1
},
"values" : {
"role_id" : [
{
"label" : " Administrator " ,
"value" : 1
}
]
}
}❗ Catatan : Kami menggunakan kode status HTTP 422 Entitas yang Tidak Dapat Diproses untuk menangani kesalahan validasi.
{
"errors" : {
"name" : [ " Field 'name' is invalid. " ],
"email" : [ " Field 'email' is invalid. " ]
},
"message" : " Validation failed "
} Pagination berfungsi dengan metode getList . Anda dapat meneruskan parameter page dan perPage ke metode getList , dan metode ini akan mengembalikan objek PaginationResult dengan items dan bidang meta .
Filter berfungsi dengan metode getList . Anda dapat meneruskan parameter filter[$field] ke metode getList , dan itu akan mengembalikan objek PaginationResult dengan items dan bidang meta .
Penyortiran bekerja dengan metode getList . Anda dapat meneruskan parameter sort[$field] ke metode getList , dan metode tersebut akan mengembalikan objek PaginationResult dengan items dan bidang meta .
Admiral memiliki router berbasis sistem file .
Halaman adalah Komponen React yang diekspor dari file .js, .jsx, .ts, atau .tsx di direktori halaman. Saat file ditambahkan ke direktori halaman, file tersebut secara otomatis tersedia sebagai rute. react-router-dom digunakan di bawah tenda.
Router akan secara otomatis merutekan file bernama indeks ke akar direktori.
pages/index.ts → / pages/users/index.ts → /users
Router mendukung file bersarang. Jika Anda membuat struktur folder bersarang, file secara otomatis akan dirutekan dengan cara yang sama.
pages/users/create.ts → /users/create
Untuk mencocokkan segmen dinamis, Anda dapat menggunakan sintaks braket. Ini memungkinkan Anda untuk mencocokkan parameter bernama.
pages/users/[id].ts → /users/:id (/users/42)
Komponen ini adalah yang paling penting di panel admin Anda. Dengannya, Anda dapat mengatur pengaturan dasar dan konfigurasi aplikasi Anda, seperti: navigasi, logo, api untuk permintaan ke server, otorisasi api, pelokalan, tema, dan lain-lain.
Contoh penggunaan:
< Admin
dataProvider = { dataProvider ( apiUrl ) }
authProvider = { authProvider ( apiUrl ) }
menu = { Menu }
oauthProviders = { [
OAuthProvidersEnum . Google ,
OAuthProvidersEnum . Github ,
OAuthProvidersEnum . Jira ,
] }
>
< Routes />
</ Admin >Komponen menerima propses berikut:
menu
Di sini Anda dapat menyesuaikan navigasi Anda. Anda harus menggunakan komponen khusus dari paket kami: Menu, MenuItemLink, SubMenu. Anda dapat menemukan contohnya di sini.
logo
Anda dapat mengubah logo yang ditampilkan di navbar samping. Prop menerima tautan ke svg, komponen JSX, atau file dengan format svg.
loginLogo
Anda dapat mengubah logo yang ditampilkan di formulir otorisasi. Prop menerima tautan ke svg, komponen JSX, atau file dengan format svg.
selain Konten
Dengan alat ini, Anda dapat menambahkan konten yang diperlukan ke bilah navigasi samping di bawah tautan. Anda harus melewati ReactNode.
Penyedia data
Kontrak utama untuk bekerja dengan data. Anda dapat memperoleh info lebih lanjut di dokumentasi kami.
Penyedia autentikasi
Kontrak utama untuk otorisasi dalam sistem. Anda dapat memperoleh info lebih lanjut di dokumentasi kami.
temaPreset
Anda dapat menyesuaikan tema warna untuk aplikasi Anda. Anda dapat memperoleh info lebih lanjut di dokumentasi kami.
lokal
Skema pelokalan panel admin Anda, yang bisa Anda dapatkan menggunakan hook useLocaleProvider. Anda dapat menemukan contoh skemanya di sini.
Penyedia oauth
Gunakan otorisasi OAuth menggunakan alat peraga ini. Berikan nama penyedia yang diperlukan dalam array menggunakan OAuthProvidersEnum enum dari laksamana.
baseAppUrl
Tambahkan props untuk mengubah jalur dasar aplikasi.
Menu adalah array objek yang memiliki struktur berikut:
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 CustomMenuAplikasi kita menggunakan React hooks. Anda dapat menggunakannya dari mana saja dalam aplikasi di dalam komponen React. Ini adalah pengait yang dapat Anda gunakan:
Kait ini memungkinkan Anda menerima dan mengelola status bilah navigasi
import { useNav } from '@devfamily/admiral'
const { collapsed , toggleCollapsed , visible , toggle , open , close } = useNav ( )Kait ini memungkinkan Anda mendapatkan nilai formulir dan mengelola status formulir. Hook dapat digunakan pada komponen yang digunakan dalam "form" di dalam konfigurasi fungsi createCRUD.
import { useForm } from '@devfamily/admiral'
const {
values ,
options ,
errors ,
setErrors ,
setValues ,
setOptions ,
isSubmitting ,
isFetching ,
locale ,
} = useForm ( )Kait ini memungkinkan Anda menerima dan mengelola status tema.
import { useTheme } from '@devfamily/admiral'
const { themeName , setTheme } = useTheme ( )Sebuah hook yang memungkinkan Anda mendapatkan status yang diperoleh dengan memanggil AuthProvider.getIdentity()
import { useGetIdentty } from '@devfamily/admiral'
const { identity , loading , loaded , error } = useGetIdentty ( )Ikon yang digunakan di Admiral berasal dari React Icons.
ThemeProvider menggunakan komponen Tema @consta/uikit di bawah tenda.
Anda dapat meneruskan preset Anda ke komponen Admin dengan prop themePresets :
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 >
)
} Buat direktori untuk preset. Di dalamnya buat folder untuk setiap pengubah - sama seperti di komponen Tema.
Buat file CSS. Di folder dengan pengubah, letakkan file CSS yang akan bertanggung jawab atas pengubah tersebut.
Anda akan mendapatkan sesuatu yang serupa:
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
Konfigurasikan variabel dalam file CSS.
Buat file preset (themeLight, themeDark).
Impor file CSS yang akan Anda gunakan.
Buat objek preset. Tentukan nilai mana (yaitu file CSS) untuk pengubah mana yang akan digunakan dalam preset. Anda akan mendapatkan sesuatu yang serupa:
// 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' ,
} Teruskan preset Anda ke komponen Admin seperti pada contoh di atas.
❗ Catatan : plugin postcss digunakan untuk transformasi warna dalam contoh preset laksamana. Jika Anda ingin mereproduksi, siapkan plugin postcss dan postcss-color-mod-function.
Jika Anda ingin berpartisipasi dalam pengembangan Admiral, buat Fork repositori, buat perubahan yang diinginkan, dan kirimkan permintaan tarik. Kami akan dengan senang hati mempertimbangkan saran Anda!
Perpustakaan ini didistribusikan di bawah lisensi MIT.
Jika Anda memiliki pertanyaan, silakan hubungi kami di: [email protected] Kami selalu senang menerima tanggapan Anda!
