Django CMS 插件升级指南：从 v3 迁移到 v4+-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00471/article/details/148415767

Django CMS 插件升级指南：从 v3 迁移到 v4+

django-cms django-cms/django-cms: 是一个基于 Django 的内容管理系统，可以用于构建多语言的 Web 应用程序和网站，提供了丰富的内容管理功能和多种插件扩展。项目地址: https://gitcode.com/gh_mirrors/dj/django-cms

核心架构变更解析

在 Django CMS 从 v3 升级到 v4 的过程中，插件系统的底层架构发生了重大变化。理解这些变化对于成功迁移自定义插件至关重要。

数据库存储结构的革命性改变

v3 版本中，插件模型 CMSPlugin 继承自 django-treebeard 库的 MP_Node 模型，使用树形结构存储插件关系。这种设计带来了以下特点：

使用 path、depth 和 numchild 字段维护树结构
基于 MPTT (Modified Preorder Tree Traversal) 算法
每个插件位置由其父节点唯一确定

而在 v4 版本中，架构简化为：

直接继承自 Django 的 Model 类
仅使用 parent 和 position 两个字段
采用 SQL CTE (Common Table Expressions) 处理递归查询
位置编号现在基于占位符(placeholder)和语言组合

必须注意的破坏性变更

已移除的字段

以下 treebeard 相关字段在 v4 中已不复存在：

path - 原用于表示节点在树中的完整路径
depth - 原表示节点在树中的层级深度
numchild - 原记录子节点数量

位置(position)字段的语义变化

| 版本 | 作用域 | 编号规则 | 允许空档 | |------|--------|----------|----------| | v3 | 每个父节点独立 | 从0开始 | 允许 | | v4 | 整个占位符+语言组合 | 从1开始连续 | 不允许 |

插件迁移实战指南

场景一：处理已移除字段的访问

替代 path 字段排序

# v3 方式
qs.order_by("path")

# v4 替代方案
qs.order_by("position")

计算深度属性

@property
def depth(self):
    return 1 if self.parent is None else self.parent.depth + 1

兼容 v3 位置计算

@property
def v3position(self):
    siblings = CMSPlugin.objects.filter(
        parent=self.parent
    ).order_by("position")
    return next(
        (i+1 for i, plugin in enumerate(siblings) if plugin == self),
        1
    )

场景二：插件编程操作

创建插件的新规范

# 错误方式 - 直接使用 create()
MyPluginModel.objects.create(...)  # 将导致数据库异常

# 正确方式 - 通过占位符API
new_plugin = MyPluginModel(
    parent=None,
    position=1,
    placeholder=my_placeholder
)
my_placeholder.add_plugin(new_plugin)

位置设置技巧速查表

| 需求场景 | 位置参数示例 | |---------|-------------| | 作为父插件的第一个子项 | position=parent.position + 1 | | 作为父插件的第n个子项 | position=parent.position + n | | 添加到占位符末尾 | position=placeholder.get_last_plugin_position(language="en") + 1 |

场景三：编写跨版本兼容插件

对于需要同时支持 v3 和 v4 的通用插件，可采用版本检测模式：

@staticmethod
def _create_plugin_safe(placeholder, plugin):
    """版本安全的插件创建方法"""
    if hasattr(placeholder, "add_plugin"):  # v4+
        placeholder.add_plugin(plugin)
    else:  # v3
        plugin.save()
        
@staticmethod 
def _delete_plugin_safe(plugin):
    """版本安全的插件删除方法"""
    placeholder = plugin.placeholder
    if hasattr(placeholder, 'delete_plugin'):  # v4+
        return placeholder.delete_plugin(plugin)
    else:
        return plugin.delete()

测试套件适配策略

发布功能的版本适配

from packaging.version import Version
from cms import __version__

DJANGO_CMS4 = Version(__version__) >= Version("4")

class CMSVersionAdapter:
    if DJANGO_CMS4:
        def publish(self, page, language=None):
            # v4 的发布逻辑
            from djangocms_versioning.models import Version
            version = Version.objects.get_for_grouper(page)
            version.publish(user=self.superuser)
    else:
        def publish(self, page, language=None):
            # v3 的发布逻辑
            page.publish(language)

占位符获取的兼容处理

def get_placeholders(self, page):
    return (
        page.get_placeholders(self.language) 
        if DJANGO_CMS4 
        else page.get_placeholders()
    )