@ycw-side-projects/dynamic-form-kit-react
Version:
A personal dynamic form kit for React.
276 lines (217 loc) • 10.4 kB
Markdown
# `dynamic-form-kit-react` (動態表單套件-`react`)
> 此專案僅用於展示。
> 如果需要實際應用的表單套件，請考慮持續發展的全面的表單套件作為表單元件庫，並且使用其他動態表單套件。
> 網站: [dynamic-form-kit-react](https://chunwei.dev/zh-Hant/projects/dynamic-form-kit-react)
<!-- LANG-TABLE-START -->
| **語言** | **README** |
|----------|------|
| **English** | [English README](README.md) |
| **繁體中文** | [繁體中文 README](README.zh-Hant.md) |
<!-- LANG-TABLE-END -->
## 概述
這是快速產生表單UI的`React`套件，使用`typescript`。
- 透過`Dynamic Form Setting`(動態表單設定)產生`Dynamic Form`(動態表單)，在`IDE`(`VSCode`)編輯時支援`Intellisense`。
- 透過指令產生`Static Form`(靜態表單)檔案，其UI行為和`Dynamic Form`(動態表單)一致，並解除套件依賴。
- 透過`Dynamic Form Setting Editor`(動態表單設定編輯器)產生`Dynamic Form Setting`(動態表單設定)。
概述圖:
## 語意列表
### 一般
|語意|說明|
|---|---|
|`Dynamic Form`(動態表單)|透過設定動態產生的表單元件的表單UI|
|`Static Form`(靜態表單)|表單元件是固定的, 而不是透過設定動態產生|
|`Dynamic Form Setting`(動態表單設定)|設定動態表單, 包含設定各個資料欄位使用的表單元件及相關參數|
### 套件元件
|語意|說明|
|---|---|
|`Dynamic Form Component Setting`(動態表單元件設定)|對於表單欄位設定表單元件|
|`Dynamic Form Validator Setting`(動態表單驗證器設定)|對於表單欄位設定驗證器|
|`Dynamic Form Builder`(動態表單建造器)|透過設定動態使用表單元件並產生表單UI的元件|
|`Form Component Library`(表單元件庫)|一組表單元件的集中入口|
### 套件使用者介面
|語意|說明|
|---|---|
|`Static Form Generator Commands`(靜態表單產生器指令集)|用於產生靜態表單的指令集|
|`Dynamic Form Setting Editor`(動態表單設定編輯器)|編輯動態表單設定的UI|
|`Dynamic Form Setting Template`(動態表單設定範本)|對於動態表單設定的欄位設定的預設設定集合, 在編輯器中使用|
## 套件架構
### 套件應用圖:
### `Dynamic Form Component Setting`(動態表單元件設定):
#### 語法說明
```ts
export const #objectName# = createDynamicFormComponentSetting<
#FormInterface#,
#ComponentLibraryObject(optional)#
>()((d) => ({
#fieldSettings(optional)#
}));
```
`#fieldSettings(optional)#`設定語法
每個欄位使用以下語法:
```ts
"#fieldName#": d({
componentName: #componentName#,
componentProps: #componentProps#
}),
```
以下支援 IntelliSense 自動提示：
- `#fieldName#`
- `#componentName#`
- `#componentProps#`:元件屬性設定
自訂表單資料範例:
設定範例:
使用`VS Code IntelliSense`範例:
### `Dynamic Form Validator Setting`(動態表單驗證器設定):
#### 語法說明
```ts
const #objectName#: DynamicFormValidatorSetting<#FormInterface#> = {
#fieldSettings(optional)#
};
```
`#fieldSettings(optional)#`設定語法
每個欄位使用以下語法:
```ts
"#fieldName#": {
validator: (fieldValue, parentObject, fieldKey, form) => {
// 驗證邏輯 ...
return {
isError: boolean,
message: string
};
},
validGroupId?: string //驗證群組 ID(選填)
}
```
> 若多個欄位擁有相同的 `validGroupId`，當其中任一欄位觸發驗證時，該群組內所有欄位會同步執行驗證。
以下支援 IntelliSense 自動提示：
- `#fieldName#`
設定範例:
使用`VS Code IntelliSense`範例:
### `Dynamic Form Builder`(動態表單建造器):
#### 語法說明
```ts
const #objectName# = <DynamicFormBuilder<#FormInterface#>
formData={...}
onChange={...}
componentSetting={...}
validatorSetting={...}
actionButtons={...} // 選填：提交、重置等動作按鈕設定
componentLibrary={...} // 選填：自訂元件庫
/>
```
簡易範例:
簡易範例介面:
### `Form Component Library`(表單元件庫):
一組表單元件的集中入口.
內建表單元件庫.
#### 自訂擴充表單元件庫
##### 語法說明
```ts
const #objectName# = {
#customComponentName#: #componentDefinition#,
// ...more components
}
```
- `#objectName#`: 自訂擴充表單元件庫名稱
- `#customComponentName#`: 作為此元件在整個自訂擴充表單元件庫中的唯一識別 ID, 在`Dynamic Form Component Setting`中使用
範例:
#### 自訂表單元件
##### 語法
```ts
export const #objectName# = createDynamicFormComponentForLib<#CustomComponentProps#>()({
component: #CustomComponent#,
props: {} as #CustomComponentProps#,
propsKeys: #keys for generator#,
demo: #DemoComponent#,
propsEditor: #PropsEditorComponent#, // 選填
icon: #icon# // 選填
})
```
| 欄位名稱 | 用途 | 必要 |
| ------------- | ------------------------------------------------------ | -- |
| `component` | 實際用於渲染的 React 元件 | 是 |
| `props` | 元件 Props 型別，用於 `IntelliSense` | 是 |
| `propsKeys` | 用於`Static Form`生成的關鍵 props（如 `value`, `onChange`, `validation`） | 是 |
| `demo` | 在 `Dynamic Form Setting Editor`中顯示的Demo元件 | 是 |
| `propsEditor` | 自訂屬性編輯器，用於`Dynamic Form Setting Editor`中設定此元件的 Props | 選擇 |
| `icon` | 自訂圖標，用於`Dynamic Form Setting Editor`顯示 | 選擇 |
- `propsEditor`規格: 使用`DynamicFormComponentStandardPropsEditor`或`DynamicFormComponentDynamicPropsTextEditor`或是符合其型別的自訂React元件.
範例:
### 多語系:
### 語法
```ts
const getI18nLang_fromUrl = (): I18nLangType | null => { /* return I18nLangType|null */ };
const setI18nLang_toUrl = (lang: I18nLangType | null) => { /* custom code */ };
const TextProviderContent = () => {
const controller = useI18nController();
return <I18nTextProvider controller={controller}>
<#App# controller={controller} />
</I18nTextProvider>;
};
const ControllerProviderContent = () => {
return <I18nControllerProvider
useControllerHook={useDefaultI18nLangController}// 可替換成自訂的 useControllerHook
options={{
localStorageKey: '#custom key#',
defaultLang: "en", // 自訂
usingUrlLang: { getUrlLang: getI18nLang_fromUrl, setUrlLang: setI18nLang_toUrl } // 選用
}}
>
<TextProviderContent />
</I18nControllerProvider>;
};
```
| 區塊 | 說明用途 |
| ------------------------------------------- | ------------------------------------------------- |
| `getI18nLang_fromUrl` / `setI18nLang_toUrl` | 自訂從 URL 讀取或寫入語系，用於網址同步語言。 |
| `<I18nControllerProvider>` | 建立全域 I18n 控制器（包含語系狀態、localStorage、URL 同步）。 |
| `useControllerHook` | 指定使用的語系控制 Hook。 |
| `options.localStorageKey` | 多語設定記錄在 localStorage的Key。 |
| `options.defaultLang` | 預設語言, 使用`I18nLangType`的類型（e.g. `"en"`）。 |
| `options.usingUrlLang` | 可選，用於啟用網址語言同步機制。 |
| `<I18nTextProvider>` | 提供實際文字對應 (字典查找))。 |
| `controller` | 語系控制器，必須給`I18nTextProvider`, `Dynamic Form Setting Editor`, `Static Form`。 |
- `useControllerHook`: 有預設的`useDefaultI18nLangController`可以使用.
範例:
### `Dynamic Form Setting Editor`(動態表單設定編輯器):
使用編輯器:
使用`<DynamicFormHome #componentLibMap(optional)# />`使用編輯器.
- `#componentLibMap#`為符合`Map<string, ComponentLibForEditor>`格式的物件. 使用`getDefaultMapComponentLibForEditor()`取得包含預設lib的libMap.
#### 語法
```ts
const #objectName# = <DynamicFormHome
componentLibMap={#Component Library Map#}
langController={#II18nLangController#}
/>
```
- `#Component Library Map#`: 為`string`對應到`Form Component Library`的`Map`物件
- `#II18nLangController#`: 為`II18nLangController`物件
範例:
`Dynamic Form Setting Editor`的UI說明:
- 在UI中查看
### `Static Form Generator Commands`(靜態表單產生器指令集):
產生靜態表單指令:
```bash
npx gen-static-form --source "#source dir#" --target "#target dir#"
```
- `"#source dir#"`是`Dynamic Form Component Setting`的來源的頂部資料夾.
- `"#target dir#"`是產生`Static Form`的目標資料夾, 會覆寫, 不會刪除.
範例:
## 附註
- IDE使用`VS Code`，其餘IDE未確認。