前端開發 是做什麼的?
供真實使用者(使用鍵盤、螢幕閱讀器、慢速手機和印表機)瀏覽的瀏覽器 UI 標準。 以下規則是在 UI「看起來完成」時常常被跳過的項目。
最重要的規則
- 使用具有含義的元素。
<button>用於動作,<a href>用於導航,每個欄位都需要<label>,表格資料使用<table>。帶有點擊處理器的<div>無法聚焦、沒有角色,且對輔助技術不可見。ARIA 僅用於填補原生元素無法涵蓋的缺口。 - 每個非同步檢視都有四種狀態: 載入中、錯誤、空資料和有資料。在宣稱檢視完成之前,先寫好這四種狀態。空白區域即為錯誤。
- 絕不捏造資料。 缺失的期間應顯示為空缺或「無資料」標籤,絕不能顯示為零或插值線。預測值必須始終與實際值明顯區分。
- 絕不單獨使用顏色來傳遞訊息。 每個用顏色編碼的狀態也必須包含文字或具有可存取名稱的圖示。否則,灰階列印和色盲讀者將無法獲得任何資訊。
- 可分享的狀態應存在於 URL 中。 篩選條件、分頁標籤、搜尋詞、選取的 ID。返回、重新整理和分享都必須保留這些狀態。短暫狀態(懸停、開啟的工具提示)不應放入 URL。
- 由多個狀態推導出的值,應使用一個函數,並在任一狀態變更時呼叫。 切勿在屬於其中一個狀態的回呼函數內部計算它。範例:一個由截止日期和群組篩選器建構的下載連結,只在截止日期的擷取回呼中重建,因此在篩選器變更後,匯出功能會默默地指向整個清單。
- 從 320 CSS 像素寬度開始響應式設計。 無水平頁面滾動、無內容裁剪、文字可縮放至 200%。請同時在手機寬度和您設計的桌面寬度上進行測試。
- 根據需求選擇工具。 在現有儲存庫中,遵循已有的框架和建置工具。對於小型新頁面或內部工具,在引入建置流程之前,請先考慮純 HTML、CSS 和少量 JavaScript;當狀態管理確實需要時才使用框架。
何時不使用
- 選擇視覺方向、字體或色板:請使用
designer和visual-design技能。 - 原生 iOS、Android 或 React Native:請使用
mobile技能(Swift 程式碼使用swift)。 - API 形狀和伺服器端點:請使用
api-design和backend-patterns技能。 - 深入的測試技術:請使用
tdd和testing-strategy技能。
狀態存放位置
在撰寫元件狀態之前決定。從本地開始,僅在有明確理由時才升級。
| 狀態 | 存放位置 | 範例 |
|---|---|---|
| 本地 UI | 元件狀態 | 模態框開啟、輸入草稿、懸停 |
| 兄弟元件共享 | 最近的共同父元件 | 兩個面板讀取的作用中分頁 |
| 伺服器資料 | 伺服器快取庫(TanStack Query、SWR)或框架的載入器 | API 回應、分頁、重新擷取 |
| 應用程式全域客戶端狀態 | 小型 store(僅在需要時) | 已登入使用者、通知佇列 |
| 可分享的檢視狀態 | URL 查詢或路由 | 篩選條件、搜尋、選取的 ID |
| 跨重新整理持久化(每裝置) | localStorage | 偏好設定、未發送的草稿 |
僅在以下情況升級:兩個不相關的元件需要相同狀態(提升它,或使用伺服器快取);狀態必須在重新整理後存活(URL 或 storage);資料來自伺服器(使用伺服器快取,而非全域 store)。將伺服器資料複製到全域 store 會導致資料過時,並重複載入和錯誤邏輯。
圖表、列印與簡化檢視
- 圖表:前端和後端共享一個顏色對照表、明確的空資料狀態、誠實的空白缺口、一個 HTML 圖例。在建置或修改圖表之前,請閱讀
references/charts.md。 - 列印或 PDF:在建置可列印檢視之前,請閱讀
references/print.md。Canvas 在沒有其所描述的擷取步驟時,無法可靠列印。 - 為非技術讀者設計的簡化或唯讀檢視:無編輯控制項、寬裕的文字和目標點擊大小、同時使用顏色和文字表示狀態、從資料計算的淺顯易懂摘要、少數幾個畫面,以及使用標題數字搭配簡短句子,而非原始表格。
效能
按影響程度依序修復:首先是請求瀑布,然後是傳送的 JavaScript 量,接著是伺服器回應時間,最後是互動期間的主執行緒工作,微優化放在最後。目標:在實際訪問量的第 75 百分位數下,LCP 2.5 秒或更少、INP 200 毫秒或更少、CLS 0.1 或更少。當頁面載入緩慢時、在加入重量級依賴項之前,或在啟動具有效能目標的專案之前,請閱讀 references/performance.md。
常見陷阱
- 渲染路徑是熱迴圈。 元件主體或計算屬性的 getter 在每次懸停和每次不相關的狀態變更時都會執行。在此進行大量推導會導致主執行緒阻塞,第一個症狀可能是其他地方出現不穩定的測試。先進行去重,然後對上游輸入進行記憶化(memoise)。
- 未宣告的 CSS 自訂屬性會靜默失敗。 當 token 是
--font-mono時,使用var(--mono)會使宣告在計算值時無效:屬性會繼承,且不會報錯。在簡寫屬性中(font: 400 10px/1 var(--mono)),字型大小和行高也會失效。請為var()提供後備值,或對照產生的樣式表檢查已宣告的 token 與被引用的 token。 - 圖表的高度應設定在其外層容器上。 在
canvas上設定高度會與函式庫的調整大小邏輯衝突,導致圖表在每次調整大小時都會變大。 - 自訂小工具中的焦點管理是您的責任。 開啟對話框時應將焦點移入其中;關閉時應將焦點返回觸發元素;按下 Escape 鍵應關閉對話框。優先使用原生的
<dialog>元素。使用innerHTML重建標記會遺失焦點。 - 使用
outline: none但未提供替代方案 會移除鍵盤使用者唯一的視覺提示。請改用:focus-visible來設定焦點樣式。 - 僅圖示的按鈕需要名稱(使用
aria-label或視覺上隱藏的文字)。 - 僅在客戶端擷取後才存在的內容 在弱裝置上載入緩慢、在 JavaScript 失敗時呈現空白,且對爬蟲程式較不友善。在技術棧允許的情況下,應在伺服器端渲染有意義的內容。
- 未設定尺寸的媒體會導致版面佈局位移。 在圖片、影片和嵌入內容上設定
width和height(或aspect-ratio)。切勿對首屏最大的可視元素進行延遲載入。 - 手動實作的下拉選單、分頁標籤和滑桿 需要符合 WAI-ARIA 創作實踐中的完整鍵盤模型。使用原生元素幾乎總是更經濟的選擇。
- 手寫的虛擬 DOM 可能會使測試失效。 如果虛擬實作每次查詢都回傳一個新的物件,那麼寫入其中的每個屬性(
href、disabled、value)都會丟失,且針對它的任何斷言都無法失敗。請還原該功能,並要求在信任測試之前,測試必須能夠失敗。 - 使用固定的 CDN 版本,絕不要使用不固定的版本。 不固定的腳本會在您不知情且沒有提交記錄的情況下變更。
驗證
在新增工具之前,先使用專案已有的工具(其測試執行器、linter、型別檢查器、無障礙工具)來驗證。
- 測試、lint 和型別檢查通過。任何新測試都應在還原該功能後能看到測試失敗。
- 頁面已渲染並檢視過,包括手機寬度和桌面寬度。在可能的情況下,提供運行的預覽以及螢幕截圖給審查者。
- 僅使用鍵盤:每個控制項都可到達、可操作且有可見的焦點;順序與視覺順序相符;無焦點陷阱。
- 自動化無障礙審計(axe、Lighthouse 或專案的工具)無新增違規。使用工具檢查對比度:正文文字 4.5:1,大型文字和 UI 元件邊框 3:1(WCAG AA)。
- 透過強制觸發,分別展示載入中、錯誤、空資料和有資料狀態。
- 可分享的狀態在重新整理和返回後仍然存在。
- 主控台在載入和使用期間無任何錯誤和警告。
- 如果變更新增了依賴項或觸及了重量級檢視(使用套件分析器、限制速率的效能分析),則檢查效能預算。
- 如果頁面可列印,則檢查列印預覽。
對於審查,請按檔案回報發現的問題,指出違反的規則和解決方案,並按嚴重程度排序,最嚴重的優先。