admiral
v5.9.7
حاول التجريبي المباشر
Admiral هو إطار عمل للواجهة الأمامية لإنشاء مكتب خلفي في React. فهو يوفر مكونات وأدوات مبتكرة تجعل تطوير واجهة الإدارة أمرًا سهلاً وسريعًا.
صنع مع ؟ بواسطة dev.family
متطلبات:
هناك عدة خيارات لتثبيت Admiral:
لاستخدام npx، تأكد من أن لديك Node.js
npx create-admiral-app@latestعندما تقوم بإدخال هذا الأمر في وحدة التحكم، سترى خيارين للتثبيت:
إذا اخترت " تثبيت القالب مع إعداد الواجهة الخلفية على Express.js "، فسوف تقوم بتثبيت القالب المخصص بالكامل مع الواجهة الخلفية على Express.js.
تعليمات التثبيت وبدء التشغيل التفصيلية
سيتم تعيين كافة متغيرات البيئة تلقائيًا. إذا كنت تريد تكوينها يدويًا، فانتقل إلى مجلد المشروع وافتح ملف .env. سيكون لديك 1 CRUDs منذ البداية - Users . للعثور عليهم، قم بتمرير الطريق - admiral/src/crud/users/index.tsx
إذا اخترت " تثبيت القالب بدون إعداد الواجهة الخلفية "، فستحصل فقط على غلاف الواجهة الأمامية لـ Admiral في مجلد Admiral مع CRUD - Users . للعثور عليه، قم بتمرير الطريق - admiral/src/crud/users/index.tsx . لاستخدام الواجهة الخلفية الخاصة بك، اقرأ الوثائق
الأدميرال متاح على 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
}مثال على التنفيذ يمكن تخصيص الواجهة نفسها حسب رغبتك، ولكن من المهم احترام العقد الذي توفره. وصف العقد التفصيلي
دعونا نلقي نظرة على الطرق الأساسية للتنفيذ:
| طريقة | اسم | وصف | حدود | قيمة الإرجاع |
|---|---|---|---|---|
| تسجيل الدخول | مصادقة المستخدم | يقدم طلب POST إلى /api/login ويخزن حقل token في localStorage، والذي يستخدم في الطلبات الأخرى | params - كائن مع username وكلمة password للحقول | كائن يحتوي على حقل token وكائن user يحتوي على حقلي email name |
| تسجيل الخروج | تسجيل خروج المستخدم | يقدم طلب POST إلى /api/logout ويزيل حقل token من localStorage | void | |
| checkAuth | التحقق من ترخيص المستخدم | يرسل طلب GET إلى /api/checkAuth ويتحقق من صلاحية الرمز المميز، ويتوقع رمز الحالة - 200. يُستخدم في كل مرة يتم فيها استخدام واجهة برمجة التطبيقات (API) | token حامل | رمز الحالة 200 |
| getIdentity | استلام بيانات المستخدم | يقدم طلب GET إلى /api/getIdentity ويعيد كائنًا يحتوي على بيانات المستخدم | token حامل | كائن user مع حقول email name |
| com.oauthLogin | التفويض عبر OAuth | يرسل طلب GET إلى /api/auth/social-login/${provider} ويعيد كائنًا بحقل redirect ، والذي يُستخدم لإعادة التوجيه | provider - مزود OAuth | كائن مع redirect الحقل |
| com.oauthCallback | إذن رد الاتصال عبر OAuth | يُجري طلب POST إلى /api/auth/social-login/${provider}/callback ويخزن حقل token في localStorage، والذي يُستخدم في طلبات أخرى | provider - موفر OAuth، data - البيانات المستلمة من موفر OAuth حيث يوجد حقل token | كائن مع 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
}مثال على التنفيذ وصف العقد التفصيلي
دعونا نلقي نظرة على الطرق الأساسية للتنفيذ:
| طريقة | اسم | وصف | حدود |
|---|---|---|---|
| getList | الحصول على قائمة الكيانات | إجراء طلب GET إلى /api/${resource} وإرجاع كائن يحتوي على بيانات لاستخدامه في مكون List | resource - اسم المورد، params - كائن مع معلمات الاستعلام |
| reorderList | تغيير ترتيب الكيانات | إجراء طلب POST إلى /api/${resource}/reorder وإرجاع كائن يحتوي على بيانات لاستخدامه في مكون List | resource - اسم المورد، params - كائن مع معلمات الاستعلام |
| getOne | الحصول على الكيان | إجراء طلب GET إلى /api/${resource}/${id} وإرجاع كائن يحتوي على بيانات لاستخدامه في مكون Show | resource - اسم المورد، id - معرف الكيان |
| getCreateFormData | الحصول على البيانات لنموذج إنشاء الكيان (Select، AjaxSelect) | إجراء طلب GET إلى /api/${resource}/create وإرجاع كائن يحتوي على بيانات لاستخدامه في مكون Create | resource - اسم المورد |
| getFiltersFormData | استقبال البيانات للمرشحات | إجراء طلب GET إلى /api/${resource}/filters وإرجاع كائن يحتوي على بيانات لاستخدامها في مكون Filters | resource - اسم المورد، urlState - كائن يحتوي على معلمات من عنوان url ليتم استخدامه في Filters المكونة |
| يخلق | إنشاء كيان | إجراء طلب POST إلى /api/${resource} وإرجاع كائن يحتوي على بيانات لاستخدامه في المكون Create | resource - اسم المورد، params - كائن بيانات الكيان |
| getUpdateFormData | الحصول على بيانات لنموذج تحرير كيان (Select، AjaxSelect) | إجراء طلب GET إلى /api/${resource}/${id}/update وإرجاع كائن يحتوي على بيانات ليتم استخدامه في مكون Edit | resource - اسم المورد، id - معرف الكيان |
| تحديث | تحديث كيان | إجراء طلب POST إلى /api/${resource}/${id} وإرجاع كائن بالبيانات التي سيتم استخدامها في مكون Edit | resource - اسم المورد، id - معرف الكيان، params - كائن بيانات الكيان |
| يمسح | حذف كيان | يجعل طلب DELETE إلى /api/${resource}/${id} ويعيد كائنًا يحتوي على بيانات لاستخدامها في مكون 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 كيان غير قابل للمعالجة للتعامل مع أخطاء التحقق من الصحة.
{
"errors" : {
"name" : [ " Field 'name' is invalid. " ],
"email" : [ " Field 'email' is invalid. " ]
},
"message" : " Validation failed "
} يعمل ترقيم الصفحات باستخدام طريقة getList . يمكنك تمرير معلمات page و perPage إلى طريقة getList ، وسوف تُرجع كائن PaginationResult مع items وحقول meta .
تعمل المرشحات باستخدام طريقة getList . يمكنك تمرير معلمة filter[$field] إلى طريقة getList ، وسوف تُرجع كائن PaginationResult مع items وحقول meta .
فرز العمل باستخدام طريقة getList . يمكنك تمرير معلمة sort[$field] إلى طريقة getList ، وسوف تُرجع كائن PaginationResult مع items وحقول meta .
لدى Admiral جهاز توجيه يعتمد على نظام الملفات .
الصفحة عبارة عن مكون React مُصدَّر من ملف .js، أو .jsx، أو .ts، أو .tsx في دليل الصفحات. عند إضافة ملف إلى دليل الصفحات، يصبح متاحًا تلقائيًا كمسار. يتم استخدام رد فعل جهاز التوجيه دوم تحت غطاء محرك السيارة.
سيقوم جهاز التوجيه تلقائيًا بتوجيه الملفات المسماة فهرس إلى جذر الدليل.
pages/index.ts → / pages/users/index.ts → /users
يدعم جهاز التوجيه الملفات المتداخلة. إذا قمت بإنشاء بنية مجلد متداخلة، فسيتم توجيه الملفات تلقائيًا بنفس الطريقة.
pages/users/create.ts → /users/create
لمطابقة مقطع ديناميكي، يمكنك استخدام صيغة القوس. يتيح لك ذلك مطابقة المعلمات المسماة.
pages/users/[id].ts → /users/:id (/users/42)
هذا المكون هو الأكثر أهمية في لوحة الإدارة الخاصة بك. باستخدامه، يمكنك ضبط الإعدادات والتكوينات الأساسية لتطبيقك، مثل: التنقل والشعار وواجهة برمجة التطبيقات للطلبات المقدمة إلى الخادم وتفويض واجهة برمجة التطبيقات والترجمة والموضوع وأشياء أخرى.
مثال للاستخدام:
< Admin
dataProvider = { dataProvider ( apiUrl ) }
authProvider = { authProvider ( apiUrl ) }
menu = { Menu }
oauthProviders = { [
OAuthProvidersEnum . Google ,
OAuthProvidersEnum . Github ,
OAuthProvidersEnum . Jira ,
] }
>
< Routes />
</ Admin >يقبل المكون الدعائم التالية:
قائمة طعام
هنا يمكنك تخصيص التنقل الخاص بك. يجب عليك استخدام مكونات خاصة من الحزمة الخاصة بنا: Menu، MenuItemLink، SubMenu. يمكنك العثور على مثال هنا.
شعار
يمكنك تغيير الشعار الذي يتم عرضه في شريط التنقل الجانبي. يقبل الدعامة رابطًا إلى مكون svg أو JSX أو ملف بتنسيق svg.
تسجيل الدخولLogo
يمكنك تغيير الشعار الذي يتم عرضه في نموذج التفويض. يقبل الدعامة رابطًا إلى مكون svg أو JSX أو ملف بتنسيق svg.
SideContent
باستخدام هذه الأداة، يمكنك إضافة المحتوى الضروري إلى شريط التنقل الجانبي الموجود أسفل الروابط. يجب عليك تمرير ReactNode.
dataProvider
العقد الرئيسي للعمل مع البيانات. يمكنك الحصول على مزيد من المعلومات في وثائقنا.
authProvider
العقد الرئيسي للترخيص في النظام. يمكنك الحصول على مزيد من المعلومات في وثائقنا.
themePresets
يمكنك تخصيص سمة اللون لتطبيقك. يمكنك الحصول على مزيد من المعلومات في وثائقنا.
لغة
مخطط الترجمة الخاص بلوحة الإدارة الخاصة بك، والذي يمكنك الحصول عليه باستخدام الخطاف useLocaleProvider. يمكنك العثور على مثال للمخطط هنا.
oauthProviders
استخدم ترخيص OAuth باستخدام هذه الدعائم. قم بتمرير اسم الموفر المطلوب في المصفوفة باستخدام تعداد OAuthProvidersEnum من الأميرال.
baseAppUrl
أضف الدعائم لتغيير المسار الأساسي للتطبيق.
القائمة عبارة عن مجموعة من الكائنات التي لها البنية التالية:
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. يمكنك استخدامها من أي مكان في التطبيق داخل مكونات React. هذه هي الخطافات التي يمكنك استخدامها:
يتيح لك هذا الخطاف تلقي وإدارة حالة شريط التنقل
import { useNav } from '@devfamily/admiral'
const { collapsed , toggleCollapsed , visible , toggle , open , close } = useNav ( )يتيح لك هذا الخطاف الحصول على قيم النموذج وإدارة حالة النموذج. يمكن استخدام الخطاف في المكونات المستخدمة في "النموذج" داخل تكوين وظيفة createCRUD.
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 Theme أسفل الغطاء.
يمكنك تمرير إعداداتك المسبقة إلى مكون Admin باستخدام خاصية 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 >
)
} إنشاء دليل للإعدادات المسبقة. في الداخل، قم بإنشاء مجلدات لكل معدل - كما هو الحال في مكون السمة.
إنشاء ملفات 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 لتحويل الألوان في مثال الإعدادات المسبقة للأدميرال. إذا كنت ترغب في إعادة الإنتاج، فقم بإعداد البرنامج المساعد postcss وpostcss-color-mod-function.
إذا كنت ترغب في المشاركة في تطوير Admiral، فقم بإجراء Fork للمستودع، وقم بإجراء التغييرات المطلوبة وأرسل طلب سحب. سنكون سعداء للنظر في اقتراحاتكم!
يتم توزيع هذه المكتبة بموجب ترخيص MIT.
إذا كان لديك أي أسئلة، يرجى الاتصال بنا على: [email protected] ويسعدنا دائمًا تلقي تعليقاتك!
