admiral
v5.9.7
Pruebe la demostración en vivo
Admiral es un marco de interfaz para crear back office en React. Proporciona componentes y herramientas listos para usar que hacen que el desarrollo de una interfaz de administración sea fácil y rápido.
Hecho con ? por dev.familia
Requisitos:
Hay varias opciones para instalar Admiral:
Para usar npx, asegúrese de tener Node.js
npx create-admiral-app@latestCuando ingresa este comando en la consola, verá 2 opciones de instalación:
Si elige " Instalar la plantilla con la configuración de backend en Express.js ", instalará la plantilla totalmente personalizada con el backend en Express.js.
Instrucciones detalladas de instalación y puesta en marcha
Todas las variables de entorno se configurarán automáticamente. Si desea configurarlos manualmente, vaya a la carpeta del proyecto y abra el .env. Tendrás 1 CRUD desde el principio: Usuarios . Para encontrarlos, pase por el camino: admiral/src/crud/users/index.tsx
Si elige " Instalar la plantilla sin configuración de backend ", obtendrá solo el shell frontal de Admiral en la carpeta de Admiral con CRUD - Usuarios . Para encontrarlo, siga el camino: admiral/src/crud/users/index.tsx . Para utilizar su backend, lea la Documentación
Almirante está disponible en http://localhost:3000. Si el puerto 3000 está ocupado, se seleccionará cualquier otro puerto libre.
En la consola verás algo como esto.
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.En cada uno de los ejemplos se encuentran instrucciones detalladas de instalación y puesta en marcha.
Abra su navegador y vaya a http://localhost:3000.
Sí, eso es correcto. Puedes simplemente clonar este repositorio e ingresar los siguientes comandos:
yarn
yarn devLuego vaya a http://localhost:3000. El Almirante con datos simulados ya está disponible para usted.
El archivo App.tsx es el punto de entrada a la aplicación. Es donde se inicializa la biblioteca y donde se procesan los componentes 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 El contrato principal de autorización en el sistema es la interfaz 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
}Ejemplo de implementación La interfaz en sí se puede personalizar a tu gusto, pero es importante respetar el contrato que proporciona. Descripción detallada del contrato
Veamos los métodos básicos de implementación:
| Método | Nombre | Descripción | Parámetros | Valor de retorno |
|---|---|---|---|---|
| acceso | Autenticación de usuario | Realiza una solicitud POST a /api/login y almacena el campo token en localStorage, que se utiliza en solicitudes posteriores. | params - objeto con los campos username y password | Un objeto con un campo token y un objeto user con campos email y name |
| cerrar sesión | Cerrar sesión de usuario | Realiza una solicitud POST a /api/logout y elimina el campo token de localStorage | void | |
| verificarAuth | Verificación de autorización de usuario | Realiza una solicitud GET a /api/checkAuth y verifica la validez del token; espera un código de estado: 200. Se usa cada vez que se usa la API | token al portador | Código de estado 200 |
| obtener identidad | Recibir datos de usuario | Realiza una solicitud GET a /api/getIdentity y devuelve un objeto con datos del usuario | token al portador | user del objeto con los campos email y name |
| oauthIniciar sesión | Autorización vía OAuth | Realiza una solicitud GET a /api/auth/social-login/${provider} y devuelve un objeto con el campo redirect , que se utiliza para la redirección | provider - proveedor de OAuth | Objeto con el campo redirect |
| oauthDevolución de llamada | Autorización de devolución de llamada a través de OAuth | Realiza una solicitud POST a /api/auth/social-login/${provider}/callback y almacena el campo token en localStorage, que se utiliza en solicitudes posteriores. | provider : proveedor de OAuth, data : datos recibidos del proveedor de OAuth donde existe el campo token | Objeto con el token de campo. |
El contrato principal para trabajar con datos representa la interfaz 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
}Ejemplo de implementación Descripción detallada del contrato
Veamos los métodos básicos de implementación:
| Método | Nombre | Descripción | Parámetros |
|---|---|---|---|
| obtener lista | Obtener una lista de entidades | Realiza una solicitud GET a /api/${resource} y devuelve un objeto con datos para usar en el componente List | resource - nombre del recurso, params - objeto con parámetros de consulta |
| reordenar lista | Cambiar el orden de las entidades | Realiza una solicitud POST a /api/${resource}/reorder y devuelve un objeto con datos para usar en el componente List | resource - nombre del recurso, params - objeto con parámetros de consulta |
| obtener uno | Obtener una entidad | Realiza una solicitud GET a /api/${resource}/${id} y devuelve un objeto con datos para usar en el componente Show | resource - nombre del recurso, id - identificador de entidad |
| obtenerCrearFormDatos | Obtener datos para un formulario de creación de entidad (Select, AjaxSelect) | Realiza una solicitud GET a /api/${resource}/create y devuelve un objeto con datos para usar en el componente Create | resource - nombre del recurso |
| obtenerFiltersFormData | Recibir datos para filtros | Realiza una solicitud GET a /api/${resource}/filters y devuelve un objeto con datos para usar en el componente Filters | resource : nombre del recurso, urlState : objeto con parámetros de la URL que se utilizará en el componente Filters |
| crear | Creando una entidad | Realiza una solicitud POST a /api/${resource} y devuelve un objeto con datos para usar en el componente Create | resource - nombre del recurso, params - objeto de datos de entidad |
| obtener datos del formulario de actualización | Obtener datos para un formulario de edición de entidad (Select, AjaxSelect) | Realiza una solicitud GET a /api/${resource}/${id}/update y devuelve un objeto con datos para usar en el componente Edit | resource - nombre del recurso, id - identificador de entidad |
| actualizar | Actualizar una entidad | Realiza una solicitud POST a /api/${resource}/${id} y devuelve un objeto con los datos que se utilizarán en el componente Edit | resource - nombre del recurso, id - identificador de entidad, params - objeto de datos de entidad |
| borrar | Eliminar una entidad | Realiza una solicitud DELETE a /api/${resource}/${id} y devuelve un objeto con datos para usar en el componente Delete | resource - nombre del recurso, id - identificador de entidad |
Consulta:
http://localhost/admin/users?page=1&perPage=10&filter%5Bid%5D=1Resultado:
{
"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
}
}Consulta:
http://localhost/admin/users/1/update?id=1Resultado:
{
"data" : {
"id" : 1 ,
"name" : " Dev family " ,
"email" : " [email protected] " ,
"role_id" : 1
},
"values" : {
"role_id" : [
{
"label" : " Administrator " ,
"value" : 1
}
]
}
}❗ Nota : Utilizamos el código de estado HTTP 422 Entidad no procesable para manejar los errores de validación.
{
"errors" : {
"name" : [ " Field 'name' is invalid. " ],
"email" : [ " Field 'email' is invalid. " ]
},
"message" : " Validation failed "
} La paginación funciona con el método getList . Puede pasar los parámetros page y perPage al método getList y devolverá el objeto PaginationResult con items y meta .
Los filtros funcionan con el método getList . Puede pasar el parámetro filter[$field] al método getList y devolverá el objeto PaginationResult con items y meta .
Ordenar el trabajo con el método getList . Puede pasar el parámetro sort[$field] al método getList y devolverá el objeto PaginationResult con items y meta .
Admiral tiene un enrutador basado en un sistema de archivos .
Una página es un componente de React exportado desde un archivo .js, .jsx, .ts o .tsx en el directorio de las páginas. Cuando se agrega un archivo al directorio de las páginas, está disponible automáticamente como ruta. reaccionar-router-dom se utiliza bajo el capó.
El enrutador enrutará automáticamente los archivos denominados index a la raíz del directorio.
pages/index.ts → / pages/users/index.ts → /users
El enrutador admite archivos anidados. Si crea una estructura de carpetas anidadas, los archivos se enrutarán automáticamente de la misma manera.
pages/users/create.ts → /users/create
Para hacer coincidir un segmento dinámico, puede utilizar la sintaxis de corchetes. Esto le permite hacer coincidir parámetros con nombre.
pages/users/[id].ts → /users/:id (/users/42)
Este componente es el más importante en su panel de administración. Con él, puede establecer los ajustes y configuraciones fundamentales de su aplicación, como: navegación, logotipo, API para solicitudes a un servidor, autorización de API, localización, tema y otras cosas.
Ejemplo de uso:
< Admin
dataProvider = { dataProvider ( apiUrl ) }
authProvider = { authProvider ( apiUrl ) }
menu = { Menu }
oauthProviders = { [
OAuthProvidersEnum . Google ,
OAuthProvidersEnum . Github ,
OAuthProvidersEnum . Jira ,
] }
>
< Routes />
</ Admin >El componente acepta las siguientes propinas:
menú
Aquí puedes personalizar tu navegación. Debe utilizar componentes especiales de nuestro paquete: Menú, MenuItemLink, SubMenu. Puedes encontrar un ejemplo aquí.
logo
Puede cambiar el logotipo que se muestra en la barra de navegación lateral. El accesorio acepta un enlace a un componente svg, JSX o un archivo con formato svg.
iniciar sesiónLogotipo
Puede cambiar el logotipo que se muestra en el formulario de autorización. El accesorio acepta un enlace a un componente svg, JSX o un archivo con formato svg.
a un ladoContenido
Con esta herramienta, puede agregar el contenido necesario a la barra de navegación lateral debajo de los enlaces. Tienes que pasar ReactNode.
proveedor de datos
El contrato principal para trabajar con datos. Puede obtener más información en nuestra documentación.
proveedor de autenticación
El contrato principal de autorización en el sistema. Puede obtener más información en nuestra documentación.
temaPresets
Puede personalizar el tema de color para su aplicación. Puede obtener más información en nuestra documentación.
lugar
El esquema de localización de su panel de administración, que puede obtener utilizando el enlace useLocaleProvider. Puede encontrar un ejemplo del esquema aquí.
oauthProveedores
Utilice la autorización OAuth utilizando estos accesorios. Pase el nombre del proveedor requerido en la matriz usando la enumeración OAuthProvidersEnum del almirante.
baseAppUrl
Agregue los accesorios para cambiar la ruta base de la aplicación.
Un menú es una matriz de objetos que tienen la siguiente estructura:
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 CustomMenuNuestra aplicación utiliza ganchos React. Puede usarlos desde cualquier lugar de la aplicación dentro de los componentes de React. Estos son los ganchos que puedes utilizar:
Este gancho le permite recibir y administrar el estado de la barra de navegación.
import { useNav } from '@devfamily/admiral'
const { collapsed , toggleCollapsed , visible , toggle , open , close } = useNav ( )Este enlace le permite obtener valores del formulario y administrar el estado del formulario. El gancho se puede utilizar en componentes utilizados en "formulario" dentro de la configuración de la función createCRUD.
import { useForm } from '@devfamily/admiral'
const {
values ,
options ,
errors ,
setErrors ,
setValues ,
setOptions ,
isSubmitting ,
isFetching ,
locale ,
} = useForm ( )Este gancho le permite recibir y administrar el estado del tema.
import { useTheme } from '@devfamily/admiral'
const { themeName , setTheme } = useTheme ( )Un gancho que le permite obtener el estado obtenido llamando a AuthProvider.getIdentity()
import { useGetIdentty } from '@devfamily/admiral'
const { identity , loading , loaded , error } = useGetIdentty ( )Los íconos utilizados en Admiral son de React Icons.
ThemeProvider utiliza el componente temático @consta/uikit bajo el capó.
Puede pasar sus ajustes preestablecidos al componente Admin con el accesorio 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 >
)
} Cree un directorio para ajustes preestablecidos. En el interior, cree carpetas para cada modificador, igual que en el componente Tema.
Crea archivos CSS. En las carpetas con los modificadores coloque los archivos CSS que serán responsables de esos modificadores.
Obtendrás algo similar:
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
Configure las variables en archivos CSS.
Cree archivos preestablecidos (themeLight, themeDark).
Importa los archivos CSS que vas a utilizar.
Crea un objeto preestablecido. Especifique qué valores (es decir, archivos CSS) y qué modificadores utilizar en el ajuste preestablecido. Obtendrás algo similar:
// 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' ,
} Pase sus ajustes preestablecidos al componente Admin como en el ejemplo anterior.
❗ Nota : los complementos postcss se utilizan para la transformación de color en el ejemplo de ajustes preestablecidos de almirante. Si desea reproducir, configure el complemento postcss y postcss-color-mod-function.
Si quieres participar en el desarrollo de Admiral, haz un Fork del repositorio, realiza los cambios deseados y envía un pull request. ¡Estaremos encantados de considerar sus sugerencias!
Esta biblioteca se distribuye bajo la licencia MIT.
Si tiene alguna pregunta, comuníquese con nosotros a: [email protected] ¡Siempre estaremos felices de recibir sus comentarios!
