feat: doc update

SailingCoder · Jun 13, 2024 · a5758ce · a5758ce
1 parent 20d0024
commit a5758ce
Show file tree

Hide file tree

Showing 19 changed files with 250 additions and 288 deletions.
diff --git a/README.md b/README.md
@@ -1,118 +1,80 @@
 # react-virtualized-list
 
-`react-virtualized-list` is a high-performance React component library designed to efficiently handle large datasets. It offers features such as virtualized lists, infinite scrolling, lazy loading, and dynamic data updates. By rendering only the visible portions of the list and supporting on-demand data loading, the library aims to enhance performance. The repository provides installation instructions, usage examples, and detailed API documentation.
+`react-virtualized-list` 是一个专为处理大型数据集而设计的高性能 React 虚拟组件库，提供虚拟化列表、无限滚动、懒加载和动态数据更新等功能。通过使用 `IntersectionObserver` 精确管理可见性，优化性能并支持灵活的渲染和加载行为配置。仓库提供了详细的安装说明、使用示例和全面的 API 文档，适合快速集成和定制。
 
-![npm version](https://img.shields.io/npm/v/react-virtualized-list)
+![npm version](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/7d1919d96fa742c098a233bb338bb047~tplv-k3u1fbpfcp-image.image#?w=116\&h=20\&s=1153\&e=svg\&b=ea7d3d)
 
-[简体中文](https://github.com/SailingCoder/react-virtualized-list/blob/main/doc/README_EN.md)
+[English](https://github.com/SailingCoder/react-virtualized-list/blob/main/doc/README_EN.md)
 
-## Features & Use Cases
 
-1. **Virtualized List** (Large Data Lists):
-
-   Suitable for scenarios requiring the presentation of a large amount of data, such as chat logs, news feeds, or product lists. It only renders the currently visible portion, reducing unnecessary DOM operations and memory consumption, thereby improving page performance and user experience. See [VirtualizedList](https://github.com/SailingCoder/react-virtualized-list/blob/main/src/examples/VirtualizedListCustom.js).
+## 特性 
 
-2. **Infinite Scrolling List**:
-
-   Implement infinite scrolling to load more content, such as social media timelines, infinite galleries, or document browsers. Supports infinite scrolling loading through the `onLoadMore` and `hasMore` properties, commonly used for scrolling to load the next page of data. See [InfiniteScrollList](https://github.com/SailingCoder/react-virtualized-list/blob/main/src/examples/InfiniteScrollList.js).
+-   **虚拟化渲染**: 仅渲染视口内可见的项目，大幅减少 DOM 操作，提升页面性能。
+-   **无限滚动**: 支持滚动加载更多数据，适用于需要动态加载内容的场景。
+-   **自定义渲染和样式**: 可根据需求自定义每个项目的渲染方式和外观样式。
+-   **加载和结束消息**: 提供加载器和结束消息的配置，优化用户体验。
+-   **支持 TypeScript 和 JavaScript**: 适用于 TypeScript 和 JavaScript 项目。
 
-3. **Data Lazy Loading**:
-
-   Suitable for scenarios requiring lazy loading, allowing for the deferred loading of large amounts of DOM, images, or videos, only loading when they are about to enter the viewport, reducing page load times and bandwidth consumption. Lazy loading of images can be implemented using `renderItem` and `fetchItemData` for thumbnail and high-resolution image loading. See [LazyImage](https://github.com/SailingCoder/react-virtualized-list/blob/main/src/examples/LazyImage.js).
+## 安装
 
-4. **Dynamic Data Updates** (Asynchronous Data Retrieval/On-Demand Loading):
-
-   Load data for each list item on demand, reducing initial load times and improving browser loading performance and server performance. For example, in a product showcase list, dynamically load detailed information or images for specific products as the user scrolls using `fetchItemData`. See [DynamicInfiniteList](https://github.com/SailingCoder/react-virtualized-list/blob/main/src/examples/DynamicInfiniteList.js).
-
-5. **Automatically Refresh Content Within the Viewport**:
-
-   Automatically refresh content within the viewport as the user scrolls, such as dynamically loading the latest article content in a news application. By configuring `refreshOnVisible`, ensure users always receive the latest news content. See 详见[RefreshOnVisible](https://github.com/SailingCoder/react-virtualized-list/blob/main/src/examples/RefreshOnVisable.js).
-
-6. **Customized List Rendering**:
-
-   Supports custom lists and list items. By using the `renderItem` item rendering function, you can customize the appearance and behavior of each item according to your needs.
-
-## Installation
-
-Install via npm or yarn:
+使用 npm 或 yarn 安装：
 
 ```bash
 npm install react-virtualized-list
-```
-
-Or
-
-```bash
+# 或者
 yarn add react-virtualized-list
 ```
 
-## Usage Example
+## 使用
 
-Here's an example demonstrating how to use the `react-virtualized-list` component:
+### 基本用法
+
+以下是一个使用示例，展示如何使用 `react-virtualized-list` 组件：
 
 ```javascript
-import React, { useState, useEffect } from 'react';
+import React from 'react';
 import VirtualizedList from 'react-virtualized-list';
 
+const itemStyle = {
+  height: '50px',
+  lineHeight: '40px',
+  border: '1px solid blue',
+  marginBottom: '10px',
+};
+
+const containerStyle = {
+  width: '400px', 
+  height: '600px', 
+  margin: '0 auto', 
+  border: '1px solid red', 
+  padding: '16px',
+  textAlign: 'center',
+}
+
 const App = () => {
-  const [listData, setListData] = useState([]);
-  const [hasMore, setHasMore] = useState(true);
-
-  useEffect(() => {
-    handleLoadMore();
-  }, []);
-
-  // Simulate fetching list data
-  const handleLoadMore = () => {
-    if (listData.length >= 100) {
-      setHasMore(false);
-      return;
-    }
-    const newItems = Array.from({ length: 10 }, (_, i) => `Item ${listData.length + i + 1}`);
-    setListData(prevItems => [...prevItems, ...newItems]);
-    if (newItems.length < 10) { // Adjust to match the number of items loaded
-      setHasMore(false);
-    }
-  };
+  // 示例数据
+  const data = Array.from({ length: 1000 }, (_, index) => `条目 ${index}`);
 
-  // Simulate asynchronous fetching of item data
-  const getFetchData = (item) => {
-    return new Promise((resolve) => {
-      // Simulate returning data after 1 second
-      setTimeout(() => {
-        resolve(`${item} (fetched data) ${new Date().toLocaleTimeString()}`);
-      }, 3000);
-    });
+  // 加载更多条目的处理函数
+  const handleLoadMore = async () => {
+    // 加载更多数据的逻辑
   };
 
-  const itemStyle = {
-    minHeight: '50px',
-    border: '1px solid blue',
-    margin: '10px 0',
-    padding: '10px',
-    backgroundColor: '#f0f0f0'
-  };
+  // 渲染每个条目的函数
+  const renderItem = (itemData) => <div>{itemData}</div>;
 
   return (
-    <div style={{ width: '400px', height: '600px', margin: '0 auto' }}>
+    <div style={containerStyle}>
       <VirtualizedList
-        listData={listData}
+        listData={data}
+        renderItem={renderItem}
         containerHeight="600px"
-        hasMore={hasMore}
-        onLoadMore={handleLoadMore}
-        loader={<div>Loading more data...</div>}
-        endMessage={<div>No more data to load!</div>}
-        fetchItemData={getFetchData}
-        refreshOnVisible={true}
+        hasMore={true}
         itemStyle={itemStyle}
-        itemLoader={<div>Not visible, Loading</div>}
-        renderItem={(itemData, fetchData) => {
-          return (
-            <div>
-              {fetchData ? fetchData : 'Loading data...'}
-            </div>
-          )
-        }}
+        itemLoader={<div>loading ...</div>}
+        onLoadMore={handleLoadMore}
+        loader={<div>加载中...</div>}
+        endMessage={<div>没有更多条目了。</div>}
       />
     </div>
   );
@@ -121,33 +83,60 @@ const App = () => {
 export default App;
 ```
 
-## API
+### 高级用法场景
+
+探索更多示例和高级用法场景，查看 [示例](https://sailingcoder.github.io/react-virtualized-list/build/)。
+
+1.  **虚拟化列表**（大型数据列表）：通过仅渲染可见部分项目，提升大型数据列表的性能，详见[BigDataListExample](https://github.com/SailingCoder/react-virtualized-list/blob/main/src/examples/BigDataListExample.tsx)、
+
+
+2.  **无限滚动**：实现无限滚动加载更多内容，适用于新闻、微博、朋友圈等场景，详见 [InfiniteScrollList](https://github.com/SailingCoder/react-virtualized-list/blob/main/src/examples/InfiniteScrollList.tsx)。
+
+2.  **懒加载数据**: 延迟加载大量图片或视频，减少页面加载时间，详见 [LazyImage](https://github.com/SailingCoder/react-virtualized-list/blob/main/src/examples/LazyImage.tsx)。
+
+2.  **动态数据更新**: 按需加载每个列表项的数据，提升性能，详见 [DynamicInfiniteList](https://github.com/SailingCoder/react-virtualized-list/blob/main/src/examples/DynamicInfiniteList.tsx)。
 
-### `VirtualizedList` Props (Continued)
+2.  **视口内自动刷新内容**: 自动刷新可见区域内的内容，确保用户获取最新数据，详见 [RefreshOnVisible](https://github.com/SailingCoder/react-virtualized-list/blob/main/src/examples/RefreshOnVisible.tsx)。
 
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `listData` | `Array` | ✅ | `[]` | The list of items to display |
-| `renderItem` | `Function(itemData, fetchData)` | ❌ | `(itemData) => (<>{itemData ? itemData : 'Loading data...'}</>)` | Function to render each item |
-| `refreshOnVisible` | `Boolean` | ❌ | `false` | Whether to reload data **every time** an item becomes visible |
-| `fetchItemData` | `Function` | ❌ |  | Asynchronous function to fetch item data |
-| `containerHeight` | `String` | ❌ | `'400px'` | Height of the list container |
-| `itemStyle` | `Object` | ❌ | `{}` | Style for each item |
-| `observerOptions` | `Object` | ❌ | `{ root: null, rootMargin: '0px', threshold: 0.1 }` | Configuration options for the IntersectionObserver |
-| `onLoadMore` | `Function` | ❌ |  | Function to load more data when scrolled to the bottom |
-| `hasMore` | `Boolean` | ❌ | `false` | Whether there is more data to load |
-| `loader` | `String` | ❌ | `''` | Content to display when loading more data |
-| `endMessage` | `String` | ❌ | `''` | Content to display when there is no more data to load |
-| `itemLoader` | `String` | ❌ | `''` | Placeholder content or background image to display while each item is loading |
+2.  **自定义渲染**: 根据需求定制每个项目的外观和行为，适应各种项目需求。
 
-### `observerOptions` Configuration Table (Continued)
+2.  **与第三方 UI 库配合使用**: 可与主流 UI 库等（如[Ant Design](https://ant-design.antgroup.com/index-cn)）灵活配合使用，提供优秀的用户体验。
+
+## 参数
+
+### `VirtualizedList` 组件接受以下参数：
+
+| Prop  | Type | Required | Default  | Description |
+| --------| ---- | -------- | ----------- | -----  |
+| `listData`         | `Array`         | ✅        | `[]` | 列表数据数组 |
+| `renderItem`       | `(itemData: T, fetchData: any) => React.ReactNode` | ❌        | `itemData => <>{itemData ? itemData : 'Loading ...'}</>` | 渲染每个项目的函数    |
+| `refreshOnVisible` | `Boolean` | ❌   | `false`  | 当项目可见时是否刷新数据 |
+| `fetchItemData`    | `((item: T) => Promise<any>) ` | ❌ |  `null` | 获取每个项目数据的异步函数 |
+| `containerHeight`  | `String` | ❌    | `'400px'` | 列表容器的高度 |
+| `listClassName`    | `String` | ❌    | `null` | 列表容器的CSS类名     |
+| `itemClassName`    | `String` | ❌    | `null` | 每个项目的CSS类名（推荐使用）   |
+| `itemStyle`        | `Object`  | ❌    | `{}` | 项目样式    |
+| `observerOptions`  | `Object`  | ❌    | `{ root: null, rootMargin: '0px', threshold: 0.1 }`       | 视口设置（见下方observerOptions配置表格） |
+| `onLoadMore`       | `() => Promise<void>` | ❌   |   `null`   | 加载更多数据的函数 |
+| `hasMore`          | `Boolean`  | ❌   | `false`  | 是否有更多数据 |
+| `loader`           | `React.ReactNode`  | ❌ | `''` | 加载更多数据时显示的内容 |
+| `endMessage`       | `React.ReactNode` | ❌  | `''` | 所有数据加载完毕时的内容 |
+| `itemLoader`       | `React.ReactNode` | ❌ | `''` | 每个项目加载时显示的占位内容或背景图 |
+| `emptyListMessage` | `React.ReactNode` | ❌    | `''` | 列表为空时的占位内容或背景图 |
+
+### `observerOptions` 配置表格
 
 | **Option**   | **Description**                                                      | **Type**  | **Required** | **Default** |
 | ------------ | -------------------------------------------------------------------- | --------- | ------------ | ----------- |
-| `root`       | The viewport element to observe. The default is null, which means the browser's viewport is used as the root container. | `Element` | ❌            | `null`      |
-| `rootMargin` | The margin around the root container. Can use CSS-like values (e.g., `10px`, `20%`). The default value is `0px`. Used to expand or shrink the root container's area. | `String`  | ❌            | `'0px'`     |
-| `threshold`  | A single number or an array of numbers which indicate at what percentage of the target's visibility the observer's callback should be executed. `0.1` means the callback will be triggered when 10% of the target is visible. | `Array`   | ❌            | `0.1`       |
+| `root`       | 观察的视口元素。默认 null 表示使用浏览器的视口作为根容器。                                     | `Element` | ❌            | `null`      |
+| `rootMargin` | 根容器的外边距。可以使用类似 CSS 的值（如 `10px`, `20%`），默认值为 `0px`。用于扩展或收缩根容器的范围。     | `String`  | ❌            | `'0px'`     |
+| `threshold`  | 一个或多个数值数组，表示目标元素可见比例达到这些值时，回调函数会被触发。`0.1` 意味着目标元素可见部分达到 `10%` 时触发回调。 | `Array`   | ❌            | `0.1`       |
+
+## 许可证
+
+**react-virtualized-list** is released under the MIT License. See the [LICENSE](https://github.com/SailingCoder/react-virtualized-list/blob/main/LICENSE) file for details.
+
+## 结论
 
-## License
+如果你发现任何问题或有改进建议，请在 [GitHub Issues](https://github.com/SailingCoder/react-virtualized-list/issues) 中提出。
 
-**react-virtualized-list** is released under the MIT License. See the [LICENSE](https://github.com/SailingCoder/react-virtualized-list/blob/main/LICENSE) file for details.
diff --git a/build/asset-manifest.json b/build/asset-manifest.json
@@ -1,15 +1,15 @@
 {
   "files": {
     "main.css": "./static/css/main.997bf269.css",
-    "main.js": "./static/js/main.a433c861.js",
+    "main.js": "./static/js/main.ca3d3e02.js",
     "static/js/845.6038aacd.chunk.js": "./static/js/845.6038aacd.chunk.js",
     "index.html": "./index.html",
     "main.997bf269.css.map": "./static/css/main.997bf269.css.map",
-    "main.a433c861.js.map": "./static/js/main.a433c861.js.map",
+    "main.ca3d3e02.js.map": "./static/js/main.ca3d3e02.js.map",
     "845.6038aacd.chunk.js.map": "./static/js/845.6038aacd.chunk.js.map"
   },
   "entrypoints": [
     "static/css/main.997bf269.css",
-    "static/js/main.a433c861.js"
+    "static/js/main.ca3d3e02.js"
   ]
 }
diff --git a/build/index.html b/build/index.html
@@ -1 +1 @@
-<!doctype html><html lang="en"><head><meta charset="utf-8"/><link rel="icon" href="./favicon.ico"/><meta name="viewport" content="width=device-width,initial-scale=1"/><meta name="theme-color" content="#000000"/><meta name="description" content="Web site created using create-react-app"/><link rel="apple-touch-icon" href="./logo192.png"/><link rel="manifest" href="./manifest.json"/><title>React App</title><script defer="defer" src="./static/js/main.a433c861.js"></script><link href="./static/css/main.997bf269.css" rel="stylesheet"></head><body><noscript>You need to enable JavaScript to run this app.</noscript><div id="root"></div></body></html>
+<!doctype html><html lang="en"><head><meta charset="utf-8"/><link rel="icon" href="./favicon.ico"/><meta name="viewport" content="width=device-width,initial-scale=1"/><meta name="theme-color" content="#000000"/><meta name="description" content="Web site created using create-react-app"/><link rel="apple-touch-icon" href="./logo192.png"/><link rel="manifest" href="./manifest.json"/><title>React App</title><script defer="defer" src="./static/js/main.ca3d3e02.js"></script><link href="./static/css/main.997bf269.css" rel="stylesheet"></head><body><noscript>You need to enable JavaScript to run this app.</noscript><div id="root"></div></body></html>
diff --git a/build/static/js/main.a433c861.js.map b/build/static/js/main.a433c861.js.map
diff --git a/build/static/js/main.a433c861.js → build/static/js/main.ca3d3e02.js b/build/static/js/main.a433c861.js → build/static/js/main.ca3d3e02.js
diff --git a/build/static/js/main.a433c861.js.LICENSE.txt → build/static/js/main.ca3d3e02.js.LICENSE.txt b/build/static/js/main.a433c861.js.LICENSE.txt → build/static/js/main.ca3d3e02.js.LICENSE.txt
diff --git a/build/static/js/main.ca3d3e02.js.map b/build/static/js/main.ca3d3e02.js.map
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		<!doctype html><html lang="en"><head><meta charset="utf-8"/><link rel="icon" href="./favicon.ico"/><meta name="viewport" content="width=device-width,initial-scale=1"/><meta name="theme-color" content="#000000"/><meta name="description" content="Web site created using create-react-app"/><link rel="apple-touch-icon" href="./logo192.png"/><link rel="manifest" href="./manifest.json"/><title>React App</title><script defer="defer" src="./static/js/main.a433c861.js"></script><link href="./static/css/main.997bf269.css" rel="stylesheet"></head><body><noscript>You need to enable JavaScript to run this app.</noscript><div id="root"></div></body></html>
		<!doctype html><html lang="en"><head><meta charset="utf-8"/><link rel="icon" href="./favicon.ico"/><meta name="viewport" content="width=device-width,initial-scale=1"/><meta name="theme-color" content="#000000"/><meta name="description" content="Web site created using create-react-app"/><link rel="apple-touch-icon" href="./logo192.png"/><link rel="manifest" href="./manifest.json"/><title>React App</title><script defer="defer" src="./static/js/main.ca3d3e02.js"></script><link href="./static/css/main.997bf269.css" rel="stylesheet"></head><body><noscript>You need to enable JavaScript to run this app.</noscript><div id="root"></div></body></html>