django-prose-editor 0.8.1

关于富文本编辑器

摘自django-content-editor文档。

我们长期以来一直与富文本编辑器作斗争。坦白说，我认为给富文本编辑器添加那么多功能不是一个好主意。在富文本编辑器中调整上传的图片大小真的很痛苦，如果你想重新使用这些图片或者使用灯箱脚本之类的显示它们呢？你必须编写大量的JavaScript代码，而这些代码只在一个浏览器上工作。你无法真正过滤用户生成的HTML代码，以排除从Word复制粘贴产生的丑陋HTML代码。用户将上传10MB的JPEG文件，并在富文本编辑器中将它们调整为50x50像素。

这一切都让我相信，为用户提供一个功能过多的富文本编辑器是一个非常糟糕的想法。FeinCMS中的富文本编辑器只启用了粗体、斜体、项目符号、链接和标题（以及HTML代码按钮，因为这是不可避免的——有时富文本编辑器会出错，除了直接进入HTML代码外无法修复。此外，如果有人真的知道自己在做什么，我仍然希望给他们权力砍掉自己的脚）。

如果您觉得这还不令人信服，您始终可以添加自己的富文本插件，并使用不同的配置（或者只需覆盖您自己项目中富文本编辑器初始化模板）。我们不想强迫您接受我们的世界观，只是我们认为在这种情况下，更多的选择可能会造成更大的伤害而不是帮助。

安装

第一步是确保您为当前项目激活了虚拟环境，例如使用 . .venv/bin/activate。

将包安装到您的环境中

pip install django-prose-editor

为了将nh3作为可选依赖项用于清理HTML，请安装额外的“sanitize”

pip install django-prose-editor[sanitize]

将 django_prose_editor 添加到 INSTALLED_APPS

INSTALLED_APPS = [
    # ...
    "django_prose_editor",
]

在适当的位置将 models.TextField 替换为 ProseEditorField

from django_prose_editor.fields import ProseEditorField

class Project(models.Model):
    description = ProseEditorField()

注意！在从 models.TextField 切换到 ProseEditorField 时不会生成迁移。这是设计如此。这些迁移大多是麻烦的。

安全性

ProseMirror在只允许符合特定方案的内容方面做得非常好。当然，用户可以提交他们想要的任何内容，他们不会受您使用的HTML小部件的限制。您仍然应该在服务器端始终清理提交的HTML。一种好方法是使用 ProseEditorField 的 sanitize 参数。您可以使用以下代码片段始终通过 nh3 清理HTML。

from django_prose_editor.sanitized import SanitizedProseEditorField

description = SanitizedProseEditorField()

使用额外的“sanitize”安装 django-prose-editor 以使用 SanitizedProseEditorField。

便利性

有时显示HTML字段的摘录可能很有用；ProseEditorField 会自动将 get_*_excerpt 方法添加到模型中，该方法返回HTML字段内容的截断和清除的开始部分。例如，上面的名称将是 Project.get_description_excerpt。

自定义

可以通过传递可选的 config 字典来稍微自定义字段或小部件。默认配置是

config = {
    "types": None,        # Allow all nodes and marks
    "history": True,      # Enable undo and redo
    "html": True,         # Add a button which allows editing the raw HTML
    "typographic": True,  # Highlight typographic characters
    "headingLevels": [1, 2, 3, 4, 5],  # Available heading levels
}

如果您只想支持段落、粗体、强调、下标和上标，没有历史记录或HTML编辑，则可以添加以下字段

text = SanitizedProseEditorField(
    config={"types": ["strong", "em", "sub", "sup"]},
)

目前无法删除段落。请注意，后端不会清理内容以确保HTML只包含提供的标签，这目前不在范围内。

doc、paragraph 和 text 总是允许。

支持的节点类型是 heading、blockquote、horizontal_rule 和 hard_break。列表节点是 ordered_list、bullet_list 和 list_item。

支持的标记类型是 link、strong、em、underline、strikethrough、sub 和 sup。

Django admin之外的使用

很容易在Django admin之外使用文本编辑器。表单字段或小部件包含必要的CSS和JavaScript。

from django_prose_editor.fields import ProseEditorFormField

class Form(forms.Form):
    text = ProseEditorFormField()

或者，您可能想要使用 django_prose_editor.widgets.ProseEditorWidget，但为什么要让事情比必要的更复杂。

如果您在模板中渲染表单，您必须包含表单媒体

<form method="post">
  {{ form.errors }} {# Always makes sense #}
  {{ form.media }}  {# This is the important line! #}
  {{ form.as_div }}
  <button type="submit">send</button>
</form>

请注意，表单媒体不是 django-prose-editor 特有的，这是一个 Django 功能。

django-prose-editor CSS 使用以下 CSS 自定义属性。

• --prose-editor-background

• --prose-editor-foreground

• --prose-editor-border-color

• --prose-editor-active-color

• --prose-editor-disabled-color

如果您没有设置它们，它们将从以下属性中获取值，这些属性在 Django 管理员的 CSS 中定义

• --border-color

• --body-fg

• --body-bg

• --primary

您应该使用适当的值设置这些属性，以便在您的网站上使用 django-prose-editor 而不限于管理员界面。

此外，您可以可选地设置一个 --prose-editor-typographic 属性来控制显示时印刷字符的颜色。