MDX Editor 自定义指令编辑器开发指南

MDX Editor 自定义指令编辑器开发指南

什么是 Markdown 指令

在 Markdown 生态系统中，指令(Directives)是一种扩展语法，允许开发者创建自定义的内容结构。指令语法通常采用::directiveName[内容]{属性}的格式，为 Markdown 提供了强大的扩展能力。

一个典型的指令示例如下：

::youtube[视频标题]{#01ab2cd3efg}

MDX Editor 中的指令支持

MDX Editor 提供了完善的指令支持系统，开发者可以：

1. 定义自定义指令的描述符
2. 为指令创建专属编辑器
3. 将指令编辑功能集成到工具栏
4. 动态更新指令属性

基础指令编辑器实现

MDX Editor 内置了GenericDirectiveEditor，可以快速实现基础指令编辑功能。下面是一个告警框(callout)指令的实现示例：

const CalloutDirectiveDescriptor: DirectiveDescriptor = {
  name: 'callout',
  testNode(node) {
    return node.name === 'callout'
  },
  attributes: [], // 可编辑属性
  hasChildren: true, // 是否包含子内容
  Editor: GenericDirectiveEditor
}

使用时，只需在插件配置中注册这个描述符：

<MDXEditor
  plugins={[directivesPlugin({ 
    directiveDescriptors: [CalloutDirectiveDescriptor] 
  })]}
/>

自定义指令编辑器开发

当需要更复杂的编辑界面时，可以完全自定义编辑器组件。下面是一个带红色边框的自定义告警框编辑器：

const CalloutCustomDirectiveDescriptor: DirectiveDescriptor = {
  name: 'callout',
  // ...其他配置相同
  Editor: (props) => {
    return (
      <div style={{ border: '1px solid red', padding: 8, margin: 8 }}>
        <NestedLexicalEditor
          block
          getContent={(node) => node.children}
          getUpdatedMdastNode={(mdastNode, children) => ({
            ...mdastNode, 
            children
          })}
        />
      </div>
    )
  }
}

这个自定义编辑器使用了NestedLexicalEditor组件来处理嵌套内容编辑，并添加了自定义样式。

工具栏集成实践

为了方便内容编辑，我们可以将指令插入功能添加到工具栏。以下是一个 YouTube 视频指令的插入按钮实现：

const YouTubeButton = () => {
  const insertDirective = usePublisher(insertDirective$)

  return (
    <DialogButton
      tooltipTitle="插入 YouTube 视频"
      submitButtonTitle="插入视频"
      dialogInputPlaceholder="粘贴 YouTube 视频链接"
      buttonContent="YT"
      onSubmit={(url) => {
        const videoId = new URL(url).searchParams.get('v')
        if (videoId) {
          insertDirective({
            name: 'youtube',
            type: 'leafDirective',
            attributes: { id: videoId },
            children: []
          })
        } else {
          alert('无效的 YouTube 链接')
        }
      }}
    />
  )
}

然后在插件配置中添加到工具栏：

toolbarPlugin({
  toolbarContents: () => <YouTubeButton />
})

指令属性动态更新

MDX Editor 提供了useMdastNodeUpdater钩子来更新指令属性。当属性变化时，编辑器会自动重新渲染：

const updateMdastNode = useMdastNodeUpdater()
const handleUpdate = (newAttrs) => {
  updateMdastNode({ 
    ...mdastNode, 
    attributes: newAttrs 
  })
}

生产环境渲染注意事项

在生产环境中渲染自定义指令时，需要使用专门的 Markdown 处理器，如remark-directive，来正确解析和渲染指令内容。

总结

MDX Editor 的指令系统为 Markdown 编辑提供了强大的扩展能力。通过本文介绍的方法，开发者可以：

1. 快速实现基础指令编辑功能
2. 开发完全自定义的指令编辑器
3. 将指令编辑集成到用户界面
4. 动态管理指令属性

这种灵活性和扩展性使得 MDX Editor 成为处理复杂 Markdown 内容的理想选择。