docs(useRequest): add refreshDepsAction options and update demo (al…

…ibaba#2334) * docs: update refresh demo * chore: fix typo of filename * docs: update ready doc * chore: restore filename for better diff
mannix-lei · Sep 27, 2023 · 6f47ac4 · 6f47ac4
1 parent 5412bb7
commit 6f47ac4
Show file tree

Hide file tree

Showing 6 changed files with 72 additions and 42 deletions.
diff --git a/packages/hooks/src/useRequest/doc/ready/ready.en-US.md b/packages/hooks/src/useRequest/doc/ready/ready.en-US.md
@@ -7,7 +7,7 @@ group:
 
 # Ready
 
-useRequest provides an `options.ready`, when its value is `false`, the request will never be sent.
+By setting `options.ready`, you can control whether a request is sent. When its value is `false`, the request will never be sent.
 
 The specific behavior is as follows:
 

diff --git a/packages/hooks/src/useRequest/doc/ready/ready.zh-CN.md b/packages/hooks/src/useRequest/doc/ready/ready.zh-CN.md
@@ -7,7 +7,7 @@ group:
 
 # Ready
 
-useRequest 提供了一个 `options.ready` 参数，当其值为 `false` 时，请求永远都不会发出。
+通过设置 `options.ready`，可以控制请求是否发出。当其值为 `false` 时，请求永远都不会发出。
 
 其具体行为如下：
 

diff --git a/packages/hooks/src/useRequest/doc/refreshDeps/demo/refreshDeps.tsx b/packages/hooks/src/useRequest/doc/refreshDeps/demo/refreshDeps.tsx
@@ -1,45 +1,34 @@
 import React, { useState } from 'react';
+import Mock from 'mockjs';
 import { useRequest } from 'ahooks';
 
-const userSchool = (id: string) => {
-  switch (id) {
-    case '1':
-      return 'Tsinghua University';
-    case '2':
-      return 'Beijing University';
-    case '3':
-      return 'Zhejiang University';
-    default:
-      return '';
-  }
-};
+function getUsername(id: number): Promise<string> {
+  console.log('use-request-refresh-deps-id', id);
 
-async function getUserSchool(userId: string): Promise<string> {
   return new Promise((resolve) => {
     setTimeout(() => {
-      resolve(userSchool(userId));
+      resolve(Mock.mock('@name'));
     }, 1000);
   });
 }
 
 export default () => {
-  const [userId, setUserId] = useState('1');
-  const { data, loading } = useRequest(() => getUserSchool(userId), {
+  const [userId, setUserId] = useState<number>();
+  const { data, loading, run } = useRequest((id: number) => getUsername(id), {
     refreshDeps: [userId],
   });
 
+  if (loading) {
+    return <div>loading...</div>;
+  }
+
   return (
     <div>
-      <select
-        onChange={(e) => setUserId(e.target.value)}
-        value={userId}
-        style={{ marginBottom: 16, width: 120 }}
-      >
-        <option value="1">user 1</option>
-        <option value="2">user 2</option>
-        <option value="3">user 3</option>
-      </select>
-      <p>School: {loading ? 'Loading' : data}</p>
+      <p>Username: {data}</p>
+      <button style={{ marginRight: '8px' }} onClick={() => setUserId(Math.random())}>
+        Use previous id to refresh
+      </button>
+      <button onClick={() => run(Math.random())}>Use latest id to refresh</button>
     </div>
   );
 };
diff --git a/packages/hooks/src/useRequest/doc/refreshDeps/demo/refreshDepsAction.tsx b/packages/hooks/src/useRequest/doc/refreshDeps/demo/refreshDepsAction.tsx
@@ -0,0 +1,35 @@
+import React, { useState } from 'react';
+import Mock from 'mockjs';
+import { useRequest } from 'ahooks';
+
+function getUsername(id: number): Promise<string> {
+  console.log('use-request-refresh-deps-id', id);
+
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve(Mock.mock('@name'));
+    }, 1000);
+  });
+}
+
+export default () => {
+  const [userId, setUserId] = useState<number>();
+  const { data, loading, run } = useRequest((id: number) => getUsername(id), {
+    refreshDeps: [userId],
+    refreshDepsAction: () => run(userId),
+  });
+
+  if (loading) {
+    return <div>loading...</div>;
+  }
+
+  return (
+    <div>
+      <p>Username: {data}</p>
+      <button style={{ marginRight: '8px' }} onClick={() => setUserId(Math.random())}>
+        Use latest id to refresh
+      </button>
+      <button onClick={() => run(Math.random())}>Use latest id to refresh</button>
+    </div>
+  );
+};
diff --git a/packages/hooks/src/useRequest/doc/refreshDeps/refresyDeps.en-US.md b/packages/hooks/src/useRequest/doc/refreshDeps/refresyDeps.en-US.md
@@ -7,11 +7,10 @@ group:
 
 # RefreshDeps
 
-useRequest provides an `options.refreshDeps`, which will trigger the request refresh when its value changes.
+By setting `options.refreshDeps`, `useRequest` will run [refresh](https://ahooks.js.org/hooks/use-request/basic/#result) automatically when initialization and dependencies changes, achieving the effect of [Refresh (repeat the last request)](https://ahooks.js.org/hooks/use-request/basic/#refresh-repeat-the-last-request).
 
 ```tsx | pure
 const [userId, setUserId] = useState('1');
-
 const { data, run } = useRequest(() => getUserSchool(userId), {
   refreshDeps: [userId],
 });
@@ -23,22 +22,26 @@ It is exactly the same with the following implementation
 
 ```tsx | pure
 const [userId, setUserId] = useState('1');
-
 const { data, refresh } = useRequest(() => getUserSchool(userId));
 
 useEffect(() => {
   refresh();
 }, [userId]);
 ```
 
-You can experience the effect through the following example
+### Refresh last request
 
 <code src="./demo/refreshDeps.tsx" />
 
+### Custom refresh
+
+<code src="./demo/refreshDepsAction.tsx" />
+
 ## API
 
 ### Options
 
-| Property    | Description                                             | Type                   | Default |
-| ----------- | ------------------------------------------------------- | ---------------------- | ------- |
-| refreshDeps | When the content of the array changes, trigger refresh. | `React.DependencyList` | `[]`    |
+| Property          | Description                                                                                                                    | Type                   | Default |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ------- |
+| refreshDeps       | When the content of the array changes, trigger refresh.                                                                        | `React.DependencyList` | `[]`    |
+| refreshDepsAction | Customize the request behavior for dependency refresh, this parameter is called after initialization and dependencies changes. | `() => void`           | -       |
diff --git a/packages/hooks/src/useRequest/doc/refreshDeps/refresyDeps.zh-CN.md b/packages/hooks/src/useRequest/doc/refreshDeps/refresyDeps.zh-CN.md
@@ -7,11 +7,10 @@ group:
 
 # 依赖刷新
 
-useRequest 提供了一个 `options.refreshDeps` 参数，当它的值变化后，会重新触发请求。
+通过设置 `options.refreshDeps`，在初始化和依赖变化时， `useRequest` 会自动调用 [refresh](https://ahooks.js.org/zh-CN/hooks/use-request/basic/#result) 方法，实现[刷新（重复上一次请求）](https://ahooks.js.org/zh-CN/hooks/use-request/basic/#刷新重复上一次请求)的效果。
 
 ```tsx | pure
 const [userId, setUserId] = useState('1');
-
 const { data, run } = useRequest(() => getUserSchool(userId), {
   refreshDeps: [userId],
 });
@@ -23,22 +22,26 @@ const { data, run } = useRequest(() => getUserSchool(userId), {
 
 ```tsx | pure
 const [userId, setUserId] = useState('1');
-
 const { data, refresh } = useRequest(() => getUserSchool(userId));
 
 useEffect(() => {
   refresh();
 }, [userId]);
 ```
 
-你可以通过下面示例来体验效果
+### 刷新上一次请求
 
 <code src="./demo/refreshDeps.tsx" />
 
+### 自定义刷新行为
+
+<code src="./demo/refreshDepsAction.tsx" />
+
 ## API
 
 ### Options
 
-| 参数        | 说明                                                                | 类型    | 默认值 |
-| ----------- | ------------------------------------------------------------------- | ------- | ------ |
-| refreshDeps | 依赖数组，当数组内容变化后，发起请求。同 `useEffect` 的第二个参数。 | `any[]` | `[]`   |
+| 参数              | 说明                                                                | 类型         | 默认值 |
+| ----------------- | ------------------------------------------------------------------- | ------------ | ------ |
+| refreshDeps       | 依赖数组，当数组内容变化后，发起请求。同 `useEffect` 的第二个参数。 | `any[]`      | `[]`   |
+| refreshDepsAction | 自定义依赖刷新时的请求行为，该参数会在初始化和依赖变化后被调用。    | `() => void` | -      |
-Original file line number
+Diff line change
@@ Expand Up / @@ -7,7 +7,7 @@ group: @@
     # Ready
-    useRequest provides an `options.ready`, when its value is `false`, the request will never be sent.
+    By setting `options.ready`, you can control whether a request is sent. When its value is `false`, the request will never be sent.
     The specific behavior is as follows:
@@ Expand Down @@