聊聊 React 新文檔

語言: CN / TW / HK

React 官方文檔改版耗時 1 年,今天已完成站點相關改版,部分文檔已初步上線。

改版是因為現在文檔代碼和文檔內容都已過於陳舊,而且大部分文檔還是基於 class components 進行的講解,這次進行了全面 Hook 化

  • 關於新文檔討論的 Issue:https://github.com/reactjs/reactjs.org/issues/3308
  • PR 地址:https://github.com/reactjs/reactjs.org/pull/3965

訪問地址:https://beta.reactjs.org

今天從中文文檔維護者的角度和你聊聊,官方文檔的變化。

分為以下幾個部分:

  • 站點更新
  • 文檔內容
  • 關於中文文檔

站點更新

先來聊聊變化:

  1. 官網將使用框架從 Gatsby 替換為了 Next.js
  2. 引入了 tailwind
  3. 去除 Flow,全面 TypeScript
  4. 全新的交互設計
  5. 暗黑主題

先説框架切換,我認為這是必然結果。儘管 Gatsby 本身是靜態站點的理想選擇,但 Next 在服務端渲染方面表現更為出色,同時 Next 可以在運行時生成 HTML/CSS/JS,而 Gatsby 只能在構建時生成。

舊版文檔是自行編寫的樣式,而新版文檔採用了 tailwind 來編寫。儘管 CSS-in-JS 真香,但從性能層面來考量,還是差強人意。

Flow 是 Facebook 早期的產物,其作用也是對 JS 進行類型化,無論從設計還是使用層面,Flow 都遜色於 TypeScript。存在即合理,沒有 TypeScript 的時代,Flow 也曾頂起了半邊天。現在 Flow 已經完成了它的歷史使命。

新的交互整體看起來非常清爽,給官方點贊!

暗黑主題就不多説了,基本上是現在 Web 應用標配。

文檔內容

上午對所有文檔進行了整理,官方重寫了除了博客以外的全部文檔,很徹底

從文檔技術上來看,和 webpack 文檔一樣採用了 MDX 的形式進行文檔編寫,使得文檔變得更加靈活。

同時,將教程與 API 部分進行了分成了獨立的 Tab。

從官方給出的數據來看,目前文檔部分完成度:

  • Learn 部分:70%
  • API 部分:5%

關於內容的建議,大家可以去 reddit 上發表你的看法。

關於中文文檔

由於文檔內容部分,並未完全穩定。官方暫時不推薦進行翻譯工作

中文文檔會選擇性的對已穩定的部分進行翻譯。

中文文檔也拉取了新的 beta 分支,會每天與官方的 beta 分支進行同步。

新的文檔地址會盡快同步給大家,作為正式發佈前的嚐鮮版本,敬請期待。

相關進展會定期在印記中文公眾號進行同步,歡迎關注。

收穫

看了文檔站點的更新,聊聊我的收穫。

官方利用 patch-package 魔改了 google-analytics 的包。

當項目中使用到的 package 不符合預期/存在 bug 時,我們通常有幾種方案:

  • clone 項目,換個名字,發到 npm/tnpm/cnpm 上去
  • copy 到項目中,魔改
  • 使用 patch-package 對使用到的 package 進行 diff 調整。

貼一段 patch 的代碼

js - src={`https://www.googletagmanager.com/gtag/js?id=${process.env.GA_TRACKING_ID}`} + src={`https://www.googletagmanager.com/gtag/js?id=${process.env.NEXT_PUBLIC_GA_TRACKING_ID}`}

參與翻譯

如果你想參與到新文檔的翻譯工作中來,可以添加 docschina-bot

發送暗號:New React Docs

也可以關注 React 中文文檔倉庫,後續任務會以 issues 的方式發佈。