blog-banner
JunyiAcademy 均一平台教育基金會
撰文者/均一平台教育基金會 宜陞

2020-04-20 Views: 4806

利用 Material-UI 統一 UI framework —— 均一前端工程師宜陞技術分享

Why we do this: 統一「自由奔放」的 UI 框架

1 個網站套用 5 個 UI 框架

開發前端 APP 的前置作業,不外乎是根據設計師送來的設計圖,從 UI 框架中選擇適用的元件(component),但均一團隊從「選擇 UI 框架」這件事開始,就是道複雜的多選題。

在還是好傻好天真的 ES5 時代,均一的網頁大多是套用 Bootstrap,當我們開始 migrate 到 ES6 + React,由於適用於 React 的 UI 框架仍未發展成熟,為了有充足的元件庫可以使用,均一先後引入了 Material-UI(註一)及 React-Bootstrap。

除了前面提到的歷史因素,造成均一 UI 框架混亂的關鍵因素還有維護套件註定要面對的「套件升級」。

當工程師發現現有的 UI 框架無法提供所需的元件,通常會考慮以下幾種解法:

  1. 自己刻出需要的元件
  2. 升級套件,擴充現有套件的元件庫
  3. 引入一個符合需求的新套件

如果是功能陽春的元件,通常會選擇「自己的元件自己刻」,但如果元件的功能複雜又遇上專案死線在即,往往會考慮引入新套件以加速開發,至於「套件升級」則因為牽一髮動全身的特性,總是淪為最不得已的選擇。

隨著新的 UI 框架持續被引入,舊框架的維護被長時間擱置,當我們鐵了心要規範框架的使用時,早已在均一的 codebase 中引入 5 大包 UI 框架 —— 引入了 Bootstrap、Semantic-UI、Material-UI、React-Bootstrap、Ant-Design。

其中較常被使用的 Material-UI、React-Bootstrap 都還停留在最初被引入時的版本號 version 0.x.x。

而過去過於「自由奔放」的管理原則,也產生了以下的技術債:

  • coding style 混亂
  • UI 框架版本老舊
  • 同一個頁面套用兩種以上框架,導致 UI 凌亂

為了償還前面提到的種種技術債,我們開始訂定相關的還債計畫。

 

註一:Material-UI 是當前流行的 UI 框架之一,它用來提供網頁中的元件(如:Button、Input)。

 

How we do this 1: 對 UI 框架專一

限縮框架數量

要確保 UI 框架不再多元發展,最直接的方式就是限縮框架的數量,因此目標之一就是選定「一個」適合長期使用的框架,並持續維護、更新。
當選定的框架無法提供工程師所需的元件,仍可以選擇引入較輕量的套件加速開發,確保工程團隊能靈活的運用第三方套件——但是,禁止再引入一整包框架!

選擇 Material-UI

在選擇框架前,我們調查了當前熱門的 UI 框架,考量到 Material-UI 的元件庫及 styling 解決方案相對完備,瀏覽器支援度符合團隊需求,且均一也已經有不少頁面是以 Material-UI 進行開發,因此,統一改成 Material-UI 的成本較小、易用性高,最後雀屏中選,成為均一主要的 UI 框架。

筆者在前一段提到均一使用的 Material-UI 還有個陳年的老問題:版本過舊,當我們開始研究 Material-UI 的發展近況時,才赫然發現 Material-UI 早已從 material-ui 轉移到 @material-ui/core。因此在採用 Material-UI 的第一個階段性任務就是:升級 Material-UI (from material-ui@0.19.0 to @material-ui/core@4.9.1),並在升級過程中改善 styling 相關技術。

 

How we do this 2: 選擇合適的 style API

升級 Material-UI 的過程,除了更新元件的語法,也花了不少心力思考怎麼善用 Material-UI 豐富的 styling 解決方案。最先遇到的問題就是如何取捨 style API(註二)。

使用 Material-UI 的 styled-components API 取代 styled-components library(註三)

在考慮引進 Material-UI 的 style API 之前,均一團隊慣用的解決方案是 styled-components library (以下簡稱 styled-components)。

使用舊版 Material-UI 時,因為 styled-components 的 CSS 權重不足,無法蓋過 Material-UI 元件的 inline style,所以我們仍是以 inline style 來實作 Material-UI 的元件客製化。

新版的 Material-UI,styled-components CSS 權重不足的問題已被解決,除此之外,Material-UI 也受到 styled-components 的啟發,進一步提供了 styled-components API (以下簡稱 styled API)。

由於 styled API 幾乎可以取代 styled-components,經過以下考量,均一團隊決定使用 styled API 取代 styled-components:

  • CSS 權重:使用 styled API 不需要額外設定 CSS 的權重
  • Theming:使用 styled API 可以直接取得 Material-UI 的 theme object,不需要混用 styled-components 的 theming 系統(註四)
  • Coding style:後面會提到我們也開放使用另一種 Material-UI 的 style API ——hook API。由於 styled API、hook API 的 CSS 皆是以 JSS 撰寫 (styled-components 的 CSS 則是用 String templates),選擇 styled API 能讓 CSS 的 coding style 更統一。

 

註二:style API 是 Material-UI 提供的 styling 解決方案之一,style API 可用來撰寫元件的 CSS。Material-UI 主要提供了 3 種 style API:hook API、styled components API、higher-order component API。 

註三:styled-components library 是一個 JavaScript 套件,它用來撰寫元件的 CSS。Material-UI 受到 styled-components library 啟發而發展出 styled-components API。 

註四:theme 可以用來更換網站的主題設計,如 styled-components library 與 Material-UI 皆提供所屬的 theme 系統(ThemeProvider)。可透過調整 theme 的設定,統一更換網站的主題(如:顏色、形狀、陰影)。

使用 classes API 客製化內層元件,並捨棄 global class

當遇上 Material-UI 元件含有內層元件時 (如:<Button> 其實內含了 MuiButton-root MuiButtom-label 兩層元件),Material-UI 針對內層元件的客製化提供了兩種方法:classes API 和 global class。

考量到 styled API 可以直接鎖定 global class,不像使用 classes API 還需要自訂義 classes,我們一開始選擇使用 global class 來客製化內層元件:

// 鎖定 global class .MuiButton-label 來客製化 Button 的內層元件 label
const StyledButton = styled(Button)(
    ({ theme }) => ({
        backgroundColor: 'white',
        '& .MuiButton-label': { // 鎖定 global class
            padding: [[theme.spacing(3)]],
        },
    }),
);

天真地用了一陣子後,才發現鎖定 global class 其實有個潛在問題:global class 是會變動的。當同一個元件樹中有巢狀的 theme 時,內層 theme 的 global class 會被加上 index,如:MuiTypography-root 會變為 MuiTypography-root-67

假如 styled API 鎖定了 MuiTypography-root ,可能會因為巢狀 theme 產生的 index 導致 CSS 選擇器失效。

而此問題的解法就是:classes API。由於 classes API 會產生獨立的 class ,不會因為巢狀 theme 導致失效,為了避免潛在問題,我們便捨棄了 global class,並統一使用 classes API:

// classes API:
const useButtonStyles = makeStyles(theme => ({
    root: {
        margin: 3,
    },
    myLabel: {
        padding: [[theme.spacing(3)]],
    },
}), { name: 'useButtonStyles' });

const StyledButton = ({ ...props }) => {
    const classes = useButtonStyles();
    return (<Button
        classes={{
            root: classes.root,
            label: classes.myLabel, // 改用 classes API 來客製化 Button 的內層元件 label
        }}
        {...props}
    />);
};

使用 hook API「拆分 style sheet」與「客製化多層的子元件」

隨著決定以 classes API 來實作內層元件客製化,團隊內也開始嘗試使用另一種 style API:hook API (makeStyles) 來操作 classes API。嘗試的過程中發現在某些情境下 hook API 能更有彈性的操作 style sheet。

例如在拆分 style sheet 的情境中,hook API 可以輕易的拆分 style sheet 並注入不同的元件:

const usePopupBtnStyles = makeStyles(theme => ({
    root: {  // 拆分出 root
        height: 70,
    },
    deleteContained: { // 拆分出 deleteContained
        color: theme.palette.primary.contrastText,
    },
}), { name: 'usePopupBtn' });

const PopupBtnDelete = ({ ...props }) => {
    const classes = usePopupBtnStyles();
    return (<Button
        classes={{
            root: classes.root, // 注入 root
            contained: classes.deleteContained, // 注入 deleteContained
        }}
        {...props}
    />);
};

const PopupBtnCancel = ({ ...props }) => {
    const classes = usePopupBtnStyles();
    return <Button classes={{ root: classes.root }} {...props} />; // 只注入 root
};

在另一種情境,當元件內有多層的子元件時,hook API 也能產生多份 style sheet 分別注入各個子元件:

// hook API
const useStepStyles = makeStyles(theme => ({ // 產生 4 份 style sheet
    labelContainer: {
        textAlign: 'center',
    },
    label: {
        fontSize: '24px',
    },
    stepLabelRoot: {
        background: theme.palette.primary.main,
    },
    stepRoot: {
        flex: 3,
    },
}), { name: 'StyledStepLabel' });

const StyledStepLabel = ({}) => {
    const classes = useStepStyles();
    return (<Step
        classes={{ root: classes.stepRoot }} // 其中 1 份,注入 Step 的 style
    >
        <StepLabel
            classes={{ // 其中 3 份,注入 StepLabel 的 styles
                root: classes.stepLabelRoot,
                labelContainer: classes.labelContainer,
                label: classes.label,
            }}
        >
            stepLabel
        </StepLabel>
    </Step>);
};

在 Material-UI 提供的 3 種 style API 之中,均一團隊主要仍使用 styled API,同時也持續嘗試 hook API 該如何和 styled API 配搭運用。

How we do this 3: 善用 theming,style 共用最大化

移除 styled-components 的 ThemeProvider

過去我們一直沒有明確規範 theming 的用法及用途,在各個專案中也會混用 Material-UI 及 styled-components 的 ThemeProvider

延續前面提到的,均一團隊將逐步淘汰 styled-components,所以在正式啟用 theming 前做的第一件事就是移除 styled-components 的 ThemeProvider 並統一使用 Material-UI 的 ThemeProvider

善用 Material-UI 的 ThemeProvider

 在統整各 package 的 theming 時,我們嘗試用以下原則進行重構:

  • 適用均一全站的 theme 統一放在 commonMuiTheme
  • 適用各個 package 的 theme 會寫在各自的 customTheme
  • 不適合套用整個 package 的元件客製化,則使用 style API
  • 同一個元件樹建議只有一個 ThemeProvider,避免巢狀 theme

重構的第一步,我們便根據設計師開出來的元件規範,寫出適用全站的 commonMuiTheme

// commonMuiTheme.js
const commonMuiTheme = {
    palette: {
        text: {
            primary: 'rgba(0, 0, 0, 0.6)',
        },
    },
};

第二步,則是在各 package 的 entry point 撰寫 customTheme,並透過 Material-UI 提供的 createMuiTheme 來 merge commonMuiTheme 和 customTheme

// entry point: index.js
const customTheme = {
    palette: {
        primary: courseMenuPalette.primary,
    },
};

/* 
 * createMuiTheme 能讓 customTheme 覆寫
 * commonMuiTheme 中相同的 key
 */
const muiTheme = createMuiTheme(commonMuiTheme, customTheme);

const show = () => (
        <ThemeProvider theme={muiTheme}>
        <Grouping/>
        </ThemeProvider>
);

最後,如果元件的客製化不適合放在 commonMuiThemecustomTheme,則會使用 hook 和 styled API 來實作。

How we fix problems: multiple ThemeProvider cause class name conflict

 除了 migration to Material-UI,均一團隊極力想完成的另一件大事就是 migration to React。

為了同時兼顧專案開發與均一團隊的技術提升,我們會在開發項目中安排 React migration,常見的作法是將頁面中的局部功能替換成 React,以逐步達成整個頁面的 migration 。

這個作法的結果,以均一的課程主題頁為例,課程主題頁只有「content」及「切換出版社 Button」是以 React + Material-UI 實作,在整個頁面中,「content」及「切換出版社 Button」是兩棵不同的元件樹,即兩棵樹有各自的 ThemeProvider

這種單一頁面多個 ThemeProvider 的情形,極有可能會發生 class name conflict,均一團隊在升級 Material-UI 的過程中就遇上了各種類型的 conflict。

以下範例可重現同一頁面中有兩個平行的 ThemeProvider會產生的問題。範例中的 Theme1 照理來說要為紅色,但因為 class name conflict 導致顯示為綠色:

const Theme1 = createMuiTheme({
  palette: {
    primary: {
      main: red[400]
    }
  }
});
const Theme2 = createMuiTheme({
  palette: {
    primary: {
      main: green[600]
    }
  }
});
const ThemeConflict = ({}) => (
    <div>
      <ThemeProvider theme={Theme1}>
          <Icon color="primary">add_circle</Icon> {// 預期為「紅色」,實際看到為「綠色」}
      </ThemeProvider>
      <ThemeProvider theme={Theme2}>
          <Icon color="primary">add_circle</Icon> {// 預期為「綠色」,實際看到為「綠色」}
      </ThemeProvider>
    </div>
);

造成 conflict 的原因是,兩個平行的 ThemeProvider 各自產生了同名的 global class MuiIcon-colorPrimary —— 不像巢狀 theme 還會為內層 theme 的 class 加上 index,由於 Theme2MuiIcon-colorPrimary 較晚被引入,導致 Theme2 的 class (綠色) 覆蓋掉 Theme1 的 class (紅色)。

<!-- output HTML -->
<div>
        <span class="material-icons MuiIcon-root MuiIcon-colorPrimary" aria-hidden="true">add_circle</span>
        <span class="material-icons MuiIcon-root MuiIcon-colorPrimary" aria-hidden="true">add_circle</span>
</div>

 

// output CSS
.MuiIcon-colorPrimary {
    color: #ef5350; // red[400]
}

.MuiIcon-colorPrimary {
    color: #43a047; // green[600]
}

當同一頁面中的 ThemeProvider 數量越來越多時就越有可能發生 conflict,甚至隨著環境 (local or production)不同還會遇到不同類型的 conflict。

幸好 Material-UI 都有提供自訂「class 生成規則」的方法,我們也在踩雷試錯的過程中找到了各種 conflict 的解法 —— conflict 都可以透過 Material-UI 提供的 createGenerateClassName 及 style API 的 name 解決。

What's next?

工程團隊費時兩個月終於完成了 Material-UI 升級,儘管仍有許多未竟之事(如:將其他 UI 框架替換成 Material-UI),但對均一的前端開發環境來說已是一大福音,光是可使用的元件大幅增加,就為開發帶來極大的便利。

為了確保統一 UI 框架之路能繼續走下去,工程團隊仍持續努力在 migration to React 或進行重構時,從其他框架轉移到 Material-UI。同時,我們也正在規劃和設計團隊協作進行 Atomic Design(註五),並基於 Material-UI 規劃共用的元件庫。

如果對均一前端的未來發展感興趣,可以持續關注我們,一起體會均一前端技術的成長與突破。

 

註五:Atomic Design 是一種設計方法論,此方法論將元件區分為五個層級 (由小到大為:原子、分子、組織、模板、頁面) 以促進元件的一致性與可擴展性。

 


 

均一招募中!

如果你對前端軟體開發充滿熱忱,而且跟宜陞一樣期待用科技來影響教育,我們正在尋找資深前端工程師、軟體工程師,馬上到招募頁面查看職位詳情!

快來認識 JunyiAcademy 均一平台教育基金會
均一平台教育基金會是一個致力於「讓每一位孩子都有機會成為終身學習者」的非營利組織。我們期許自己是一個「專業」導向的新形態非營利組織。過去的非營利組織比較是「善心、愛心」導向,定位在 Charity(慈善),功能為社會最後一道安全網。而均一定位自己為 Philantrophy(公益),從社會關懷出發,進而對社會產生實質、可衡量的正向改變與影響力。
JunyiAcademy 均一平台教育基金會
均一平台教育基金會(Junyi Academy Foundation,簡稱均一)是一個致力於「讓每一位孩子都有機會成為終身學習者」的非營利組織。 我們相信教育不僅是學習學科知...