Update README.md
This commit is contained in:
parent
717f3847b8
commit
1ff37fcc6f
254
README.md
254
README.md
@ -111,19 +111,9 @@ function AppHeader() {
|
||||
|
||||
---
|
||||
|
||||
# استفاده از core
|
||||
# Core
|
||||
|
||||
بخش core شامل این موارد است:
|
||||
|
||||
* API config
|
||||
* `createApi`
|
||||
* `BiProvider`
|
||||
* Keycloak
|
||||
* Permission
|
||||
* React Query provider
|
||||
* Chakra provider
|
||||
|
||||
Required dependencies:
|
||||
required dependencies:
|
||||
|
||||
```bash
|
||||
yarn add @chakra-ui/react @emotion/react @emotion/styled framer-motion @tanstack/react-query axios keycloak-js
|
||||
@ -131,7 +121,7 @@ yarn add @chakra-ui/react @emotion/react @emotion/styled framer-motion @tanstack
|
||||
|
||||
---
|
||||
|
||||
## استفاده از BiProvider
|
||||
## BiProvider
|
||||
|
||||
```jsx
|
||||
import { BiProvider } from "uikit/core";
|
||||
@ -149,37 +139,27 @@ export default function App() {
|
||||
}
|
||||
```
|
||||
|
||||
`BiProvider` به صورت داخلی این کارها را انجام میدهد:
|
||||
---
|
||||
|
||||
* تنظیم base url برای API
|
||||
* راهاندازی Keycloak در صورت فعال بودن
|
||||
* گرفتن permissionها در صورت فعال بودن
|
||||
* اضافه کردن `ChakraProvider`
|
||||
* اضافه کردن `QueryClientProvider`
|
||||
* اضافه کردن فونت و theme داخلی
|
||||
* فعال کردن اختیاری `UpdateChecker`
|
||||
## BiProvider props
|
||||
|
||||
| Prop |
|
||||
| -------------------- |
|
||||
| `apiBaseUrl` |
|
||||
| `keycloakClientId` |
|
||||
| `permissionClientId` |
|
||||
| `loading` |
|
||||
| `updateChecker` |
|
||||
| `updateCheckerProps` |
|
||||
| `keycloakUrl` |
|
||||
| `keycloakRealm` |
|
||||
| `permissionUrl` |
|
||||
| `keycloakEnabled` |
|
||||
| `permissionEnabled` |
|
||||
|
||||
---
|
||||
|
||||
## props مربوط به BiProvider
|
||||
|
||||
| Prop | توضیح |
|
||||
| -------------------- | ------------------------------------------------------ |
|
||||
| `apiBaseUrl` | آدرس اصلی API |
|
||||
| `keycloakClientId` | client id مربوط به Keycloak |
|
||||
| `permissionClientId` | client id مربوط به Permission |
|
||||
| `loading` | کامپوننت loading هنگام init شدن Keycloak یا Permission |
|
||||
| `updateChecker` | فعال یا غیرفعال کردن بررسی آپدیت |
|
||||
| `updateCheckerProps` | props مربوط به UpdateChecker |
|
||||
| `keycloakUrl` | آدرس Keycloak |
|
||||
| `keycloakRealm` | realm مربوط به Keycloak |
|
||||
| `permissionUrl` | آدرس API مربوط به permission |
|
||||
| `keycloakEnabled` | فعال یا غیرفعال کردن Keycloak به صورت دستی |
|
||||
| `permissionEnabled` | فعال یا غیرفعال کردن Permission به صورت دستی |
|
||||
|
||||
---
|
||||
|
||||
## مقدارهای پیشفرض BiProvider
|
||||
## BiProvider defaults
|
||||
|
||||
```js
|
||||
keycloakUrl = "https://auth.ibagher.ir";
|
||||
@ -188,42 +168,9 @@ permissionUrl = "https://api.d.aiengines.ir/user_api/v1/permissions/list";
|
||||
updateChecker = false;
|
||||
```
|
||||
|
||||
نکته: اگر `keycloakClientId` داده شود، Keycloak فعال میشود. اگر `permissionClientId` داده شود، Permission فعال میشود.
|
||||
|
||||
برای کنترل دستی:
|
||||
|
||||
```jsx
|
||||
<BiProvider
|
||||
apiBaseUrl="https://api.example.com"
|
||||
keycloakEnabled={false}
|
||||
permissionEnabled={false}
|
||||
>
|
||||
<YourApp />
|
||||
</BiProvider>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# UpdateChecker
|
||||
|
||||
به صورت پیشفرض `updateChecker` خاموش است.
|
||||
|
||||
برای فعال کردن:
|
||||
|
||||
```jsx
|
||||
<BiProvider
|
||||
apiBaseUrl="https://api.example.com"
|
||||
keycloakClientId="front-client"
|
||||
permissionClientId="permission-client"
|
||||
updateChecker
|
||||
>
|
||||
<YourApp />
|
||||
</BiProvider>
|
||||
```
|
||||
|
||||
اگر `updateChecker` را فعال میکنی، پروژه باید فایل version تولید کند. معمولاً باید یک اسکریپت مثل `write-version.js` در root پروژه داشته باشی و در `package.json` پروژه target، قبل از build اجرا شود.
|
||||
|
||||
نمونه:
|
||||
To enable `updateChecker` you should have a script `write-version.js` in the root of the project and in the `package.json` of the target project, run before the build:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -236,23 +183,18 @@ updateChecker = false;
|
||||
|
||||
---
|
||||
|
||||
# استفاده از API پایه
|
||||
# API
|
||||
|
||||
```js
|
||||
import { api, fetcher, configureApi, getApi } from "uikit/core";
|
||||
```
|
||||
|
||||
اگر از `BiProvider` استفاده میکنی، معمولاً نیازی نیست دستی `configureApi` را صدا بزنی، چون `BiProvider` این کار را انجام میدهد.
|
||||
|
||||
نمونه استفاده مستقیم:
|
||||
|
||||
```js
|
||||
import { api } from "uikit/core";
|
||||
|
||||
const response = await api.get("/users");
|
||||
```
|
||||
|
||||
یا:
|
||||
or
|
||||
|
||||
```js
|
||||
import { fetcher } from "uikit/core";
|
||||
@ -262,35 +204,39 @@ const data = await fetcher("/users");
|
||||
|
||||
---
|
||||
|
||||
# استفاده از createApi
|
||||
|
||||
`createApi` برای ساختن یک API ساده بر پایه React Query استفاده میشود.
|
||||
# createApi
|
||||
|
||||
```js
|
||||
import { createApi } from "uikit/core";
|
||||
|
||||
export const profileApi = createApi({
|
||||
key: "profile",
|
||||
url: "/content/rokn/profiles",
|
||||
export const sampleApi = createApi({
|
||||
key: "sample",
|
||||
url: "/...",
|
||||
|
||||
actions: {
|
||||
create: {
|
||||
method: "post",
|
||||
url: "/...",
|
||||
},
|
||||
|
||||
update: {
|
||||
method: "patch",
|
||||
url: (id) => `/content/rokn/profiles/${id}`,
|
||||
url: (id) => `/.../${id}`,
|
||||
},
|
||||
|
||||
delete: {
|
||||
method: "delete",
|
||||
url: (id) => `/.../${id}`,
|
||||
},
|
||||
|
||||
generate: {
|
||||
confirm: {
|
||||
method: "post",
|
||||
url: "/content/rokn/generate/profile",
|
||||
url: "/...",
|
||||
},
|
||||
|
||||
updateImages: {
|
||||
updateImage: {
|
||||
method: "post",
|
||||
url: (id) => `/content/rokn/profile-update/${id}/images`,
|
||||
url: (id) => `/.../${id}/image`,
|
||||
body: ({ formData }) => formData,
|
||||
},
|
||||
},
|
||||
@ -299,120 +245,17 @@ export const profileApi = createApi({
|
||||
|
||||
---
|
||||
|
||||
## گرفتن لیست
|
||||
|
||||
```jsx
|
||||
const { data, isLoading, error } = profileApi.useGet({
|
||||
page: 1,
|
||||
size: 20,
|
||||
is_confirmed: true,
|
||||
});
|
||||
```
|
||||
|
||||
این request ساخته میشود:
|
||||
|
||||
```txt
|
||||
GET /content/rokn/profiles?page=1&size=20&is_confirmed=true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## اجرای action
|
||||
|
||||
```jsx
|
||||
const updateProfile = profileApi.useAction("update");
|
||||
|
||||
await updateProfile.mutateAsync({
|
||||
id: 10,
|
||||
username: "new_username",
|
||||
});
|
||||
```
|
||||
|
||||
در این حالت:
|
||||
|
||||
```txt
|
||||
PATCH /content/rokn/profiles/10
|
||||
```
|
||||
|
||||
body:
|
||||
|
||||
```js
|
||||
{
|
||||
username: "new_username"
|
||||
}
|
||||
```
|
||||
|
||||
`id` به صورت پیشفرض از body حذف میشود، چون برای ساختن URL استفاده شده است.
|
||||
|
||||
---
|
||||
|
||||
## action با همان URL اصلی
|
||||
|
||||
اگر action همان URL اصلی را لازم دارد، نیازی نیست `url` را دوباره بنویسی.
|
||||
|
||||
```js
|
||||
export const identityGenerateApi = createApi({
|
||||
key: "identity-generate",
|
||||
url: "/content/rokn/identity-generate/logs",
|
||||
|
||||
actions: {
|
||||
delete: {
|
||||
method: "delete",
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
یعنی:
|
||||
|
||||
```txt
|
||||
DELETE /content/rokn/identity-generate/logs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## action با FormData
|
||||
|
||||
```js
|
||||
const updateImages = profileApi.useAction("updateImages");
|
||||
|
||||
const formData = new FormData();
|
||||
formData.append("image", file);
|
||||
|
||||
await updateImages.mutateAsync({
|
||||
id: 10,
|
||||
formData,
|
||||
});
|
||||
```
|
||||
|
||||
در تعریف action:
|
||||
|
||||
```js
|
||||
updateImages: {
|
||||
method: "post",
|
||||
url: (id) => `/content/rokn/profile-update/${id}/images`,
|
||||
body: ({ formData }) => formData,
|
||||
}
|
||||
```
|
||||
|
||||
`body` مشخص میکند چه چیزی واقعاً به عنوان body ارسال شود.
|
||||
|
||||
---
|
||||
|
||||
# استفاده از Keycloak
|
||||
# Keycloak
|
||||
|
||||
```js
|
||||
import {
|
||||
getKeycloakToken,
|
||||
loginKeycloak,
|
||||
logoutKeycloak,
|
||||
updateKeycloakToken,
|
||||
} from "uikit/core";
|
||||
|
||||
const token = getKeycloakToken();
|
||||
|
||||
await updateKeycloakToken(30);
|
||||
|
||||
loginKeycloak();
|
||||
|
||||
logoutKeycloak({
|
||||
@ -422,7 +265,7 @@ logoutKeycloak({
|
||||
|
||||
---
|
||||
|
||||
# استفاده از Permission
|
||||
# Permission
|
||||
|
||||
```jsx
|
||||
import { Can, usePermission } from "uikit/core";
|
||||
@ -442,27 +285,16 @@ function Page() {
|
||||
}
|
||||
```
|
||||
|
||||
نکته: prop کامپوننت `Can` برابر `perm` است.
|
||||
|
||||
```jsx
|
||||
<Can perm="users:list">
|
||||
<UsersList />
|
||||
</Can>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# استفاده از DataTable
|
||||
# DataTable
|
||||
|
||||
`DataTable` داخل مسیر `uikit/table` قرار دارد.
|
||||
|
||||
dependencyهای لازم:
|
||||
required dependencies:
|
||||
|
||||
```bash
|
||||
yarn add @chakra-ui/react @emotion/react @emotion/styled framer-motion @tanstack/react-table react-icons
|
||||
```
|
||||
|
||||
استفاده:
|
||||
using:
|
||||
|
||||
```jsx
|
||||
import { DataTable } from "uikit/table";
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user