From af243c80f84c7710e4a9843b9f75262960ee3ec1 Mon Sep 17 00:00:00 2001 From: Alex Liu Date: Sun, 12 Jan 2025 03:54:43 +0800 Subject: [PATCH] docs: add `status` detail and enhance `getCachedData` readability (#30536) --- docs/3.api/2.composables/use-async-data.md | 16 ++++++++++++++-- docs/3.api/2.composables/use-fetch.md | 16 ++++++++++++++-- 2 files changed, 28 insertions(+), 4 deletions(-) diff --git a/docs/3.api/2.composables/use-async-data.md b/docs/3.api/2.composables/use-async-data.md index 26296c56a9..afabbce35e 100644 --- a/docs/3.api/2.composables/use-async-data.md +++ b/docs/3.api/2.composables/use-async-data.md @@ -69,7 +69,13 @@ const { data: posts } = await useAsyncData( - `immediate`: when set to `false`, will prevent the request from firing immediately. (defaults to `true`) - `default`: a factory function to set the default value of the `data`, before the async function resolves - useful with the `lazy: true` or `immediate: false` option - `transform`: a function that can be used to alter `handler` function result after resolving - - `getCachedData`: Provide a function which returns cached data. A _null_ or _undefined_ return value will trigger a fetch. By default, this is: `key => nuxt.isHydrating ? nuxt.payload.data[key] : nuxt.static.data[key]`, which only caches data when `payloadExtraction` is enabled. + - `getCachedData`: Provide a function which returns cached data. A `null` or `undefined` return value will trigger a fetch. By default, this is: + ```ts + const getDefaultCachedData = (key) => nuxtApp.isHydrating + ? nuxtApp.payload.data[key] + : nuxtApp.static.data[key] + ``` + Which only caches data when `experimental.payloadExtraction` of `nuxt.config` is enabled. - `pick`: only pick specified keys in this array from the `handler` function result - `watch`: watch reactive sources to auto-refresh - `deep`: return data in a deep ref object (it is `true` by default). It can be set to `false` to return data in a shallow ref object, which can improve performance if your data does not need to be deeply reactive. @@ -94,7 +100,13 @@ Learn how to use `transform` and `getCachedData` to avoid superfluous calls to a - `data`: the result of the asynchronous function that is passed in. - `refresh`/`execute`: a function that can be used to refresh the data returned by the `handler` function. - `error`: an error object if the data fetching failed. -- `status`: a string indicating the status of the data request (`"idle"`, `"pending"`, `"success"`, `"error"`). +- `status`: a string indicating the status of the data request: + - `idle`: when the request has not started, such as: + - when `execute` has not yet been called and `{ immediate: false }` is set + - when rendering HTML on the server and `{ server: false }` is set + - `pending`: the request is in progress + - `success`: the request has completed successfully + - `error`: the request has failed - `clear`: a function which will set `data` to `undefined`, set `error` to `null`, set `status` to `'idle'`, and mark any currently pending requests as cancelled. By default, Nuxt waits until a `refresh` is finished before it can be executed again. diff --git a/docs/3.api/2.composables/use-fetch.md b/docs/3.api/2.composables/use-fetch.md index fdafe98ea2..42e1119b6e 100644 --- a/docs/3.api/2.composables/use-fetch.md +++ b/docs/3.api/2.composables/use-fetch.md @@ -109,7 +109,13 @@ All fetch options can be given a `computed` or `ref` value. These will be watche - `immediate`: when set to `false`, will prevent the request from firing immediately. (defaults to `true`) - `default`: a factory function to set the default value of the `data`, before the async function resolves - useful with the `lazy: true` or `immediate: false` option - `transform`: a function that can be used to alter `handler` function result after resolving - - `getCachedData`: Provide a function which returns cached data. A _null_ or _undefined_ return value will trigger a fetch. By default, this is: `key => nuxt.isHydrating ? nuxt.payload.data[key] : nuxt.static.data[key]`, which only caches data when `payloadExtraction` is enabled. + - `getCachedData`: Provide a function which returns cached data. A `null` or `undefined` return value will trigger a fetch. By default, this is: + ```ts + const getDefaultCachedData = (key) => nuxtApp.isHydrating + ? nuxtApp.payload.data[key] + : nuxtApp.static.data[key] + ``` + Which only caches data when `experimental.payloadExtraction` of `nuxt.config` is enabled. - `pick`: only pick specified keys in this array from the `handler` function result - `watch`: watch an array of reactive sources and auto-refresh the fetch result when they change. Fetch options and URL are watched by default. You can completely ignore reactive sources by using `watch: false`. Together with `immediate: false`, this allows for a fully-manual `useFetch`. (You can [see an example here](/docs/getting-started/data-fetching#watch) of using `watch`.) - `deep`: return data in a deep ref object (it is `true` by default). It can be set to `false` to return data in a shallow ref object, which can improve performance if your data does not need to be deeply reactive. @@ -134,7 +140,13 @@ Learn how to use `transform` and `getCachedData` to avoid superfluous calls to a - `data`: the result of the asynchronous function that is passed in. - `refresh`/`execute`: a function that can be used to refresh the data returned by the `handler` function. - `error`: an error object if the data fetching failed. -- `status`: a string indicating the status of the data request (`"idle"`, `"pending"`, `"success"`, `"error"`). +- `status`: a string indicating the status of the data request: + - `idle`: when the request has not started, such as: + - when `execute` has not yet been called and `{ immediate: false }` is set + - when rendering HTML on the server and `{ server: false }` is set + - `pending`: the request is in progress + - `success`: the request has completed successfully + - `error`: the request has failed - `clear`: a function which will set `data` to `undefined`, set `error` to `null`, set `status` to `'idle'`, and mark any currently pending requests as cancelled. By default, Nuxt waits until a `refresh` is finished before it can be executed again.