flushSync

易犯错误

使用 flushSync 并不常见，并且会损害应用的性能。

¥Using flushSync is uncommon and can hurt the performance of your app.

flushSync 允许你强制 React 同步刷新提供的回调中的任何更新。这确保了 DOM 立即更新。

¥flushSync lets you force React to flush any updates inside the provided callback synchronously. This ensures that the DOM is updated immediately.

flushSync(callback)

参考

¥Reference

`flushSync(callback)`

调用 flushSync 以强制 React 刷新所有待处理的工作并同步更新 DOM。

¥Call flushSync to force React to flush any pending work and update the DOM synchronously.

import { flushSync } from 'react-dom';

flushSync(() => {
  setSomething(123);
});

大多数时候，flushSync 是可以避免的。使用 flushSync 作为最后的手段。

¥Most of the time, flushSync can be avoided. Use flushSync as last resort.

请参阅下面的更多示例。

¥See more examples below.

参数

¥Parameters

callback：一个功能。React 将立即调用此回调并同步刷新它包含的任何更新。它还可能刷新任何挂起的更新、副作用或副作用内部的更新。如果更新由于此 flushSync 调用而暂停，则可能会重新显示回退。

¥callback: A function. React will immediately call this callback and flush any updates it contains synchronously. It may also flush any pending updates, or Effects, or updates inside of Effects. If an update suspends as a result of this flushSync call, the fallbacks may be re-shown.

¥Returns

flushSync 返回 undefined。

¥flushSync returns undefined.

注意事项

¥Caveats

flushSync 会严重影响性能。谨慎使用。

¥flushSync can significantly hurt performance. Use sparingly.
flushSync 可能会强制挂起的 Suspense 边界显示其 fallback 状态。

¥flushSync may force pending Suspense boundaries to show their fallback state.
flushSync 可以运行待处理的效果并在返回之前同步应用它们包含的任何更新。

¥flushSync may run pending Effects and synchronously apply any updates they contain before returning.
flushSync 可能会在必要时刷新回调外部的更新以刷新回调内部的更新。例如，如果有来自点击的未决更新，React 可能会在刷新回调内的更新之前刷新这些更新。

¥flushSync may flush updates outside the callback when necessary to flush the updates inside the callback. For example, if there are pending updates from a click, React may flush those before flushing the updates inside the callback.

用法

¥Usage

刷新第三方集成的更新

¥Flushing updates for third-party integrations

当与第三方代码（如浏览器 API 或 UI 库）集成时，可能需要强制 React 刷新更新。使用 flushSync 强制 React 同步刷新回调中的任何状态 updates：

¥When integrating with third-party code such as browser APIs or UI libraries, it may be necessary to force React to flush updates. Use flushSync to force React to flush any state updates inside the callback synchronously:

flushSync(() => {
  setSomething(123);
});
// By this line, the DOM is updated.

这确保了在下一行代码运行时，React 已经更新了 DOM。

¥This ensures that, by the time the next line of code runs, React has already updated the DOM.

使用 flushSync 并不常见，经常使用它会严重损害应用的性能。如果你的应用只使用 React API，没有集成第三方库，那么 flushSync 应该是不必要的。

¥Using flushSync is uncommon, and using it often can significantly hurt the performance of your app. If your app only uses React APIs, and does not integrate with third-party libraries, flushSync should be unnecessary.

但是，它有助于与浏览器 API 等第三方代码集成。

¥However, it can be helpful for integrating with third-party code like browser APIs.

一些浏览器 API 期望在回调结束时将回调内的结果同步写入 DOM，以便浏览器可以对渲染的 DOM 执行某些操作。在大多数情况下，React 会自动为你处理。但在某些情况下，可能需要强制同步更新。

¥Some browser APIs expect results inside of callbacks to be written to the DOM synchronously, by the end of the callback, so the browser can do something with the rendered DOM. In most cases, React handles this for you automatically. But in some cases it may be necessary to force a synchronous update.

例如，浏览器 onbeforeprint API 允许你在打印对话框打开之前立即更改页面。这对于应用自定义打印样式非常有用，可以让文档更好地显示以进行打印。在下面的示例中，你在 onbeforeprint 回调中使用 flushSync 以立即将 React 状态 “刷新” 传递给 DOM。然后，当打印对话框打开时，isPrinting 显示 “yes”：

¥For example, the browser onbeforeprint API allows you to change the page immediately before the print dialog opens. This is useful for applying custom print styles that allow the document to display better for printing. In the example below, you use flushSync inside of the onbeforeprint callback to immediately “flush” the React state to the DOM. Then, by the time the print dialog opens, isPrinting displays “yes”:

复刻

import { useState, useEffect } from 'react';
import { flushSync } from 'react-dom';

export default function PrintApp() {
  const [isPrinting, setIsPrinting] = useState(false);

  useEffect(() => {
    function handleBeforePrint() {
      flushSync(() => {
        setIsPrinting(true);
      })
    }

    function handleAfterPrint() {
      setIsPrinting(false);
    }

    window.addEventListener('beforeprint', handleBeforePrint);
    window.addEventListener('afterprint', handleAfterPrint);
    return () => {
      window.removeEventListener('beforeprint', handleBeforePrint);
      window.removeEventListener('afterprint', handleAfterPrint);
    }
  }, []);

  return (
    <>
      <h1>isPrinting: {isPrinting ? 'yes' : 'no'}</h1>
      <button onClick={() => window.print()}>
        Print
      </button>
    </>
  );
}

如果没有 flushSync，打印对话框将把 isPrinting 显示为 “no”。这是因为 React 异步批处理更新，并且在更新状态之前显示打印对话框。

¥Without flushSync, the print dialog will display isPrinting as “no”. This is because React batches the updates asynchronously and the print dialog is displayed before the state is updated.

易犯错误

flushSync 会严重损害性能，并且可能会意外地强制挂起的 Suspense 边界显示其回退状态。

¥flushSync can significantly hurt performance, and may unexpectedly force pending Suspense boundaries to show their fallback state.

大多数时候，flushSync 是可以避免的，所以不得已才使用 flushSync。

¥Most of the time, flushSync can be avoided, so use flushSync as a last resort.

上一章createPortal

下一章preconnect