merge develop & 手动加注释

plugins/article_copyright/plugin.py

@@ -1,32 +1,75 @@
+# 1. 导入所需的基础类和模块
+
+# 从插件管理模块导入基类 BasePlugin
+# 所有自定义插件都应该继承这个基类，它提供了插件的基本结构和生命周期管理
 from djangoblog.plugin_manage.base_plugin import BasePlugin
+
+# 导入钩子管理模块
+# 这个模块提供了注册和触发钩子的功能
 from djangoblog.plugin_manage import hooks
+
+# 从常量定义文件导入文章内容钩子的名称
+# 使用常量可以避免硬编码字符串，增加代码的可读性和可维护性
+# ARTICLE_CONTENT_HOOK_NAME 的值很可能就是 'article_content' 或类似的字符串
 from djangoblog.plugin_manage.hook_constants import ARTICLE_CONTENT_HOOK_NAME
 
 
+# 2. 定义插件主类
+
+# 定义一个名为 ArticleCopyrightPlugin 的类，并让它继承自 BasePlugin
 class ArticleCopyrightPlugin(BasePlugin):
-    PLUGIN_NAME = '文章结尾版权声明'
-    PLUGIN_DESCRIPTION = '一个在文章正文末尾添加版权声明的插件。'
-    PLUGIN_VERSION = '0.2.0'
-    PLUGIN_AUTHOR = 'liangliangyy'
+    # 定义插件的元数据，这些信息通常会在后台管理界面显示
+    PLUGIN_NAME = '文章结尾版权声明'            # 插件的显示名称
+    PLUGIN_DESCRIPTION = '一个在文章正文末尾添加版权声明的插件。' # 插件的详细描述
+    PLUGIN_VERSION = '0.2.0'                 # 插件的版本号
+    PLUGIN_AUTHOR = 'liangliangyy'           # 插件的作者
 
-    # 2. 实现 register_hooks 方法，专门用于注册钩子
+    # 3. 实现钩子注册方法 (关键步骤)
     def register_hooks(self):
-        # 在这里将插件的方法注册到指定的钩子上
+        """
+        这个方法是插件与系统交互的入口。
+        当插件被加载时，系统会调用这个方法，让插件有机会注册自己的功能。
+        """
+        # 使用 hooks.register() 函数来注册钩子
+        # 参数1: 要注册到哪个钩子上。这里我们使用导入的常量 ARTICLE_CONTENT_HOOK_NAME，
+        #        它指向文章内容处理的那个钩子。
+        # 参数2: 当钩子被触发时，要执行的函数。这里是 self.add_copyright_to_content，
+        #        即当前类的 add_copyright_to_content 方法。
         hooks.register(ARTICLE_CONTENT_HOOK_NAME, self.add_copyright_to_content)
 
+    # 4. 定义插件的核心功能方法
     def add_copyright_to_content(self, content, *args, **kwargs):
         """
-        这个方法会被注册到 'the_content' 过滤器钩子上。
-        它接收原始内容，并返回添加了版权信息的新内容。
+        这是插件的核心逻辑所在。
+        当文章内容钩子被触发时，这个方法会被调用。
+
+        :param content: 文章的原始 HTML 内容。
+        :param *args:   预留参数，方便未来扩展。
+        :param **kwargs: 一个包含额外上下文信息的字典，比如当前的文章对象。
+        :return: 经过处理后、添加了版权声明的新内容。
         """
+        # 从 kwargs 中获取当前的文章对象 (Article instance)
+        # 使用 .get() 方法是一个好习惯，如果 'article' 键不存在，它会返回 None 而不是抛出错误
         article = kwargs.get('article')
+
+        # 做一个安全检查：如果文章对象不存在，或者钩子在没有文章上下文的情况下被调用，
+        # 就直接返回原始内容，不做任何处理。
         if not article:
             return content
 
+        # 构建版权声明的 HTML 字符串
+        # 使用 f-string (格式化字符串字面值) 来方便地插入变量
+        # <hr> 会插入一条水平线，<p> 标签包裹版权信息。
         copyright_info = f"\n<hr><p>本文由 {article.author.username} 原创，转载请注明出处。</p>"
+
+        # 将原始内容和版权声明拼接起来，并返回新的内容
         return content + copyright_info
 
 
-# 3. 实例化插件。
-# 这会自动调用 BasePlugin.__init__，然后 BasePlugin.__init__ 会调用我们上面定义的 register_hooks 方法。
-plugin = ArticleCopyrightPlugin()
+# 5. 实例化插件 (关键步骤)
+# 这行代码非常重要。当 Python 解释器加载这个文件时，它会执行这行代码。
+# 1. 创建一个 ArticleCopyrightPlugin 类的实例。
+# 2. 这个实例化过程会调用父类 BasePlugin 的 __init__ 构造方法。
+# 3. 在 BasePlugin 的 __init__ 方法中，会自动调用我们上面定义的 register_hooks() 方法。
+# 4. 这样，插件就完成了自身的注册，静静地等待着文章内容钩子被触发。
+plugin = ArticleCopyrightPlugin()