Skip to content

Commit

Permalink
chore: using prettier to format markdown files
Browse files Browse the repository at this point in the history
  • Loading branch information
@wuweiweiwu
wuweiweiwu committed Nov 13, 2019
1 parent 489794a commit 23942b3
Show file tree
Hide file tree
Showing 26 changed files with 733 additions and 805 deletions.
120 changes: 56 additions & 64 deletions README.md
View file
Expand Up @@ -13,6 +13,7 @@ React components for efficiently rendering large lists and tabular data.
Check out [the demo](https://bvaughn.github.io/react-virtualized/) for some examples.

### Sponsors

The following wonderful companies have sponsored react-virtualized:

<a href="https://www.treasuredata.com/"><img width="64" height="64" title="Treasure Data" src="https://cloud.githubusercontent.com/assets/29597/17391516/962647f8-59cb-11e6-83be-aa1bac299dd0.png"></a>
Expand Down Expand Up @@ -81,13 +82,11 @@ The following wonderful companies have sponsored react-virtualized:
<a href="https://opencollective.com/react-virtualized/backer/28/website" target="_blank"><img src="https://opencollective.com/react-virtualized/backer/28/avatar.svg"></a>
<a href="https://opencollective.com/react-virtualized/backer/29/website" target="_blank"><img src="https://opencollective.com/react-virtualized/backer/29/avatar.svg"></a>

A word about `react-window`
---------------
## A word about `react-window`

If you're considering adding `react-virtualized` to a project, take a look at [`react-window`](https://github.com/bvaughn/react-window) as a possible lighter-weight alternative. [Learn more about how the two libraries compare here.](https://github.com/bvaughn/react-window#how-is-react-window-different-from-react-virtualized)

Getting started
---------------
## Getting started

Install `react-virtualized` using npm.

Expand All @@ -104,16 +103,16 @@ For example:
// The Table component ships with a few presentational styles as well.
// They are optional, but if you want them you will need to also import the CSS file.
// This only needs to be done once; probably during your application's bootstrapping process.
import 'react-virtualized/styles.css'
import 'react-virtualized/styles.css';

// You can import any component you want as a named export from 'react-virtualized', eg
import { Column, Table } from 'react-virtualized'
import {Column, Table} from 'react-virtualized';

// But if you only use a few react-virtualized components,
// And you're concerned about increasing your application's bundle size,
// You can directly import only the components you need, like so:
import AutoSizer from 'react-virtualized/dist/commonjs/AutoSizer'
import List from 'react-virtualized/dist/commonjs/List'
import AutoSizer from 'react-virtualized/dist/commonjs/AutoSizer';
import List from 'react-virtualized/dist/commonjs/List';
```

Note webpack 4 makes this optimization itself, see the [documentation](https://webpack.js.org/guides/tree-shaking/#mark-the-file-as-side-effect-free).
Expand All @@ -131,6 +130,7 @@ If the above syntax looks too cumbersome, or you import react-virtualized compon
```

Then you can just import like so:

```js
import List from 'react-virtualized/List';

Expand All @@ -140,24 +140,22 @@ import List from 'react-virtualized/List';
You can also use a global-friendly UMD build:

```html
<link rel="stylesheet" href="path-to-react-virtualized/styles.css">
<link rel="stylesheet" href="path-to-react-virtualized/styles.css" />
<script src="path-to-react-virtualized/dist/umd/react-virtualized.js"></script>
```

Now you're ready to start using the components.
You can learn more about which components react-virtualized has to offer [below](#documentation).

Dependencies
---------------
## Dependencies

React Virtualized has very few dependencies and most are managed by NPM automatically.
However the following peer dependencies must be specified by your project in order to avoid version conflicts:
[`react`](https://www.npmjs.com/package/react),
[`react-dom`](https://www.npmjs.com/package/react-dom).
NPM will not automatically install these for you but it will show you a warning message with instructions on how to install them.

Pure Components
---------------
## Pure Components

By default all react-virtualized components use [`shallowCompare`](https://facebook.github.io/react/docs/shallow-compare.html) to avoid re-rendering unless props or state has changed.
This occasionally confuses users when a collection's data changes (eg `['a','b','c']` => `['d','e','f']`) but props do not (eg `array.length`).
Expand All @@ -174,89 +172,83 @@ However you can pass through the additional sort property to trigger a re-render
For example:

```js
<List
{...listProps}
sortBy={sortBy}
/>
<List {...listProps} sortBy={sortBy} />
```

###### Public methods

`Grid` and `Collection` components can be forcefully re-rendered using [`forceUpdate`](https://facebook.github.io/react/docs/component-api.html#forceupdate).
For `Table` and `List`, you'll need to call [`forceUpdateGrid`](https://github.com/bvaughn/react-virtualized/blob/master/docs/Table.md#forceupdategrid) to ensure that the inner `Grid` is also updated. For `MultiGrid`, you'll need to call [`forceUpdateGrids`](https://github.com/bvaughn/react-virtualized/blob/master/docs/MultiGrid.md#forceupdategrids) to ensure that the inner `Grid`s are updated.

Documentation
---------------
## Documentation

API documentation available [here](docs/README.md).

There are also a couple of how-to guides:
* [Customizing classes and styles](docs/customizingStyles.md)
* [Displaying items in reverse order](docs/reverseList.md)
* [Using AutoSizer](docs/usingAutoSizer.md)
* [Creating an infinite-loading list](docs/creatingAnInfiniteLoadingList.md)
* [Natural sort Table](docs/tableWithNaturalSort.md)
* [Sorting a Table by multiple columns](docs/multiColumnSortTable.md)

- [Customizing classes and styles](docs/customizingStyles.md)
- [Displaying items in reverse order](docs/reverseList.md)
- [Using AutoSizer](docs/usingAutoSizer.md)
- [Creating an infinite-loading list](docs/creatingAnInfiniteLoadingList.md)
- [Natural sort Table](docs/tableWithNaturalSort.md)
- [Sorting a Table by multiple columns](docs/multiColumnSortTable.md)

Examples
---------------
## Examples

Examples for each component can be seen in [the documentation](docs/README.md).

Here are some online demos of each component:

* [ArrowKeyStepper](https://bvaughn.github.io/react-virtualized/#/components/ArrowKeyStepper)
* [AutoSizer](https://bvaughn.github.io/react-virtualized/#/components/AutoSizer)
* [CellMeasurer](https://bvaughn.github.io/react-virtualized/#/components/CellMeasurer)
* [Collection](https://bvaughn.github.io/react-virtualized/#/components/Collection)
* [ColumnSizer](https://bvaughn.github.io/react-virtualized/#/components/ColumnSizer)
* [Grid](https://bvaughn.github.io/react-virtualized/#/components/Grid)
* [InfiniteLoader](https://bvaughn.github.io/react-virtualized/#/components/InfiniteLoader)
* [List](https://bvaughn.github.io/react-virtualized/#/components/List)
* [Masonry](https://bvaughn.github.io/react-virtualized/#/components/Masonry)
* [MultiGrid](https://bvaughn.github.io/react-virtualized/#/components/MultiGrid)
* [ScrollSync](https://bvaughn.github.io/react-virtualized/#/components/ScrollSync)
* [Table](https://bvaughn.github.io/react-virtualized/#/components/Table)
* [WindowScroller](https://bvaughn.github.io/react-virtualized/#/components/WindowScroller)
- [ArrowKeyStepper](https://bvaughn.github.io/react-virtualized/#/components/ArrowKeyStepper)
- [AutoSizer](https://bvaughn.github.io/react-virtualized/#/components/AutoSizer)
- [CellMeasurer](https://bvaughn.github.io/react-virtualized/#/components/CellMeasurer)
- [Collection](https://bvaughn.github.io/react-virtualized/#/components/Collection)
- [ColumnSizer](https://bvaughn.github.io/react-virtualized/#/components/ColumnSizer)
- [Grid](https://bvaughn.github.io/react-virtualized/#/components/Grid)
- [InfiniteLoader](https://bvaughn.github.io/react-virtualized/#/components/InfiniteLoader)
- [List](https://bvaughn.github.io/react-virtualized/#/components/List)
- [Masonry](https://bvaughn.github.io/react-virtualized/#/components/Masonry)
- [MultiGrid](https://bvaughn.github.io/react-virtualized/#/components/MultiGrid)
- [ScrollSync](https://bvaughn.github.io/react-virtualized/#/components/ScrollSync)
- [Table](https://bvaughn.github.io/react-virtualized/#/components/Table)
- [WindowScroller](https://bvaughn.github.io/react-virtualized/#/components/WindowScroller)

And here are some "recipe" type demos:
* [Table with resizable (drag and drop) columns](https://codesandbox.io/s/j30k46l7xw)
* [Collapsable tree view](https://rawgit.com/bvaughn/react-virtualized/master/playground/tree.html)
* [Full-page grid (spreadsheet)](https://rawgit.com/bvaughn/react-virtualized/master/playground/grid.html)
* [Dynamic cell measuring](https://rawgit.com/bvaughn/react-virtualized/master/playground/chat.html)
* [Cell hover effects](https://rawgit.com/bvaughn/react-virtualized/master/playground/hover.html)

Supported Browsers
---------------

- [Table with resizable (drag and drop) columns](https://codesandbox.io/s/j30k46l7xw)
- [Collapsable tree view](https://rawgit.com/bvaughn/react-virtualized/master/playground/tree.html)
- [Full-page grid (spreadsheet)](https://rawgit.com/bvaughn/react-virtualized/master/playground/grid.html)
- [Dynamic cell measuring](https://rawgit.com/bvaughn/react-virtualized/master/playground/chat.html)
- [Cell hover effects](https://rawgit.com/bvaughn/react-virtualized/master/playground/hover.html)

## Supported Browsers

react-virtualized aims to support all evergreen browsers and recent mobile browsers for iOS and Android. IE 9+ is also supported (although IE 9 will require some user-defined, custom CSS since flexbox layout is not supported).

If you find a browser-specific problem, please report it along with a repro case. The easiest way to do this is probably by forking [this Plunker](https://plnkr.co/edit/6syKo8cx3RfoO96hXFT1).

Friends
---------------
## Friends

Here are some great components built on top of react-virtualized:
* [react-infinite-calendar](https://github.com/clauderic/react-infinite-calendar): Infinite scrolling date-picker with localization, themes, keyboard support, and more
* [react-sortable-hoc](https://github.com/clauderic/react-sortable-hoc): Higher-order components to turn any list into an animated, touch-friendly, sortable list
* [react-sortable-tree](https://github.com/fritz-c/react-sortable-tree): Drag-and-drop sortable representation of hierarchical data
* [react-virtualized-checkbox](https://github.com/emilebres/react-virtualized-checkbox): Checkbox group component with virtualization for large number of options
* [react-virtualized-select](https://github.com/bvaughn/react-virtualized-select): Drop-down menu for React with windowing to support large numbers of options.
* [react-virtualized-tree](https://github.com/diogofcunha/react-virtualized-tree/): A reactive tree component that aims to render large sets of tree structured data in an elegant and performant way
* [react-timeline-9000](https://github.com/BHP-DevHub/react-timeline-9000/): A calendar timeline component that is capable of displaying and interacting with a large number of items

Contributions
------------
- [react-infinite-calendar](https://github.com/clauderic/react-infinite-calendar): Infinite scrolling date-picker with localization, themes, keyboard support, and more
- [react-sortable-hoc](https://github.com/clauderic/react-sortable-hoc): Higher-order components to turn any list into an animated, touch-friendly, sortable list
- [react-sortable-tree](https://github.com/fritz-c/react-sortable-tree): Drag-and-drop sortable representation of hierarchical data
- [react-virtualized-checkbox](https://github.com/emilebres/react-virtualized-checkbox): Checkbox group component with virtualization for large number of options
- [react-virtualized-select](https://github.com/bvaughn/react-virtualized-select): Drop-down menu for React with windowing to support large numbers of options.
- [react-virtualized-tree](https://github.com/diogofcunha/react-virtualized-tree/): A reactive tree component that aims to render large sets of tree structured data in an elegant and performant way
- [react-timeline-9000](https://github.com/BHP-DevHub/react-timeline-9000/): A calendar timeline component that is capable of displaying and interacting with a large number of items

## Contributions

Use [GitHub issues](https://github.com/bvaughn/react-virtualized/issues) for requests.

I actively welcome pull requests; learn how to [contribute](https://github.com/bvaughn/react-virtualized/blob/master/CONTRIBUTING.md).

Changelog
---------
## Changelog

Changes are tracked in the [changelog](https://github.com/bvaughn/react-virtualized/blob/master/CHANGELOG.md).

License
---------
## License

*react-virtualized* is available under the MIT License.
_react-virtualized_ is available under the MIT License.
48 changes: 23 additions & 25 deletions docs/ArrowKeyStepper.md
View file
@@ -1,5 +1,4 @@
ArrowKeyStepper
---------------
## ArrowKeyStepper

High-order component that decorates another virtualized component and responds to arrow-key events by scrolling one row or column at a time.
This provides a snap-to behavior rather than the default browser scrolling behavior.
Expand All @@ -8,33 +7,35 @@ Note that unlike the other HOCs in react-virtualized, the `ArrowKeyStepper` adds
The appearance of this wrapper element can be customized using the `className` property.

### Prop Types
| Property | Type | Required? | Description |
|:---|:---|:---:|:---|
| children | Function | ✓ | Function responsible for rendering children. This function should implement the following signature: `({ onSectionRendered: Function, scrollToColumn: number, scrollToRow: number }) => PropTypes.element` |
| className | String | | CSS class name to attach to the wrapper `<div>`. |
| columnCount | Number | ✓ | Number of columns in grid; for `Table` and `List` this property should always be `1`. |
| disabled | Boolean | | Disables all scrolling using arrow-keys; defaults to `false` |
| isControlled | Boolean | | This component is "controlled"; it will not update `scrollToColumn` or `scrollToRow`. This property should be used with `onScrollToChange`. |
| mode | "edges" or "cells" | | Controls behavior of stepper when arrow key direction changes. "cells" means that the index will only increment or decrement by 1; "edges" (default) means that the opposite side of the grid will be incremented. |
| onScrollToChange | Function | | Called when arrow key navigation should update the current scroll-to values. |
| rowCount | Number | ✓ | Number of rows in grid. |
| scrollToColumn | Number | | Optional default/initial `scrollToColumn` value |
| scrollToRow | Number | | Optional default/initial `scrollToRow` value |

| Property | Type | Required? | Description |
| :--------------- | :----------------- | :-------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| children | Function | ✓ | Function responsible for rendering children. This function should implement the following signature: `({ onSectionRendered: Function, scrollToColumn: number, scrollToRow: number }) => PropTypes.element` |
| className | String | | CSS class name to attach to the wrapper `<div>`. |
| columnCount | Number | ✓ | Number of columns in grid; for `Table` and `List` this property should always be `1`. |
| disabled | Boolean | | Disables all scrolling using arrow-keys; defaults to `false` |
| isControlled | Boolean | | This component is "controlled"; it will not update `scrollToColumn` or `scrollToRow`. This property should be used with `onScrollToChange`. |
| mode | "edges" or "cells" | | Controls behavior of stepper when arrow key direction changes. "cells" means that the index will only increment or decrement by 1; "edges" (default) means that the opposite side of the grid will be incremented. |
| onScrollToChange | Function | | Called when arrow key navigation should update the current scroll-to values. |
| rowCount | Number | ✓ | Number of rows in grid. |
| scrollToColumn | Number | | Optional default/initial `scrollToColumn` value |
| scrollToRow | Number | | Optional default/initial `scrollToRow` value |

### Public Methods

##### setScrollIndexes ({ scrollToColumn: number, scrollToRow: number })

Override the local state of the component with new values for `scrollToRow` and `scrollToColumn`.

### Children function

The child function is passed the following named parameters:

| Parameter | Type | Description |
|:---|:---|:---|
| Parameter | Type | Description |
| :---------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------- |
| onSectionRendered | Function | Pass-through callback to be attached to child component; informs the key-stepper which range of cells are currently visible. |
| scrollToColumn | Number | Specifies which column in the child component should be visible |
| scrollToRow | Number | Specifies which row in the child component should be visible |
| scrollToColumn | Number | Specifies which column in the child component should be visible |
| scrollToRow | Number | Specifies which row in the child component should be visible |

### Examples

Expand All @@ -43,15 +44,12 @@ You can decorate any virtualized component (eg. `Table`, `Grid`, or `List`) with
```javascript
import React from 'react';
import ReactDOM from 'react-dom';
import { ArrowKeyStepper, Grid } from 'react-virtualized';
import {ArrowKeyStepper, Grid} from 'react-virtualized';
import 'react-virtualized/styles.css'; // only needs to be imported once

ReactDOM.render(
<ArrowKeyStepper
columnCount={columnCount}
rowCount={rowCount}
>
{({ onSectionRendered, scrollToColumn, scrollToRow }) => (
<ArrowKeyStepper columnCount={columnCount} rowCount={rowCount}>
{({onSectionRendered, scrollToColumn, scrollToRow}) => (
<Grid
columnCount={columnCount}
onSectionRendered={onSectionRendered}
Expand All @@ -62,6 +60,6 @@ ReactDOM.render(
/>
)}
</ArrowKeyStepper>,
document.getElementById('example')
document.getElementById('example'),
);
```

0 comments on commit 23942b3

Please sign in to comment.