高级话题 - Decorators(装饰器) - 《draft中文文档》

CompositeDecorator(组合decorator)
Decorator Components
Beyond CompositeDecorator
Setting new decorators

内联样式和块样式并不是我们想要添加到编辑器中的唯一一种丰富样式。例如，Facebook的评论输入为mentions和hashtag提供蓝色的背景高亮显示。
为了支持定制富文本的灵活性，Draft提供了一个“装饰器(Decorators)”系统。tweet示例提供了一个可运行的装饰器示例。

CompositeDecorator(组合decorator)

装饰器的概念是基于对给定ContentBlock的内容进行扫描，寻找与已定义策略(比如一个正则)相匹配的文本范围，然后使用指定的React组件呈现它们。
您可以使用CompositeDecorator类来定义您想要的装饰器行为。这个类允许您提供多个DraftDecorator对象，并将依次使用每个策略搜索一个文本块。
装饰器存储在EditorState记录中。当创建一个新的EditorState对象时，例如通过EditorState. createEmpty()，可以选择传递一个装饰器参数。

额外说一点当内容改变的时候，最终的EditorState对象会用它的装饰器重新计算新的ContentState ，并且定义要装饰的部分。渲染输出的时候会形成一个完整的有块元素、装饰器、内联元素的树。用这种方式，我们能确保当内容改变的时候，被渲染的装饰器跟EditorState实时同步。

在这个“Tweet”编辑器的例子中，举个例子，我们用一个CompositeDecorator搜索@-handle字符串和#hashtag字符串

const compositeDecorator = new CompositeDecorator([
  {
    strategy: handleStrategy,
    component: HandleSpan,
  },
  {
    strategy: hashtagStrategy,
    component: HashtagSpan,
  },
]);

这个复合的装饰器会首先扫描给定区域内的文字，找完@-handle后会找匹配matches的内容。

// Note: these aren't very good regexes, don't use them!
const HANDLE_REGEX = /\@[\w]+/g;
const HASHTAG_REGEX = /\#[\w\u0590-\u05ff]+/g;
function handleStrategy(contentBlock, callback, contentState) {
  findWithRegex(HANDLE_REGEX, contentBlock, callback);
}
function hashtagStrategy(contentBlock, callback, contentState) {
  findWithRegex(HASHTAG_REGEX, contentBlock, callback);
}
function findWithRegex(regex, contentBlock, callback) {
  const text = contentBlock.getText();
  let matchArr, start;
  while ((matchArr = regex.exec(text)) !== null) {
    start = matchArr.index;
    callback(start, start + matchArr[0].length);
  }
}

这个策略函数会执行返回一个回调函数,回调函数传递匹配文字的start值和end值。

Decorator Components

为了要装饰部分文字，你必须定义一个用于渲染他们的React component。这些可以是一个带着CSS类或者样式的span标签。
在我们这个例子中，CompositeDecorator对象声明了HandleSpan 和 HashtagSpan 用于装饰用的Component，这些是React的无状态组件。

const HandleSpan = props => {
  return (
    <span {...props} style={styles.handle}>
      {props.children}
    </span>
  );
};
const HashtagSpan = props => {
  return (
    <span {...props} style={styles.hashtag}>
      {props.children}
    </span>
  );
};

Decorator Component 在props中接收一系列元数据,包括contentState的副本,entityKey(如果有的话)和blockKey,有关提供给Decorator Component完整的props列表，请参考 DraftDecoratorComponentProps type。
注意props.children被传递给渲染的输出。这样做是为了确保装饰后的文字会在span内渲染。
你可以用相同的方法处理链接，就像link example中那样做的。

Beyond CompositeDecorator

装饰器对象被用于EditorState，它仅仅需要匹配DraftDecoratorType的类型定义，这意味着你可以创建任何一个你期望的装饰器类，只要他们匹配期望的类型，你将不会被CompositeDecorator束缚。

Setting new decorators

未来，我们将可以在EditorState中设置新的decorator值，通过immutable的方法，在正常的状态下进行传递和设置。
这意味着在你的app工作流中，如果你的decorator成为无效或者需要一个修改，你可以创建一个新的装饰器对象或者用null删除所有的装饰器，并且EditorState.set()使用新的装饰器设置。
举个例子，因为某些原因，我们希望当用户操作编辑器的时候，禁用@-handle装饰器，它会变得很简单，就像下面这样做：

function turnOffHandleDecorations(editorState) {
  const onlyHashtags = new CompositeDecorator([{
    strategy: hashtagStrategy,
    component: HashtagSpan,
  }]);
  return EditorState.set(editorState, {decorator: onlyHashtags});
}

editorState中的ContentState会用新的装饰器重新计算，并且@-handle装饰器不会在下个渲染中呈现出来。
要再一次说明一下，因为使用持久化数据，它依然会是高效的。

<!--
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 • Decorators</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 {CompositeDecorator, Editor, EditorState} = Draft;
      class TweetEditorExample extends React.Component {
        constructor() {
          super();
          const compositeDecorator = new CompositeDecorator([
            {
              strategy: handleStrategy,
              component: HandleSpan,
            },
            {
              strategy: hashtagStrategy,
              component: HashtagSpan,
            },
          ]);
          this.state = {
            editorState: EditorState.createEmpty(compositeDecorator),
          };
          this.focus = () => this.refs.editor.focus();
          this.onChange = (editorState) => this.setState({editorState});
          this.logState = () => console.log(this.state.editorState.toJS());
        }
        render() {
          return (
            <div style={styles.root}>
              <div style={styles.editor} onClick={this.focus}>
                <Editor
                  editorState={this.state.editorState}
                  onChange={this.onChange}
                  placeholder="Write a tweet..."
                  ref="editor"
                  spellCheck={true}
                />
              </div>
              <input
                onClick={this.logState}
                style={styles.button}
                type="button"
                value="Log State"
              />
            </div>
          );
        }
      }
      /**
       * Super simple decorators for handles and hashtags, for demonstration
       * purposes only. Don't reuse these regexes.
       */
      const HANDLE_REGEX = /@[\w]+/g;
      const HASHTAG_REGEX = /#[\w\u0590-\u05ff]+/g;
      function handleStrategy(contentBlock, callback, contentState) {
        findWithRegex(HANDLE_REGEX, contentBlock, callback);
      }
      function hashtagStrategy(contentBlock, callback, contentState) {
        findWithRegex(HASHTAG_REGEX, contentBlock, callback);
      }
      function findWithRegex(regex, contentBlock, callback) {
        const text = contentBlock.getText();
        let matchArr, start;
        while ((matchArr = regex.exec(text)) !== null) {
          start = matchArr.index;
          callback(start, start + matchArr[0].length);
        }
      }
      const HandleSpan = (props) => {
        return (
          <span
            style={styles.handle}
            data-offset-key={props.offsetKey}
          >
            {props.children}
          </span>
        );
      };
      const HashtagSpan = (props) => {
        return (
          <span
            style={styles.hashtag}
            data-offset-key={props.offsetKey}
          >
            {props.children}
          </span>
        );
      };
      const styles = {
        root: {
          fontFamily: '\'Helvetica\', sans-serif',
          padding: 20,
          width: 600,
        },
        editor: {
          border: '1px solid #ddd',
          cursor: 'text',
          fontSize: 16,
          minHeight: 40,
          padding: 10,
        },
        button: {
          marginTop: 10,
          textAlign: 'center',
        },
        handle: {
          color: 'rgba(98, 177, 254, 1.0)',
          direction: 'ltr',
          unicodeBidi: 'bidi-override',
        },
        hashtag: {
          color: 'rgba(95, 184, 138, 1.0)',
        },
      };
      ReactDOM.render(
        <TweetEditorExample />,
        document.getElementById('target')
      );
    </script>
  </body>
</html>