API基础

This document provides an overview of the basics of the Draft API. A working example is also available to follow along.

本文档提供了Draft基础知识的概述。一个工作实例也可以同时参考。

受控输入框

The Editor React component is built as a controlled ContentEditable component, with the goal of providing a top-level API modeled on the familiar React controlled input API.

这个Editor React组件是作为一个受控的、内容可编辑的组件被构建的。它的目的是在相似的React受控输入框API上，提供一个模型化的顶层API。

As a brief refresher, controlled inputs involve two key pieces:

作为一个简短的复习，受控输入涉及两个关键件：

1. A value to represent the state of the input
2. An onChange prop function to receive updates to the input

1. 表示输入状态的值
2. 一个onChange prop方法接受输入更新

This approach allows the component that composes the input to have strict control over the state of the input, while still allowing updates to the DOM to provide information about the text that the user has written.

这个方法允许组成输入框的组件对于输入状态有严格的控制，但同时也允许对DOM进行更新，以提供用户所写的文本信息。

class MyInput extends React.Component {
  constructor(props) {
    super(props);
    this.state = {value: ''};
    this.onChange = (evt) => this.setState({value: evt.target.value});
  }
  render() {
    return <input value={this.state.value} onChange={this.onChange} />;
  }
}

The top-level component can maintain control over the input state via this value state property.

顶层组件可以通过该 value 状态属性来维护控制输入的状态。

受控富文本

In a React rich text scenario, however, there are two clear problems:

然而，在React富文本场景中，有两个明显的问题：

1. A string of plaintext is insufficient to represent the complex state of a rich editor.
2. There is no such onChange event available for a ContentEditable element.

1. 一个明文字符串不足以代表富文本的复杂状态。
2. 没有这样一个可以提供给ContentEditable元素的 onChange 事件。

State is therefore represented as a single immutable EditorState object, and onChange is implemented within the Editor core to provide this state value to the top level.

状态因此被一个唯一的不变的 EditorState 对象代表，并且实施在 Editor 核心中的 onChange 提供它的状态值给顶层。

The EditorState object is a complete snapshot of the state of the editor, including contents, cursor, and undo/redo history. All changes to content and selection within the editor will create new EditorState objects. Note that this remains efficient due to data persistence across immutable objects.

这个 EditorState 对象是这个编辑器状态的一个完整的快照，包括内容、光标和撤销/重做历史。所有编辑器中的内容和选择的改变，将会创建新的 EditorState 对象。请注意，由于数据持久化，这在不可变对象上仍然是有效的。

import {Editor, EditorState} from 'draft-js';

class MyEditor extends React.Component {
  constructor(props) {
    super(props);
    this.state = {editorState: EditorState.createEmpty()};
    this.onChange = (editorState) => this.setState({editorState});
  }
  render() {
    return <Editor editorState={this.state.editorState} onChange={this.onChange} />;
  }
}

For any edits or selection changes that occur in the editor DOM, your onChange handler will execute with the latest EditorState object based on those changes.

对于任何发生在编辑器DOM中的编辑或选择变化，你的onChange处理方法，会对以这些变化为基础的 EditorState 对象进行处理。