diff --git a/src/content/reference/react/hooks.md b/src/content/reference/react/hooks.md index dc80c55998..0e4e1e3cf7 100644 --- a/src/content/reference/react/hooks.md +++ b/src/content/reference/react/hooks.md @@ -79,6 +79,9 @@ Effect 是从 React 范式中的“脱围机制”。避免使用 Effect 协调 * [`useLayoutEffect`](/reference/react/useLayoutEffect) 在浏览器重新绘制屏幕前执行，可以在此处测量布局。 * [`useInsertionEffect`](/reference/react/useInsertionEffect) 在 React 对 DOM 进行更改之前触发，库可以在此处插入动态 CSS。 +You can also separate events from Effects: + +- [`useEffectEvent`](/reference/react/useEffectEvent) creates a non-reactive event to fire from any Effect hook. --- ## 性能 Hook {/*performance-hooks*/} diff --git a/src/content/reference/react/useEffectEvent.md b/src/content/reference/react/useEffectEvent.md index 533af144b4..b69eee22aa 100644 --- a/src/content/reference/react/useEffectEvent.md +++ b/src/content/reference/react/useEffectEvent.md @@ -4,65 +4,113 @@ title: useEffectEvent +<<<<<<< HEAD `useEffectEvent` 是一个 React Hook，它可以让你将 Effect 中的非响应式逻辑提取到一个可复用的函数中，这个函数称为 [Effect Event](/learn/separating-events-from-effects#declaring-an-effect-event)。 +======= +`useEffectEvent` is a React Hook that lets you separate events from Effects. +>>>>>>> e05afa56d3f0cb2db80c8f9d5d81705b0a289782 ```js -const onSomething = useEffectEvent(callback) +const onEvent = useEffectEvent(callback) ``` +<<<<<<< HEAD ## 参考 {/*reference*/} ### `useEffectEvent(callback)` {/*useeffectevent*/} 在组件的顶层调用 `useEffectEvent` 来声明一个 Effect Event。Effect Event 是你可以在 Effect 中调用的函数，例如 `useEffect`： +======= +--- + +## Reference {/*reference*/} + +### `useEffectEvent(callback)` {/*useeffectevent*/} + +Call `useEffectEvent` at the top level of your component to create an Effect Event. +>>>>>>> e05afa56d3f0cb2db80c8f9d5d81705b0a289782 -```js {4-6,11} +```js {4,6} import { useEffectEvent, useEffect } from 'react'; function ChatRoom({ roomId, theme }) { const onConnected = useEffectEvent(() => { showNotification('已连接！', theme); }); - - useEffect(() => { - const connection = createConnection(serverUrl, roomId); - connection.on('connected', () => { - onConnected(); - }); - connection.connect(); - return () => connection.disconnect(); - }, [roomId]); - - // ... } ``` +<<<<<<< HEAD [在下方查看更多示例](#usage) +======= +Effect Events are a part of your Effect logic, but they behave more like an event handler. They always “see” the latest values from render (like props and state) without re-synchronizing your Effect, so they're excluded from Effect dependencies. See [Separating Events from Effects](/learn/separating-events-from-effects#extracting-non-reactive-logic-out-of-effects) to learn more. + +[See more examples below.](#usage) +>>>>>>> e05afa56d3f0cb2db80c8f9d5d81705b0a289782 #### 参数 {/*parameters*/} +<<<<<<< HEAD - `callback`：一个包含你 Effect Event 逻辑的函数。当你使用 `useEffectEvent` 定义一个 Effect Event 时，`callback` 在被调用时总是可以访问到最新的 props 和 state。这有助于避免陈旧闭包问题。 +======= +* `callback`: A function containing the logic for your Effect Event. The function can accept any number of arguments and return any value. When you call the returned Effect Event function, the `callback` always accesses the latest committed values from render at the time of the call. +>>>>>>> e05afa56d3f0cb2db80c8f9d5d81705b0a289782 #### 返回值 {/*returns*/} +<<<<<<< HEAD 返回一个 Effect Event 函数。你可以在 `useEffect`、`useLayoutEffect` 或 `useInsertionEffect` 中调用这个函数。 +======= +`useEffectEvent` returns an Effect Event function with the same type signature as your `callback`. + +You can call this function inside `useEffect`, `useLayoutEffect`, `useInsertionEffect`, or from within other Effect Events in the same component. +>>>>>>> e05afa56d3f0cb2db80c8f9d5d81705b0a289782 将强制执行此限制，以防止在错误的上下文中调用效果事件。 +<<<<<<< HEAD #### 注意事项 {/*caveats*/} - **仅在 Effect 中调用**：Effect Event 应该只在 Effect 中调用。在使用它的 Effect 之前定义它。不要将它传递给其他组件或 hooks。[`eslint-plugin-react-hooks`](/reference/eslint-plugin-react-hooks) linter（6.1.1 或者更高版本）将强制执行此限制，以防止在错误的上下文中调用 Effect Events。 - **不是依赖数组的捷径**：不要用 `useEffectEvent` 来避免在 Effect 的依赖数组中声明依赖。这可能会隐藏 bug 并让代码更难理解。更推荐显式依赖，或使用 ref 来比较之前的值。 - **用于非响应式逻辑**：仅在逻辑不依赖变化的值时使用 `useEffectEvent` 来提取。 +======= +* `useEffectEvent` is a Hook, so you can only call it **at the top level of your component** or your own Hooks. You can't call it inside loops or conditions. If you need that, extract a new component and move the Effect Event into it. +* Effect Events can only be called from inside Effects or other Effect Events. Do not call them during rendering or pass them to other components or Hooks. The [`eslint-plugin-react-hooks`](/reference/eslint-plugin-react-hooks) linter enforces this restriction. +* Do not use `useEffectEvent` to avoid specifying dependencies in your Effect's dependency array. This hides bugs and makes your code harder to understand. Only use it for logic that is genuinely an event fired from Effects. +* Effect Event functions do not have a stable identity. Their identity intentionally changes on every render. +>>>>>>> e05afa56d3f0cb2db80c8f9d5d81705b0a289782 + + + +#### Why are Effect Events not stable? {/*why-are-effect-events-not-stable*/} + +Unlike `set` functions from `useState` or refs, Effect Event functions do not have a stable identity. Their identity intentionally changes on every render: + +```js +// 🔴 Wrong: including Effect Event in dependencies +useEffect(() => { + onSomething(); +}, [onSomething]); // ESLint will warn about this +``` -___ +This is a deliberate design choice. Effect Events are meant to be called only from within Effects in the same component. Since you can only call them locally and cannot pass them to other components or include them in dependency arrays, a stable identity would serve no purpose, and would actually mask bugs. + +The non-stable identity acts as a runtime assertion: if your code incorrectly depends on the function identity, you'll see the Effect re-running on every render, making the bug obvious. + +This design reinforces that Effect Events conceptually belong to a particular effect, and are not a general purpose API to opt-out of reactivity. + + + +--- ## 用法 {/*usage*/} +<<<<<<< HEAD ### 读取最新的 props 和 state {/*reading-the-latest-props-and-state*/} 通常，当你在 Effect 中访问一个响应式值时，你必须把它包含在依赖数组里。这样可以确保当这个值改变时，Effect 会再次运行，这通常是期望的行为。 @@ -70,27 +118,485 @@ ___ 但在某些情况下，你可能只想在 Effect 中读取最新的 props 或 state，而不希望当这些值改变时让 Effect 重新运行。 要在 Effect 中[读取最新的 props 或 state](/learn/separating-events-from-effects#reading-latest-props-and-state-with-effect-events)，而不让这些值成为响应式依赖，请把它们放进一个 Effect Event 中。 +======= + +### Using an event in an Effect {/*using-an-event-in-an-effect*/} + +Call `useEffectEvent` at the top level of your component to create an *Effect Event*: + +>>>>>>> e05afa56d3f0cb2db80c8f9d5d81705b0a289782 + +```js [[1, 1, "onConnected"]] +const onConnected = useEffectEvent(() => { + if (!muted) { + showNotification('Connected!'); + } +}); +``` + +`useEffectEvent` accepts an `event callback` and returns an Effect Event. The Effect Event is a function that can be called inside of Effects without re-connecting the Effect: + +```js [[1, 3, "onConnected"]] +useEffect(() => { + const connection = createConnection(roomId); + connection.on('connected', onConnected); + connection.connect(); + return () => { + connection.disconnect(); + } +}, [roomId]); +``` + +Since `onConnected` is an Effect Event, `muted` and `onConnect` are not in the Effect dependencies. + + + +##### Don't use Effect Events to skip dependencies {/*pitfall-skip-dependencies*/} + +It might be tempting to use `useEffectEvent` to avoid listing dependencies that you think are "unnecessary." However, this hides bugs and makes your code harder to understand: + +```js +// 🔴 Wrong: Using Effect Events to hide dependencies +const logVisit = useEffectEvent(() => { + log(pageUrl); +}); + +useEffect(() => { + logVisit() +}, []); // Missing pageUrl means you miss logs +``` + +If a value should cause your Effect to re-run, keep it as a dependency. Only use Effect Events for logic that genuinely should not re-trigger your Effect. + +See [Separating Events from Effects](/learn/separating-events-from-effects) to learn more. -```js {7-9,12} -import { useEffect, useContext, useEffectEvent } from 'react'; + -function Page({ url }) { - const { items } = useContext(ShoppingCartContext); - const numberOfItems = items.length; +--- + +### Using a timer with latest values {/*using-a-timer-with-latest-values*/} + +When you use `setInterval` or `setTimeout` in an Effect, you often want to read the latest values from render without restarting the timer whenever those values change. - const onNavigate = useEffectEvent((visitedUrl) => { - logVisit(visitedUrl, numberOfItems); +This counter increments `count` by the current `increment` value every second. The `onTick` Effect Event reads the latest `count` and `increment` without causing the interval to restart: + + + +```js +import { useState, useEffect, useEffectEvent } from 'react'; + +export default function Timer() { + const [count, setCount] = useState(0); + const [increment, setIncrement] = useState(1); + + const onTick = useEffectEvent(() => { + setCount(count + increment); }); useEffect(() => { - onNavigate(url); - }, [url]); - - // ... + const id = setInterval(() => { + onTick(); + }, 1000); + return () => { + clearInterval(id); + }; + }, []); + + return ( + <> +

+ Counter: {count} + +

+
+

+ Every second, increment by: + + {increment} + +

+ + ); } ``` +<<<<<<< HEAD 在本例中，当 `url` 发生变化时，Effect 应在呈现后重新运行（以记录新页面的访问），但当 `numberOfItems` 发生变化时，它 **不** 应该重新运行。通过将日志记录逻辑封装在一个 Effect 事件中，`numberOfItems` 就变成了非响应的。它总是从最新值读取，而不会触发 Effect。 你可以将 `url` 等响应式值作为参数传递给 Effect Event，使其保持响应状态，同时在事件内部访问最新的非响应式值。 +======= +```css +button { margin: 10px; } +``` + + +>>>>>>> e05afa56d3f0cb2db80c8f9d5d81705b0a289782 + +Try changing the increment value while the timer is running. The counter immediately uses the new increment value, but the timer keeps ticking smoothly without restarting. + +--- + +### Using an event listener with latest values {/*using-an-event-listener-with-latest-values*/} + +When you set up an event listener in an Effect, you often need to read the latest values from render in the callback. Without `useEffectEvent`, you would need to include the values in your dependencies, causing the listener to be removed and re-added on every change. + +This example shows a dot that follows the cursor, but only when "Can move" is checked. The `onMove` Effect Event always reads the latest `canMove` value without re-running the Effect: + + + +```js +import { useState, useEffect, useEffectEvent } from 'react'; + +export default function App() { + const [position, setPosition] = useState({ x: 0, y: 0 }); + const [canMove, setCanMove] = useState(true); + + const onMove = useEffectEvent(e => { + if (canMove) { + setPosition({ x: e.clientX, y: e.clientY }); + } + }); + + useEffect(() => { + window.addEventListener('pointermove', onMove); + return () => window.removeEventListener('pointermove', onMove); + }, []); + + return ( + <> + +
+
+ + ); +} +``` + +```css +body { + height: 200px; +} +``` + + + +Toggle the checkbox and move your cursor. The dot responds immediately to the checkbox state, but the event listener is only set up once when the component mounts. + +--- + +### Avoid reconnecting to external systems {/*showing-a-notification-without-reconnecting*/} + +A common use case for `useEffectEvent` is when you want to do something in response to an Effect, but that "something" depends on a value you don't want to react to. + +In this example, a chat component connects to a room and shows a notification when connected. The user can mute notifications with a checkbox. However, you don't want to reconnect to the chat room every time the user changes the settings: + + + +```json package.json hidden +{ + "dependencies": { + "react": "latest", + "react-dom": "latest", + "react-scripts": "latest", + "toastify-js": "1.12.0" + }, + "scripts": { + "start": "react-scripts start", + "build": "react-scripts build", + "test": "react-scripts test --env=jsdom", + "eject": "react-scripts eject" + } +} +``` + +```js +import { useState, useEffect, useEffectEvent } from 'react'; +import { createConnection } from './chat.js'; +import { showNotification } from './notifications.js'; + +function ChatRoom({ roomId, muted }) { + const onConnected = useEffectEvent((roomId) => { + console.log('✅ Connected to ' + roomId + ' (muted: ' + muted + ')'); + if (!muted) { + showNotification('Connected to ' + roomId); + } + }); + + useEffect(() => { + const connection = createConnection(roomId); + console.log('⏳ Connecting to ' + roomId + '...'); + connection.on('connected', () => { + onConnected(roomId); + }); + connection.connect(); + return () => { + console.log('❌ Disconnected from ' + roomId); + connection.disconnect(); + } + }, [roomId]); + + return

Welcome to the {roomId} room!

; +} + +export default function App() { + const [roomId, setRoomId] = useState('general'); + const [muted, setMuted] = useState(false); + return ( + <> + + +
+ + + ); +} +``` + +```js src/chat.js +const serverUrl = 'https://localhost:1234'; + +export function createConnection(roomId) { + // A real implementation would actually connect to the server + let connectedCallback; + let timeout; + return { + connect() { + timeout = setTimeout(() => { + if (connectedCallback) { + connectedCallback(); + } + }, 100); + }, + on(event, callback) { + if (connectedCallback) { + throw Error('Cannot add the handler twice.'); + } + if (event !== 'connected') { + throw Error('Only "connected" event is supported.'); + } + connectedCallback = callback; + }, + disconnect() { + clearTimeout(timeout); + } + }; +} +``` + +```js src/notifications.js +import Toastify from 'toastify-js'; +import 'toastify-js/src/toastify.css'; + +export function showNotification(message, theme) { + Toastify({ + text: message, + duration: 2000, + gravity: 'top', + position: 'right', + style: { + background: theme === 'dark' ? 'black' : 'white', + color: theme === 'dark' ? 'white' : 'black', + }, + }).showToast(); +} +``` + +```css +label { display: block; margin-top: 10px; } +``` + + + +Try switching rooms. The chat reconnects and shows a notification. Now mute the notifications. Since `muted` is read inside the Effect Event rather than the Effect, the chat stays connected. + +--- + +### Using Effect Events in custom Hooks {/*using-effect-events-in-custom-hooks*/} + +You can use `useEffectEvent` inside your own custom Hooks. This lets you create reusable Hooks that encapsulate Effects while keeping some values non-reactive: + + + +```js +import { useState, useEffect, useEffectEvent } from 'react'; + +function useInterval(callback, delay) { + const onTick = useEffectEvent(callback); + + useEffect(() => { + if (delay === null) { + return; + } + const id = setInterval(() => { + onTick(); + }, delay); + return () => clearInterval(id); + }, [delay]); +} + +function Counter({ incrementBy }) { + const [count, setCount] = useState(0); + + useInterval(() => { + setCount(c => c + incrementBy); + }, 1000); + + return ( +
+

Count: {count}

+

Incrementing by {incrementBy} every second

+
+ ); +} + +export default function App() { + const [incrementBy, setIncrementBy] = useState(1); + + return ( + <> + +
+ + + ); +} +``` + +```css +label { display: block; margin-bottom: 8px; } +``` + + + +In this example, `useInterval` is a custom Hook that sets up an interval. The `callback` passed to it is wrapped in an Effect Event, so the interval does not reset even if a new `callback` is passed in every render. + +--- + +## Troubleshooting {/*troubleshooting*/} + +### I'm getting an error: "A function wrapped in useEffectEvent can't be called during rendering" {/*cant-call-during-rendering*/} + +This error means you're calling an Effect Event function during the render phase of your component. Effect Events can only be called from inside Effects or other Effect Events. + +```js +function MyComponent({ data }) { + const onLog = useEffectEvent(() => { + console.log(data); + }); + + // 🔴 Wrong: calling during render + onLog(); + + // ✅ Correct: call from an Effect + useEffect(() => { + onLog(); + }, []); + + return
{data}
; +} +``` + +If you need to run logic during render, don't wrap it in `useEffectEvent`. Call the logic directly or move it into an Effect. + +--- + +### I'm getting a lint error: "Functions returned from useEffectEvent must not be included in the dependency array" {/*effect-event-in-deps*/} + +If you see a warning like "Functions returned from `useEffectEvent` must not be included in the dependency array", remove the Effect Event from your dependencies: + +```js +const onSomething = useEffectEvent(() => { + // ... +}); + +// 🔴 Wrong: Effect Event in dependencies +useEffect(() => { + onSomething(); +}, [onSomething]); + +// ✅ Correct: no Effect Event in dependencies +useEffect(() => { + onSomething(); +}, []); +``` + +Effect Events are designed to be called from Effects without being listed as dependencies. The linter enforces this because the function identity is [intentionally not stable](#why-are-effect-events-not-stable). Including it would cause your Effect to re-run on every render. + +--- + +### I'm getting a lint error: "... is a function created with useEffectEvent, and can only be called from Effects" {/*effect-event-called-outside-effect*/} + +If you see a warning like "... is a function created with React Hook `useEffectEvent`, and can only be called from Effects and Effect Events", you're calling the function from the wrong place: + +```js +const onSomething = useEffectEvent(() => { + console.log(value); +}); + +// 🔴 Wrong: calling from event handler +function handleClick() { + onSomething(); +} + +// 🔴 Wrong: passing to child component +return ; + +// ✅ Correct: calling from Effect +useEffect(() => { + onSomething(); +}, []); +``` +Effect Events are specifically designed to be used in Effects local to the component they're defined in. If you need a callback for event handlers or to pass to children, use a regular function or `useCallback` instead. \ No newline at end of file