Schema 类的实例化对象包含了可以在文档中使用的 nodes 和 marks 的类型

通过方法 new Schema(spec) 进行实例化（其中参数 spec 是符合一种 TypeScript interface SchemaSpec），得到一个 schema 对象，以下称作「数据结构的约束对象」

schema 数据结构的约束对象包含一些属性和方法：

• spec 属性：一个对象，与该数据结构约束对象的配置参数类似（但是有所不同）
  提示

  它包含三个属性：

  • nodes 属性：是一个 OrderMap 映射，表示该文档所支持的节点类型。
  • marks 属性：是一个 OrderMap 映射，表示该文档所支持的样式标记类型。
  • topNode（可选）属性：字符串，顶级节点的名称

  在实例化 schema 对象时在所传递的参数中 node 和 marks 可以是纯 JS 对象，而在 schema 对象的 spec 属性中它们都以一个 OrderMap 映射来表示，虽然和纯 JS 对象类似但是它更强调顺序，由于 nodes 和 marks 涉及对 DOM 的匹配和转换，而优先级别对此有重要影响

• nodes 属性：一个对象，以键值对的形式列出所有类型的节点，键名是各种节点的名称，对应的值为一个 nodeType 对象（具体介绍可查看 node.type 属性的相关介绍）
• marks 属性：一个对象，以键值对的形式列出所有类型的样式标记，键名是各种样式标记的名称，对应的值为一个 markType 对象（具体介绍可查看 mark.type 属性的相关介绍）
• topNodeType 属性：一个 nodeType 对象（具体介绍可查看 node.type 属性的相关介绍），表示文档顶级节点的类型
• cached 属性：一个对象，用于存储数据（开发者可以将所需的数据存储到该属性上，作为缓存，避免重复计算），但需要注意为该对象添加数据（设置新的属性）时避免属性名的冲突
• node(type, attrs?, content?, marks?) 方法：基于该 schema 创建一个指定类型 type 的节点
  各个参数的具体说明：
  • 第一个参数 type 设置节点的类型，可以是表示节点名称的字符串，也可以是表示节点类型的 nodeType 对象
  • 第二个（可选）参数 attrs 设置节点所具有的属性 attributes 的值，默认值为 null 表示 attributes 采用预设值
  • 第三个（可选）参数 content 设置节点内容（子节点），可以是 fragment 片段，也可以是一个 node 节点实例，也可以是 [nodes] 一系列节点构成的数组
  • 第四个（可选）参数 marks 设置节点的样式标记，是 [marks] 一系列样式标记对象构成的数组
• text(textContent, marks?) 方法：根据给定的文本内容 textContent（字符串）创建一个文本节点，可以通过第二个（可选）参数 marks（它是一系列样式标记对象构成的数组）为文本添加样式标记
• mark(type, attrs?) 方法：基于该 schema 创建一个指定类型 type 的样式标记，可以通过第二个（可选）参数 attrs 为样式标记设置 attributes 属性值
• nodeFromJSON(jsonObj) 方法：将传入的 JSON 对象 jsonObj 反序列化为一个 node 节点。
  提示

  该方法 this 已经重绑定为当前对象（即当前的 schema 数据结构约束对象）

  传入的 JSON 对象 jsonObj 是由相应的 Node.toJSON() 方法所生成

• markFromJSON(jsonObj) 方法：将传入的 JSON 对象 jsonObj 反序列化为一个 mark 样式标记。
  提示

  该方法 this 已经重绑定为当前对象（即当前的 schema 数据结构约束对象）

  传入的 JSON 对象 jsonObj 是由相应的 Mark.toJSON() 方法所生成

该类的实例化对象在 ProseMirror 不同模块中都需要使用，由于它是编辑器内容的基础。

可以调用 Node 类的静态方法 Node.fromJSON(schema, json) 来解析 JSON 对象获取一个 node 对象。该方法的各参数的说明如下：

• 第一个参数 schema 是一个对象，表示该节点的数据结构（约束规则）
• 第二个参数 json 是 JSON 对象，它包含了节点的内容

后面的章节列出了 node 节点对象所包含的一些属性和方法

Fragment 类的实例化对象用于表示一些节点的集合（数组形式），它们一般作为某个目标节点的属性 content 的值，即用来描述目标节点包含哪些内容/子节点。

该类提供了一些静态方法和属性进行实例化：

• static Fragment.fromJSON(schema, value) 静态方法：基于传入的 JSON 对象进行反序列化，获取一个 fragment 对象。第一个参数 schema 是数据约束对象，第二个（可选）参数 value 是 JSON 对象（一般是通过 fragment.toJSON() 生成的）
• static Fragment.fromArray(array) 静态方法：基于传入的一组节点 array（其元素是一系列节点对象 node），创建一个 fragment 对象。
  相邻的文本节点可自动整合

  如果入参的数组 array 中相邻的元素是 text 文本节点，而且具有相同的样式标记，那么它们会被连接整合为一个 text 文本节点

• static Fragment.from(nodes) 静态方法：这是一个更通用的方法，入参 nodes 可以多种类型（可以是一个 fragment 对象，也可以是一个 node 节点，也可以是一个由一系列 node 节点构成的数组），根据参数创建一个相应的 fragment 对象。如果入参是 null 则返回一个空的 fragment 对象
• static Fragment.empty 静态属性：获取一个空的 fragment 对象，表示没有包含任何节点
  空片段

  这不是一个方法，而是 class Fragment 类的一个属性，以避免创建一大堆空的片段，每次通过该属性访问的都是同一个 fragment 对象（它指向同一个内存地址），以便复用

class Fragment 实例化得到 fragment 对象，以下称作「片段」

后面的章节列出了 fragment 片段对象包含的一些属性和方法

// refer to https://github.com/ProseMirror/website/blob/master/example/footnote/index.js#L129-L133
// fragment.findDiffStart(otherFragment) 从左往右找出两个片段之间的差异的起始位置（遵循 index schema 规则）
let start = node.content.findDiffStart(state.doc.content);

// 如果两个片段存在差异，则继续执行后续操作
if (start != null) {
  // fragment.findDiffEnd(otherFragment) 从左往右找出两个片段之间的差异的结束位置（遵循 index schema 规则）
  const endResult = node.content.findDiffEnd(state.doc.content)
  if (endResult) {
    let {a: endA, b: endB} = endResult
    // 为了提高查找的效率，寻找差异时起始位置是从左往右查找，而结束位置是从右往左查找
    // 但是在特定的场景下，可能存在倒置的情况，即 start 比 end 更大，则需要进行校正
    // 具体可以参考 https://discuss.prosemirror.net/t/overlap-handling-of-finddiffstart-and-finddiffend/2856/4
    let overlap = start - Math.min(endA, endB)
    if (overlap > 0) { endA += overlap; endB += overlap }
  }
}

Slice 类的实例化对象用于表示文档中的一个片段，它与 fragment 对象类似，区别在于它所包含的前后两端的节点可能是不完整的（只包含部分内容）

class Slice 实例化得到 slice 对象，以下称作「切片」，它使用一个 fragment 对象和两个数字openStart 和 openEnd 来表示

开放深度

可以将 slice 片段理解为 fragment 片段的「进阶」版本，除了可以描述完整的片段对象，还可以描述不完整的片段。它使用两个数字来表示片段两端的开放深度 Open depth ，即片段两端的不完整节点（相对于片段）的深度（不完整的节点位于该 fragment 片段中的嵌套的最深的值）

假如 ProseMirror 文档所在页面渲染出的 HTML 结构如下，由一个标题节点内嵌有一个段落节点构成，内容为 abc

如果按照以下示意图对文档进行裁剪

则可以得到 <p>ab，则该切片（所操作）的目标片段 fragment 是 heading 标题节点的内容，由于在切片的开头包含完整的段落节点，所以 openStart=0 并无开放节点；而在切片的末端段落节点并不完整/存在开放节点，（段落节点在该 fragment 片段中是第一层节点）所以 openEnd=1

如果按照以下示意图对文档进行裁剪

则可以得到 <h1><p>ab，则该切片（所操作）的目标片段 fragment 是整个文档的内容，由于在切片的开头包含完整的节点，所以 openStart=0 并无开放节点；而在切片的末端段落节点并不完整/存在开放节点，（段落节点在该 fragment 片段中是嵌套在第二层的节点）所以 openEnd=2

如果按照以下示意图对文档进行裁剪

则可以得到 <p>ab</p>，则该切片（所操作）的目标片段 fragment 是 heading 标题节点的内容，由于在切片的开头和结尾都包含完整的节点（段落节点），所以两个数值为 openStart=0 和 openEnd=0，表示两端并无开放节点

一般以编程方式 programmatic 操作文档都是生成片段（具有完整的节点），而用户通过视图 view 操作文档则一般生成切片（具有不完整的节点），例如框选文档内容（选中节点的部分）进行复制粘贴时

通过 new Slice(content, openStart, openEnd) 实例化得到一个 slice 切片对象

相关参数的具体说明如下：

• 第一个参数 content 是一个 fragment 对象，可以将切片理解为对哪一个节点的内容 content（即 fragment 对象）进行操作/裁剪，也可以理解为通过自动补全开始或结束的标签来构建出完整的 fragment 对象
• 第二个参数 openStart 是切片左侧开放节点（相对于片段）的嵌套深度
• 第三个参数 openEnd 是切片右侧开放节点（相对于片段）的嵌套深度

此外 class Slice 还提供了一些静态方法和属性可以进行实例化：

• static Slice.fromJSON(schema, json) 静态方法：基于传入的 JSON 对象进行反序列化，获取一个 slice 对象。第一个参数 schema 是数据约束对象，第二个（可选）参数 json 是 JSON 对象（一般是通过 slice.toJSON() 生成的）
• static Slice.maxOpen(fragment, openIsolating?) 静态方法：基于给定的 fragment 片段创建一个 slice 对象，而且让两端开放节点的「深度」达到最大。第二个（可选）参数 openIsolating 是一个布尔值，用以表示是否让 isolating 独立隔离的节点也可以开放（默认为 true，即可以对该节点进行部分裁剪）
  最大开放深度

  该方法可以理解为从 fragment 片段的第一个节点和最后一个节点里面嵌套最深的后代节点截取内容

• static Slice.empty 静态属性：获取一个空的 slice 切片对象，表示没有包含任何节点
  空切片

  这不是一个方法，而是 class Slice 类的一个属性，以避免创建一大堆空的切片，每次通过该属性访问的都是同一个 slice 对象（它指向同一个内存地址），以便复用

还可以使用节点的方法 node.slice() 对该节点的内容进行裁剪，生成一个 slice 对象

slice 切片对象包含一些属性和方法：

• content 属性：一个 fragment 对象，该切片是基于哪个片段裁剪而得的
  说明

  基于 slice 构建的 fragment 是自包含的，即 fragment 的内容和 slice 的内容相同，只是 slice 可能表示该 fragment 的左（和/或）右的标签不完整

  

  例如上图是基于选区构建的 slice，然后再通过方法 slice.content 获取对应的 fragment 并将其打印出来，可以看到该 fragment 包含两个 paragraph 节点，但是其内容都分别只有一个字母（因为每个段落都只选中的一个字母），这和文档里的完整段落节点不同

• openStart 属性：一个数字，表示该片段开始/左侧的开放节点（相对于片段）的嵌套深度
• openEnd 属性：一个数字，表示该片段结束/右侧的开放节点（相对于片段）的嵌套深度
• size 属性：一个数字，表示切片的大小
  切片大小

  切片大小是指如果将该它插入文档后，文档增加多少个 token 值

  该值遵循 index schema 规则

  实际上是通过 fragment 片段大小和开放深度计算出来的 this.content.size - this.openStart - this.openEnd

• eq(otherSlice) 方法：返回一个布尔值，以表示给定的切片 otherSlice 与当前切片是否相同
• toJSON() 方法：将该切片序列化为一个 JSON 对象，它包含切片的详细信息

文档的每个位置可以用一个数字（整数）来表示，这样就可以将文档描述为扁平化的线性结构。该数字是遵循 ProseMirror 自定义的 index schema 规则计算出来的，这样在 ProseMirror 核心模块的代码中可以通过简单的一个数字就对文档进行精确定位。

但是数字所包含的信息太有限了，所以 ProseMirror 提供了 ResolvedPos 类，它的实例化对象表示对一个特定的 position 位置的解析结果，包含更多的描述性信息，例如该 position 所在的节点（以及祖先节点）等，以及提供了一些实用的方法

class ResolvedPos 实例化得到 resolvedPos 对象，以下称为「位置解析结果」

可以通过调用节点的方法 node.resolve(pos) 对给定的位置进行解析，得到一个 resolvedPos 对象

参数 pos 是一个数字，遵循 index schema 规则，表示文档的位置，即相对于节点 node 片段/内容的开头位置的偏移量

也可以直接解构选区对象，例如 let {$from, $to} = state.selection 直接得到 resolvedPos 对象

resolvedPos 位置解析结果包含一些属性和方法：

• doc 属性：该位置的根节点
  根节点

  对于使用节点的方法 node.resolve(pos) 获取的位置解析结果对象，则该属性是指节点 node

  对于通过 state.doc.resolve(pos) 获取的位置解析结果对象，则该属性就是指文档的根节点 doc

  如果通过解构选区（例如 selection.$from）获取的位置解析结果对象，则该属性也是指文档的根节点 doc

• parent 属性：该位置的父节点
  文本节点

  需要注意如果所解析的位置在文本内容里，但是文本节点并不能作为父节点

  因为文本节点在 ProseMirror 模型中是扁平的，它们是没有 content 属性，它不能视作一个具有深度的层级

  所以当所解析的位置在文本内容中，则它的父节点是指包含该文本节点的节点（例如段落节点）

• depth 属性：一个数字，表示该位置的父节点相对于「根节点」的深度
  文本节点

  需要注意如果所解析的位置在文本内容里，但是文本节点并不能作为父节点来考虑（因为文本节点在 ProseMirror 模型中是扁平的，它们是没有 content 属性，它不能视作一个具有深度的层级）

  所以当所解析的位置在文本内容中，则深度信息所属的节点是包含该文本内容的节点（例如段落节点）

  
  该属性相当于把扁平的线性位置 pos 信息转换为树形的层级 depth 信息
  例如在顶级段落节点的文本内容上的位置，基于文档根节点 doc 进行解析，则该位置的属性 depth 是 1（表示该段落节点相对于根节点 doc 的层级为 1）
  

  

  
  

  

• pos 属性：一个数字，表示所解析的位置相对于「根节点」的偏移量
  提示

  如果该位置解析结果是通过方法 node.resolve(pos) 获得的，则该属性就和参数 pos 一致

  它们都是表示解析位置相对于节点 node 片段/内容的开头位置的偏移量，遵循 index schema 规则

  开头位置

  对于以 HTML 展示文档数据的情况而言，节点的开头位置就是起始标签前的位置

  而节点的片段/内容的开头位置即起始标签后的位置（根据 index schema 规则，标签的大小是 1 个 token）

• parentOffset 属性：一个数值，表示该位置相对于父节点的偏移量
  偏移量

  相对于直接父节点偏移量是指解析位置相对于其所在的父节点节点的片段/内容的开头的偏移量，遵循 index schema 规则（根据该规则，如果所解析的位置在文本内容里，则按照字符数量计算偏移量）

  开头位置

  对于以 HTML 展示文档数据的情况而言，节点的开头位置就是起始标签前的位置

  而节点的片段/内容的开头位置即起始标签后的位置（根据 index schema 规则，标签的大小是 1 个 token）

• textOffset 属性：一个数值，如果所解析的位置在文本内容中，就表示该位置距离该文本节点开头的偏移量（字符数量）
  节点交界处

  如果所解析的位置在两个节点的交界处（即使前后两个都是文本节点），则会返回 0

  

  也就是说在文本节点的末尾，该属性值为 0（因为这种情况也算是节点的交界处）

  

• node(depth?) 方法：获取指定层级深度 depth 的祖先节点
  层级深度

  在 ProseMirror 中节点通过嵌套形成文档树，所以节点之间存在层级关系

  该方法的参数 depth 就是表示相对于「根节点」而言的内嵌层级

  根节点

  对于使用节点的方法 node.resolve(pos) 获取的位置解析结果对象，则「根节点」是该节点 node

  对于通过 state.doc.resolve(pos) 或通过解构选区（例如 selection.$from）获取的位置解析结果对象，则「根节点」就是指文档的根节点 doc

  
  例如 depth=0 就表示根节点
  

  

  
  参数 depth 是可选的
  • 如果省略（即传入 undefined）或传入 null，则在内部会采用默认值 this.depth（即该位置解析结果的父节点相对于「根节点」的深度），那么该方法获取到的就是父节点（与属性 resolvedPos.parent 的值一样）
    

    

  • 如果传入的是负数，则内部会采用 this.depth+depth（即该位置解析结果的父节点相对于「根节点」的深度值与参数 depth 相加），相当于基于当前位置的深度信息往上回溯 depth 层，获取内嵌层级更小的祖先节点
    

    

  • 如果传入的值超过了该位置（父节点）所在的深度，则返回 undefined（对于参数为负值的情况也类似）
• index(depth?) 方法：以层级深度 depth 的祖先节点作为容器，它包含一系列子节点，则该方法返回的值表示该位置所属的那个子节点（在同级节点所构成的数组中）的索引值
  索引值

  索引值计数是从 0 开始的

  
  例如 depth=0 就表示以根节点为容器，它所包含的一系列子节点中，该位置所属的子节点的索引值
  参数 depth 是可选的
  • 如果省略（即传入 undefined）或传入 null，则在内部会采用默认值 this.depth（即该位置解析结果的父节点相对于「根节点」的深度），那么该方法以父节点作为容器
    

    

  • 如果传入的是负数，则内部会采用 this.depth+depth（即该位置解析结果的父节点相对于「根节点」的深度值与参数 depth 相加），相当于基于当前位置的深度值获取内嵌层级更小的祖先节点作为容器
  • 如果传入的值超过了该位置（父节点）所在的深度，则返回 undefined（对于参数为负值的情况也类似）
  节点交界处

  如果所解析的位置在两个节点的交界处，则所返回索引值是用于表示后一个节点

  

  也就是说在文本节点的末尾，该方法的返回值依然表示下一个文本节点（假设后方存在一个虚拟的文本节点）

  

  需要注意 depth 的值决定了所选择的容器是哪一个，即使光标的位置在文本节点的尾部，但是对于段落节点而言所解析的位置依然在其内部

  

• indexAfter(depth⁠?) 方法：它和方法 index() 类似，都是以层级深度 depth 的祖先节点作为容器，它包含一系列子节点，则该方法返回的值表示该位置所属的那个子节点的后一个相邻节点（在同级节点所构成的数组中）的索引值
  节点交界处

  如果所解析的位置在两个节点的交界处，则方法 resolvedPos.index() 所返回索引值就是用于表示后一个节点，所以它和方法 resolvedPos.indexAfter() 返回的值一样

  

  
  参数 depth 是可选的，更多介绍参照前一个方法 index()
• start(depth?) 方法：获取指定层级深度 depth 的祖先节点的内容的开头相对于「根节点」的偏移量
  节点内容的开头位置

  偏移量遵循根据 index schema 规则

  对于以 HTML 展示文档数据的情况而言，节点的片段/内容的开头位置即起始标签后的位置，根据 index schema 规则，标签的大小是 1 个 token

  
  参数 depth 是可选的
  • 如果省略（即传入 undefined）或传入 null，则在内部会采用默认值 this.depth （即该位置解析结果的父节点相对于「根节点」的深度），那么该方法获取到就是父节点的内容的开头位置相对于根节点的偏移量
  • 如果传入的是负数，则内部会采用 this.depth+depth（即该位置解析结果的父节点相对于「根节点」的深度值与参数 depth 相加），相当于基于当前位置的深度值信息往上回溯 depth 层，获取内嵌层级更小的祖先节点的内容的开头的偏移量
• end(depth?) 方法：它和方法 start() 类似，获取指定层级深度 depth 的祖先节点的内容的结尾相对于「根节点」的偏移量
  节点内容的结尾位置

  偏移量遵循根据 index schema 规则

  对于以 HTML 展示文档数据的情况而言，节点的片段/内容的开头位置即结束标签前的位置

  
  参数 depth 是可选的，更多介绍参照前一个方法 start()
  

  

• before(depth⁠?) 方法：获取指定层级深度 depth 的祖先节点的开头相对于「根节点」的偏移量
  节点的开头位置

  偏移量遵循根据 index schema 规则

  对于以 HTML 展示文档数据的情况而言，节点的开头位置即起始标签前的位置

  
  参数 depth 是可选的
  • 如果省略（即传入 undefined）或传入 null，则在内部会采用默认值 this.depth （即该位置解析结果的父节点相对于「根节点」的深度），那么该方法获取到就是父节点的开头位置相对于根节点的偏移量
  • 如果传入的是负数，则内部会采用 this.depth+depth（即该位置解析结果的父节点相对于「根节点」的深度值与参数 depth 相加），相当于基于当前位置的深度值信息往上回溯 depth 层，获取内嵌层级更小的祖先节点的开头的偏移量
  特殊的深度值

  如果参数 depth 为当前解析位置的深度值加上一（即 this.depth+1），则该方法返回的是当前位置相对于「根节点」的偏移量，和属性 resolvedPos.pos 值一样

• after(depth?) 方法：获取指定层级深度 depth 的祖先节点的结尾相对于「根节点」的偏移量
  节点的结尾位置

  偏移量遵循根据 index schema 规则

  对于以 HTML 展示文档数据的情况而言，节点的结尾位置即结束标签后的位置

  
  参数 depth 是可选的，更多介绍参照前一个方法 before()
  特殊的深度值

  如果参数 depth 为当前解析位置的深度值加上一（即 this.depth+1），则该方法返回的是当前位置相对于「根节点」的偏移量，和属性 resolvedPos.pos 值一样

  
  

  

• nodeAfter 属性：所解析位置的后面的节点。如果后面没有节点，则返回 null。如果所解析的位置在文本节点里，则返回该位置之后的文本内容
• nodeBefore 属性：所解析位置的前面的节点。如果前面没有节点，则返回 null。如果所解析的位置在文本节点里，则返回该位置之前的文本内容
• posAtIndex(index, depth?) 方法：以层级深度 depth 的祖先节点作为容器，它包含一系列子节点，该方法获取索引值为 index 的子节点的开头位置（相对于「根节点」）的偏移量
  偏移量

  偏移量遵循 index schema 规则

  开头位置

  对于文本节点，则是第一个字符前面的位置

  而对于其他节点，如果以 HTML 展示文档数据的情况而言，节点的开头位置就是起始标签前的位置

  
  参数 depth 是可选的
  • 如果省略（即传入 undefined）或传入 null，则在内部会采用默认值 this.depth（即该位置解析结果的父节点相对于「根节点」的深度），则以该位置的父节点作为容器，获取指定索引值 index 的子节点的开头的偏移量
    

    

  • 如果传入的是负数，则内部会采用 this.depth+depth（即该位置解析结果所在的节点相对于「根节点」的深度值与参数 depth 相加），相当于基于当前位置的深度值获取内嵌层级更小的祖先节点作为容器
• marks() 方法：获取该位置所具有的样式标记，返回一个数组（其中元素是一系列的 mark 对象）
  如果所解析的位置是在一个内容非空的节点的开始位置，则返回该节点所具有的样式标记
  如果所解析的位置在一个节点的末尾，则会根据样式标记的配置属性 inclusive 来判断是否将其包含到所返回的数组中
• marksAcross($end) 方法：获取当前位置之后应该使用的样式标记，返回一个数组（其中元素是一系列的 mark 对象）
  这个方法与上一个方法 marks() 类似，也是返回样式标记，但适用场景不同，该方法是用于获取执行完删除操作后（光标所在）位置的样式标记情况
  提示

  通过鼠标点击或键盘方向键移动光标，所对应位置的样式标记（更准确而言应该是如果继续键入内容，所需应用的样式标记）是由该位置前方内容所具有的样式标记决定的

  而执行完删除操作后，光标所对应位置的样式标记是由删除内容所具有的样式标记决定，以确保文本格式的连续性，让用户体验更符合直觉

  关于该方法所针对场景的具体介绍可以参考这个 Issue

  
  该方法会排除配置属性 inclusive 为 false 的样式标记，以及没有出现在 $end 位置（一般是选区的 upper boundary 上界 $to）样式标记
  如果该位置是在它的父级节点的结束的位置，或者它的父级节点不是一个 textblock，则会返回 null（不会有任何样式标记被保留）
• sharedDepth(anotherPos) 方法：返回的是一个数值，表示当前位置与另一个给定位置 anotherPos（一个数值，表示文档中的位置）所具有的最近的共同祖先节点的层级深度
• blockRange(anotherResolvedPos⁠?, pred⁠?) 方法：基于当前位置和给定位置创建一个 nodeRange 节点范围对象，它包含这里两个位置；如果无法创建，则返回 null
  注意

  正如名称 blockRange 通过该方法创建的 nodeRange 所包含节点是 block 块级节点

  如果需要创建一个可以包含 inline 内联节点的 nodeRange，可以通过实例化 class NodeRange 来实现

  有一个与之相关的帖子

  NodeRange 节点范围对象

  上面所说的 nodeRange 对象（以下称为节点内容范围）是 class NodeRange 的实例化，用于表示一系列同级的相邻节点

  除了使用 resolvedPos.blockRange() 方法构建一个节点范围对象，还可以通过方法 new NodeRange($from, $to, depth) 进行实例化

  各参数的具体说明如下：

  • 参数 $from 和 $to 都是 ResolvedPos 位置解析结果对象（它们一般基于同一个根节点获得），分别表示该节点内容范围的开始和结束位置
  • 参数 depth 是一个数值，表示该节点范围对象所指向的节点（相对于根节点）的层级深度

  提示

  官方文档中的一段描述

  $from and $to should point into the same node until at least the given depth, since a node range denotes an adjacent set of nodes in a single parent node.

  其意思是分别从 $from 或 $to 的「根节点」（两者一般基于同一个根节点获得）向下 depth 层寻找该范围所指向的节点的过程中，需要确保至少从 0 到 depth 每一个层级的节点都是包含这两个位置的，这样才可以保证通过 $from 或 $to 所定义的范围是指向一个节点

  例如文档结构如下

  html

  <ul>
    <li>
      <p>abc</p>
    </li>
    <li>
      <p>123</p>
      <p>456</p>
    </li>
  </ul>
  

  如果 $from 在 1 后面位置， $to 在 4 后面位置，在构造一个 NodeRange 的时候，参数 depth 最大只能是第二个 li 节点所对应的深度（或者更浅），因为如果再深的话 $from 和 $to 就没有共同的父级节点，就无法构建一个 NodeRange

  💡 而 $from 和 $to 两个位置本身的深度可能不同，且一般都大于 NodeRange 构建函数的参数 depth，这样才能保证可以从「根节点」向下 depth 层（有足够的「下探」深度）能寻找到共享的节点

  nodeRange 对象包含一些属性：

  • $from 和 $to 属性：都是 ResolvedPos 位置解析结果对象，表示该范围的开始和结束位置
  • parent 属性：该范围所指向的节点，即以该节点作为容器，包含 $from 和 $to 两个位置
  • depth 属性：一个数值，表示该范围所指向的节点（相对于根节点）的层级深度
  • start 属性：以该范围所指向的节点作为容器，它包含一系列的子节点，则该属性表示开头位置 $from 所在子节点的开头（相对于根节点）的偏移量
  • end 属性：以该范围所指向的节点作为容器，它包含一系列的子节点，则该属性表示结尾位置 $to 所在子节点的结尾（相对于根节点）的偏移量
    节点的开头与结尾

    偏移量遵循根据 index schema 规则

    对于以 HTML 展示文档数据的情况而言，节点的开头位置即起始标签前的位置；节点的结尾位置即结束标签后的位置

    而对于文本节点，则节点的开头位置就是第一个字符前面的位置；结尾位置就是最后一个字符后面的位置

    
    

    

  • startIndex 属性：它是属性 start 所指的节点（在同级节点构成的数组中）的索引值
  • endIndex 属性：它是属性 end 所指的节点（在同级节点构成的数组中）的索引值（ ⚠️ 注意所指的节点是 $end 位置后面的那个子节点）
    注意

    以范围所指向的节点作为容器，它包含一系列的子节点，则属性 startIndex 索引值所指的子节点，它一般就是包含 $from 位置的那个子节点

    但是属性 endIndex 所指的子节点，一般并不是包含 $end 位置的那个子节点

    这是由于属性 end 表示子节点的结尾的偏移量，对于以 HTML 展示文档数据的情况而言，节点的结尾位置即结束标签后的位置，该位置已经属于后一个兄弟节点

    所以属性 endIndex 所指的子节点，一般是指 $end 位置后面的那个子节点

    

  
  第二个（可选）参数 pred 是你可以传递一个指示函数，来决定该祖先节点是否可接受（如果较近的祖先节点不可接受，则继续沿着文档树向上回溯，返回所找到的最近的符合条件的祖先节点，直至文档的根节点为止）
  提示

  如果可以通过调用位置解析结果的方法 resolvedPos.blockRange(otherResolvedPos) 生成该对象，只需要提供两个 ResolvedPos 对象即可，不需要指定共享的节点（相对于根节点）的深度

  ProseMirror 会自动沿着文档树向上回溯，寻找最靠近这两个位置的共享祖先节点

  该方法的源码如下

  ts

  blockRange(other: ResolvedPos = this, pred?: (node: Node) => boolean): NodeRange | null {
    if (other.pos < this.pos) return other.blockRange(this)
    for (let d = this.depth - (this.parent.inlineContent || this.pos == other.pos ? 1 : 0); d >= 0; d--)
      if (other.pos <= this.end(d) && (!pred || pred(this.node(d))))
        return new NodeRange(this, other, d)
    return null
  }
  

  可知该方法选择位于前方的位置（即偏移量较小的 ResolvedPos 对象）的深度作为基础，往上回溯寻找共享的祖先节点

  在初始化循环参数时，深度值 let d = this.depth - (this.parent.inlineContent || this.pos == other.pos ? 1 : 0) 会基于前方位置的父节点的内容类型是否为 inlineContent 来决定是否从父节点还是祖父节点开始迭代

  当父节点所包含的子节点为 inline 内联类型，则跳过父节点（即使它可能就是最近两个位置的共享节点），从祖父节点开始寻找两个位置共享的节点

  

• sameParent(anotherResolvedPos⁠) 方法：返回一个布尔值，以表示当前位置与给定的其他位置 anotherResolvedPos⁠（它也是位置解析结果对象）是否位于相同的父节点
  注意

  根据该方法的源码

  ts

  sameParent(other: ResolvedPos): boolean {
    return this.pos - this.parentOffset == other.pos - other.parentOffset
  }
  

  判断的依据是 this.pos-this.parentOffset 差值是否相等

  所以隐含的前提是这两个位置解析结果对象的根节点需要是相同的

  一般使用 state.doc.resolve(pos) 基于文档的根节点 doc 得到 resolvedPos 对象；或直接解构选区对象，例如 let {$from, $to} = state.selection 直接得到 resolvedPos 对象，其根节点也是文档的根节点 doc，所以一般都满足上述隐含条件

• max(anotherResolvedPos⁠) 方法：比较当前位置与给定的另一个位置 anotherResolvedPos⁠ 的（相对于根节点）偏移量，返回较大的那一个 ResolvedPos 对象
  注意

  隐含的前提是这两个位置解析结果对象的根节点需要是相同的

• min(anotherResolvedPos⁠) 方法：比较当前位置与给定的另一个位置 anotherResolvedPos⁠ 的（相对于根节点）偏移量，返回较小的那一个 ResolvedPos 对象
  注意

  隐含的前提是这两个位置解析结果对象的根节点需要是相同的

该类的实例化对象用于为节点对象添加样式或额外信息的，例如为节点标记上 emphasized 强调。

ProseMirror 在创建 schema 数据结构约束对象时（根据配置参数）实例化生成一系列的 mark 对象，以下称作「样式标记」

const markSchema = new Schema({
  nodes: {
    doc: {content: "block+"},
    // 段落节点支持所有 mark 样式标记添加到它的内容/后代节点上
    paragraph: {group: "block", content: "text*", marks: "_"},
    // 段落节点在它的内容/后代节点上不允许使用任何样式标记
    heading: {group: "block", content: "text*", marks: ""},
    text: {inline: true}
  },
  // 声明在文档中需要使用的一系列 mark 样式标记
  marks: {
    strong: {},
    em: {}
  }
})

mark 样式标记对象包含一些属性和方法：

• type 属性：表示该样式标记类型，它是一个 markType 对象
  markType

  上面所说的 markType 对象是 class MarkType 的实例化，它是编辑器在使用 new Schema() 实例化数据约束对象时，根据传入的参数 marks（该参数值是一个对象，每一个属性的属性名称是样式标记名称，相应的属性值是该样式标记的配置对象），创建一系列相应的 markType 实例对象，它们包含了不同样式标记的信息，例如名称。

  这些 markType 对象可以用于标记/表示相应的样式标记 mark 的类型。

  markType 对象包含一些属性和方法：

  • name 属性：一个字符串，表示该类型的样式标记的名称
  • schema 属性：一个 schema 对象，表示该类型的样式表季在哪个 schema 对象中进行定义的
  • spec 属性：一个对象（它需要符合一种 TypeScript interface MarkSpec），描述该类型的样式标记可接受的配置参数
    MarkSpec

    TypeScript interface MarkSpec 描述该类型的样式标记可接受哪些配置参数

    实际在哪里定义

    其实该 interface 所约束的是在实例化 schema 时，在配置对象中，针对该类型的样式标记可以设置哪些属性

    • attrs（可选）属性：一个对象，设置该样式标记所拥有的 attributes 以添加额外的信息
      添加额外信息

      在实例化 schema 时，可以在各样式标记的 attrs 属性中设置额外的信息

      其属性值需要是一个「纯对象」 plain object（可以进行 JSON 反序列化的对象），其中该对象的每一个选项都可以通过（可选）属性 default 设置默认值

    • inclusive（可选）属性：布尔值（默认值为 true），表示光标位于该样式标记结尾处，该样式标记是否需要 active 激活
      激活样式标记

      样式标记 active 激活是指对未来输入的内容也应用上该样式标记

      例如对于文本节点设置了该样式标记，如果光标位于文本节点最后，继续输入的文字是否依然采用该样式标记

      如果光标置于样式标记的开头时，而该样式标记所应用节点同时位于其父节点的开头，则是否激活也同样受该属性控制

    • excludes（可选）属性：字符串，用于设置当前样式标记不能与哪些样式标记共存。可以是样式标记类型名称或组别名称，如果要设置多个名称则用空格分隔。
      不可共存的样式标记

      默认排除的是同类型的样式标记，即该样式标记应用到节点上时，如果节点已经有同类型的样式标记（可能所具有的 attrs 是不同的），则会被覆盖替换

      可以使用 _ 下划线来表示不能与其他样式标记共存；可以使用空字符，或任何字符串（非样式标记类型名称或组别名称）来表示可以与任何其他样式标记共存（对于同类型的样式标记也可以共存，只要 attrs 是不同的即可）

      另外该属性会影响方法 mark.addToSet(set) 的执行结果，该方法将当前样式标记对象 mark 添加指定集合 set（该集合包含一系列的样式标记对象）中。如果在当前样式标记的属性 excludes 所指明的不能共存的类型，在集合中出现（但反过来，集合中的样式标记对象的 excludes 属性并没有指明当前样式标记类型），则表示可以将当前样式标记添加到集合中，但是要先将这些不相容的样式标记对象清除，再将当前样式标记对象添加到集合中；如果集合所包含的样式标记中，它们的属性 excludes 对当前样式标记类型进行了排除（但反过来，当前样式标记没有指明不能与之共存），则当前样式标记对象并不能添加到集合中

    • group（可选）属性：字符串，以设置该样式标记所属的组别。可以指定多个组别，组别名称之间用空格分隔。
    • spanning（可选）属性：布尔值（默认值为 true），以设置该样式标记序列化为 HTML 时是否可以跨越多个相邻的节点，将该样式标记应用到这些节点上。
    • toDOM（可选）属性：一个函数 fn(mark, inline) 以定义该样式标记序列化为 HTML 的默认方式
      函数 fn(mark, inline) 第一个参数 mark 是该样式标记实例化对象，第二个参数 inline 是一个布尔值以表示该样式标记的内容（节点）是否为 inline 内联类型（与之相对应的是 block 块级类型）
      该函数的返回值需要符合一种 TypeScript type DOMOutputSpec，具体介绍可查看 node.toDOM() 方法的相关介绍
      如果返回值是数组形式，而且在它的（包括内嵌数组）元素中有数字 0（称为 hole 占位符），则意味着该样式标记所对应的 DOM 元素可以插入内容/子节点（在 hole 的位置）；否则会将该样式标记的内容/子节点追加 append 到（该样式标记所对应/修饰的）Node 节点里面 ❓
    • parseDOM（可选）属性：一个数组，包含了将 DOM 元素解析为样式标记的一些规则。
      HTML 反序列化为样式标记

      该属性值是一个数组，其中每个元素都是一个对象（需要符合一种 TypeScript type ParseRule）以表示一种解析规则。

      ParseRule

      TypeScript type ParseRule=TagParseRule | StyleParseRule 它可以是两种接口类型之一，分别表示基于 HTML 标签名称或行内样式 inline style 将 DOM 解析为相应类型的样式标记的规则

      💡 关于 TypeScript interface TagParseRule 的具体介绍可查看 node.parseDOM() 方法的相关部分

      StyleParseRule

      TypeScript interface StyleParseRule（它继承了另一个 TypeScript interface GenericParseRule，具体介绍可查看 node.parseDOM() 方法的相关部分）描述了基于行内样式 inline style 将 DOM 元素解析为相应类型的样式标记的规则

      • style（可选）属性：一个字符串，它是一个 style property 样式属性名称，则所匹配 DOM 元素需要具有该 inline style property 行内样式（ 💡 字符串也可以采用 "property=value" 的形式，以指定行内样式属性需要具有特定的值， ⚠️ 注意属性名称和值之间用 = 等号来连接）。所匹配成功的 DOM 元素会解析为样式标记 Mark（而不是节点 node，所以该属性只能在 marks 的 parseDOM 中设置）。
        js

        const schema = new Schema({
          marks: {
              em: {
                // 为「强调样式」设置 3 个 DOM 解析规则
                parseDOM: [
                  // 将含有内联样式 style="font-style:italic"（注意以下使用 = 等号而不是 : 冒号来连接样式属性和值）的 DOM 元素转换为该类型的样式标记
                  {style: "font-style=italic"}
                ],
              },
          }
        })
        

        提示

        如果需要基于 DOM 元素的 property 或 attribute 设置构建更复杂的匹配条件，可以通过 getAttrs 属性来设置

      • clearMark（可选）属性：一个函数 fn(mark: Mark)（参数 mark 是在 pending marks 待添加的样式标记实例），返回值是一个布尔值，表示是否清除 active mark 激活的/待添加的样式标记
        解释

        该属性设置为 false 可以清除该样式标记，可用于标准化一些原本语义混乱的 HTML，以保证解析所得到的文档的语义一致性

        例如一段 HTML <i style="font-style=normal">abc</i>，如果基于 prosemirror-schema-basic 模块的 schema 构建编辑器，则这一段 HTML 可以匹配多个解析规则，首先基于标签名称匹配到的是 em 强调样式标记的规则，则 pending marks 待添加的样式标记中就包含了 em mark；然后又基于内联样式匹配到另一条规则

        如果希望在包含 font-style=normal 内联样式标记的文本上清除 em 强调样式标记，则可以为 em mark 添加一条解析规则（基于内联样式来匹配），并在其中设置 clearMark 属性（将其函数 fn(mark)的返回值）设置为 true

      • getAttrs（可选）属性：一个函数 fn(style: string)，它的返回值有多种类型，对应于有不同的作用。
        更精细地设置 attributes

        属性 getAttrs 是一个函数，用于构建更精细、更复杂的条件，可以基于 attributes 来匹配 DOM 元素，或者为转换而得的 node（或 mark）设置 attribute。

        该函数的入参是 string 即当前所匹配的 DOM 元素所拥有对应内联样式的值（例如在 style 属性所设置的样式 property 是 font-weight，而解析的 HTML 元素的相关内联样式是 "font-weight: 900"，则该函数的的入参就是 900）

        该函数的返回值可以有多用类型：

        • 可以返回一个对象，表示转换生成的 node 或 mark 所拥有的 attribute
        • 可以返回 null 或 undefined，表示转换生成的 node 或 mark 没有 attribute
        • 可以返回 false，表示该 DOM 元素无法满足规则，即无法匹配
    • 其他属性，还可以为节点添加任意属性（属性的名称是字符串，属性值是任意类型）
      添加额外信息

      还可以为节点添加任意属性，以便为节点添加额外的信息。

      然后就可以通过 mark.type.spec.xxx 来获取该信息

  • create(attrs?) 方法：创建一个该类型的样式标记实例
    （可选）参数 attrs（默认值是 null）是一个对象，用于设置样式标记的 attributes。如果该类型的样式标记没有必须要指派的 attribute 属性，则可以传递 null 表示使用默认值来作为该节点的各种 attribute 的值。
  • removeFromSet(set) 方法：从集合 set（一个数组，包含一系列的 mark 样式标记对象）中移除该类型的样式标记实例。如果 set 原本不是一个空数组，则返回一个新数组（它剔除了该类型的样式标记）；如果 set 本来是一个空数组，则直接返回该数组
  • isInSet(set) 方法：返回一个布尔值，以表示集合 set （一个数组，包含一系列的 mark 样式标记对象）中是否包含该类型的样式标记实例
  • excludes(otherMark) 方法：返回一个布尔值，以表示该类型的样式标记是否不能与给定的 otherMark（一个 mark 对象）共存（即该类型的样式标记的 markType.spec.excludes 字符串中包含了 otherMark 名称）
• attrs 属性：一个对象，表示该样式标记拥有的 attributes
• addToSet(set) 方法：将当前的样式标记添加到给定的集合 set （一个数组，包含一系列的 mark 样式标记对象）中。返回一个新的集合（包含了该样式标记）。
  如果在当前样式标记的属性 markType.spec.excludes 所指明的不能共存的类型，在集合中出现（但反过来，集合中的样式标记对象的 excludes 属性并没有指明当前样式标记类型），则表示可以将当前样式标记添加到集合中，但是要先将这些不相容的样式标记对象清除，再将当前样式标记对象添加到集合中；如果集合所包含的样式标记中，它们的属性 markType.spec.excludes 对当前样式标记类型进行了排除（但反过来，当前样式标记没有指明不能与之共存），则当前样式标记对象并不能添加到集合中
• removeFromSet(set) 方法：将当前的样式标记从给定的集合 set（一个数组，包含一系列的 mark 样式标记对象）中移除。返回一个新的集合（移除了该样式标记）。
• isInset(set) 方法：返回一个布尔值，以表示集合 set （一个数组，包含一系列的 mark 样式标记对象）中是否包含该样式标记
• eq(otherMark) 方法：返回一个布尔值，以表示当前样式标记是否与给定的 otherMark 另一个样式标记对象具有相同的类型和 attributes
• toJSON() 方法：将该样式标记对象序列化为 JSON 对象

此外该类还提供了一些静态方法：

• static Mark.fromJSON(schema, json) 静态方法：基于 schema 数据结构约束对象将 json 对象反序列化为一个样式标记实例
• static Mark.sameSet(markArrA, markArrB) 静态方法：返回一个布尔值，以表示两个数组（它们的元素都是一系列的样式标记对象）是否为同一个样式标记的集合
• static Mark.setFrom(markArr) 静态方法：基于给定的参数 markArr（可以是 null、单独一个 标记对象，或者一个未排序的 marks 数组），新建一个样式标记的集合
• static Mark.none 静态属性：返回一个空的样式标记的集合（空数组）