docs: add note for refreshDeps

alibaba · Dec 18, 2023 · 9d82bd4 · 9d82bd4
1 parent b06cfea
commit 9d82bd4
Show file tree

Hide file tree

Showing 4 changed files with 63 additions and 37 deletions.
diff --git a/packages/hooks/src/useRequest/doc/refreshDeps/demo/refreshDeps.tsx b/packages/hooks/src/useRequest/doc/refreshDeps/demo/refreshDeps.tsx
@@ -1,9 +1,18 @@
+/**
+ * title: Repeat last request
+ * desc: When the dependency array changes, use the previous parameters to make the request again.
+ *
+ * title.zh-CN: 重复上一次请求
+ * desc.zh-CN: 依赖数组变化时，使用上一次的参数重新发起请求。
+ */
+
 import React, { useState } from 'react';
 import Mock from 'mockjs';
+import { Space, Button } from 'antd';
 import { useRequest } from 'ahooks';
 
 function getUsername(id: number): Promise<string> {
-  console.log('use-request-refresh-deps-id', id);
+  console.log('getUsername id:', id);
 
   return new Promise((resolve) => {
     setTimeout(() => {
@@ -18,17 +27,11 @@ export default () => {
     refreshDeps: [userId],
   });
 
-  if (loading) {
-    return <div>loading...</div>;
-  }
-
   return (
-    <div>
-      <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>
+    <Space direction="vertical">
+      <p>Username: {loading ? 'loading...' : data}</p>
+      <Button onClick={() => setUserId(Math.random())}>Use previous id to refresh</Button>
+      <Button onClick={() => run(Math.random())}>Use latest id to refresh</Button>
+    </Space>
   );
 };
diff --git a/packages/hooks/src/useRequest/doc/refreshDeps/demo/refreshDepsAction.tsx b/packages/hooks/src/useRequest/doc/refreshDeps/demo/refreshDepsAction.tsx
@@ -1,9 +1,19 @@
+/**
+ * title: Custom refresh
+ * desc: This example shows checking parameter validity when the dependency array changes, and then making a new request.
+ *
+ * title.zh-CN: 自定义刷新行为
+ * desc.zh-CN: 该示例展示了当依赖数组变化时，校验参数合法性，然后发起新的请求。
+ */
+
 import React, { useState } from 'react';
 import Mock from 'mockjs';
+import { isNumber } from 'lodash-es';
+import { Button, Space } from 'antd';
 import { useRequest } from 'ahooks';
 
 function getUsername(id: number): Promise<string> {
-  console.log('use-request-refresh-deps-id', id);
+  console.log('getUsername id:', id);
 
   return new Promise((resolve) => {
     setTimeout(() => {
@@ -16,20 +26,25 @@ export default () => {
   const [userId, setUserId] = useState<number>();
   const { data, loading, run } = useRequest((id: number) => getUsername(id), {
     refreshDeps: [userId],
-    refreshDepsAction: () => run(userId),
+    refreshDepsAction: () => {
+      if (!isNumber(userId)) {
+        console.log(
+          `parameter "userId" expected to be a number, but got ${typeof userId}.`,
+          userId,
+        );
+        return;
+      }
+      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>
+    <Space direction="vertical">
+      <p>Username: {loading ? 'loading...' : data}</p>
+      <Button onClick={() => setUserId(Math.random())}>
+        Use latest id to refresh (by `refreshDeps`)
+      </Button>
+      <Button onClick={() => run(Math.random())}>Use latest id to refresh (by `run`)</Button>
+    </Space>
   );
 };
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,7 +7,7 @@ group:
 
 # RefreshDeps
 
-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).
+By setting `options.refreshDeps`, `useRequest` will run [refresh](https://ahooks.js.org/hooks/use-request/basic/#result) automatically when dependencies change, 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');
@@ -29,7 +29,7 @@ useEffect(() => {
 }, [userId]);
 ```
 
-### Refresh last request
+### Repeat last request
 
 <code src="./demo/refreshDeps.tsx" />
 
@@ -41,7 +41,11 @@ useEffect(() => {
 
 ### Options
 
-| 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`           | -       |
+| Property          | Description                                                                                                   | Type                   | Default |
+| ----------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------- | ------- |
+| refreshDeps       | When the content of the array changes, trigger refresh.                                                       | `React.DependencyList` | `[]`    |
+| refreshDepsAction | Customize the request behavior during dependency refresh; this parameter is invoked when dependencies change. | `() => void`           | -       |
+
+## Remark
+
+- If you set `options.manual = true`, both `refreshDeps` and `refreshDepsAction` are no longer effective, you need to trigger the request by `run/runAsync`.
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,7 +7,7 @@ group:
 
 # 依赖刷新
 
-通过设置 `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/#刷新重复上一次请求)的效果。
+通过设置 `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');
@@ -29,7 +29,7 @@ useEffect(() => {
 }, [userId]);
 ```
 
-### 刷新上一次请求
+### 重复上一次请求
 
 <code src="./demo/refreshDeps.tsx" />
 
@@ -41,7 +41,11 @@ useEffect(() => {
 
 ### Options
 
-| 参数              | 说明                                                                | 类型         | 默认值 |
-| ----------------- | ------------------------------------------------------------------- | ------------ | ------ |
-| refreshDeps       | 依赖数组，当数组内容变化后，发起请求。同 `useEffect` 的第二个参数。 | `any[]`      | `[]`   |
-| refreshDepsAction | 自定义依赖刷新时的请求行为，该参数会在初始化和依赖变化后被调用。    | `() => void` | -      |
+| 参数              | 说明                                                                                                                                                       | 类型         | 默认值 |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------ |
+| refreshDeps       | 依赖数组。当数组内容变化后[刷新（重复上一次请求）](https://ahooks.js.org/zh-CN/hooks/use-request/basic/#刷新重复上一次请求)。同 `useEffect` 的第二个参数。 | `any[]`      | `[]`   |
+| refreshDepsAction | 自定义依赖数组变化时的请求行为。                                                                                                                           | `() => void` | -      |
+
+## 备注
+
+- 如果设置 `options.manual = true`，则 `refreshDeps`, `refreshDepsAction` 都不再生效，需要通过 `run/runAsync` 手动触发请求。