admiral
v5.9.7
Probieren Sie eine Live-Demo aus
Admiral ist ein Frontend-Framework zum Erstellen eines Backoffices in React. Es bietet sofort einsatzbereite Komponenten und Tools, die die Entwicklung einer Admin-Schnittstelle einfach und schnell machen.
Hergestellt mit ? von dev.family
Anforderungen:
Für die Installation von Admiral gibt es mehrere Möglichkeiten:
Um npx zu verwenden, stellen Sie sicher, dass Sie über Node.js verfügen
npx create-admiral-app@latestWenn Sie diesen Befehl in die Konsole eingeben, werden Ihnen zwei Installationsoptionen angezeigt:
Wenn Sie „ Vorlage mit Backend-Einstellung auf Express.js installieren “ wählen, installieren Sie die vollständig angepasste Vorlage mit Backend auf Express.js.
Detaillierte Installations- und Inbetriebnahmeanweisungen
Alle Umgebungsvariablen werden automatisch festgelegt. Wenn Sie sie manuell konfigurieren möchten, gehen Sie zum Projektordner und öffnen Sie die .env. Sie verfügen von Anfang an über 1 CRUDs – Benutzer . Um sie zu finden, gehen Sie den Weg - admiral/src/crud/users/index.tsx
Wenn Sie „ Vorlage ohne Backend-Einstellung installieren “ wählen, erhalten Sie nur die Frontend-Shell von Admiral im Admiral-Ordner mit CRUD- Benutzern . Um es zu finden, gehen Sie zu admiral/src/crud/users/index.tsx . Um Ihr Backend zu verwenden, lesen Sie die Dokumentation
Admiral ist unter http://localhost:3000 verfügbar. Wenn Port 3000 belegt ist, wird jeder andere freie Port ausgewählt.
In der Konsole sehen Sie so etwas
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.Detaillierte Installations- und Startanweisungen finden Sie in jedem der Beispiele.
Öffnen Sie Ihren Browser und gehen Sie zu http://localhost:3000.
Ja, das stimmt. Sie können dieses Repository einfach klonen und die folgenden Befehle eingeben:
yarn
yarn devGehen Sie dann zu http://localhost:3000. Der Admiral mit Scheindaten steht Ihnen jetzt zur Verfügung.
Die App.tsx-Datei ist der Einstiegspunkt in die Anwendung. Hier wird die Bibliothek initialisiert und die Komponenten 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 Der Hauptvertrag für die Autorisierung im System ist die Schnittstelle 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
}Beispiel für eine Implementierung Die Schnittstelle selbst kann nach Ihren Wünschen angepasst werden, es ist jedoch wichtig, den darin enthaltenen Vertrag zu respektieren. Detaillierte Vertragsbeschreibung
Schauen wir uns die grundlegenden Implementierungsmethoden an:
| Verfahren | Name | Beschreibung | Parameter | Rückgabewert |
|---|---|---|---|---|
| Login | Benutzerauthentifizierung | Stellt eine POST-Anfrage an /api/login und speichert das token Feld in localStorage, das in weiteren Anfragen verwendet wird | params – Objekt mit den Feldern username und password | Ein Objekt mit einem token -Feld und ein user mit email und name |
| Abmelden | Benutzerabmeldung | Stellt eine POST-Anfrage an /api/logout und entfernt das token Feld aus localStorage | void | |
| checkAuth | Überprüfung der Benutzerberechtigung | Stellt eine GET-Anfrage an /api/checkAuth und prüft die Gültigkeit des Tokens. Erwartet einen Statuscode – 200. Wird bei jeder Verwendung der API verwendet | token | Statuscode 200 |
| getIdentity | Empfangen von Benutzerdaten | Stellt eine GET-Anfrage an /api/getIdentity und gibt ein Objekt mit Benutzerdaten zurück | token | user mit den Feldern email und name |
| oauthLogin | Autorisierung über OAuth | Stellt eine GET-Anfrage an /api/auth/social-login/${provider} und gibt ein Objekt mit dem redirect zurück, das für die Weiterleitung verwendet wird | provider – OAuth-Anbieter | Objekt mit dem Feld redirect |
| oauthCallback | Rückrufautorisierung über OAuth | Stellt eine POST-Anfrage an /api/auth/social-login/${provider}/callback und speichert das token Feld in localStorage, das in weiteren Anfragen verwendet wird | provider – OAuth-Anbieter, data – vom OAuth-Anbieter empfangene Daten, bei denen das token Feld vorhanden ist | Objekt mit dem token |
Der Hauptvertrag für die Arbeit mit Daten stellt die Schnittstelle DataProvider dar.
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
}Beispiel einer Umsetzung Ausführliche Vertragsbeschreibung
Schauen wir uns die grundlegenden Implementierungsmethoden an:
| Verfahren | Name | Beschreibung | Parameter |
|---|---|---|---|
| getList | Eine Liste von Entitäten abrufen | Stellt eine GET-Anfrage an /api/${resource} und gibt ein Objekt mit Daten zurück, die in der List verwendet werden sollen | resource – Ressourcenname, params – Objekt mit Abfrageparametern |
| Neuordnungsliste | Ändern der Reihenfolge von Entitäten | Stellt eine POST-Anfrage an /api/${resource}/reorder und gibt ein Objekt mit Daten zurück, die in der List verwendet werden sollen | resource – Ressourcenname, params – Objekt mit Abfrageparametern |
| getOne | Erhalten einer Entität | Stellt eine GET-Anfrage an /api/${resource}/${id} und gibt ein Objekt mit Daten zurück, die in der Show Komponente verwendet werden sollen | resource – Ressourcenname, id – Entitätskennung |
| getCreateFormData | Daten für ein Entitätserstellungsformular abrufen (Select, AjaxSelect) | Stellt eine GET-Anfrage an /api/${resource}/create und gibt ein Objekt mit Daten zurück, die in der Create Komponente verwendet werden sollen | resource – Ressourcenname |
| getFiltersFormData | Empfangen von Daten für Filter | Stellt eine GET-Anfrage an /api/${resource}/filters und gibt ein Objekt mit Daten zurück, die in der Filters verwendet werden sollen | resource – Ressourcenname, urlState – Objekt mit Parametern aus der URL, die in den Filters verwendet werden sollen |
| erstellen | Eine Entität erstellen | Stellt eine POST-Anfrage an /api/${resource} und gibt ein Objekt mit Daten zurück, die in der Komponente Create verwendet werden sollen | resource – Ressourcenname, params – Entitätsdatenobjekt |
| getUpdateFormData | Daten für ein Entitätsbearbeitungsformular abrufen (Select, AjaxSelect) | Stellt eine GET-Anfrage an /api/${resource}/${id}/update und gibt ein Objekt mit Daten zurück, die in der Komponente Edit verwendet werden sollen | resource – Ressourcenname, id – Entitätskennung |
| aktualisieren | Aktualisieren einer Entität | Stellt eine POST-Anfrage an /api/${resource}/${id} und gibt ein Objekt mit den Daten zurück, die in der Edit verwendet werden sollen | resource – Ressourcenname, id – Entitätskennung, params – Entitätsdatenobjekt |
| löschen | Eine Entität löschen | Stellt eine DELETE-Anfrage an /api/${resource}/${id} und gibt ein Objekt mit Daten zurück, die in der Komponente Delete verwendet werden sollen | resource – Ressourcenname, id – Entitätskennung |
Abfrage:
http://localhost/admin/users?page=1&perPage=10&filter%5Bid%5D=1Ergebnis:
{
"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
}
}Abfrage:
http://localhost/admin/users/1/update?id=1Ergebnis:
{
"data" : {
"id" : 1 ,
"name" : " Dev family " ,
"email" : " [email protected] " ,
"role_id" : 1
},
"values" : {
"role_id" : [
{
"label" : " Administrator " ,
"value" : 1
}
]
}
}❗ Hinweis : Wir verwenden den HTTP-Statuscode 422 Unprocessable Entity, um Validierungsfehler zu behandeln.
{
"errors" : {
"name" : [ " Field 'name' is invalid. " ],
"email" : [ " Field 'email' is invalid. " ]
},
"message" : " Validation failed "
} Paginierung funktioniert mit getList -Methode. Sie können page und perPage Parameter an die getList -Methode übergeben und sie gibt PaginationResult Objekt mit items und meta zurück.
Filter funktionieren mit getList -Methode. Sie können den Parameter filter[$field] an getList -Methode übergeben und sie gibt PaginationResult Objekt mit items und meta zurück.
Sortierarbeit mit der getList -Methode. Sie können den Parameter sort[$field] an getList -Methode übergeben und sie gibt PaginationResult Objekt mit items und meta zurück.
Admiral verfügt über einen dateisystembasierten Router.
Eine Seite ist eine React-Komponente, die aus einer .js-, .jsx-, .ts- oder .tsx-Datei im Verzeichnis der Seiten exportiert wird. Wenn eine Datei zum Seitenverzeichnis hinzugefügt wird, ist sie automatisch als Route verfügbar. React-Router-Dom wird unter der Haube verwendet.
Der Router leitet Dateien mit dem Namen index automatisch an das Stammverzeichnis des Verzeichnisses weiter.
pages/index.ts → / pages/users/index.ts → /users
Der Router unterstützt verschachtelte Dateien. Wenn Sie eine verschachtelte Ordnerstruktur erstellen, werden Dateien weiterhin automatisch auf die gleiche Weise weitergeleitet.
pages/users/create.ts → /users/create
Um ein dynamisches Segment abzugleichen, können Sie die Klammersyntax verwenden. Dadurch können Sie benannte Parameter abgleichen.
pages/users/[id].ts → /users/:id (/users/42)
Diese Komponente ist die wichtigste in Ihrem Admin-Panel. Damit können Sie die grundlegenden Einstellungen und Konfigurationen Ihrer Anwendung festlegen, wie zum Beispiel: Navigation, Logo, API für Anfragen an einen Server, API-Autorisierung, Lokalisierung, Design und andere Dinge.
Anwendungsbeispiel:
< Admin
dataProvider = { dataProvider ( apiUrl ) }
authProvider = { authProvider ( apiUrl ) }
menu = { Menu }
oauthProviders = { [
OAuthProvidersEnum . Google ,
OAuthProvidersEnum . Github ,
OAuthProvidersEnum . Jira ,
] }
>
< Routes />
</ Admin >Die Komponente akzeptiert die folgenden Requisiten:
Speisekarte
Hier können Sie Ihre Navigation anpassen. Sie sollten spezielle Komponenten aus unserem Paket verwenden: Menu, MenuItemLink, SubMenu. Ein Beispiel finden Sie hier.
Logo
Sie können das Logo ändern, das in der seitlichen Navigationsleiste angezeigt wird. Die Requisite akzeptiert einen Link zu einer SVG-, JSX-Komponente oder einer Datei im SVG-Format.
loginLogo
Sie können das Logo ändern, das im Autorisierungsformular angezeigt wird. Die Requisite akzeptiert einen Link zu einer SVG-, JSX-Komponente oder einer Datei im SVG-Format.
beiseiteInhalt
Mit diesem Tool können Sie der nebenstehenden Navigationsleiste unter den Links die erforderlichen Inhalte hinzufügen. Sie müssen ReactNode übergeben.
Datenanbieter
Der Hauptvertrag für die Arbeit mit Daten. Weitere Informationen erhalten Sie in unserer Dokumentation.
AuthProvider
Der Hauptvertrag für die Autorisierung im System. Weitere Informationen erhalten Sie in unserer Dokumentation.
themePresets
Sie können das Farbthema für Ihre Anwendung anpassen. Weitere Informationen erhalten Sie in unserer Dokumentation.
Gebietsschema
Das Lokalisierungsschema Ihres Admin-Panels, das Sie mit dem useLocaleProvider-Hook abrufen können. Ein Beispiel für das Schema finden Sie hier.
oauthProviders
Verwenden Sie die OAuth-Autorisierung mit diesen Requisiten. Übergeben Sie den Namen des erforderlichen Anbieters im Array mithilfe der OAuthProvidersEnum-Enumeration vom Admiral.
baseAppUrl
Fügen Sie die Requisiten hinzu, um den Basispfad der App zu ändern.
Ein Menü ist ein Array von Objekten, die die folgende Struktur haben:
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 CustomMenuUnsere Anwendung verwendet React-Hooks. Sie können sie von überall in der Anwendung innerhalb der React-Komponenten verwenden. Dies sind die Haken, die Sie verwenden können:
Mit diesem Hook können Sie den Status der Navigationsleiste empfangen und verwalten
import { useNav } from '@devfamily/admiral'
const { collapsed , toggleCollapsed , visible , toggle , open , close } = useNav ( )Mit diesem Hook können Sie Formularwerte abrufen und den Status des Formulars verwalten. Der Hook kann in Komponenten verwendet werden, die in „form“ innerhalb der Konfiguration der Funktion „createCRUD“ verwendet werden.
import { useForm } from '@devfamily/admiral'
const {
values ,
options ,
errors ,
setErrors ,
setValues ,
setOptions ,
isSubmitting ,
isFetching ,
locale ,
} = useForm ( )Mit diesem Hook können Sie den Status des Themas empfangen und verwalten.
import { useTheme } from '@devfamily/admiral'
const { themeName , setTheme } = useTheme ( )Ein Hook, der es Ihnen ermöglicht, den durch Aufruf von AuthProvider.getIdentity() erhaltenen Status abzurufen
import { useGetIdentty } from '@devfamily/admiral'
const { identity , loading , loaded , error } = useGetIdentty ( )Die in Admiral verwendeten Symbole stammen von React Icons.
ThemeProvider verwendet unter der Haube die Theme-Komponente @consta/uikit.
Sie können Ihre Voreinstellungen mit themePresets Prop an Admin Komponente übergeben:
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 >
)
} Erstellen Sie ein Verzeichnis für Voreinstellungen. Erstellen Sie darin Ordner für jeden Modifikator – genau wie in der Theme-Komponente.
Erstellen Sie CSS-Dateien. Legen Sie in den Ordnern mit den Modifikatoren die CSS-Dateien ab, die für diese Modifikatoren verantwortlich sind.
Sie erhalten etwas Ähnliches:
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
Konfigurieren Sie die Variablen in CSS-Dateien.
Erstellen Sie voreingestellte Dateien (themeLight, themeDark).
Importieren Sie die CSS-Dateien, die Sie verwenden möchten.
Erstellen Sie ein voreingestelltes Objekt. Geben Sie an, welche Werte (z. B. CSS-Dateien) für welche Modifikatoren in der Voreinstellung verwendet werden sollen. Sie erhalten etwas Ähnliches:
// 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' ,
} Übergeben Sie Ihre Voreinstellungen wie im obigen Beispiel an Admin Komponente.
❗ Hinweis : Im Beispiel für Admiral-Voreinstellungen werden PostCSS-Plugins für die Farbtransformation verwendet. Wenn Sie reproduzieren möchten, richten Sie Postcss und das Postcss-Color-Mod-Function-Plugin ein.
Wenn Sie an der Entwicklung von Admiral teilnehmen möchten, erstellen Sie einen Fork des Repositorys, nehmen Sie die gewünschten Änderungen vor und senden Sie eine Pull-Anfrage. Gerne berücksichtigen wir Ihre Anregungen!
Diese Bibliothek wird unter der MIT-Lizenz vertrieben.
Wenn Sie Fragen haben, kontaktieren Sie uns bitte unter: [email protected]. Wir freuen uns immer über Ihr Feedback!
