admiral
v5.9.7
라이브 데모를 사용해 보세요
Admiral은 React에서 백오피스를 생성하기 위한 프론트엔드 프레임워크입니다. 관리 인터페이스를 쉽고 빠르게 개발할 수 있는 기본 구성 요소와 도구를 제공합니다.
로 만든? 작성자: dev.family
요구사항:
Admiral 설치에는 여러 가지 옵션이 있습니다:
npx를 사용하려면 Node.js가 있어야 합니다.
npx create-admiral-app@latest콘솔에 이 명령을 입력하면 두 가지 설치 옵션이 표시됩니다.
" Express.js에 백엔드 설정을 사용하여 템플릿 설치 "를 선택하면 Express.js에 백엔드와 함께 완전히 사용자 정의된 템플릿을 설치하게 됩니다.
자세한 설치 및 시작 지침
모든 환경 변수는 자동으로 설정됩니다. 수동으로 구성하려면 프로젝트 폴더로 이동하여 .env를 엽니다. 처음부터 1개의 CRUD( Users) 가 있습니다. 그들을 찾으려면 길을 지나가세요 - admiral/src/crud/users/index.tsx
" 백엔드 설정 없이 템플릿 설치 "를 선택하면 CRUD - Users 를 사용하여 admiral 폴더에 Admiral의 프런트엔드 셸만 표시됩니다. 이를 찾으려면 - 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 요청을 만들고 추가 요청에 사용되는 localStorage에 token 필드를 저장합니다. | params - username 과 password 필드가 있는 객체 | token 필드가 있는 개체와 email 및 name 필드가 있는 user 개체 |
| 로그아웃 | 사용자 로그아웃 | /api/logout 에 대한 POST 요청을 만들고 localStorage에서 token 필드를 제거합니다. | void | |
| 인증 확인 | 사용자 인증 확인 | /api/checkAuth 에 대한 GET 요청을 만들고 토큰 유효성을 확인하며 상태 코드 - 200이 예상됩니다. API가 사용될 때마다 사용됩니다. | 무기명 token | 상태 코드 200 |
| getIdentity | 사용자 데이터 수신 | /api/getIdentity 에 대한 GET 요청을 만들고 사용자 데이터가 포함된 객체를 반환합니다. | 무기명 token | email 및 name 필드가 있는 개체 user |
| oauth로그인 | OAuth를 통한 승인 | /api/auth/social-login/${provider} 에 GET 요청을 하고 리디렉션에 사용되는 redirect 필드가 있는 객체를 반환합니다. | provider - OAuth 공급자 | 필드 redirect 있는 개체 |
| oauth콜백 | OAuth를 통한 콜백 승인 | /api/auth/social-login/${provider}/callback 에 대한 POST 요청을 만들고 추가 요청에 사용되는 localStorage에 token 필드를 저장합니다. | 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
}구현 예 계약 세부 설명
기본 구현 방법을 살펴 보겠습니다.
| 방법 | 이름 | 설명 | 매개변수 |
|---|---|---|---|
| getList | 엔터티 목록 가져오기 | /api/${resource} 에 대한 GET 요청을 만들고 List 구성 요소에서 사용할 데이터가 포함된 객체를 반환합니다. | resource - 리소스 이름, params - 쿼리 매개변수가 있는 객체 |
| 재정렬 목록 | 엔터티 순서 변경 | /api/${resource}/reorder 에 대한 POST 요청을 만들고 List 구성 요소에서 사용할 데이터가 포함된 객체를 반환합니다. | resource - 리소스 이름, params - 쿼리 매개변수가 있는 객체 |
| getOne | 엔터티 얻기 | /api/${resource}/${id} 에 대한 GET 요청을 만들고 Show 구성 요소에서 사용할 데이터가 포함된 개체를 반환합니다. | resource - 리소스 이름, id - 엔터티 식별자 |
| getCreateFormData | 엔터티 생성 양식에 대한 데이터 가져오기(Select, AjaxSelect) | /api/${resource}/create 에 GET 요청을 만들고 Create 구성 요소에서 사용할 데이터가 포함된 객체를 반환합니다. | resource - 자원 이름 |
| getFiltersFormData | 필터에 대한 데이터 수신 | /api/${resource}/filters 에 대한 GET 요청을 만들고 Filters 구성 요소에서 사용할 데이터가 포함된 객체를 반환합니다. | resource - 리소스 이름, urlState - 구성요소에 사용되는 URL의 매개변수가 포함된 개체 Filters |
| 만들다 | 엔터티 생성 | /api/${resource} 에 대한 POST 요청을 만들고 구성 요소 Create 에 사용할 데이터가 포함된 객체를 반환합니다. | resource - 리소스 이름, params - 엔터티 데이터 개체 |
| getUpdateFormData | 엔터티 편집 양식에 대한 데이터 가져오기(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 처리할 수 없는 엔터티를 활용합니다.
{
"errors" : {
"name" : [ " Field 'name' is invalid. " ],
"email" : [ " Field 'email' is invalid. " ]
},
"message" : " Validation failed "
} getList 메소드를 사용한 페이지 매김 작업. page 및 perPage 매개변수를 getList 메소드에 전달할 수 있으며 items 및 meta 필드가 있는 PaginationResult 객체를 반환합니다.
필터는 getList 메소드와 함께 작동합니다. getList 메소드에 filter[$field] 매개변수를 전달할 수 있으며 items 및 meta 필드가 포함된 PaginationResult 객체를 반환합니다.
getList 메소드를 사용하여 작업을 정렬합니다. sort[$field] 매개변수를 getList 메소드에 전달하면 items 및 meta 필드가 포함된 PaginationResult 객체가 반환됩니다.
Admiral에는 파일 시스템 기반 라우터가 있습니다.
페이지는 페이지 디렉터리의 .js, .jsx, .ts 또는 .tsx 파일에서 내보낸 React 구성 요소입니다. 파일이 페이지 디렉토리에 추가되면 자동으로 경로로 사용할 수 있습니다. 반응 라우터 돔은 내부적으로 사용됩니다.
라우터는 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 >구성 요소는 다음과 같은 propes를 허용합니다.
메뉴
여기에서 탐색을 사용자 정의할 수 있습니다. 우리 패키지의 특수 구성 요소인 Menu, MenuItemLink, SubMenu를 사용해야 합니다. 여기에서 예를 찾을 수 있습니다.
심벌 마크
측면 탐색 모음에 표시되는 로고를 변경할 수 있습니다. 소품은 svg, JSX 구성 요소 또는 svg 형식의 파일에 대한 링크를 허용합니다.
로그인로고
인증 양식에 표시되는 로고를 변경할 수 있습니다. 소품은 svg, JSX 구성 요소 또는 svg 형식의 파일에 대한 링크를 허용합니다.
따로내용
이 도구를 사용하면 링크 아래에 있는 탐색 모음에 필요한 콘텐츠를 추가할 수 있습니다. ReactNode를 전달해야 합니다.
데이터 제공자
데이터 작업을 위한 주요 계약입니다. 우리 문서에서 더 많은 정보를 얻을 수 있습니다.
인증 제공자
시스템 승인을 위한 주요 계약입니다. 우리 문서에서 더 많은 정보를 얻을 수 있습니다.
테마 사전 설정
애플리케이션의 색상 테마를 사용자 정의할 수 있습니다. 우리 문서에서 더 많은 정보를 얻을 수 있습니다.
장소
useLocaleProvider 후크를 사용하여 얻을 수 있는 관리 패널의 현지화 구성표입니다. 여기에서 구성표의 예를 찾을 수 있습니다.
oauthProviders
이 소품을 사용하여 OAuth 인증을 사용하세요. admiral의 OAuthProvidersEnum enum을 사용하여 배열에 필요한 공급자의 이름을 전달합니다.
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 테마 구성 요소를 사용합니다.
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 >
)
} 사전 설정용 디렉터리를 만듭니다. 내부에서는 각 수정자에 대한 폴더를 만듭니다. 테마 구성 요소와 동일합니다.
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]로 문의해 주세요. 우리는 항상 여러분의 피드백을 기쁘게 받아들입니다!
