高级话题 - Entities(实体) - 《draft中文文档》

介绍
创建和检索实体
“Mutability”
Modifying Entities
Using Entities for Rich Content

本文讨论了实体系统，Draft使用它来用元数据注释文本范围。实体引入了样式文本之外的丰富的文本显示。超链接、提及和嵌入的内容都可以使用实体来实现。
在Draft的代码存储库中,超链接文本编辑器和实体demo提供了实际的代码示例，以帮助阐明如何使用实体以及它们的内置行为。
在实体的api参考中,提供了有关创建、检索或更新实体对象时使用的静态方法的详细信息。
有关实体API最近更改的信息，以及如何更新应用程序的示例，请参阅我们的v0.10 API迁移指南。

介绍

一个实体是一个在Draft编辑器中代表一个范围文本的元数据的对象。它有三个属性:

type:表示它是哪种实体的字符串。 ‘LINK’, ‘MENTION’, ‘PHOTO’,这三种类型中的其中一个
mutability:不要将其与immutable-js中的immutability混淆，该属性表示在编辑器中编辑文本范围时使用该实体对象注释的文本范围的行为。下面将更详细地讨论这个问题。
data:包含实体元数据的可选对象。例如，’LINK’实体可能包含一个数据对象，该对象包含该链接的href值。

所有实体都存储在ContentState记录中。实体由ContentState中的key键引用，而React组件用于修饰带注释的范围。(我们目前正在弃用以前用于访问实体的API;见问题# 839。)

使用decorators或custom block components，您可以基于实体元数据向编辑器添加丰富的文本呈现。

创建和检索实体

实体应该使用contentState.createEntity，它接受上述三个属性作为参数。这个方法返回一个ContentState包含新创建的实体的新状态记录，也就是返回一个新的ContentState带上了新建的实体,然后你可以调用contentState.getLastCreatedEntityKey获取新创建的实体记录的键。

此键是将实体应用到内容时应该使用的值。例如,Modifier模块包含了一个applyEntity方法:

const contentState = editorState.getCurrentContent();
const contentStateWithEntity = contentState.createEntity('LINK', 'MUTABLE', {
  url: 'http://www.zombo.com',
});
const entityKey = contentStateWithEntity.getLastCreatedEntityKey();
const contentStateWithLink = Modifier.applyEntity(
  contentStateWithEntity,
  selectionState,
  entityKey,
);
const newEditorState = EditorState.push(editorState, {
  currentContent: contentStateWithLink,
});

然后对于给定的文本范围,你可以使用ContentBlock对象上的getEntityAt()方法提取其文本相关联的实体key键,其中你可以在方法中传入目标文本中偏移量值。

const contentState = editorState.getCurrentContent();
const blockWithLinkAtBeginning = contentState.getBlockForKey('...');
const linkKey = blockWithLinkAtBeginning.getEntityAt(0);
const linkInstance = contentState.getEntity(linkKey);
const {url} = linkInstance.getData();

“Mutability”

实体可能有三个”Mutability”值中的一个。它们之间的区别是当用户对它们进行编辑时它们的行为方式。注意DraftEntityInstance对象一直都是持久化的记录，并且这个属性意味着只能表明带注释的文字在编辑器里是如何突变的。(未来的更改可能会重命名此属性，以避免命名方面的潜在混乱)

Immutable

如果不从文字中删除整个实体，文字是不能被改变的。带这个属性的实体都是一个完整的粒子。
举个例子，在Facebook的输入框中，添加一个@功能，比如(@ mqyqingfeng)。然后，增加一个字符或者删掉一个字符，注意每当增加字符的时候，实体被删除，当删除字符的时候，整个实体被删除。
这个属性值非常有用当文字必须完全匹配它的相关的元数据，而且不能被改变。

Mutable

文字可以自由的改变。举个例子，链接的文字是可以设置成”mutable”的，因为链接的地址和文字不是强关联的。

Segmented

Segmented分段像”mutable”实体一样强关联对应的文字，但是允许自定义的删除。
举个例子，在Facebook的输入框中，@一个朋友，然后，给这个名字添加一个字符。注意，实体会被从整个字符串中移除，因为你@的朋友们没有你改后的名字。
接下来，在@的字符串中，尝试删除一个字符或者一个单词。注意只有你删除的那一部分实体会被删除，用这样方式。我们可以允许缩写名。

Modifying Entities

因为DraftEntityInstance记录是持久化的，你也许不能直接更新data属性。
相应的，两个Entity方法可以用来修改实体：mergeData 和 replaceData。前者允许通过传入一个对象来合并来更新数据，而后者则完全交换新数据对象。

Using Entities for Rich Content

下一篇文章会讲到装饰器(decorator)对象的用法,这些对象可用于检索用于呈现渲染目的的实体。
link编辑器示例提供了一个可直接运行的实体创建和装饰器(decorator)的工作示例。

<!--
Copyright (c) Facebook, Inc. and its affiliates. All rights reserved.
This file provided by Facebook is for non-commercial testing and evaluation
purposes only. Facebook reserves all rights not expressly granted.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
FACEBOOK BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-->
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Draft • Link Editor</title>
    <link rel="stylesheet" href="../../../dist/Draft.css" />
  </head>
  <body>
    <div id="target"></div>
    <script src="../../../node_modules/react/umd/react.development.js"></script>
    <script src="../../../node_modules/react-dom/umd/react-dom.development.js"></script>
    <script src="../../../node_modules/immutable/dist/immutable.js"></script>
    <script src="../../../node_modules/es6-shim/es6-shim.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/babel-core/5.8.34/browser.js"></script>
    <script src="../../../dist/Draft.js"></script>
    <script type="text/babel">
      'use strict';
      const {
        convertToRaw,
        CompositeDecorator,
        Editor,
        EditorState,
        RichUtils,
      } = Draft;
      class LinkEditorExample extends React.Component {
        constructor(props) {
          super(props);
          const decorator = new CompositeDecorator([
            {
              strategy: findLinkEntities,
              component: Link,
            },
          ]);
          this.state = {
            editorState: EditorState.createEmpty(decorator),
            showURLInput: false,
            urlValue: '',
          };
          this.focus = () => this.refs.editor.focus();
          this.onChange = (editorState) => this.setState({editorState});
          this.logState = () => {
            const content = this.state.editorState.getCurrentContent();
            console.log(convertToRaw(content));
          };
          this.promptForLink = this._promptForLink.bind(this);
          this.onURLChange = (e) => this.setState({urlValue: e.target.value});
          this.confirmLink = this._confirmLink.bind(this);
          this.onLinkInputKeyDown = this._onLinkInputKeyDown.bind(this);
          this.removeLink = this._removeLink.bind(this);
        }
        _promptForLink(e) {
          e.preventDefault();
          const {editorState} = this.state;
          const selection = editorState.getSelection();
          if (!selection.isCollapsed()) {
            const contentState = editorState.getCurrentContent();
            const startKey = editorState.getSelection().getStartKey();
            const startOffset = editorState.getSelection().getStartOffset();
            const blockWithLinkAtBeginning = contentState.getBlockForKey(startKey);
            const linkKey = blockWithLinkAtBeginning.getEntityAt(startOffset);
            let url = '';
            if (linkKey) {
              const linkInstance = contentState.getEntity(linkKey);
              url = linkInstance.getData().url;
            }
            this.setState({
              showURLInput: true,
              urlValue: url,
            }, () => {
              setTimeout(() => this.refs.url.focus(), 0);
            });
          }
        }
        _confirmLink(e) {
          e.preventDefault();
          const {editorState, urlValue} = this.state;
          const contentState = editorState.getCurrentContent();
          const contentStateWithEntity = contentState.createEntity(
            'LINK',
            'MUTABLE',
            {url: urlValue}
          );
          const entityKey = contentStateWithEntity.getLastCreatedEntityKey();
          const newEditorState = EditorState.set(editorState, { currentContent: contentStateWithEntity });
          this.setState({
            editorState: RichUtils.toggleLink(
              newEditorState,
              newEditorState.getSelection(),
              entityKey
            ),
            showURLInput: false,
            urlValue: '',
          }, () => {
            setTimeout(() => this.refs.editor.focus(), 0);
          });
        }
        _onLinkInputKeyDown(e) {
          if (e.which === 13) {
            this._confirmLink(e);
          }
        }
        _removeLink(e) {
          e.preventDefault();
          const {editorState} = this.state;
          const selection = editorState.getSelection();
          if (!selection.isCollapsed()) {
            this.setState({
              editorState: RichUtils.toggleLink(editorState, selection, null),
            });
          }
        }
        render() {
          let urlInput;
          if (this.state.showURLInput) {
            urlInput =
              <div style={styles.urlInputContainer}>
                <input
                  onChange={this.onURLChange}
                  ref="url"
                  style={styles.urlInput}
                  type="text"
                  value={this.state.urlValue}
                  onKeyDown={this.onLinkInputKeyDown}
                />
                <button onMouseDown={this.confirmLink}>
                  Confirm
                </button>
              </div>;
          }
          return (
            <div style={styles.root}>
              <div style={{marginBottom: 10}}>
                Select some text, then use the buttons to add or remove links
                on the selected text.
              </div>
              <div style={styles.buttons}>
                <button
                  onMouseDown={this.promptForLink}
                  style={{marginRight: 10}}>
                  Add Link
                </button>
                <button onMouseDown={this.removeLink}>
                  Remove Link
                </button>
              </div>
              {urlInput}
              <div style={styles.editor} onClick={this.focus}>
                <Editor
                  editorState={this.state.editorState}
                  onChange={this.onChange}
                  placeholder="Enter some text..."
                  ref="editor"
                />
              </div>
              <input
                onClick={this.logState}
                style={styles.button}
                type="button"
                value="Log State"
              />
            </div>
          );
        }
      }
      function findLinkEntities(contentBlock, callback, contentState) {
        contentBlock.findEntityRanges(
          (character) => {
            const entityKey = character.getEntity();
            return (
              entityKey !== null &&
              contentState.getEntity(entityKey).getType() === 'LINK'
            );
          },
          callback
        );
      }
      const Link = (props) => {
        const {url} = props.contentState.getEntity(props.entityKey).getData();
        return (
          <a href={url} style={styles.link}>
            {props.children}
          </a>
        );
      };
      const styles = {
        root: {
          fontFamily: '\'Georgia\', serif',
          padding: 20,
          width: 600,
        },
        buttons: {
          marginBottom: 10,
        },
        urlInputContainer: {
          marginBottom: 10,
        },
        urlInput: {
          fontFamily: '\'Georgia\', serif',
          marginRight: 10,
          padding: 3,
        },
        editor: {
          border: '1px solid #ccc',
          cursor: 'text',
          minHeight: 80,
          padding: 10,
        },
        button: {
          marginTop: 10,
          textAlign: 'center',
        },
        link: {
          color: '#3b5998',
          textDecoration: 'underline',
        },
      };
      ReactDOM.render(
        <LinkEditorExample />,
        document.getElementById('target')
      );
    </script>
  </body>
</html>