配置式表單渲染器的實作-有解無憂

我們是袋鼠云數堆疊 UED 團隊，致力于打造優秀的一站式資料中臺產品，我們始終保持工匠精神，探索前端道路，為社區積累并傳播經驗價值，，

本文作者：奇銘(掘金)

需求背景

前段時間，離線計算產品接到改造資料同步表單的需求，
一方面，資料同步模塊的代碼可讀性和可維護性比較差，相對應的，在資料同步模塊開發新功能和定位問題的效率很低；另一方面，整體規劃上，希望在對接新的資料源時，可以不再關心表單渲染相關問題，從資料源中心新建資料源一直到資料源在資料同步模塊的應用全鏈路的表單都可以通過配置化的方式解決；

資料同步表單

資料同步模塊整體上分為四個部分，資料來源表單，同步目標表單，欄位映射組件和通道控制表單，

file

其中前三個部分對應的代碼非常混亂，代碼量也很大，單個組件代碼 5000+ 行，這里著重說一下資料來源表單和同步目標表單，

資料同步來源和目標表單的主要功能就是收集資料源對應的配置資訊，并且根據資料源型別的不同，對應需要渲染的表單項也不相同，

目前離線計算產品資料同步功能的資料源有多達 50種，在長時間的迭代程序中，榷訓月累就出現了很多強行復用的代碼，這些強行復用的代碼內部又包含著大量的 if else 邏輯；

另外，資料同步模塊的表單內部有很多聯動關系，比如：

某個表單項的值變化時，需要發起介面請求，請求的回傳值被用作另一個表單項下拉框的資料
某個表單項的值變化時，需要去清空/重置其他一些表單項的值
某個表單項的值變化時，需要顯示/隱藏某個表單項
某個表單項的值變化時，某個表單項的 label 文案、表單項組件（比如從 select 變成 input ）等隨之發生變化

需求分析

基于上述需求背景，表單渲染器的核心功能是輸入一份配置，輸出表單UI組件，

file

基于上述資料同步表單背景，我們希望渲染器可以盡可能吸收掉表單內部的復雜度，也就是說在表單的配置中要能夠描述上述的聯動關系

那么可以大概得出表單的配置需要描述：

表單項的基礎資訊，比如欄位名、label、表單組件、校驗資訊等
表單項資料之間的聯動
表單項UI的聯動（控制顯示/隱藏）
表單項的值變化時需要觸發的副作用（比如呼叫介面）

表單基礎資訊描述

這里配置格式使用 JSON 格式，用一個陣列描述所有的表單項資訊，UI 上表單項的渲染順序即配置陣列中表單項配置的順序，表單組件使用 Ant Design Form.

對于表單項基礎資訊的描述配置，大多可以直接搬用 Ant Design Form Item 的 props，比如 label、rules、tooltip 等屬性，這里不多贅述，比較特殊的是，需要在配置里描述表單項描述的 UI 組件，比如 Select、Input，那么這里使用 widget 欄位去描述，另外，組件的描述除了組件名稱，還需要描述組件的 props，所以還需要一個 widgetProps 欄位去描述組件的屬性，比如 placeholder、disabled 等，

那么一個用于選擇資料源的表單項應該這樣描述：

{
  "fieldName": "sourceId",
  "label": "資料源",
  "rules": [
    {
      "required": true,
      "message": "請選擇資料源!",
    },
  ],
  "widget": "Select",
  "widgetProps": {
    "placeholder": "請選擇資料源",
    "options": [
      {
        "lable": "資料源1",
        "value": 1
      }
    ]
  },
}

當然可能會存在某些表單項的UI組件有自定義的情況，比如可編輯表格，代碼編輯器等，這個時候就需要開發自定義表單組件了，然后把這些組件注入到 formRenderer 中，偽代碼如下所示

import { Editor, EditableTable } from './customWigets'

export const getWidets = (widgetsName) => {
    switch(widgetsName) {
      case 'Editor': {
        return Editor
      }
      case 'EditableTable': {
        return EditableTable
      }
    }
} 

function Form () {
  return (
    <FormRenderer
        getWidets={getWidets}
    />
  )
}

那么目前的結構如圖所示

file

這份配置寫到這里的時候，問題出現了，

無法在配置中描述 onChange、onSelect 等事件回呼函式
相比于 jsx 強大的表達能力，json 中只能表達基本的資料結構，而沒辦法直接表達邏輯，
另外，Select 下拉框的資料可能來源于介面，這種情況在業務中相當常見，這里也沒辦法表達，
不能自定義表單校驗器，無法支持復雜的 Tootip 提示，比如帶有 a 標簽的 tootip

上述問題產生的根本原因，實際上是 JSON 與 jsx 之間表達能力的差距，但是從另一個角度來講，正因為 JSON 的表達能力和靈活性不如 jsx，所以在用來描述 UI 時，JSON 更不容易導致混亂，

我們先思考如何表達Select 下拉框的資料來源于介面，這里可以拆解為兩個部分：資料獲取和取得介面的回傳值并在配置項中表達，

資料獲取

實際上，select 下拉框中的資料也并不一定來源于介面，也可能是來源于其他業務資料，所以在配置項描述資料獲取邏輯時，不應該關心資料的來源，

很顯然，資料獲取邏輯需要用 js 描述，這里我們抽象出一個 Service 的概念，用于描述/宣告資料獲取邏輯，Service 的宣告使用 js，在 JSON 配置中，只需要去描述 Service 的呼叫邏輯即可
對于 JSON 配置來說， Service 呼叫需要三個要素：

Service 的標識/名稱，表示哪一個 Service 被觸發
Service 的觸發時機
Service 回傳的資料如何存盤

Service 的觸發時機

Service 的觸發一般來說是由于用戶的互動引起的，當然也存在在表單項組件掛載時就需要觸發的情況，那么呼叫時機大概就是以下幾種：

onMount
onChange
onSearch
onFocus
onBlur

Service 回傳的資料如何存盤

這里 Service 回傳的資料存盤需要能被 UI 獲取到，那么需要將回傳的資料都維護在 FormRender 內部，這里將存盤資料的地方命名為 extraData，那么我們描述 Service 回傳的資料的存盤，可以使用一個 fieldInExtraData 的欄位，描述當前 service 回傳的資料被存盤在 extraData 的那個欄位中，取值時：extraData[fieldInExtraData]

那么在表單項配置中描述 Service，如下所示

{
  "serviceName": "getSourceList",
  "triggers": ["onMount", "onSearch"],
  "fieldInExtraData": "schemaList"
}

Service 的宣告

對于 Service 本身來說，要做的事情就是獲取并處理資料然后回傳，當然 Service 本身可能需要接受一些引數比如當前 Form 收集到的資料、Service 是被哪個欄位觸發的、觸發時機是什么等等，那么 Service 的格式如下所示

const getSourceList = ({ formData, extraData, trigger, triggerFieldName }) => {
  return Promise((resolve) => {
    resolve(...)
  })
}

由于 Service 可能是異步的，所以這里 Service 都回傳一個 Promise

然后將所有的 Service 都注入到 FormRenderer 中，FormRenderer 根據表單項配置中宣告的呼叫時機去呼叫Service，整個資料獲取的鏈路就完成了，

獲取 Service 回傳值并在配置項中表達

上文中提到，Service 的回傳的資料都被存盤在 FormRenderer 內部的 extraData 中，一般情況下如果使用 jsx 當然能很容易的取到對應的值，但是在 JSON 中，是沒辦法表達的，但是我們可以借鑒 jsx 的插值運算式和vue的插值運算式，

<div>{user.name}</div>

在 jsx 中，如果在一對標簽內部寫了一串字串，對應的會有兩種決議策略，第一種是直接識別為字串，第二種如果識別到花括號，則將其視為js運算式，
同理，在JSON 配置中也可以使用這種方式去取值：

{
  "fieldName": "sourceId",
  "label": "資料源",
  "widget": "Select",
  "widgetProps": {
    "placeholder": "請選擇資料源",
    "options": "{{ extraData.sourceList }}"
  },
  "triggerServices": [
    {
      "serviceName": "getSourceList",
      "triggers": ["onMount", "onSearch"],
      "fieldInExtraData": "sourceList"
    }
  ]
}

函式運算式

上例中，使用一對花括號宣告函式運算式，表面上是借鑒了 jsx 的插值運算式，但是其實兩者有很大的區別，jsx 的插值運算式是在編譯階段就轉化成了 js 運算式，而在 JSON 中的這種自定義的函式運算式要在運行時轉換，上述的函式運算式只能被轉換為函式執行，即：

"{{ extraData.schemaList  }}"
// 轉化為
const valueGetter = new Function('extraData', 'return extraData.schemaList')

出于安全問題考慮，運算式還需要去被放在一個類似沙箱的環境執行，避免運算式內部修改全域環境變數，創建簡易沙箱使用 proxy + with + symbol.unscopables 的方式，這里不展開講解了，最終函式運算式的應用大概是如下形式

function Comp () {
  return <Select options={valueGetter(extraData)} />
}

到目前為止，已經有了兩個新概念：Service 和 函式運算式，回到上文中提到的問題，我們已經解決了 Select 下拉框來源于介面的問題，那么還剩下如下問題：

json 中只能表達基本的資料結構，而沒辦法直接表達邏輯，
無法在配置中描述 onChange、onSelect 等事件回呼函式，也不能自定義表單校驗器，
不能自定義表單校驗器，無法支持復雜的 Tootip 提示，比如帶有 a 標簽的 tootip

json 中沒辦法表達邏輯的問題，其實已經可以通過函式運算式來解決了，函式運算式內部支持寫任意的 js 運算式，另外，在函式運算式中也可以支持訪問form表單資料，有了資料支持和邏輯表達能力支持，絕大多數情況下的已經能夠滿足UI 渲染中的邏輯表達了，

而描述 onChange、onSelect 等事件回呼函式可以通過配置 Service 來解決，

自定義表達校驗器可以通過函式運算式的變種來解決，可以向 formRenderer 中注入 form 校驗器的集合，然后通過 {{ ruleMap.xxx }} 來指定表單項的某一條校驗規則的校驗器

{
  "fieldName": "sourceId",
  "label": "資料源",
  "rules": [
    {
    	validator: "{{ ruleMap.checkSourceId }}"
    },
  ],
}

tooltip 提示也是如此，
目前結構如下圖所示

file

表單資料聯動

表單資料聯動實際上就是當表單中某個表單項值變化時，去重置其他表單項的值，那么要在配置中描述這種聯動關系有兩種方式

當前欄位受哪些欄位的影響
當前欄位的值變化會影響到哪些欄位

一般情況下，在代碼中描述這種邏輯時都是采用第二種方式，也就是監聽某個欄位的值的變化，然后在回呼函式中去做對應的資料聯動操作，

但是在配置json時，第二種方式就變得不那么友好了，那會讓欄位配置之間產生更多的耦合，更加友好的方式是在某個欄位內表達本欄位受到哪些欄位的影響，這樣做的另一個好處時，當開發者填寫或者修改某一個欄位的配置時，可以更加聚焦，不用關心其他欄位的配置，

這里用 dependecies 欄位來表達當前欄位的值受哪些欄位的影響，舉個例子，表單中有資料源、schema、table 三個欄位，資料源變化時，schema 的值應該被重置；schema 變化時，table 的值會被重置，那么在 json 中應該這樣描述：

[
    {fieldName: 'sourceId', dependencies: []},
    {fieldName: 'schema', dependencies: ['sourceId']},
    {fieldName: 'table', dependencies: ['schema']},
]

對應的依賴關系圖：

file

這里新的問題產生了，當資料源變化時，table 的值是否要被重置？一般情況下是肯定的，那么實際上它們的依賴關系是這樣的：

file

這里有兩種方式來解決這種隱式的依賴關系

開發者在配置時顯式的宣告所有的依賴關系
渲染器內部決議依賴關系時，將這種隱式的依賴關系也決議出來

那么如何選擇使用哪一種方式呢？

如果采用第一種方式，優點是渲染器不再需要關心這種隱式的依賴關系了，但是在配置時的心智負擔可能比較大，很容易出現漏配依賴關系的情況，

如果采用第二種方式，優點是配置起來心智負擔低，但是也有可能出現 table 確實不依賴 sourceId 的情況，也就是間接依賴不生效的情況

結合實際業務看，目前的業務中，所有的欄位之間間接依賴其實都是隱式依賴，也就是需要生效的，這里采用第二種方式，前文中也提到了，期望是 formRenderer 可以盡可能的吸收掉表單內部的復雜度，

特殊的表單資料聯動

在實際業務中還存在著一些比較特殊的表單資料聯動，比如

選擇資料源時，除了需要收集資料源的 id，還需要收集資料源型別
選擇資料源后，需要將資料源的其他資訊展示為表單項，比如下圖中的表單

file

對于這種業務場景，我們可以理解為某個表單項的值是由其他表單項的值派生出來的，那么就需要去描述這種派生邏輯，當然，這種派生邏輯可以在業務代碼中描述，只需要在資料源變化時，手動的 setFieldValue 就可以了，但是還是上文中提到的期望，formRenderer 可以盡可能吸收掉復雜度，

處理這種情況，需要新增一個配置項去描述派生邏輯，這里配置項定為 valueDerived，這個配置項的值應該為一個取值運算式，那么以第一個例子為例，配置應該這樣子：

[
  {
    "fieldName": "sourceId",
    "label": "資料源",
    "widget": "Select",
    "widgetProps": {
      "placeholder": "請選擇資料源",
      "options": "{{ extraData.sourceList }}"
    },
  },
  {
    "fieldName": "sourceType",
    "label": "資料源型別",
    "hidden": true,
    "valueDerived": "{{ extraData.sourceList.find(s => s.value =https://www.cnblogs.com/dtux/archive/2023/05/10/== formData.sourceId).type }}",
  },
]

formRenderer 內部根據配置的 valueDerived 去自動更新表單中對應欄位的值

表單UI聯動

表單UI聯動可以分為兩個部分：

表單項UI文案、樣式等根據資料聯動，
表單項 UI 的顯示與隱藏

表單項UI文案、樣式等根據資料聯動

表單項的 UI 聯動在 React 和 JSX 中，都能很輕易、很自然的發生，但是想要在 JSON 中描述，由于JSON本身不具備表達邏輯的能力，還是要借助函式運算式，只需要支持對應的配置項可以使用函式運算式就能完成表單項的聯動，舉個例子：

[
  {
    "fieldName": "time",
    "label": "{{ extraData.type === 1 ? '開始時間' : '結束時間' }}",
    "widget": "Input",
    "widgetProps": {
      "placeholder":"{{ extraData.type === 1 ? '請輸入開始時間' : '請輸入結束時間' }}",
    },
  }
]

那么它們實際渲染時等同于以下偽代碼

function Comp (props) {
  const {fieldName, label, widget, widgetProps, extraData} = props
  
  const form = useFormInstance()
  const formData = https://www.cnblogs.com/dtux/archive/2023/05/10/form.getFieldsValue()
  
  const tarnsformer = (configItem) => {
    const fn = new Function('formData', 'extraData', `return $[configItem}`)
    return fn.call(null, formData, extraData)
  }

  return 
    <Form.Item
      name=fieldName
      label={tarnsformer(label)}
    >
    	<widget  placeholder={tarnsformer(widgetProps.placeholder)}/>
  	</Form.Item>
}

這樣就能做到表單項的文案樣式等根據資料變化自然的聯動，

表單項的顯示與隱藏

表單項的隱藏也能拆分為兩種情況

隱藏但不銷毀，表單項的值仍然會被收集和保留
銷毀，不再保留/收集表單項的值

隱藏但不銷毀的情況，antd form 本身就有 hidden 配置支持，那么這里只需要支持 hidden 配置使用函式運算式就可以了，

對于表單項的銷毀，就需要新增一個欄位了，這里命名為 destory，同樣通過支持使用函式運算式完成聯動，但是這里需要考慮一些其他情況，比如從銷毀狀態變成顯示狀態時，需要去觸發 mount service 等，

思路小結

回顧上文需求分析中所說的需要實作的功能

表單項的基礎資訊，比如欄位名、label、表單組件、校驗資訊等
表單項資料之間的聯動
表單項UI的聯動（控制顯示/隱藏）
表單項的值變化時需要觸發的副作用（比如呼叫介面）

目前在思路上，都是有上述功能都是可以實作的，除了基礎的渲染功能以外，FormRender 要額外實作的功能有

內置一個 extraData 存盤 Service 回傳的資料
支持根據配置在正確的時機觸發 Service
支持函式運算式
支持根據配置在內部處理資料聯動邏輯

大體實作

整體上，匯出一個 FormRenderer 組件，上文中提到的 json config、Service宣告、自定義的表單校驗器，自定義表單項組件等，都通過 FormRenderer 的 props 傳入，

內置 extraData

由于 extraData 內部存盤的資料變化可能導致視圖更新，那么只能使用 React.Context 或者 state，事實上即使使用 Context 也還是需要宣告 state 來觸發視圖更新，但是 Conetxt 在傳遞資料時有著獨特的優勢，這里直接使用 Context 存盤資料，

// 避免閉包問題
export function useExtraData(init: IExtraDataType) {
    const stateRef = useRef<IExtraDataType>(init);
    const [_, updateState] = useReducer((preState, action) => {
        stateRef.current =
            typeof action === 'function'
                ? { ...action(preState) }
                : { ...action };
        return stateRef.current;
    }, init);

    return [stateRef, updateState] as const;
}

// 創建context
const ExtraContext = React.createContext<ExtraContextType>({
    extraDataRef: { current: { } },
    update: () => void 0,
});

使用

import { useExtraData, ExtraContext } from 'extraDataContext.ts'

const FormRenderer: React.FC = () => {
  const [extraDataRef, updateExtraData] = useExtraData({});
  // ....
  return(
    <ExtraContext.Provider
      value=https://www.cnblogs.com/dtux/archive/2023/05/10/{{ extraDataRef, update: updateExtraData }}
    >
      {....}
    
  )     
}

在正確的時機觸發 Service

在JSON 配置中 service 相關描述如下所示

[
  {
    "fieldName": "sourceId",
    "label": "資料源",
    "triggerServices": [
      {
        "serviceName": "getSourceList",
        "triggers": ["onMount", "onSearch"],
        "fieldInExtraData": "sourceList"
      },
      {
        "serviceName": "getSchemaList",
        "triggers": ["onChange"],
        "fieldInExtraData": "schemaList"
      },
    ]
  }
]

triggerServices 已經很清楚直觀的描述了，該欄位在什么時機應該呼叫哪個 service，在代碼實作上，為了這部分觸發邏輯與視圖渲染分離，采用發布訂閱模式，大體流程如下圖所示：

file

這里流程已經走通了，但是可以發現，renderer 中仍然需要去處理訂閱的邏輯，Service 觸發邏輯與視圖渲染邏輯分離的不夠徹底，那么可以繼續優化一下，加入一個訂閱器去處理這部分邏輯，優化后的邏輯如下圖所示：

file

支持函式運算式

上文中提到了，函式運算式的實作是用 new Function，以及處于安全問題考慮需要將函式運算式放到模擬沙箱環境中執行，執行流程如下所示

file

實作代碼如下所示（不包含正則處理）

class FnExpressionTransformer {
    private sandboxProxiesMap: WeakMap<ScopeType, InstanceType<typeof Proxy>> =
        new WeakMap();

    private createProxy(scopeObj: ScopeType) {
        /** 存盤創建的 proxy 避免重復創建 */
        if (this.sandboxProxiesMap.has(scopeObj)) {
            return this.sandboxProxiesMap.get(scopeObj);
        }
        const scope = {
            extraData: scopeObj.extraDataRef,
            formData: scopeObj.formData,
            Math: Math,
            Date: Date,
        };
        const proxy = new Proxy(scope, {
            has() {
                return true;
            },
            get(target, prop) {
                if (prop === Symbol.unscopables) return undefined;
                if (prop === 'extraData') {
                    return target[prop]['current'];
                }
                return target[prop];
            },
        });
        this.sandboxProxiesMap.set(scopeObj, proxy);
        return proxy;
    }

    transform = (code: string): TransformedFnType => {
        return (scope: ScopeType) => {
            const proxy = this.createProxy(scope);
            const fnBody = `with(scope) {  return ${code} }`;
            const fn = new Function('scope', fnBody);
            return fn(proxy);
        };
    };
}

比如在 label 配置中使用了函式運算式

[
  {
    "fieldName": "name",
    "label": "{{ extraData.xxx ? '用戶名' : '昵稱' }}"
  }
]

那么經過轉換后，就是等同于以下函式

function lableValue (scope) {
  return scope.extraData.xxx;
}

應用:

<FormItem
  name={name}
  label={lableValue({ formData, extraData })}
>
{/* xxxx */}
</FormItem>

支持根據配置在內部處理資料聯動邏輯

與上文中service 觸發邏輯一樣，將這部分聯動的邏輯通過發布訂閱與視圖渲染邏輯分離，但是相比于service 觸發邏輯，這里多了分析依賴的步驟
比如，有如下 json 配置

[
   {fieldName: 'schema', dependencies: []},
   {fieldName: 'table', dependencies: ['schema']},
   {fieldName: 'partition', dependencies: ['schema', 'table']},
   {fieldName: 'coprate', dependencies: ['table', 'partition']}
]

那么生成的依賴關系圖就應該是：

[
  {fieldName: 'schema', isField: true]},
  {fieldName: 'table', isField: true},
  {fieldName: 'partition', isField: true},
  {fieldName: 'coprate', isField: true},
  {fieldName: 'schema', dependBy: 'table', isRelation: true},
  {fieldName: 'schema', dependBy: 'partition', isRelation: true},
  {fieldName: 'table', dependBy: 'partition', isRelation: true},
  {fieldName: 'table', dependBy: 'coprate', isRelation: true},
  {fieldName: 'partition', dependBy: 'coprate', isRelation: true},
]

生成上述依賴關系后，剩下的流程與觸發service 的流程類似，在這里不多做贅述了，

總結

回顧本文開頭需求分析部分中提到的需要實作的功能，到目前為止，似乎都實作了，但是其實很容易就產生一些疑問，這個東西它好用嗎？

作為開發者，我很難客觀的評價它好不好用，不過個人認為針對好不好用這個問題，還是有一些客觀條件去評價的

穩定性
可維護性
使用成本

對于穩定性， 目前還沒有在真實業務場景去落地，目前看不出，但是最近正在將部分業務中表單遷移到 FormRenderer，目前給我的感覺不是很穩定，經常需要去修改FormRenderer 的原始碼去修復一些小bug，或者是讓它的某些表現更符合實際的業務場景，貼一個 TODO LIST

file

這只是一部分，很多修改也沒有記錄在這上面，

可維護性，只針對于文章開頭提到的需求背景來說來說，使用 FormRenderer，顯然比已有的代碼更容易維護，

使用成本，這個成本要分為多方面來講，首先是學習使用 FormRenderer 的成本，這個成本顯然要比直接用 JSX 和 Antd 去開發表單的成本要高的多，使用者不僅需要了解 Antd 表單的使用，也需要熟悉 FormRenderer 的使用，其次是維護成本，我個人感覺它的維護成本會比資料同步的表單的維護成本要低，最后是開發成本，相比于開發組件，這個表單的開發成本主要體現在沒有自動提示以及糾錯，但是這個問題是可以通過開發一個類似 PlayGround 的在線編輯器去降低的，另外撰寫詳細的說明檔案也能顯著降低使用成本，

轉載請註明出處，本文鏈接：https://www.uj5u.com/qiye/552151.html

標籤：其他

上一篇：SAP 開發環境搭建入門

下一篇：返回列表