Basic usage

In this section, we will introduce the core and basic functionalities of useRequest, that is, the functionalities of the useRequest kernel.

Default request

By default, the first parameter of useRequest is an asynchronous function, which is automatically executed when the component is initialized. At the same time, it automatically manages the status of loading, data, error of the asynchronous function.

const { data, error, loading } = useRequest(service);

Manually trigger

If options.manual = true is set, useRequest will not be executed by default, and the execution needs to be triggered by run or runAsync.

const { loading, run, runAsync } = useRequest(service, {
  manual: true
});

<button onClick={run} disabled={loading}>
  {loading ? 'Loading' : 'Edit'}
</button>

The difference between run and runAsync is:

• run is a normal synchronous function, we will automatically catch the exception, you can use options.onError to handle the behavior of the exception.

• runAsync is a asynchronous function that returns a Promise. If you use runAsync to call it, it means you need to catch the exception yourself.

  runAsync().then((data) => {
    console.log(data);
  }).catch((error) => {
    console.log(error);
  })

Next, we will demonstrate the difference between run and runAsync through the simple scenario of editing the username.

In this example, we use run(username) to edit the username, and use onSuccess and onError to handle success and failure.

In this example, we use runAsync(username) to edit the user name. At this time, we must catch the exception through catch.

The life cycle

useRequest provides the following life cycle for you to do some processing in different stages of asynchronous functions.

• onBefore: Triggered before the request
• onSuccess: Triggered when the request is resolved
• onError: Triggered when the request is rejected
• onFinally: Triggered when the request is completed

Refresh (repeat the last request)

useRequest provides the refresh and refreshAsync methods so that we can use the last parameters to re-run the request.

If in the scenario of reading user information

1. We read the user information with ID 1 run(1)
2. We updated user information by some ways
3. We want to re-initiate the last request, then we can use refresh instead of run(1), which is very useful in scenarios with complex parameters

Of course, the difference between refresh and refreshAsync is the same as run and runAsync.

Change data immediately

useRequest provides mutate, which can immediate modify the data.

The usage of mutate is consistent with React.setState, supports: mutate(newData) and mutate((oldData) => newData).

In the following example, we demonstrate a scenario of mutate.

We have modified the user name, but we do not want to wait for the request to be successful before giving feedback to the user. Instead, modify the data directly, then call the modify request in background, and provide additional feedback after the request returns.

Cancel response

useRequest provides a cancel function, which will ignore the data and error returned by the current promise

Note: Calling cancel doesn't cancel the execution of promise

At the same time, useRequest will automatically ignore the response at the following timing:

• When the component is unmounting, the ongoing promise
• Race cancellation, when the previous promise has not returned, if the next promise is initiated, the previous promise will be ignored

Parameter management

The params returned by useRequest will record the parameters of service. For example, if you trigger run(1, 2, 3), then params is equal to [1, 2, 3].

If we set options.manual = false, the parameters of calling service for the first time can be set by options.defaultParams.

API

const {
  loading: boolean,
  data?: TData,
  error?: Error,
  params: TParams || [],
  run: (...params: TParams) => void,
  runAsync: (...params: TParams) => Promise<TData>,
  refresh: () => void,
  refreshAsync: () => Promise<TData>,
  mutate: (data?: TData | ((oldData?: TData) => (TData | undefined))) => void,
  cancel: () => void,
} = useRequest<TData, TParams>(
  service: (...args: TParams) => Promise<TData>,
  {
    manual?: boolean,
    defaultParams?: TParams,
    onBefore?: (params: TParams) => void,
    onSuccess?: (data: TData, params: TParams) => void,
    onError?: (e: Error, params: TParams) => void,
    onFinally?: (params: TParams, data?: TData, e?: Error) => void,
  }
);

Result

Options

Above we have introduced the most basic functionalities of useRequest, and then we will introduce some more advanced functionalities.