React 19.3 有哪些值得升級？ViewTransition、Fragment Refs 與 browser() 實作邊界

React 19.3 的四個重點，先分清用途#

官方這次把穩定功能和 React DOM／Server Components 的更新放在同一篇 release post。實作前可以先用下面的表格縮小範圍：

這些 API 在 React 19.3 穩定，不代表所有 framework adapter、SSR pipeline 或瀏覽器都已經以相同方式整合。升級時仍要把 React、React DOM、framework、測試 renderer 和 TypeScript 型別一起檢查。

<ViewTransition>：讓有意義的 state transition 產生動畫#

最小用法是把需要協調的畫面包在 <ViewTransition> 裡，並且由 startTransition 標記這次更新：

1
import { ViewTransition, startTransition, useState } from 'react'
2

3
export function DetailsToggle() {
4
  const [showDetails, setShowDetails] = useState(false)
5

6
  return (
7
    <>
8
      <button
9
        onClick={() => {
10
          startTransition(() => setShowDetails((value) => !value))
11
        }}
12
      >
13
        {showDetails ? '收合' : '展開'}
14
      </button>
15

16
      {showDetails && (
17
        <ViewTransition>
18
          <Details />
19
        </ViewTransition>
20
      )}
21
    </>
22
  )
23
}

React 會依 tree 的變化判斷 enter、exit、update 或 share。預設可以先得到 cross-fade，再用 CSS 的 View Transition class 或 onEnter、onExit、onShare、onUpdate 事件細調。要注意的是，沒有被標記為 Transition 的 urgent update 不會因此自動變成動畫；這是保留即時回應的設計。

Fragment Refs：沒有 wrapper 也能管理一組子節點#

元件回傳多個 sibling 時，傳統做法往往是加一個 <div> 當 ref anchor；這可能改變 CSS layout、accessibility tree 或 flex／grid 結構。React 19.3 的 Fragment Refs 讓 ref 可以直接放在 <Fragment> 上：

1
import { Fragment, useEffect, useRef } from 'react'
2

3
export function HeadingGroup({ headings }: { headings: string[] }) {
4
  const groupRef = useRef(null)
5

6
  useEffect(() => {
7
    groupRef.current?.focus()
8
  }, [])
9

10
  return (
11
    <Fragment ref={groupRef}>
12
      {headings.map((heading) => (
13
        <h2 tabIndex={-1} key={heading}>
14
          {heading}
15
        </h2>
16
      ))}
17
    </Fragment>
18
  )
19
}

這類 ref 提供的是一組子節點的有限操作介面，包括 event listener、focus／blur、IntersectionObserver／ResizeObserver 以及量測和 scroll。它不是一個虛擬 DOM 節點，也不是把 children 變成可以任意搬動的容器；程式仍要尊重 React 的 reconciliation 和元件生命週期。

實作時特別注意：

• 要把 ref 放在真正的 Fragment，不是任意 shorthand <>...</>。
• 先確認你需要的是「群組操作」，不是某一個深層 DOM 元素的 ref。
• observer 需要在 effect 中註冊和清理，避免每次 render 重複連線。
• 若只為了 focus 一個按鈕，直接讓該按鈕接收 ref 通常更簡單。

如果你的元件是第三方 library，Fragment Refs 可以減少為了暴露單一 wrapper 而修改 API 的需求；但這也表示元件的 DOM 子節點成為行為依賴，升級 library 時要補上 structure-level regression test。

use(browser())：只對真正 browser-only 的元件使用#

Server rendering 的元件應該盡量在 server 和 client 產生相同的初始 HTML。遇到 localStorage、裝置時區、瀏覽器權限或只能在 window 存在時取得的資料，React 19.3 提供 browser() 讓元件主動退出 SSR：

1
import { Suspense, use } from 'react'
2
import { browser } from 'react-dom'
3

4
function LocalTimeZone() {
5
  use(browser())
6

7
  const timeZone = new Intl.DateTimeFormat().resolvedOptions().timeZone
8
  return <p>{timeZone}</p>
9
}
10

11
export function TimeZonePanel() {
12
  return (
13
    <Suspense fallback={<p>正在讀取時區……</p>}>
14
      <LocalTimeZone />
15
    </Suspense>
16
  )
17
}

server render 時，最近的 Suspense fallback 會進到 HTML；元件 hydrate 後，use(browser()) 不會在 client suspend，元件才繼續讀取 browser-only API。這個模型比在 useEffect 裡設一個 mounted state 更直接，但代價是該區塊的 server HTML 只有 fallback，可能影響 SEO、首屏內容和無 JavaScript 的可用性。

可以用這個決策順序：

1. 能不能由 server 傳入固定的 initialValue？可以的話，優先用它，保留穩定初始 HTML。
2. 能不能把 browser-only 讀取延後到互動發生時？可以的話，不要讓整個元件退出 SSR。
3. 只有在沒有合理 server fallback 時，才使用 use(browser())，並替 Suspense fallback 寫好 loading、accessibility 和 layout 保留。

不要只把 typeof window !== 'undefined' 換成 browser() 就算完成；兩者的目的都是處理環境差異，但 browser() 會和 Suspense、SSR streaming 與 hydration 一起工作，驗收範圍更大。

Trusted Types：React 支援不等於網站已經安全#

React 19.3 會在 Trusted Types 物件傳到 DOM injection sink 前保留它，而不是先用字串串接把 TrustedHTML、TrustedScript 或 TrustedScriptURL 轉回普通字串。要發揮效果，網站仍需要瀏覽器 CSP 的 require-trusted-types-for 'script' 和可信任的 sanitizer policy。

升級後如果要啟用，請分三層驗證：

不要因為 React release note 寫了 Trusted Types support，就把現有的 HTML sanitize 移除。React 只改善值在 DOM API 間的傳遞方式，內容安全仍由你的 policy、來源驗證和 CSP 負責。

升級驗收：一次只導入一種新能力#

React 19.3 升級建議分階段做：

1
pnpm why react react-dom
2
pnpm exec tsc --noEmit
3
pnpm test
4
pnpm build

先只升級 react、react-dom 和對應型別，確認 hydration、Strict Mode、Suspense、router 與 test renderer 沒有回歸；再以小型元件導入 <ViewTransition>；最後才在確定 server fallback 可接受的區塊使用 browser()。若你原本就直接使用 DOM state-preserving API，也可以參考 moveBefore() 的狀態邊界；它和 React reconciliation 一樣，都要求先確認「誰擁有這個 DOM」。

CI 至少加上以下情境：

• SSR 輸出的 HTML 與 client 第一次 render 是否符合預期。
• transition 中的 fallback、錯誤邊界和取消更新。
• Fragment Ref 的 focus、observer cleanup 與無 wrapper layout。
• prefers-reduced-motion 和不支援 View Transition 的瀏覽器。
• Trusted Types report-only 與正式 CSP 的 console／response header。

結論：穩定 API 不代表可以跳過邊界設計#

React 19.3 的價值，是把常見的 UI 需求放進更清楚的 primitives：動畫交給 <ViewTransition>，群組 DOM 行為交給 Fragment Refs，browser-only rendering 交給 use(browser())，Trusted Types 則改善安全 API 的相容性。升級時先選一個真實問題導入，為它補上 SSR、fallback、accessibility 和 reduced-motion 測試，再擴大範圍，比一次把所有新 API 套進元件庫更容易定位回歸。

常見問題#