improvement(alias & demos): add alias @components and add useRequest …

…demos

.dumi/theme/builtins/index.less

@@ -2,6 +2,12 @@
   display: none;
 }
 
+.__dumi-default-mobile-previewer {
+  .__dumi-default-tabs-nav {
+    display: none;
+  }
+}
+
 .__dumi-default-mobile-demo-layout {
   font-size: 0.36rem;
   padding: 0 !important;

.umirc.ts

@@ -18,6 +18,7 @@ export default defineConfig({
     '@tarojs/taro': '@tarojs/taro-h5',
     '@tarojs/runtime': '@taro-hooks/website-runtime',
     '@pages': __dirname + '/packages/app/src/pages',
+    '@components': __dirname + '/packages/app/src/components',
   },
   define: {
     'process.env.TARO_ENV': 'h5',

packages/app/config/index.js

@@ -1,3 +1,5 @@
+const { resolve } = require('path');
+
 const config = {
   projectName: 'taro-hooks',
   date: '2021-6-24',
@@ -16,6 +18,9 @@ const config = {
     options: {},
   },
   framework: 'react',
+  alias: {
+    '@components': resolve(__dirname, '../', 'src/components'),
+  },
   mini: {
     postcss: {
       pxtransform: {

packages/app/src/app.config.ts

@@ -16,6 +16,9 @@ export default {
     'pages/useUpdateManager/index',
     // network
     'pages/useRequest/index',
+    'pages/useRequest/defaultRequest/index',
+    'pages/useRequest/manual/index',
+    'pages/useRequest/polling/index',
     'pages/useNetworkType/index',
     'pages/useOnline/index',
   ],

packages/app/src/components/DocPage/index.tsx

@@ -29,7 +29,7 @@ const DocPage = ({ children, title, panelTitle }: IDocPageProps) => {
       <DocHeader title={title} />
       <View className="doc-body">
         <View className="panel">
-          <PaneTitle title={panelTitle} />
+          {panelTitle && <PaneTitle title={panelTitle} />}
           <View className="panel__content">{children}</View>
         </View>
       </View>

packages/app/src/pages/useAPICheck/index.tsx

@@ -6,7 +6,7 @@ import {
   AtNoticebar,
 } from 'taro-ui';
 import { View } from '@tarojs/components';
-import DocPage from '../../components/DocPage';
+import DocPage from '@components/DocPage';
 
 import { useEnv, useAPICheck } from 'taro-hooks';
 import { ENV_TYPE } from '@tarojs/taro';

packages/app/src/pages/useArrayBufferToBase64/index.tsx

@@ -6,7 +6,7 @@ import 'taro-ui/dist/style/components/article.scss';
 
 import { View } from '@tarojs/components';
 import { AtButton } from 'taro-ui';
-import DocPage from '../../components/DocPage';
+import DocPage from '@components/DocPage';
 
 import './index.less';
 

packages/app/src/pages/useBase64ToArrayBuffer/index.tsx

@@ -7,7 +7,7 @@ import 'taro-ui/dist/style/components/article.scss';
 
 import { View } from '@tarojs/components';
 import { AtInput } from 'taro-ui';
-import DocPage from '../../components/DocPage';
+import DocPage from '@components/DocPage';
 
 import './index.less';
 

packages/app/src/pages/useEnv/index.tsx

@@ -1,6 +1,6 @@
 import React, { useCallback } from 'react';
 import { AtRadio, AtMessage } from 'taro-ui';
-import DocPage from '../../components/DocPage';
+import DocPage from '@components/DocPage';
 
 import { useEnv } from 'taro-hooks';
 import Taro, { ENV_TYPE } from '@tarojs/taro';

packages/app/src/pages/useEvent/index.tsx

@@ -1,7 +1,7 @@
 import React, { useCallback } from 'react';
 import { AtList, AtListItem, AtMessage, AtDivider, AtCard } from 'taro-ui';
 import { View } from '@tarojs/components';
-import DocPage from '../../components/DocPage';
+import DocPage from '@components/DocPage';
 
 import { useEvent } from 'taro-hooks';
 import Taro, { ENV_TYPE } from '@tarojs/taro';

packages/app/src/pages/useNetworkType/index.tsx

@@ -1,6 +1,6 @@
 import React, { useCallback, useEffect } from 'react';
 import { AtMessage, AtRadio, AtNoticebar } from 'taro-ui';
-import DocPage from '../../components/DocPage';
+import DocPage from '@components/DocPage';
 
 import { useNetworkType } from 'taro-hooks';
 import Taro from '@tarojs/taro';

packages/app/src/pages/useOnline/index.tsx

@@ -1,6 +1,6 @@
 import React, { useCallback, useEffect } from 'react';
 import { AtMessage, AtSwitch, AtNoticebar } from 'taro-ui';
-import DocPage from '../../components/DocPage';
+import DocPage from '@components/DocPage';
 
 import { useOnline } from 'taro-hooks';
 import Taro from '@tarojs/taro';

packages/app/src/pages/useRequest/defaultRequest/index.config.ts

@@ -0,0 +1,3 @@
+export default {
+  navigationBarTitleText: 'useRequest 默认用法',
+};

packages/app/src/pages/useRequest/defaultRequest/index.tsx

@@ -0,0 +1,35 @@
+/**
+ * desc: 在这个例子中， useRequest 接收了一个异步函数 `getUsername` ，在组件初次加载时， 自动触发该函数执行。同时 useRequest 会自动管理异步请求的 `loading` , `data` , `error` 等状态。
+ */
+import React from 'react';
+import Mock from 'mockjs';
+import { useRequest } from 'taro-hooks';
+
+import { View } from '@tarojs/components';
+import DocPage from '@components/DocPage';
+
+function getUsername(): Promise<string> {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      // 兼容小程序写法
+      resolve(Mock.mock('@name()'));
+    }, 1000);
+  });
+}
+
+const DefaultRequest = () => {
+  const { data, error, loading } = useRequest(getUsername);
+  return (
+    <DocPage title="useRequest 请求" panelTitle="默认请求">
+      {error ? (
+        <View>failed to load</View>
+      ) : loading ? (
+        'loading...'
+      ) : (
+        <View>Username: {data}</View>
+      )}
+    </DocPage>
+  );
+};
+
+export default DefaultRequest;

packages/app/src/pages/useRequest/index.tsx

@@ -1,44 +1,51 @@
 import React, { useCallback } from 'react';
-import { AtMessage } from 'taro-ui';
-import { View } from '@tarojs/components';
-import DocPage from '../../components/DocPage';
 
-import { useUpdateManager } from 'taro-hooks';
-import Taro from '@tarojs/taro';
+import { navigateTo } from '@tarojs/taro';
+
+import { AtList, AtListItem } from 'taro-ui';
+import DocPage from '@components/DocPage';
 
 import 'taro-ui/dist/style/components/icon.scss';
+import { AtListItemProps } from 'taro-ui/types/list';
 
-export default () => {
-  const onCheckForUpdate = useCallback((res) => {
-    Taro.atMessage({
-      message: res.hasUpdate ? '有新版本' : '无新版本',
-    });
-  }, []);
+interface IListItem extends AtListItemProps {
+  route: string;
+}
 
-  const onUpdateReady = useCallback(() => {
-    Taro.atMessage({
-      message: '检查更新成功',
-    });
-  }, []);
+const list: IListItem[] = [
+  {
+    title: '默认请求',
+    note: '在组件初次加载时， 自动触发该函数执行。',
+    route: 'defaultRequest',
+  },
+  {
+    title: '手动触发',
+    note: '通过设置 options.manual = true , 则需要手动调用 run 时才会触发执行异步函数。',
+    route: 'manual',
+  },
+  {
+    title: '轮询',
+    note: '通过设置 options.pollingInterval，进入轮询模式，定时触发函数执行。',
+    route: 'polling',
+  },
+];
 
-  const onUpdateFailed = useCallback(() => {
-    Taro.atMessage({
-      message: '检查更新失败',
-    });
+export default () => {
+  const routePage = useCallback((route: string) => {
+    navigateTo({ url: `${route}/index` });
   }, []);
 
-  const updateManager = useUpdateManager({
-    onCheckForUpdate,
-    onUpdateReady,
-    onUpdateFailed,
-  });
-
   return (
-    <>
-      <AtMessage />
-      <DocPage title="useRequest 请求" panelTitle="useRequest">
-        <View>检查更新中....</View>
-      </DocPage>
-    </>
+    <DocPage title="useRequest 请求">
+      <AtList>
+        {list.map((listItem, index) => (
+          <AtListItem
+            {...listItem}
+            key={index}
+            onClick={() => routePage(listItem.route)}
+          />
+        ))}
+      </AtList>
+    </DocPage>
   );
 };

packages/app/src/pages/useRequest/manual/index.config.ts

@@ -0,0 +1,3 @@
+export default {
+  navigationBarTitleText: 'useRequest 手动触发',
+};

packages/app/src/pages/useRequest/manual/index.tsx

@@ -0,0 +1,52 @@
+/**
+ * desc: 通过设置 `options.manual = true` , 则需要手动调用 `run` 时才会触发执行异步函数。
+ */
+import React, { useState } from 'react';
+import { useRequest } from 'taro-hooks';
+import Taro from '@tarojs/taro';
+
+import { AtMessage, AtInput, AtButton } from 'taro-ui';
+import DocPage from '@components/DocPage';
+
+type Result = { success: boolean };
+
+function changeUsername(username: string): Promise<Result> {
+  console.log(username);
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve({ success: true });
+    }, 1000);
+  });
+}
+
+const DefaultRequest = () => {
+  const [state, setState] = useState('');
+
+  const { loading, run } = useRequest(changeUsername, {
+    manual: true,
+    onSuccess: (result: Result, params: string[]) => {
+      if (result.success) {
+        setState('');
+        Taro.atMessage({
+          message: `The username was changed to "${params[0]}" !`,
+        });
+      }
+    },
+  });
+  return (
+    <DocPage title="useRequest 请求" panelTitle="手动触发">
+      <AtMessage />
+      <AtInput
+        name="username"
+        onChange={(e) => setState(e as string)}
+        value={state}
+        placeholder="Please enter username"
+      />
+      <AtButton type="primary" loading={loading} onClick={() => run(state)}>
+        {loading ? 'loading' : 'Edit'}
+      </AtButton>
+    </DocPage>
+  );
+};
+
+export default DefaultRequest;

packages/app/src/pages/useRequest/polling/index.config.ts

@@ -0,0 +1,3 @@
+export default {
+  navigationBarTitleText: 'useRequest 轮询',
+};

packages/app/src/pages/useRequest/polling/index.tsx

@@ -0,0 +1,43 @@
+/**
+ * desc: |
+ *  通过设置 `options.pollingInterval` ，进入轮询模式，定时触发函数执行。
+ *
+ *  - 通过设置 `options.pollingWhenHidden=false` ，在屏幕不可见时，暂时暂停定时任务。
+ *  - 通过 `run` / `cancel` 来 开启/停止 轮询。
+ *  - 在 `options.manual=true` 时，需要第一次执行 `run` 后，才开始轮询。
+ */
+
+import React from 'react';
+import { useRequest } from 'taro-hooks';
+import Mock from 'mockjs';
+
+import { View } from '@tarojs/components';
+import DocPage from '@components/DocPage';
+import { AtButton } from 'taro-ui';
+
+function getUsername(): Promise<string> {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve(Mock.mock('@name()'));
+    }, 1000);
+  });
+}
+
+export default () => {
+  const { data, loading, run, cancel } = useRequest(getUsername, {
+    pollingInterval: 1000,
+    pollingWhenHidden: false,
+  });
+
+  return (
+    <DocPage title="useRequest 请求" panelTitle="轮询">
+      <View>Username: {loading ? 'loading' : data}</View>
+      <AtButton type="primary" onClick={run} customStyle={{ margin: '10px 0' }}>
+        start
+      </AtButton>
+      <AtButton type="secondary" onClick={cancel}>
+        stop
+      </AtButton>
+    </DocPage>
+  );
+};

packages/app/src/pages/useSystemInfo/index.tsx

@@ -1,6 +1,6 @@
 import React, { useCallback } from 'react';
 import { AtRadio } from 'taro-ui';
-import DocPage from '../../components/DocPage';
+import DocPage from '@components/DocPage';
 
 import { useSystemInfo } from 'taro-hooks';
 import { getSystemInfoSync } from '@tarojs/taro';

packages/app/src/pages/useUpdateManager/index.tsx

@@ -1,7 +1,7 @@
 import React, { useCallback } from 'react';
 import { AtMessage, AtNoticebar } from 'taro-ui';
 import { View } from '@tarojs/components';
-import DocPage from '../../components/DocPage';
+import DocPage from '@components/DocPage';
 
 import { useEnv, useUpdateManager } from 'taro-hooks';
 import Taro, { ENV_TYPE } from '@tarojs/taro';

packages/app/src/pages/useVisible/index.tsx

@@ -2,7 +2,7 @@ import React, { useEffect, useState, useContext } from 'react';
 import { AtNoticebar, AtTimeline } from 'taro-ui';
 import { AtTimelineProps } from 'taro-ui/types/timeline';
 
-import DocPage from '../../components/DocPage';
+import DocPage from '@components/DocPage';
 
 import { useVisible } from 'taro-hooks';
 

packages/hooks/src/useRequest/index.md

@@ -61,6 +61,20 @@ const { data, error, loading, run, params, cancel, refresh, mutate, fetches } =
   });
 ```
 
+## 代码演示
+
+### 默认请求
+
+<code src="@pages/useRequest/defaultRequest"></code>
+
+### 手动触发
+
+<code src="@pages/useRequest/manual"></code>
+
+### 轮询
+
+<code src="@pages/useRequest/polling"></code>
+
 ## 返回值说明
 
 | 参数    | 说明                                                                                                                                                                            | 类型                                                                    |