SWR 1.0 版本發布

大約 2 年前，我們開源（在新分頁中開啟）了 SWR，這個深受人們喜愛的小型數據獲取 React 函式庫。今天，我們將達到另一個里程碑：SWR 的 1.0 版本！

新功能

更小的尺寸

效能是 SWR 最重要的功能之一。在 1.0 版本中，我們在不移除任何現有功能的情況下，顯著縮小了函式庫的尺寸

• 核心部分縮小了 41%（經過 gzip 壓縮後縮小了 24%，3.9 kB）
• 套件安裝尺寸縮小了 52%
• 改進了 tree-shaking

縮小函式庫尺寸的原因有很多：您的應用程式將擁有更小的 bundle、更精簡的運行時，以及更小的 node_modules 目錄。

我們也改進了套件的打包，現在支援路徑導入

import useSWR from 'swr'
import useSWRInfinite from 'swr/infinite'

如果您沒有使用 useSWRInfinite，它將不會包含在您的應用程式中。

回退數據

在 1.0 版本中，有一個新的 fallback 選項，您可以將任何預先獲取的數據作為所有具有特定 key 的 SWR Hook 的初始值提供

<SWRConfig value={{
  fallback: {
    '/api/user': { name: 'Bob', ... },
    '/api/items': ...,
    ...
  }
}}>
  <App/>
</SWRConfig>

這對於 SSG、SSR 和測試的數據模擬等情境非常有幫助。請查看文件 Next.js SSG 和 SSR 以了解更多詳細資訊。

為了更好的一致性並避免混淆，舊的 initialData 現在被重新命名為 fallbackData，它仍然為給定的 Hook 提供單個回退值。

不可變模式

有時，您想要將資源標記為不可變，如果它永遠不會變更。最好為其停用自動重新驗證，並且只發出一次請求。現在有一個輔助 Hook 可以使這更容易

import useSWRImmutable from 'swr/immutable'
 
// ...
 
useSWRImmutable(key, fetcher, options)

它具有與 useSWR Hook 完全相同的 API，但它永遠不會在頁籤聚焦或網路恢復時重新驗證。還有一個新的選項 revalidateIfStale，您可以使用它來精確控制行為。更多資訊可以在這裡找到。

自定義快取供應商

預設情況下，SWR 使用單個全域快取來儲存所有數據。在 1.0 版本中，您可以使用新的 provider 選項來自定義它

<SWRConfig value={{
  provider: () => myCache
}}>
  <App/>
</SWRConfig>

您可以使用這個新功能來完成許多強大的事情。我們這裡有一些範例：使用 RegEx 異動多個 Key、基於 LocalStorage 的持久快取、在測試案例之間重置快取。

這個新的快取供應商 API 也更相容於 React 18 的並行渲染。如果您要新增快取供應商，請確保使用從 useSWRConfig() 回傳的全域 mutate 函數。

您可以閱讀快取供應商文件以了解更多詳細資訊。

useSWRConfig()

有一個新的 Hook API 可以回傳所有全域設定，包括目前的快取供應商和全域 mutate 函數

import { useSWRConfig } from 'swr'
 
function Foo () {
  const { refreshInterval, cache, mutate, ...restConfig } = useSWRConfig()
 
  // ...
}

更多資訊可以在這裡找到。

中介層

SWR 中介層為您提供了一種新的方式來建立和重複使用 SWR Hook 之上的抽象

<SWRConfig value={{ use: [...middleware] }}>
 
// ... or directly in `useSWR`:
useSWR(key, fetcher, { use: [...middleware] })

可以使用此功能實施許多新概念，我們建立了一些範例：請求記錄器、在變更 Key 時保留先前的數據，以及序列化物件 Key。

請查看中介層 API 以了解更多詳細資訊。

改進和更好的測試覆蓋率

自 0.x 版本以來，我們進行了數百項小的改進和錯誤修復。SWR 現在有 157 個測試，涵蓋了數據獲取中的大多數邊緣案例。請閱讀更新日誌（在新分頁中開啟）以了解更多詳細資訊。

文件翻譯

感謝我們的貢獻者（在新分頁中開啟）和 Nextra 的i18n 功能（在新分頁中開啟），我們現在提供六種不同語言的 SWR 文件

• 英文（在新分頁中開啟）
• 西班牙文（在新分頁中開啟）
• 簡體中文（在新分頁中開啟）
• 日文（在新分頁中開啟）
• 韓文（在新分頁中開啟）
• 俄文（在新分頁中開啟）

遷移指南

更新 useSWRInfinite 的引入

useSWRInfinite 需要從 swr/infinite 引入。

- import { useSWRInfinite } from 'swr'
+ import useSWRInfinite from 'swr/infinite'

如果您正在使用對應的類型，也請更新引入路徑。

- import { SWRInfiniteConfiguration, SWRInfiniteResponse } from 'swr'
+ import { SWRInfiniteConfiguration, SWRInfiniteResponse } from 'swr/infinite'

將 revalidate 變更為 mutate

useSWR 不再回傳 revalidate 方法，請改用 mutate。

- const { revalidate } = useSWR(key, fetcher, options)
+ const { mutate } = useSWR(key, fetcher, options)
 
 
  // ...
 
 
- revalidate()
+ mutate()

將 initialData 重新命名為 fallbackData

- useSWR(key, fetcher, { initialData: ... })
+ useSWR(key, fetcher, { fallbackData: ... })

不再有預設的 Fetcher

SWR 不再提供預設的 fetcher（會將資料解析為 JSON 的 fetch 呼叫）。 遷移此變更最簡單的方式是使用 <SWRConfig> 元件。

<SWRConfig value={{ fetcher: (url) => fetch(url).then(res => res.json()) }}>
  <App/>
</SWRConfig>
 
// ... or
useSWR(key, (url) => fetch(url).then(res => res.json()))

建議使用 Hook 回傳的 mutate

這並不是破壞性的變更，但我們現在會建議一律使用從 useSWRConfig Hook 回傳的 mutate。

- import { mutate } from 'swr'
+ import { useSWRConfig } from 'swr'
 
 
  function Foo () {
+   const { mutate } = useSWRConfig()
 
    return <button onClick={() => mutate('key')}>
      Mutate Key
    </button>
  }

如果您未使用快取提供者，目前全域引入 import { mutate } from 'swr' 仍然有效。

已重新命名的類型

如果您正在使用 TypeScript，為了保持一致性，已變更以下類型名稱。

Beta 版和非官方功能使用者

如果您正在使用 SWR 的 Beta 版本，或使用任何未記載的 API，請留意以下變更：

• import { cache } from 'swr' 已移除；請改用新的 useSWRConfig API。
• import { createCache } from 'swr' 已移除；請改用新的 快取提供者 API。
• revalidateWhenStale 已重新命名為 revalidateIfStale。
• middlewares 已重新命名為 use。

變更記錄

請在 GitHub 上閱讀完整的變更記錄 （在新分頁中開啟） （在新分頁中開啟）。

下一步

在未來的版本中，我們將持續改進此函式庫，同時維持其穩定性。我們也致力於支援未來的 React 版本，因為 1.0 中的數個新功能和改進已在為此做準備。此外，我們也正在努力開發新功能，以改善在 React 中進行資料提取的體驗，以及使用此函式庫的體驗。

如果您對此版本有任何意見回饋，請告訴我們 （在新分頁中開啟）。

謝謝！

特別感謝 Toru Kobayashi （在新分頁中開啟） 和 Yixuan Xu （在新分頁中開啟） 對此函式庫的貢獻，以及 Paco Coursey （在新分頁中開啟）、 uttk （在新分頁中開啟）、 Tomohiro SHIOYA （在新分頁中開啟）、 Markoz Peña （在新分頁中開啟）、 SeulGi Choi （在新分頁中開啟）、 Fang Lu （在新分頁中開啟）、 Valentin Politov （在新分頁中開啟） 對翻譯和文件的貢獻。 沒有他們的付出，這個版本不可能發布。

我們還要感謝整個社群、我們的 110 位貢獻者 （在新分頁中開啟）（+ 45 位文件貢獻者 （在新分頁中開啟）），以及所有協助我們並給予我們意見回饋的人！