Entities 实体

This article discusses the Entity system, which Draft uses for annotating ranges of text with metadata. Entities enable engineers to introduce levels of richness beyond styled text to their editors. Links, mentions, and embedded content can all be implemented using entities.

本文讨论了 Entity 系统，Draft 通过它，来使用元数据注释文本范围。Entity 使工程师们能够向他们的编辑器引入比文本的样式层次更丰富的内容。链接 ( link )，提及 ( @ )和嵌入内容都可以使用 Entity来实现。

In the Draft repository, the link editor and entity demo provide live code examples to help clarify how entities can be used, as well as their built-in behavior.

在Draft库中，链接编辑器和 Entity演示都提供了实时代码示例来帮助阐明 Entity 该如何使用，以及 Entity 的内置行为。

The Entity API Reference provides details on the static methods to be used when creating, retrieving, or updating entity objects.

EntityAPI引用提供了创建、检索或更新 Entity 对象时，所使用的静态方法的详细信息。

For information about recent changes to the Entity API, and examples of how to update your application, see our v0.10 API Migration Guide.

获取关于Entity API的最新变化，以及该如何更新你的程序的例子，请看我们的v0.10 API迁移指南。

介绍

An entity is an object that represents metadata for a range of text within a Draft editor. It has three properties:

Entity 是表示Draft编辑器内文本范围的元数据的对象。它有三个属性：

type: A string that indicates what kind of entity it is, e.g. 'LINK', 'MENTION', 'PHOTO'.

mutability: Not to be confused with immutability a la immutable-js, this property denotes the behavior of a range of text annotated with this entity object when editing the text range within the editor. This is addressed in greater detail below.

data: An optional object containing metadata for the entity. For instance, a 'LINK' entity might contain a data object that contains the href value for that link.

type 类型：一个显示这是什么种类的 Entity 的字符串，如“LINK”，“MENTION”，“PHOTO”。

mutability 易变性：不要和 immutable-js的不变性混淆，这个属性是指当在编辑器中编辑一个文本范围时，这个被注释的文本范围的 Entity 对象的行为。这在下文将有更多细节。

data 数据：一个包含 Entity 的元数据的可选对象。例如，一个 “LINK” 的 Entity 可能包含一个data对象，这个对象包含了链接的href值。

All entities are stored in the ContentState record. The entites are referenced by key within ContentState and React components used to decorate annotated ranges. (We are currently deprecating a previous API for accessing Entities; see issue #839 .)

所有的 Entity 都存储在 ContentState 记录中。ContentState和 React 组件用 key 来引用 Entity ，以修饰注释的范围。（我们正在评估以前访问实体的API；看这个 issue# 839。）

Using decorators or custom block components, you can add rich rendering to your editor based on entity metadata.

使用装饰器或自定义块级组件，基于 Entity 元数据，你可以给你的编辑器添加丰富的表现力。

创建和检索实体

Entities should be created using contentState.createEntity, which accepts the three properties above as arguments. This method returns a string key, which can then be used to refer to the entity.

创建 Entity 应该使用contentState.createEntity，这个方法接受三个以上的属性参数。此方法返回一个字符串key，可被用来引用实体。

This key is the value that should be used when applying entities to your content. For instance, the Modifier module contains an applyEntity method:

这个 key 是在将 Entity 应用到你的内容上时，应该使用的值。例如，Modifier模块包含了一个applyEntity方法：

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

For a given range of text, then, you can extract its associated entity key by using the getEntityAt() method on a ContentBlock object, passing in the target offset value.

对于一个给定的文本区域，你可以通过目标的 offset 值，在contentBlock对象上使用getEntity()方法，提取它的相关 Entity 的 key。

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

“Mutability” 易变性

Entities may have one of three "mutability" values. The difference between them is the way they behave when the user makes edits to them.

Entity 可能有三种 “mutability” 值。它们之间的区别是，当用户对它们进行编辑时，它们的行为方式。

Note that DraftEntityInstanceobjects are always immutable Records, and this property is meant only to indicate how the annotated text may be "mutated" within the editor. (Future changes may rename this property to ward off potential confusion around naming.)

注意，DraftEntityInstance对象总是作为 immutable 的记录，这个属性的意义仅在于，表明编辑器中的被注释的文本可能是 “mutated” 的。（我们可能会因为未来的变化重命名此属性，以避免潜在的命名混淆。）

Immutable 不变的

This text cannot be altered without removing the entity annotation from the text. Entities with this mutability type are effectively atomic.

除非从文本中移除相关 Entity ，不然文本无法被修改。这种 mutability 类型的实体是完整的原子式的（即不可分割）。

For instance, in a Facebook input, add a mention for a Page (i.e. Barack Obama). Then, either add a character within the mentioned text, or try to delete a character. Note that when adding characters, the entity is removed, and when deleting character, the entire entity is removed.

例如，在 Facebook 输入框中，添加一个页面引用（即 @ 功能）（如巴拉克·奥巴马）。然后，在上述文本中添加字符，或尝试删除字符。请注意，当添加字符时，这个文本的实体将被移除，当删除字符时，整个文本的实体将被移除。

This mutability value is useful in cases where the text absolutely must match its relevant metadata, and may not be altered.

在文本必须绝对匹配它的对应元数据，并且不能被更改的情况下，这种 mutability 值非常有用。

Mutable 可变的

This text may be altered freely. For instance, link text is generally intended to be "mutable" since the href and linkified text are not tightly coupled.

这个文本可以被自由的更改。例如，link 文本一般倾向于 “mutable” ，因为引用和链接的文本并不是紧密耦合的。

Segmented 分离的

Entities that are "segmented" are tightly coupled to their text in much the same way as "immutable" entities, but allow customization via deletion.

“segmented” 的 Entity 紧密耦合到他们的文本，在许多方面和 “immutable” 的 Entity 相似，但允许定制它的删除。

For instance, in a Facebook input, add a mention for a friend. Then, add a character to the text. Note that the entity is removed from the entire string, since your mentioned friend may not have their name altered in your text.

例如，在 Facebook 输入框中，添加一个朋友的引用 ( @ ) 。然后，向文本添加一个字符。注意，该 Entity 将从整个字符串中移除，因为您所 @ 的朋友可能没有更改您的文本中的名称。

Next, try deleting a character or word within the mention. Note that only the section of the mention that you have deleted is removed. In this way, we can allow short names for mentions.

下一步，在 @ 中尝试删除字符或文字。注意仅仅是你删除的部分的 @ 被移除了。通过这种方法，我们可以允许短名称的 @。

修改实体

Since DraftEntityInstancerecords are immutable, you may not update the data property on an instance directly.

因为DraftEntityInstance记录是 immutable 的，你不能直接在实例上更新数据属性。

Instead, two Entitymethods are available to modify entities: mergeData and replaceData. The former allows updating data by passing in an object to merge, while the latter completely swaps in the new data object.

相对的，有两个Entity的方法可以修改 Entity ：mergedata和replacedata。前者允许通过合并对象来更新数据，而后者则用新的数据对象完全替换。

给富文本内容使用实体

The next article in this section covers the usage of decorator objects, which can be used to retrieve entities for rendering purposes.

本节中的下一篇文章将介绍装饰器对象的用法，该对象可用于检索用于呈现目的的 Entity 。

The link editor example provides a working example of entity creation and decoration in use.

link编辑器实例提供了实体创建和可使用的装饰器的工作实例。

实体