Milkdown自定义节点属性配置指南

前言

Milkdown作为一款现代化的Markdown编辑器框架，提供了强大的扩展能力。在实际开发中，我们经常需要为节点添加自定义属性，以满足特定的业务需求。本文将详细介绍如何在Milkdown中为节点添加自定义属性。

基础概念

在Milkdown中，每个节点都有其对应的Schema定义，这决定了节点的行为和属性。要自定义节点属性，我们需要理解几个核心概念：

1. 节点Schema：定义了节点的类型、属性和行为
2. 属性(attrs)：节点的附加信息，如class、id等
3. Markdown解析/生成：处理Markdown与节点之间的转换

实现步骤

1. 扩展节点Schema

首先需要扩展目标节点的Schema。以标题节点(heading)为例：

const customHeadingSchema = headingSchema.extendSchema((prev) => {
  return ctx => {
    const baseSchema = prev(ctx)
    return {
      ...baseSchema,
      attrs: {
        ...baseSchema.attrs,
        hProperties: {  // 添加自定义属性
          default: null,
        },
        // 其他自定义属性...
      }
    }
  }
});

2. 修改Markdown解析逻辑

需要重写parseMarkdown方法，确保能从Markdown解析出自定义属性：

parseMarkdown: {
  ...baseSchema.parseMarkdown,
  runner: (state, node, type) => {
    const depth = node.depth as number
    const hProperties = node.data?.hProperties || {}
    state.openNode(type, { 
      level: depth, 
      hProperties  // 传入自定义属性
    })
    state.next(node.children)
    state.closeNode()
  }
}

3. 修改Markdown生成逻辑

同样需要处理节点到Markdown的转换：

toMarkdown: {
  ...baseSchema.toMarkdown,
  runner: (state, node) => {
    const attrs = node.attrs || {}
    state.openNode('heading', {
      depth: attrs.level,
      data: {
        hProperties: attrs.hProperties  // 输出自定义属性
      }
    })
    state.next(node.content)
    state.closeNode()
  }
}

完整示例

结合上述概念，我们可以创建一个完整的自定义标题节点实现：

import { headingSchema } from '@milkdown/kit/preset/commonmark';

const customHeading = headingSchema.extendSchema((prev) => {
  return ctx => {
    const baseSchema = prev(ctx)
    return {
      ...baseSchema,
      attrs: {
        ...baseSchema.attrs,
        customClass: {
          default: 'default-class'
        },
        customId: {
          default: ''
        }
      },
      parseMarkdown: {
        ...baseSchema.parseMarkdown,
        runner: (state, node, type) => {
          const depth = node.depth as number
          const customClass = node.data?.customClass || 'default-class'
          const customId = node.data?.customId || ''
          state.openNode(type, { 
            level: depth,
            customClass,
            customId
          })
          state.next(node.children)
          state.closeNode()
        }
      },
      toMarkdown: {
        ...baseSchema.toMarkdown,
        runner: (state, node) => {
          const attrs = node.attrs || {}
          state.openNode('heading', {
            depth: attrs.level,
            data: {
              customClass: attrs.customClass,
              customId: attrs.customId
            }
          })
          state.next(node.content)
          state.closeNode()
        }
      }
    }
  }
});

使用自定义节点

在编辑器配置中使用自定义节点：

const editor = Editor.make()
  .config((ctx) => {
    ctx.set(rootCtx, root)
    ctx.set(defaultValueCtx, markdownContent)
  })
  .use(commonmark.replace('heading', customHeading))

注意事项

1. 属性继承：扩展Schema时要注意保留原有的属性和方法
2. 类型安全：TypeScript环境下要确保类型定义正确
3. 性能考虑：复杂的自定义逻辑可能影响编辑器性能
4. 兼容性：确保自定义属性不会破坏Markdown的标准兼容性

总结

通过扩展节点Schema和修改Markdown解析/生成逻辑，我们可以在Milkdown中灵活地为节点添加各种自定义属性。这种机制为开发者提供了极大的灵活性，可以满足各种定制化需求。实际开发中，建议根据具体需求选择最合适的扩展方式，并注意保持代码的可维护性。

掌握这些技巧后，开发者可以轻松实现如自定义样式、特殊交互等高级功能，充分发挥Milkdown的潜力。