diff --git a/beta/src/content/reference/react/useSyncExternalStore.md b/beta/src/content/reference/react/useSyncExternalStore.md index 38ab316cd..1f5fa22cb 100644 --- a/beta/src/content/reference/react/useSyncExternalStore.md +++ b/beta/src/content/reference/react/useSyncExternalStore.md @@ -4,7 +4,7 @@ title: useSyncExternalStore -`useSyncExternalStore` is a React Hook that lets you subscribe to an external store. +`useSyncExternalStore` es un Hook de React que te permite suscribirte a una fuente de almacenamiento de datos (*store*) externa. ```js const snapshot = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?) @@ -16,11 +16,11 @@ const snapshot = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot? --- -## Reference {/*reference*/} +## Referencia {/*reference*/} ### `useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?)` {/*usesyncexternalstore*/} -Call `useSyncExternalStore` at the top level of your component to read a value from an external data store. +Llama a `useSyncExternalStore` en el nivel superior de tu componente para leer un valor de una fuente de almacenamiento de datos externa. ```js import { useSyncExternalStore } from 'react'; @@ -32,43 +32,43 @@ function TodosApp() { } ``` -It returns the snapshot of the data in the store. You need to pass two functions as arguments: +Devuelve la instantánea de los datos en la fuente de almacenamiento de datos. Necesitas pasar dos funciones como argumentos: -1. The `subscribe` function should subscribe to the store and return a function that unsubscribes. -2. The `getSnapshot` function should read a snapshot of the data from the store. +1. La función `subscribe` debe suscribirse a la fuente de almacenamiento de datos y devolver una función que cancela dicha suscripción. +2. La función `getSnapshot` debería obtener una instantánea de los datos de la fuente de almacenamiento de datos. -[See more examples below.](#usage) +[Ver más ejemplos debajo.](#uso) -#### Parameters {/*parameters*/} +#### Parámetros {/*parameters*/} -* `subscribe`: A function that takes a single `callback` argument and subscribes it to the store. When the store changes, it should invoke the provided `callback`. This will cause the component to re-render. The `subscribe` function should return a function that cleans up the subscription. +* `subscribe`: Una función que toma un solo argumento `callback` y lo suscribe a la fuente de almacenamiento de datos. Cuando la fuente de almacenamiento de datos cambia, debe invocar el `callback` proporcionado. Esto hará que el componente se vuelva a rerenderizar. La función `subscribe` debería devolver una función que limpia dicha suscripción. -* `getSnapshot`: A function that returns a snapshot of the data in the store that's needed by the component. While the store has not changed, repeated calls to `getSnapshot` must return the same value. If the store changes and the returned value is different (as compared by [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)), React will re-render the component. +* `getSnapshot`: Una función que devuelve una instantánea de los datos de la fuente de almacenamiento de datos que necesita el componente. Si bien la fuente de almacenamiento de datos no ha cambiado, las llamadas repetidas a `getSnapshot` deben devolver el mismo valor. Si la fuente de almacenamiento de datos cambia y el valor devuelto es diferente (usando para la comparación [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) ), React volverá a rerenderizar el componente. -* **optional** `getServerSnapshot`: A function that returns the initial snapshot of the data in the store. It will be used only during server rendering and during hydration of server-rendered content on the client. The server snapshot must be the same between the client and the server, and is usually serialized and passed from the server to the client. If this function is not provided, rendering the component on the server will throw an error. +* **opcional** `getServerSnapshot`: Una función que devuelve la instantánea inicial de los datos de la fuente de almacenamiento de datos. Se usará solo durante el renderizado en el servidor y durante la hidratación del contenido renderizado por el servidor en el cliente. La instantánea del servidor debe ser la misma entre el cliente y el servidor, y generalmente se serializa y pasa del servidor al cliente. Si no se proporciona esta función, el renderizado del componente en el servidor generará un error. -#### Returns {/*returns*/} +#### Devuelve {/*returns*/} -The current snapshot of the store which you can use in your rendering logic. +La instantánea actual de la fuente de almacenamiento que puedes usar en tu lógica de renderizado. -#### Caveats {/*caveats*/} +#### Advertencias {/*caveats*/} -* The store snapshot returned by `getSnapshot` must be immutable. If the underlying store has mutable data, return a new immutable snapshot if the data has changed. Otherwise, return a cached last snapshot. +* La instantánea de la fuente de almacenamiento de datos devuelta por `getSnapshot` debe ser inmutable. Si la fuente subyacente tiene datos mutables, devuelve una nueva instantánea inmutable si los datos han cambiado. De lo contrario, devuelve la última instantánea almacenada en caché. -* If a different `subscribe` function is passed during a re-render, React will re-subscribe to the store using the newly passed `subscribe` function. You can prevent this by declaring `subscribe` outside the component. +* Si se pasa una función `subscribe` diferente durante un rerenderizado, React se volverá a suscribir a la fuente de almacenamiento de datos usando la función `subscribe` recién pasada. Puedes evitarlo declarando `subscribe` fuera del componente. --- -## Usage {/*usage*/} +## Uso {/*usage*/} -### Subscribing to an external store {/*subscribing-to-an-external-store*/} +### Suscripción a una fuente de almacenamiento datos externa {/*subscribing-to-an-external-store*/} -Most of your React components will only read data from their [props,](/learn/passing-props-to-a-component) [state,](/reference/react/useState) and [context.](/reference/react/useContext) However, sometimes a component needs to read some data from some store outside of React that changes over time. This includes: +Normalmente la mayoría de tus componentes de React solo leerán datos de sus [props,](/learn/passing-props-to-a-component), [estado,](/reference/react/useState) y [contexto.](/reference/react/useContext). Sin embargo, a veces un componente necesita leer algunos datos de alguna fuente de almacenamiento fuera de React que cambia con el tiempo. Esto incluye: -* Third-party state management libraries that hold state outside of React. -* Browser APIs that expose a mutable value and events to subscribe to its changes. +* Bibliotecas de gestión de estado de terceros que mantienen el estado fuera de React. +* APIs del navegador que exponen un valor mutable y eventos para suscribirse a sus cambios. -Call `useSyncExternalStore` at the top level of your component to read a value from an external data store. +Llama a `useSyncExternalStore` en el primer nivel de tu componente para leer un valor de una fuente de datos externa. ```js [[1, 5, "todosStore.subscribe"], [2, 5, "todosStore.getSnapshot"], [3, 5, "todos", 0]] import { useSyncExternalStore } from 'react'; @@ -80,14 +80,14 @@ function TodosApp() { } ``` -It returns the snapshot of the data in the store. You need to pass two functions as arguments: +Esto devuelve la instantánea del dato en la fuente de almacenamiento de datos. Necesitas pasar dos funciones como argumentos: -1. The `subscribe` function should subscribe to the store and return a function that unsubscribes. -2. The `getSnapshot` function should read a snapshot of the data from the store. +1. La función `subscribe` deberá suscribirse a la fuente de almacenamiento de datos y devolver una función que permita des suscribirse. +2. La función `getSnapshot` deberá obtener una instantánea de los datos de la fuente. -React will use these functions to keep your component subscribed to the store and re-render it on changes. +React utilizará estas funciones para mantener tu componente suscrito a la fuente de almacenamiento de datos y volver a renderizarlo con los cambios. -For example, in the sandbox below, `todosStore` is implemented as an external store that stores data outside of React. The `TodosApp` component connects to that external store with the `useSyncExternalStore` Hook. +Por ejemplo, en el *sandbox* debajo, `todosStore` se implementa como una fuente de almacenamiento de datos externa que almacena datos fuera de React. El componente `TodosApp` se conecta a esta fuente de almacenamiento externa de datos con el Hook `useSyncExternalStore`. @@ -112,11 +112,11 @@ export default function TodosApp() { ``` ```js todoStore.js -// This is an example of a third-party store -// that you might need to integrate with React. +// Este es un ejemplo de una fuente de almacenamiento de datos de terceros +// que podría necesitar integrarse con React. -// If your app is fully built with React, -// we recommend using React state instead. +// Si tu aplicación está completamente construida con React, +// recomendamos usar el control de estado de React en su lugar. let nextId = 0; let todos = [{ id: nextId++, text: 'Todo #1' }]; @@ -149,15 +149,15 @@ function emitChange() { -When possible, we recommend to use the built-in React state with [`useState`](/reference/react/useState) and [`useReducer`](/reference/react/useReducer) instead. The `useSyncExternalStore` API is mostly useful if you need to integrate with existing non-React code. +Cuando sea posible, recomendamos usar el control de estado incorporado en React con [`useState`](/reference/react/useState) y [`useReducer`](/reference/react/useReducer) en su lugar. La API `useExternalSyncStore` es útil mayormente si necesitas integrarte con código existente que no sea de React. --- -### Subscribing to a browser API {/*subscribing-to-a-browser-api*/} +### Suscripción a una API del navegador {/*subscribing-to-a-browser-api*/} -Another reason to add `useSyncExternalStore` is when you want to subscribe to some value exposed by the browser that changes over time. For example, suppose that you want your component to display whether the network connection is active. The browser exposes this information via a property called [`navigator.onLine`.](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine) This value can change over time without React's knowledge, so you need to read it with `useSyncExternalStore`. +Otra razón para usar `useSyncExternalStore` es cuando deseas suscribirte a algún valor expuesto por el navegador que cambia con el tiempo. Por ejemplo, supón que deseas que tu componente muestre si la conexión de red está activa. El navegador expone esta información a través de una propiedad llamada [`navigator.onLine`.](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine) Este valor puede cambiar con el tiempo sin que React sea notificado, por lo que necesitas leerlo con `useSyncExternalStore`. ```js import { useSyncExternalStore } from 'react'; @@ -168,7 +168,7 @@ function ChatIndicator() { } ``` -To implement the `getSnapshot` function, read the current value from the browser API: +Para implementar la función `getSnapshot`, lee el valor actual de la API del navegador: ```js function getSnapshot() { @@ -176,7 +176,7 @@ function getSnapshot() { } ``` -Next, you need to implement the `subscribe` function. For example, when `navigator.onLine` changes, the browser fires the [`online`](https://developer.mozilla.org/en-US/docs/Web/API/Window/online_event) and [`offline`](https://developer.mozilla.org/en-US/docs/Web/API/Window/offline_event) events on the `window` object. You need to subscribe the `callback` argument to the corresponding events, and then return a function that cleans up the subscriptions: +A continuación, debes implementar la función `subscribe`. Por ejemplo, cuando `navigator.onLine` cambia, el navegador activa los eventos [`online`](https://developer.mozilla.org/en-US/docs/Web/API/Window/online_event) y [`offline` ](https://developer.mozilla.org/en-US/docs/Web/API/Window/offline_event) en el objeto `window`. Debe suscribir el argumento `callback` a los eventos correspondientes y luego devolver una función que limpie estas suscripciones: ```js function subscribe(callback) { @@ -189,7 +189,7 @@ function subscribe(callback) { } ``` -Now React knows how to read the value from the external `navigator.onLine` API and how to subscribe to its changes. Try to disconnect your device from the network and notice that the component re-renders in response: +Ahora React sabe cómo leer el valor de la API `navigator.onLine` externa y cómo suscribirse a sus cambios. Intenta desconectar tu dispositivo de la red y observa que como respuesta el componente se vuelve a renderizar: @@ -219,11 +219,11 @@ function subscribe(callback) { --- -### Extracting the logic to a custom Hook {/*extracting-the-logic-to-a-custom-hook*/} +### Extracción de lógica en un Hook personalizado {/*extracting-the-logic-to-a-custom-hook*/} -Usually you won't write `useSyncExternalStore` directly in your components. Instead, you'll typically call it from your own custom Hook. This lets you use the same external store from different components. +Por lo general, no deberías escribir `useSyncExternalStore` directamente en tus componentes. En su lugar, normalmente lo llamarás desde tu propio Hook personalizado. Esto te permite usar la misma fuente de almacenamiento externa desde diferentes componentes. -For example, this custom `useOnlineStatus` Hook tracks whether the network is online: +Por ejemplo, este Hook personalizado `useOnlineStatus` monitoriza si la red está en línea: ```js {3,6} import { useSyncExternalStore } from 'react'; @@ -242,7 +242,7 @@ function subscribe(callback) { } ``` -Now different components can call `useOnlineStatus` without repeating the underlying implementation: +Ahora diferentes componentes pueden llamar a `useOnlineStatus` sin repetir la implementación subyacente: @@ -304,14 +304,14 @@ function subscribe(callback) { --- -### Adding support for server rendering {/*adding-support-for-server-rendering*/} +### Añadir compatibilidad con el renderizado en el servidor {/*adding-support-for-server-rendering*/} -If your React app uses [server rendering,](/reference/react-dom/server) your React components will also run outside the browser environment to generate the initial HTML. This creates a few challenges when connecting to an external store: +Si tu aplicación React usa [renderizado en el servidor,](/reference/react-dom/server), tus componentes React también se ejecutarán fuera del entorno del navegador para generar el HTML inicial. Esto crea algunos desafíos cuando se conecta a una fuente de datos externa: -- If you're connecting to a browser-only API, it won't work because it does not exist on the server. -- If you're connecting to a third-party data store, you'll need its data to match between the server and client. +- Si te estás conectando a una API única del navegador, no funcionará porque no existe en el servidor. +- Si te estás conectando a una fuente de datos externa de terceros, necesitarás que sus datos coincidan entre el servidor y el cliente. -To solve these issues, pass a `getServerSnapshot` function as the third argument to `useSyncExternalStore`: +Para resolver estos problemas, pasa una función `getServerSnapshot` como tercer argumento a `useSyncExternalStore`: ```js {4,12-14} import { useSyncExternalStore } from 'react'; @@ -334,26 +334,26 @@ function subscribe(callback) { } ``` -The `getServerSnapshot` function is similar to `getSnapshot`, but it runs only in two situations: +La función `getServerSnapshot` es similar a `getSnapshot`, pero solo se ejecuta en dos situaciones: -- It runs on the server when generating the HTML. -- It runs on the client during [hydration](/reference/react-dom/client/hydrateRoot), i.e. when React takes the server HTML and makes it interactive. +- Se ejecuta en el servidor al generar el HTML. +- Se ejecuta en el cliente durante la [hidratación](/reference/react-dom/client/hydrateRoot), es decir, cuando React toma el HTML del servidor y lo hace interactivo. -This lets you provide the initial snapshot value which will be used before the app becomes interactive. If there is no meaningful initial value for the server rendering, you can [force the component to render only on the client.](/reference/react/Suspense#providing-a-fallback-for-server-errors-and-server-only-content) +Esto te permite proporcionar la instantánea del valor inicial que se utilizará antes de que la aplicación se vuelva interactiva. Si no hay un valor inicial significativo para el renderizado en el servidor, puedes [forzar el componente para que se renderice solo en el cliente.](/reference/react/Suspense#providing-a-fallback-for-server-errors-and-server-only-content) -Make sure that `getServerSnapshot` returns the same exact data on the initial client render as it returned on the server. For example, if `getServerSnapshot` returned some prepopulated store content on the server, you need to transfer this content to the client. One common way to do this is to emit a `