Draft.js Entity API 完整指南：实体创建、检索、更新与 v0.10 迁移实践

前端UI组件【免费下载链接】draft-jsA React framework for building text editors.项目地址https://gitcode.com/gh_mirrors/dr/draft-js点击查看免费下载Entity是 Draft.js 中负责创建、检索与更新文档实体document entity的静态模块实体用于为一段文本范围标注元数据如链接的 URI、提及用户的 ID。本文将基于仓库中的 APIReference-Entity.md 展开逐方法讲解create、add、get、mergeData、replaceData的签名、语义与底层实现并对照 v0.10 API 迁移指南 说明如何把旧 API 平滑迁移到以ContentState为核心的新 API。读完本文你将掌握实体的完整生命周期创建、存储、检索、更新以及在编辑器中把实体标注到文本范围并完成渲染的实战方案。Entity 是什么在 Draft.js 中实体是用于给一段文本附加元数据的对象。例如一个LINK实体可能携带{uri: https://...}数据当ContentBlock渲染到浏览器时被该实体标注的文本可渲染成a锚点uri即成为href。实体是实现链接、提及mention、嵌入内容embedded content等富文本能力的基础。按照官方 API 参考文档的定义Entity是一个静态模块同时满足两件事提供创建create、检索retrieve、更新update实体对象的 API承载整个 Draft 运行时中唯一的数据存储the single store used to maintain entity data。也就是说实体数据由这个模块全局维护任何位置都可以通过模块方法读写。关于实体的概念性介绍mutability 语义、装饰器渲染等详见仓库中的 Advanced-Topics-Entities.md。版本提醒实体存储与管理的 API 在 v0.10 发生了变更——全局的DraftEntity模块正被弃用实体实例改由ContentState统一管理。升级应用请参照 APIReference-APIMigration.md。本文会同时给出旧 API 的完整参考与新 API 的迁移写法。实体对象的结构Entity方法返回的实体对象是DraftEntityInstance不可变记录immutable record。其定义位于 DraftEntityInstance.jsconst DraftEntityInstanceRecord (Record({ type: TOKEN, mutability: IMMUTABLE, data: Object, }): any);这是一个基于 Immutable.jsRecord构建的数据结构拥有三个字段typeDraftEntityType标识实体种类的字符串如LINK、MENTION、PHOTO。从源码类型定义看DraftEntityType.js 中DraftEntityType string即任意字符串均可作为类型。mutabilityDraftEntityMutability编辑行为标记取值MUTABLE、IMMUTABLE、SEGMENTED三者之一详见下文Mutability 三态语义。data可选的元数据对象例如LINK实体存放href值。DraftEntityInstance提供了三个 getter 方法用于只读访问class DraftEntityInstance extends DraftEntityInstanceRecord { getType(): DraftEntityType { ... } getMutability(): DraftEntityMutability { ... } getData(): Object { ... } }按官方文档的告诫这些 getter 只用于检索不应直接对实例做修改——因为实例是不可变的。Entity 方法全解Entity 模块对外暴露五个方法签名总览如下方法签名用途createcreate(type, mutability, data?): string创建新实体返回其字符串 keyaddadd(instance: DraftEntityInstance): string把已存在的实例加入存储返回 keygetget(key: string): DraftEntityInstance按 key 取回实体实例不存在则抛错mergeDatamergeData(key, toMerge): DraftEntityInstance合并更新实体 data返回新实例replaceDatareplaceData(key, newData): DraftEntityInstance整体替换实体 data返回新实例create(type, mutability, data?)已弃用推荐改用contentState.createEntity。create( type: DraftEntityType, mutability: DraftEntityMutability, data?: Object ): stringcreate用于生成一个具备指定属性的新实体对象。注意它返回的是一个字符串——实体在ContentState中通过字符串 key 被引用该字符串应写入CharacterMetadata对象中用来标记哪些字符属于该实体。其底层实现位于 DraftEntity.js__create( type: DraftEntityType, mutability: DraftEntityMutability, data?: Object, ): string { return DraftEntity.__add( new DraftEntityInstance({type, mutability, data: data || {}}), ); }可以看到create实际是构造实例 调用add的组合先用type、mutability、data缺省为空对象构造一个新的DraftEntityInstance再把它加入存储并返回新生成的 key。add(instance)已弃用推荐改用contentState.addEntity。add(instance: DraftEntityInstance): string大多数情况下你只需要Entity.create()add是一个便捷方法常规 Draft 使用中大概率用不到。add的适用场景是实例已经被创建好例如正在把一份普通 JavaScript 表示的ContentState恢复为可编辑状态现在需要把这些实例逐个放入 Entity 存储。从实现看DraftEntity.jsadd会生成一个新的随机 key 并把实例写入有序映射__add(instance: DraftEntityInstance): string { instanceKey uuid(); instances instances.set(instanceKey, instance); return instanceKey; }key 由uuid模块生成因此每次调用都会得到全新的唯一字符串。get(key)已弃用推荐改用contentState.getEntity。get(key: string): DraftEntityInstance返回指定 key 对应的DraftEntityInstance如果该 key 下不存在实例会直接抛出异常。这一行为在实现中通过invariant保证DraftEntity.js__get(key: string): DraftEntityInstance { const instance instances.get(key); invariant(!!instance, Unknown DraftEntity key: %s., key); return instance; }即Unknown DraftEntity key: key。这意味着调用get前应确保 key 确实来自一次成功的创建或先用CharacterMetadata.getEntity()判断字符是否真的关联了实体。mergeData(key, toMerge)已弃用推荐改用contentState.mergeEntityData。mergeData( key: string, toMerge: {[key: string]: any} ): DraftEntityInstance由于DraftEntityInstance是不可变对象你不能用常规的赋值方式修改实体的元数据。mergeData允许对指定实体施加增量更新传入一个待合并的对象方法会把它与现有data浅合并浅层展开合并并返回一个携带新数据的新实例。实现如下DraftEntity.js__mergeData( key: string, toMerge: {[key: string]: any, ...}, ): DraftEntityInstance { const instance DraftEntity.__get(key); const newData: Object {...instance.getData(), ...toMerge}; const newInstance: DraftEntityInstance instance.set(data, newData); instances instances.set(key, newInstance); return newInstance; }要点合并是浅层展开{...old, ...toMerge}toMerge中出现的字段会覆盖旧值未涉及的字段保留更新后存储中的映射也会被替换为携带新数据的新实例。replaceData(key, newData)已弃用推荐改用contentState.replaceEntityData。replaceData( key: string, newData: {[key: string]: any} ): DraftEntityInstancereplaceData与mergeData类似区别在于它会彻底丢弃实例现有的data整体替换为传入的newData。实现DraftEntity.js不进行任何合并__replaceData( key: string, newData: {[key: string]: any, ...}, ): DraftEntityInstance { const instance DraftEntity.__get(key); const newInstance: DraftEntityInstance instance.set(data, newData); instances instances.set(key, newInstance); return newInstance; }mergeData与replaceData的选择原则只改动其中几个字段用mergeData需要彻底重置实体的元数据例如把链接实体整体指向一个新对象用replaceData。底层实现单例存储与不可变更新实体模块的内部实现DraftEntity.js非常直白可以从源码结构看出以下设计单例存储模块级变量instances是一个 Immutable.jsOrderedMapstring, DraftEntityInstanceDraftEntity.js所有实体都保存在这一个 Map 中模块同时暴露__getAll()与__loadWithEntities(entities)用于整体读取与加载。其中__loadWithEntities在加载后还会重新生成instanceKeyDraftEntity.js以保证恢复旧数据后新创建的 key 不会冲突。随机 key模块级变量instanceKey由uuid()生成每次add都生成新 keyDraftEntity.js并通过__getLastCreatedEntityKey()暴露最近一次创建的 key供新 APIgetLastCreatedEntityKey过渡使用。不可变更新所有写操作都遵循取旧实例 → 生成新实例 →instances.set(key, newInstance)替换存储的模式绝不原地修改旧实例因此旧引用保持不变符合不可变数据结构的约束。临时兼容层源码中还存在get、set、last三个标注为gkd deprecation的临时公开 APIDraftEntity.js其中注释明确指出当前公开 API 将在下一版本弃用其下方标注的方法都是私有的不应直接调用。Mutability 三态语义DraftEntityMutability的取值在 ComposedEntityMutability.js 中定义只有三个var ComposedEntityMutability { MUTABLE: true, IMMUTABLE: true, SEGMENTED: true, };对应的语义源码注释与 Advanced-Topics-Entities.md 均做了说明MUTABLE可变文本可被自由修改。适用于文本内容与实体之间没有强绑定关系的场景例如链接——链接文字与 URI 可以完全无关用户在范围内增删字符时实体被保留并继续应用到新增字符上。IMMUTABLE不可变实体标注的文本范围整体不可改动相当于原子单元。在范围内新增字符会移除整个范围的实体删除字符会删除整个范围。典型场景Facebook 输入框中的 Page 提及如提及一个公众人物。SEGMENTED分段与IMMUTABLE类似地紧耦合文本但允许通过删除进行定制。在范围内新增字符同样会移除整个范围的实体删除范围内的字符则只删除受影响的段从而支持昵称式提及。典型场景Facebook 的用户提及。需要特别强调DraftEntityInstance本身始终是不可变 Record这里的 mutability 只是标注文本在编辑器内可如何被编辑的行为标记与不可变数据结构是两个不同的概念Advanced-Topics-Entities.md 也提示未来可能为该属性改名以避免混淆。v0.10 迁移从全局 Entity 到 ContentState根据 APIReference-APIMigration.mdv0.10 起全局DraftEntity模块被弃用实体实例改由ContentState管理原先在Entity上的方法全部迁移到ContentState记录上。迁移带来的收益包括DraftEntityInstance及实体存储将变得完全不可变DraftEntity不再全局可访问消除隐式全局状态任何对实体数据的修改都会触发重新渲染。旧 API 原定在 v0.11 移除现推迟到v0.12移除——但官方文档明确敦促务必尽早迁移。方法对应关系旧 APIEntity 静态模块新 APIContentStateEntity.create(type, mutability, data)contentState.createEntity(type, mutability, data)contentState.getLastCreatedEntityKey()Entity.add(instance)contentState.addEntity(instance)Entity.get(key)contentState.getEntity(key)Entity.mergeData(key, toMerge)contentState.mergeEntityData(key, toMerge)Entity.replaceData(key, newData)contentState.replaceEntityData(key, newData)对应新 API 的完整说明可见 APIReference-ContentState.mdcreateEntity、getEntity、mergeEntityData、replaceEntityData、addEntity均有签名与说明。迁移示例创建实体旧 → 新// 旧语法 const entityKey Entity.create(urlType, IMMUTABLE, {src: urlValue}); // 新语法 const contentStateWithEntity contentState.createEntity(urlType, IMMUTABLE, { src: urlValue, }); const entityKey contentStateWithEntity.getLastCreatedEntityKey();注意新语法中createEntity返回的是更新后的ContentState实体 key 需要通过getLastCreatedEntityKey()获取对应 APIReference-ContentState.md 中的说明key 是字符串应写入CharacterMetadata用于标记字符。获取实体旧 → 新// 旧语法 const entityInstance Entity.get(entityKey); // 新语法 const entityInstance contentState.getEntity(entityKey);装饰器策略的变化v0.10 同时把contentState作为第三个参数传入装饰器 strategy以便在策略中按实体类型/可变性过滤。典型用法来自迁移文档function findLinkEntities(contentBlock, callback, contentState) { contentBlock.findEntityRanges(character { const entityKey character.getEntity(); return ( entityKey ! null contentState.getEntity(entityKey).getType() LINK ); }, callback); }实战创建实体并应用到文本范围下面组合一套完整的实战流程创建实体 → 把实体标注到选中文本 → 读取实体数据。以下示例来自 Advanced-Topics-Entities.mdconst 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.set(editorState, { currentContent: contentStateWithLink, });步骤拆解editorState.getCurrentContent()取得当前内容contentState.createEntity(LINK, MUTABLE, {url})创建链接实体返回新的ContentStategetLastCreatedEntityKey()拿到新实体的字符串 keyModifier.applyEntity(contentState, selectionState, entityKey)把实体应用到当前选区覆盖的文本上EditorState.set(editorState, {currentContent: contentStateWithLink})生成新的EditorState交给编辑器。读取指定位置的实体给定一个块和偏移量可以用ContentBlock.getEntityAt(offset)取出实体 key再用contentState.getEntity(key)取回实例、读取数据const contentState editorState.getCurrentContent(); const blockWithLinkAtBeginning contentState.getBlockForKey(...); const linkKey blockWithLinkAtBeginning.getEntityAt(0); const linkInstance contentState.getEntity(linkKey); const {url} linkInstance.getData();可运行的完整示例仓库的 examples/draft-0-10-0/entity/entity.html 与 examples/draft-0-10-0/link/link.html 提供了实体创建与链接装饰的完整浏览器端示例可直接对照学习实体在实际编辑器中的内置行为。注意事项与常见坑不要直接改实例DraftEntityInstance是不可变 Record只能通过mergeData/replaceData或新 API 的mergeEntityData/replaceEntityData更新。get未知 key 会抛错invariant保证访问不存在的 key 会抛出Unknown DraftEntity key: key因此建议先用character.getEntity()判断再取值。mergeData与replaceData的取舍前者浅合并、后者整体替换务必按需求选择避免意外覆盖。优先使用新 API全局Entity静态模块已弃用并将在 v0.12 移除新代码一律使用contentState.createEntity/getLastCreatedEntityKey/getEntity/mergeEntityData/replaceEntityData/addEntity这套接口参见 APIReference-APIMigration.md 与 APIReference-ContentState.md。私有方法勿直接调用源码 DraftEntity.js 明确警告__create、__add、__get、__mergeData、__replaceData等带双下划线的方法是私有实现仅用于新旧 API 过渡不应在应用代码中调用。至此你已掌握 Draft.js 实体从创建、存储、检索到更新的完整 API 脉络以及从全局Entity静态模块迁移到ContentState的标准做法可以放心地在自己的编辑器中实现链接、提及等富文本能力。赞分享前端UI组件【免费下载链接】draft-jsA React framework for building text editors.项目地址https://gitcode.com/gh_mirrors/dr/draft-js点击查看免费下载相关推荐Draft.js v0.10 API 迁移指南从全局 DraftEntity 到 ContentState 管理的实体数据Draft.js v0.10 API 迁移指南从全局 DraftEntity 到 ContentState 管理的实体数据 Draft.js v0.10 对前端UI组件如何让 OpenSRE 深挖 AWSCloudTrail 事件与 ELB 故障的 AI 深度排查完整指南如何让 OpenSRE 深挖 AWSCloudTrail 事件与 ELB 故障的 AI 深度排查完整指南 OpenSRE 是一款开源的 AI SRE 智能体工人工智能AI Agent运维可观测性根因分析工具调用后端MCP ClientsWekan 卡片 REST API 完整指南按泳道/列表检索、创建、更新与删除Wekan 卡片 REST API 完整指南按泳道/列表检索、创建、更新与删除 卡片Card是 Wekan 看板中最核心的业务实体一张卡片承载着标题、描后端前端协同办公上一篇ChatTTS-Enhanced Speaker音色导入教程打造专属AI语音助手下一篇如何快速上手Kretes5分钟搭建你的TypeScript开发环境创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考