dynamic-form-kit-react (動態表單套件-react)

此專案僅用於展示。
如果需要實際應用的表單套件，請考慮持續發展的全面的表單套件作為表單元件庫，並且使用其他動態表單套件。
網站: dynamic-form-kit-react

| 語言 | README | |----------|------| | English | English README | | 繁體中文 | 繁體中文 README |

概述

這是快速產生表單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(動態表單元件設定):

語法說明

export const #objectName# = createDynamicFormComponentSetting<
  #FormInterface#, 
  #ComponentLibraryObject(optional)#
>()((d) => ({
  #fieldSettings(optional)#
}));

#fieldSettings(optional)#設定語法
每個欄位使用以下語法:

"#fieldName#": d({  
  componentName: #componentName#,  
  componentProps: #componentProps#  
}),  

以下支援 IntelliSense 自動提示：

• #fieldName#
• #componentName#
• #componentProps#:元件屬性設定

自訂表單資料範例:

設定範例:

使用VS Code IntelliSense範例:

Dynamic Form Validator Setting(動態表單驗證器設定):

語法說明

const #objectName#: DynamicFormValidatorSetting<#FormInterface#> = {
  #fieldSettings(optional)#
};

#fieldSettings(optional)#設定語法
每個欄位使用以下語法:

"#fieldName#": {
  validator: (fieldValue, parentObject, fieldKey, form) => {
    // 驗證邏輯 ...
    return {
      isError: boolean,
      message: string
    };
  },
  validGroupId?: string   //驗證群組 ID(選填)
}

若多個欄位擁有相同的 validGroupId，當其中任一欄位觸發驗證時，該群組內所有欄位會同步執行驗證。

以下支援 IntelliSense 自動提示：

• #fieldName#

設定範例:

使用VS Code IntelliSense範例:

Dynamic Form Builder(動態表單建造器):

語法說明

const #objectName# = <DynamicFormBuilder<#FormInterface#>
  formData={...}
  onChange={...}
  componentSetting={...}
  validatorSetting={...}
  actionButtons={...}         // 選填：提交、重置等動作按鈕設定
  componentLibrary={...}      // 選填：自訂元件庫
/>

簡易範例:

簡易範例介面:

Form Component Library(表單元件庫):

一組表單元件的集中入口.
內建表單元件庫.

自訂擴充表單元件庫

語法說明

const #objectName# = {
  #customComponentName#: #componentDefinition#,
  // ...more components
}

• #objectName#: 自訂擴充表單元件庫名稱
• #customComponentName#: 作為此元件在整個自訂擴充表單元件庫中的唯一識別 ID, 在Dynamic Form Component Setting中使用

範例:

自訂表單元件

語法

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元件.

範例:

多語系:

語法

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.

語法

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(靜態表單產生器指令集):

產生靜態表單指令:

npx gen-static-form --source "#source dir#" --target "#target dir#"

• "#source dir#"是Dynamic Form Component Setting的來源的頂部資料夾.
• "#target dir#"是產生Static Form的目標資料夾, 會覆寫, 不會刪除.

範例:

附註

• IDE使用VS Code，其餘IDE未確認。