从预定义模板插入Tiptap编辑器时自定义属性被移除的解决咨询

Tiptap基于ProseMirror，默认会按内置schema过滤未知的HTML属性和元素。要保留自定义属性（如data-element-name）和特殊元素，需通过扩展配置修改编辑器的解析/渲染规则，具体方法如下：

1. 为已有节点添加自定义属性支持 #

对于编辑器默认支持的节点（如<p>、<div>），可扩展对应的内置扩展，添加自定义属性的解析与渲染逻辑：

import { Paragraph } from '@tiptap/extension-paragraph'

// 扩展Paragraph节点，支持data-element-name属性
const CustomParagraph = Paragraph.extend({
  addAttributes() {
    return {
      ...this.parent?.(),
      'data-element-name': {
        default: null,
        // 从HTML解析属性值
        parseHTML: element => element.getAttribute('data-element-name'),
        // 渲染HTML时输出属性
        renderHTML: attributes => {
          if (!attributes['data-element-name']) return {}
          return { 'data-element-name': attributes['data-element-name'] }
        },
      },
    }
  },
})

之后在编辑器配置中，用这个自定义扩展替换默认的Paragraph：

const editor = new Editor({
  extensions: [
    CustomParagraph,
    // 其他扩展...
  ],
  content: yourTemplateHTML,
})

2. 自定义节点支持特殊HTML元素 #

如果模板包含Tiptap默认不识别的HTML元素（如自定义标签），需创建自定义节点扩展：

import { Node } from '@tiptap/core'

const MyCustomElement = Node.create({
  name: 'myCustomElement',
  group: 'block', // 定义为块级元素，可根据实际需求调整
  atom: true, // 标记为原子节点，避免被拆分

  addAttributes() {
    return {
      'data-element-name': {
        default: null,
        parseHTML: element => element.getAttribute('data-element-name'),
        renderHTML: attributes => ({
          'data-element-name': attributes['data-element-name'],
        }),
      },
      // 可添加更多自定义属性
    }
  },

  // 配置HTML解析规则
  parseHTML() {
    return [{ tag: 'my-custom-element' }]
  },

  // 配置HTML渲染规则
  renderHTML({ HTMLAttributes }) {
    return ['my-custom-element', HTMLAttributes, 0]
  },
})

将该自定义节点加入编辑器的extensions数组即可。

3. 调整内容解析选项（谨慎使用） #

如果只是临时放宽解析限制，可在设置内容时指定parseOptions：

editor.commands.setContent(yourTemplateHTML, {
  parseOptions: {
    preserveWhitespace: 'full',
    // 允许未知元素，不推荐生产环境使用，存在XSS风险
    allowUnknownElements: true,
  },
})

注意：allowUnknownElements会让编辑器接受所有HTML元素，存在安全隐患，建议优先通过自定义节点实现需求。

4. 避免清理类扩展误删内容 #

如果使用了CleanNode这类自动清理节点的扩展，需配置它忽略自定义属性：

import { CleanNode } from '@tiptap/extension-clean-node'

const CustomCleanNode = CleanNode.extend({
  addOptions() {
    return {
      ...this.parent?.(),
      // 指定不清理的属性
      ignoreAttributes: ['data-element-name'],
    }
  },
})

用这个自定义的CleanNode替换默认扩展，即可保留目标属性。

内容的提问来源于stack exchange，提问作者Karthik