From 950370db663210483bbe2e7e854db36ca29fbc40 Mon Sep 17 00:00:00 2001 From: John Date: Thu, 8 Jun 2023 10:46:33 +0800 Subject: [PATCH] docs: update readme --- README-en_US.md | 148 ++++++++++++++++++++++++++++++++++++++++++++ README-zh_CN.md | 160 ------------------------------------------------ README.md | 94 +++++++++++++--------------- 3 files changed, 190 insertions(+), 212 deletions(-) create mode 100644 README-en_US.md delete mode 100644 README-zh_CN.md diff --git a/README-en_US.md b/README-en_US.md new file mode 100644 index 0000000..dd6678f --- /dev/null +++ b/README-en_US.md @@ -0,0 +1,148 @@ +English | [简体中文](README.md) + +

+ + VueRequest logo + +

+

VueRequest

+
+

⚡️ This is a library that can easily help you manage request states, supporting common features such as SWR, polling, error retry, caching, and pagination, etc.

+ + Coverage Status + + + Size + + + Version + + + Languages + + + License + + + Star + + + Download + +
+ +## Why VueRequest + +In past projects, we were often troubled by the repetitive implementation of loading state management, request throttling and debouncing, API data caching, pagination, etc. Every time we started a new project, we had to handle these issues manually, which was a repetitive task that also required ensuring team consistency. + +VueRequest is designed to provide developers with a convenient and fast way to manage API states. By simply configuring it, you can eliminate the tedious tasks and focus on core development. + +## Features + +- 🌈  Support Vue 2 & 3 +- 🚀  All data is reactive +- 🔄  Interval polling +- 🤖  Automatic error retry +- 🗄  Built-in cache +- 💧  Throttle and Debounce +- ⚙️  Powerful pagination extension and load more extensions +- 📠  Written in TypeScript +- ⚡️  Compatible with Vite +- 🍃  Lightweight +- 📦  Out of the box + +## Documentation + +- [English](https://www.attojs.org/) +- [中文文档](https://www.attojs.com/) + +## Install + +You can install VueRequest with [NPM](https://www.npmjs.com/), [YARN](https://yarnpkg.com/), or a ` +``` + +Once you add it to your page, you can access our exported methods in `window.VueRequest`. + +## Usage + +```vue + + + +``` + +In this example, `useRequest` receives a `service` function. `service` is an asynchronous request function, which means you can use **axios** to retrieve data and return a **Promise**. More specific details can be found in the [documentation](https://www.attojs.org/guide/documentation/dataFetching.html). + +The `useRequest` function also returns three values: `data`, `loading`, and `error`. While the request is still in progress, `data` will be set to `undefined` and `loading` will be `true`. Once the request is completed, `data` and `error` will be set based on the result, and the page will be rendered accordingly. This is because `data`, `loading`, and `error` are [Reactivity(Refs)](https://vuejs.org/guide/essentials/reactivity-fundamentals.html) in Vue, and their values will be updated based on the request status and result. + +## Some of the coolest features: + +VueRequest provides many features, such as error retry, caching, pagination, throttling, debouncing, and more. Here are two particularly cool features: + +### 1.Refresh On Focus + +Sometimes, you need to ensure data consistency across multiple browser windows or synchronize page data to the latest state when a user's computer resumes from sleep mode. Using `refreshOnWindowFocus` can save you a lot of logic code. [Click here to go to the document](https://www.attojs.org/guide/documentation/refreshOnWindowFocus.html) + +```ts +const { data, error, run } = useRequest(getUserInfo, { + refreshOnWindowFocus: true, + refocusTimespan: 1000, // refresh interval 1s +}); +``` + +![vue-request](https://z3.ax1x.com/2021/09/10/hXAs8s.gif) + +### 2.Polling Data + +Sometimes, you need to ensure data synchronization across multiple devices. In this case, you can use `pollingInterval` provided by us to periodically re-request the API, ensuring data consistency across multiple devices. When a user modifies the data, the changes will be synced in real-time between two windows. [Click here to go to the document](https://www.attojs.org/guide/documentation/polling.html) + +```ts +const { data, error, run } = useRequest(getUserInfo, { + pollingInterval: 1000, // polling interval 1s +}); +``` + +![vue-request](https://z3.ax1x.com/2021/09/10/hXAy2n.gif) + +## Thanks + +Thank them for inspiring us. + +- [vercel/swr](https://github.com/vercel/swr) +- [alibaba/hooks](https://ahooks.js.org/hooks/async#userequest) + +## License + +[MIT License](https://github.com/AttoJS/vue-request/blob/master/LICENSE) © 2020-present [AttoJS](https://github.com/AttoJS) diff --git a/README-zh_CN.md b/README-zh_CN.md deleted file mode 100644 index fad46e4..0000000 --- a/README-zh_CN.md +++ /dev/null @@ -1,160 +0,0 @@ -[English](./README.md) | 简体中文 - -

- - VueRequest logo - -

-

VueRequest

-
-

⚡️ 一个能轻松帮你管理请求状态（支持SWR，轮询，错误重试，缓存，分页等）的 Vue composition API 请求库

- - Coverage Status - - - Size - - - Version - - - Languages - - - License - - - Star - - - Download - -
- -## 为什么选择 VueRequest - -在以往的业务项目中，常常被 loading 状态的管理、请求的节流防抖、接口数据的缓存、分页等这些重复的实现所困惑。每当开启一个新项目时，我们都得手动去处理以上这些问题，这将是一个重复性的工作，而且还得确保团队的一致。 - -VueRequest 旨在为开发者提供便捷、快速的方式来管理接口的状态。在业务开发中省去上述的那些“脏活累活”，只需要简单的配置即可使用，专注于业务核心的开发。 - -## 特性 - -- 🌈  兼容 Vue 2 & 3 -- 🚀  所有数据都具有响应式 -- 🔄  轮询请求 -- 🤖  自动处理错误重试 -- 🗄  内置请求缓存 -- 💧  节流请求与防抖请求 -- 🎯  聚焦页面时自动重新请求 -- ⚙️  强大的分页扩展以及加载更多扩展 -- 📠  完全使用 Typescript 编写，具有强大的类型提示 -- ⚡️  兼容 Vite -- 🍃  轻量化 -- 📦  开箱即用 - -## 文档 - -- [English](https://next.attojs.org/) -- [中文文档](https://next.attojs.com/) - -## 安装 - -你可以通过 [NPM](https://www.npmjs.com/)、[YARN](https://yarnpkg.com/) 或者通过 ` -``` - -一旦你在页面中添加了它，你就可以在 `window.VueRequest` 中访问我们导出的方法。 - -## 示例 - -```vue - - - -``` - -在这个例子中，`useRequest` 接收了一个 `service` 函数。`service`是一个异步的请求函数，换句话说，你可以使用 **axios** 来获取数据，然后返回一个 **Promise**。更具体的说明可以在[文档](https://next.attojs.com/guide/documentation/dataFetching.html)中查看。 - -`useRequest` 还返回了三个值， `data`、`loading` 和 `error`。当请求还没完成时, `data` 将会为 `undefined` 同时，`loading` 将被设置为 `true`。当请求完成后，则将会根据请求结果来设定 `data` 和 `error`，并对页面进行渲染。这是因为 `data`、 `loading` 和 `error` 是 Vue 的 [响应式引用(Refs)](https://v3.cn.vuejs.org/guide/reactivity-fundamentals.html)，它们的值将根据请求状态及请求结果来修改。 - -## 一些很酷的特性 - -VueRequest 有非常多的特性，如 错误重试、缓存、分页、节流、防抖...，这里列举两个个比较酷的特性 - -### 1.聚焦页面时自动重新请求 - -有些时候，你要确保多个浏览器窗口之间数据的一致性；又或者是当用户电脑在休眠状态重新激活后，页面的数据需要同步到最新状态时。`refreshOnWindowFocus` 可能会为你节省很多逻辑代码。[点击这里直达文档](https://next.attojs.com/guide/documentation/refreshOnWindowFocus.html) - -```ts -const { data, error, run } = useRequest(getUserInfo, { - refreshOnWindowFocus: true, - refocusTimespan: 1000, // 请求间隔时间 -}); -``` - -![vue-request](https://z3.ax1x.com/2021/09/10/hXAs8s.gif) - -### 2.轮询数据 - -有些时候，你要确保多个设备间数据的同步更新。这时候可以用我们提供的 `pollingInterval` 来定期重新请求接口，这样就可以保证多设备间的数据一致性。当用户进行修改数据时，两个窗口将会实时同步更新。[点击这里直达文档](https://next.attojs.com/guide/documentation/polling.html) - -```ts -const { data, error, run } = useRequest(getUserInfo, { - pollingInterval: 1000, // 请求间隔时间 -}); -``` - -![vue-request](https://z3.ax1x.com/2021/09/10/hXAy2n.gif) - -## 致谢 - -感谢他们为我们提供了灵感 - -- [vercel/swr](https://github.com/vercel/swr) -- [alibaba/hooks](https://ahooks.js.org/hooks/async#userequest) - -## License - -[MIT License](https://github.com/AttoJS/vue-request/blob/master/LICENSE) © 2020-present [AttoJS](https://github.com/AttoJS) diff --git a/README.md b/README.md index 13ad83b..c8e4765 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -English | [简体中文](README-zh_CN.md) +[English](./README-en_US.md) | 简体中文

- +

VueRequest

-

⚡️ Vue composition API for data fetching, supports SWR, polling, error retry, cache request, pagination, etc.

- +

⚡️ 这是一个能够轻松帮助你管理请求状态的库，支持 SWR、轮询、错误重试、缓存、分页等常用功能。

+ Coverage Status
-## Why VueRequest +## 为什么选择 VueRequest -In the past projects, they were often confused by repeated implementations such as the management of the loading state, the requested throttling and debounce, the caching of request data, and pagination. Whenever we start a new project, we have to manually deal with the above problems, which will be a repetitive work, but also to ensure that the team is consistent. +在以往的业务项目中，我们经常会被 loading 状态的管理、请求的节流防抖、接口数据的缓存、分页等重复的功能实现所困扰。每次开启一个新项目都需要重新实现一遍，这是一项重复的工作，还需要确保团队的一致性。 -VueRequest aims to provide developers with a convenient and fast way to manage the state of the request API. In the development, save repetitive work, and it can be used only with a simple configuration, focusing on the core of the development project. +VueRequest 的目的是为开发人员提供一种方便、快速的方式来管理 API 状态。通过简单的配置，可以省去那些繁琐的任务，专注于业务核心的开发。 -## Features +## 特性 -- 🌈  Support Vue 2 & 3 -- 🚀  All data is reactive -- 🔄  Interval polling -- 🤖  Automatic error retry -- 🗄  Built-in cache -- 💧  Throttle and Debounce -- ⚙️  Powerful pagination extension and load more extensions -- 📠  Written in TypeScript -- ⚡️  Compatible with Vite -- 🍃  Lightweight -- 📦  Out of the box +- 🌈  兼容 Vue 2 & 3 +- 🚀  所有数据都具有响应式 +- 🔄  轮询请求 +- 🤖  自动处理错误重试 +- 🗄  内置请求缓存 +- 💧  节流请求与防抖请求 +- 🎯  聚焦页面时自动重新请求 +- ⚙️  强大的分页扩展以及加载更多扩展 +- 📠  完全使用 Typescript 编写，具有强大的类型提示 +- ⚡️  兼容 Vite +- 🍃  轻量化 +- 📦  开箱即用 -## Documentation +## 文档 -- [English](https://next.attojs.org/) -- [中文文档](https://next.attojs.com/) +- [English](https://www.attojs.org/) +- [中文文档](https://www.attojs.com/) -## Install +## 安装 -You can install VueRequest with [NPM](https://www.npmjs.com/), [YARN](https://yarnpkg.com/), or a ` ``` -Once you've added this you will have access to the `window.VueRequest` object and its exports. +一旦你在页面中添加了它，你就可以在 `window.VueRequest` 中访问我们导出的方法。 -## Usage +## 示例 ```vue - ``` -In this example, `useRequest` accepts a `service` function. `service` is a asynchronous function. In other words, you can use **axios** to fetch data and return a **Promise**. More specific instructions can be viewed in [document](https://next.attojs.org/guide/documentation/dataFetching.html). +在这个例子中，`useRequest` 接收了一个 `service` 函数。`service`是一个异步的请求函数，换句话说，你可以使用 **axios** 来获取数据，然后返回一个 **Promise**。更具体的说明可以在[文档](https://www.attojs.com/guide/documentation/dataFetching.html)中查看。 -`useRequest` also return 3 values: `data`, `loading` and `error`. When the request is not yet finished, data will be `undefined` and `loading` will be `true`. And when we get a response, it sets data and error based on the result of service and rerenders the component. This is because `data` and `error` are [Reactivity(Refs)](https://v3.vuejs.org/guide/reactivity-fundamentals.html), and their values will be set by the service response. +`useRequest` 函数还会返回三个值：`data`、`loading` 和 `error`。当请求还未完成时，`data` 的值为 `undefined`，同时 `loading` 的值会被设置为 `true`。当请求完成后，`data` 和 `error` 的值将根据请求结果进行设置，并且页面也会相应地进行渲染。这是因为 `data`、`loading` 和 `error` 是 Vue 中的[响应式引用(Refs)](https://cn.vuejs.org/guide/essentials/reactivity-fundamentals.html)，它们的值会根据请求状态和结果进行修改。 -## Some of the coolest features: +## 一些很酷的特性 -VueRequest has many features, such as error retry, cache, pagination, throttle, debounce..., here are two cool features +VueRequest 提供了很多特性，如：错误重试、缓存、分页、节流、防抖等等。这里列举两个比较酷的特性： -### 1.Refresh On Focus +### 1.聚焦页面时自动重新请求 -Sometimes, you need to ensure data consistency between multiple browser windows; or when the user's computer is reactivated in the dormant state, the page data needs to be synchronized to the latest state. `refreshOnWindowFocus` may save you a lot of code. [Click here to go to the document](https://next.attojs.org/guide/documentation/refreshOnWindowFocus.html) +有时，你需要确保多个浏览器窗口之间的数据保持一致性；或者在用户电脑从休眠状态中恢复并重新激活时，需要将页面的数据同步到最新状态。使用 `refreshOnWindowFocus` 可以帮助你节省很多逻辑代码。[点击这里直达文档](https://www.attojs.com/guide/documentation/refreshOnWindowFocus.html) ```ts const { data, error, run } = useRequest(getUserInfo, { refreshOnWindowFocus: true, - refocusTimespan: 1000, // refresh interval 1s + refocusTimespan: 1000, // 请求间隔时间 }); ``` ![vue-request](https://z3.ax1x.com/2021/09/10/hXAs8s.gif) -### 2.Polling Data +### 2.轮询数据 -Sometimes, you want to ensure that data is synchronized and updated between multiple devices. At this time, we can use the `pollingInterval` provided by us to periodically re-request the request API, so that the data consistency between multiple devices can be guaranteed. When the user modifies the data, the two windows will be updated simultaneously in real time. [Click here to go to the document](https://next.attojs.org/guide/documentation/polling.html) +有时候，你需要确保多个设备之间的数据同步更新。这时候可以使用我们提供的 `pollingInterval` 定期重新请求接口，以确保多个设备之间的数据一致性。当用户修改数据时，两个窗口将会实时同步更新。[点击这里直达文档](https://www.attojs.com/guide/documentation/polling.html) ```ts const { data, error, run } = useRequest(getUserInfo, { - pollingInterval: 1000, // polling interval 1s + pollingInterval: 1000, // 请求间隔时间 }); ``` ![vue-request](https://z3.ax1x.com/2021/09/10/hXAy2n.gif) -## Thanks +## 致谢 -Thank them for inspiring us. +感谢他们为我们提供了灵感 - [vercel/swr](https://github.com/vercel/swr) - [alibaba/hooks](https://ahooks.js.org/hooks/async#userequest)