Django CKEditor 技术文档

本文档旨在帮助用户了解和使用 Django CKEditor 项目，包括安装指南、使用说明、API 使用文档和安装方式。

1. 安装指南

1.1 必要条件

1. 安装或将 django-ckeditor 添加到您的 python 路径。

   pip install django-ckeditor
   

2. 在您的 INSTALLED_APPS 设置中添加 ckeditor。
3. 运行 collectstatic 管理命令：$ ./manage.py collectstatic。这将将静态 CKEditor 必需的媒体资源复制到 STATIC_ROOT 设置指定的目录中。有关更多信息，请参阅 Django 的文档，了解如何管理静态文件。
4. CKEditor 需要知道其资产的位置，因为它只在需要时才延迟加载它们。位置在 ckeditor-init.js 脚本中确定，默认为 static/ckeditor/ckeditor/。这并不总是有效，例如在使用 ManifestStaticFilesStorage、任何资产打包管道或类似工具时。django-ckeditor 非常擅长在那时自动检测正确的地方，但有时您必须硬编码 CKEDITOR_BASEPATH。这可以在设置中硬编码，例如：

   CKEDITOR_BASEPATH = "/my_static/ckeditor/ckeditor/"
   

   当然，如果您确实需要这样做，您可以使用自己的 admin/change_form.html 模板覆盖它，例如：

   {% extends "admin/change_form.html" %}
   
   {% block extrahead %}
   <script>window.CKEDITOR_BASEPATH = '/my_static/ckeditor/ckeditor/';</script>
   {{ block.super }}
   {% endblock %}
   

   当然，在使用 CKEditor 的非管理应用时，您应该根据您的需要调整此代码片段。

1.2 使用文件上传小部件的必要条件

1. 在您的 INSTALLED_APPS 设置中添加 ckeditor_uploader。
2. 在项目的 settings.py 文件中添加一个 CKEDITOR_UPLOAD_PATH 设置。此设置指定到您的 CKEditor 媒体上传目录的相对路径。CKEditor 使用 Django 的存储 API。默认情况下，Django 使用文件系统存储后端（它将使用您的 MEDIA_ROOT 和 MEDIA_URL），如果您不使用不同的后端，则必须在 CKEDITOR_UPLOAD_PATH 路径内具有写入权限，例如：

   CKEDITOR_UPLOAD_PATH = "uploads/"
   

   当使用默认的文件系统存储配置时，图像将上传到您的 MEDIA_ROOT 中的 "uploads" 文件夹，并且将针对 MEDIA_URL 创建网址（/media/uploads/image.jpg）。
3. 如果您想控制文件名生成，则必须将自定义文件名生成器添加到您的设置中：

   # utils.py
   
   def get_filename(filename, request):
       return filename.upper()
   

   # settings.py
   
   CKEDITOR_FILENAME_GENERATOR = 'utils.get_filename'
   

4. 对于默认的文件系统存储配置，MEDIA_ROOT 和 MEDIA_URL 必须正确设置，以便媒体文件可以正常工作（例如，由 ckeditor 小部件上传的文件）。
5. 将 CKEditor URL 包含添加到您的项目的 urls.py 文件中：

   path('ckeditor/', include('ckeditor_uploader.urls')),
   

   注意：通过添加这些 URL，您会添加可以上传和浏览上传图像的视图。从 django-ckeditor 4.4.6 开始，这些视图使用 @staff_member_required 进行装饰。如果您想要不同的权限装饰器（login_required、user_passes_test 等），则必须手动将 ckeditor.urls 中定义的视图添加到您的 urls.py。

2. 项目的使用说明

2.1 字段

将富文本编辑功能添加到您的模型的最快方法是使用包含的 RichTextField 模型字段类型。CKEditor 小部件作为表单字段渲染，但在其他所有方面，该字段的行为与标准的表单字段相同。

from ckeditor.fields import RichTextField

class MyModel(models.Model):
    content = RichTextField()

2.2 富文本上传字段

如果您需要支持上传和浏览文件的富文本编辑功能，可以使用 RichTextUploadingField。

from ckeditor.fields import RichTextUploadingField

class MyModel(models.Model):
    content = RichTextUploadingField()

2.3 小部件

您还可以单独使用 CKEditorWidget，如果您需要自定义表单字段的行为。

from ckeditor.widgets import CKEditorWidget

class MyModel(models.Model):
    content = models.TextField(widget=CKEditorWidget())

2.4 配置 CKEditor

您可以通过在 CKEDITOR_CONFIGS 设置中指定一组 CKEditor 设置来配置 CKEditor 编辑器（请参阅 CKEditor 的文档中的 Setting Configurations）。

CKEDITOR_CONFIGS = {
    'default': {
        'toolbar': 'full',
        'height': 300,
        'width': 300,
    },
}

您还可以在创建 RichTextField 或 CKEditorWidget 实例时指定配置名称：

content = RichTextField(config_name='default')

或者：

widget = CKEditorWidget(config_name='default')

3. 项目 API 使用文档

目前，Django CKEditor 没有公开的 API 文档。但是，您可以查看源代码和单元测试来了解项目的内部工作原理。

4. 项目安装方式

Django CKEditor 可以通过 PyPI 安装：

pip install django-ckeditor

或者，您可以克隆 GitHub 仓库并将其添加到您的 Python 路径中。

总结

本文档涵盖了 Django CKEditor 的主要功能和用法。如果您有任何问题或需要进一步的帮助，请参阅 Django CKEditor 的 GitHub 仓库和文档。