快速入门

Create React App#

Recoil 是 React 的状态管理库，因此你需要将 Recoil 安装到 React 项目中才能使用。创建 React 项目最方便且推荐的方式是使用 Create React App：

npx create-react-app my-app

npx 是 npm 5.2+ 版本之后自带的软件包运行工具，如果你所用的 npm 版本较低，请参阅 npm 老版本安装 npx 指南。

安装 Create React App 的方式有很多种，具体请参见官方文档。

安装#

Recoil 软件包已经发布到 npm 上了。要安装 Recoil 的最新版本，请执行如下命令：

npm install recoil

使用 yarn 安装请执行：

yarn add recoil

Or if you're using bower:

bower install --save recoil

RecoilRoot#

对于使用 Recoil 的组件，需要将 RecoilRoot 放置在组件树上的任一父节点处。最好将其放在根组件中：

import React from 'react';
import {
  RecoilRoot,
  atom,
  selector,
  useRecoilState,
  useRecoilValue,
} from 'recoil';

function App() {
  return (
    <RecoilRoot>
      <CharacterCounter />
    </RecoilRoot>
  );
}

后续章节中我们将实现 CharacterCounter 组件。

Atom#

一个 atom 代表一个状态。Atom 可在任意组件中进行读写。读取 atom 值的组件隐式订阅了该 atom，因此任何 atom 的更新都将导致订阅该 atom 的组件重新渲染：

const textState = atom({
  key: 'textState', // unique ID (with respect to other atoms/selectors)
  default: '', // default value (aka initial value)
});

在需要向 atom 读取或写入的组件中，应该使用 useRecoilState()，如下所示：

function CharacterCounter() {
  return (
    <div>
      <TextInput />
      <CharacterCount />
    </div>
  );
}

function TextInput() {
  const [text, setText] = useRecoilState(textState);

  const onChange = (event) => {
    setText(event.target.value);
  };

  return (
    <div>
      <input type="text" value={text} onChange={onChange} />
      <br />
      Echo: {text}
    </div>
  );
}

Selector#

selector 代表一个派生状态，派生状态是状态的转换。你可以将派生状态视为将状态传递给以某种方式修改给定状态的纯函数的输出：

const charCountState = selector({
  key: 'charCountState', // unique ID (with respect to other atoms/selectors)
  get: ({get}) => {
    const text = get(textState);

    return text.length;
  },
});

我们可以使用 useRecoilValue() 这一 hook，来读取 charCountState 的值：

function CharacterCount() {
  const count = useRecoilValue(charCountState);

  return <>Character Count: {count}</>;
}

演示#

以下时一个完整项目演示：

Echo:

Character Count: 0