wagtailmedia

为Wagtail提供类似wagtail.documents模块功能的模块，但用于音频和视频文件。

加入Wagtail Space社区！

今年我们将参加Wagtail Space US！Wagtail Space 2024活动的参与邀请和注册现已开放。我们非常希望您在6月份发表演讲，或者只是作为参会者。

• Wagtail Space NL，荷兰阿恩赫姆。2024-06-14
• Wagtail Space US，宾夕法尼亚州费城。2024-06-20至2024-06-22

安装

使用pip安装

pip install wagtailmedia

wagtailmedia与Wagtail 4.1及以上版本兼容。查看旧版本以了解与旧版本Wagtail的兼容性。

设置

在您的设置文件中，将wagtailmedia添加到INSTALLED_APPS

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

所有wagtailmedia设置都定义在您的设置文件中的单个WAGTAILMEDIA字典中。默认值为

# settings.py

WAGTAILMEDIA = {
    "MEDIA_MODEL": "wagtailmedia.Media",  # string, dotted-notation.
    "MEDIA_FORM_BASE": "",  # string, dotted-notation. Defaults to an empty string
    "AUDIO_EXTENSIONS": [
        "aac",
        "aiff",
        "flac",
        "m4a",
        "m4b",
        "mp3",
        "ogg",
        "wav",
    ],  # list of extensions
    "VIDEO_EXTENSIONS": [
        "avi",
        "h264",
        "m4v",
        "mkv",
        "mov",
        "mp4",
        "mpeg",
        "mpg",
        "ogv",
        "webm",
    ],  # list of extensions
}

URL配置

您的项目需要设置以从MEDIA_ROOT提供用户上传的文件。您的Django项目可能已经实现了这一点，如果没有，请在urls.py中添加以下片段

from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # ... the rest of your URLconf goes here ...
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

请注意，此操作仅在开发模式下有效（DEBUG = True）；在生产环境中，您需要配置您的Web服务器以从MEDIA_ROOT提供文件。有关更多信息，请参阅Django文档：在开发期间提供用户上传的文件和部署静态文件。

配置就绪后，您可以运行./manage.py migrate来创建wagtailmedia使用的数据库表。

wagtailmedia为选择器面板界面加载了额外的资产。在迁移步骤之后运行./manage.py collectstatic以收集所有必需的资产。

自定义Media模型

可以自定义Media模型。为此，您需要在项目中添加一个新的模型，它从wagtailmedia.models.AbstractMedia继承。

然后设置WAGTAILMEDIA设置字典中的MEDIA_MODEL属性以指向它

# settings.py
WAGTAILMEDIA = {
    "MEDIA_MODEL": "my_app.CustomMedia",
    # ...
}

您可以使用MEDIA_FORM_BASE设置来自定义与您的Media模型一起使用的模型表单。它应该是表单的点分路径，将在构造媒体表单时作为基础表单传递给modelform_factory()。

# settings.py

WAGTAILMEDIA = {
    "MEDIA_FORM_BASE": "my_app.forms.CustomMediaForm",
    # ...
}

钩子

construct_media_chooser_queryset

在渲染媒体选择器视图时调用，以允许自定义媒体列表查询集。传递给钩子的可调用函数将接收当前的媒体查询集和请求对象，并必须返回一个媒体查询集（原始的一个或一个新的一个）。

from wagtail import hooks


@hooks.register("construct_media_chooser_queryset")
def show_my_uploaded_media_only(media, request):
    # Only show uploaded media
    media = media.filter(uploaded_by_user=request.user)

    return media

如何使用

作为常规Django字段

您可以将Media用作常规Django字段。以下是一个示例

from django.db import models

from wagtail.fields import RichTextField
from wagtail.models import Page
from wagtail.admin.panels import FieldPanel

from wagtailmedia.edit_handlers import MediaChooserPanel


class BlogPageWithMedia(Page):
    author = models.CharField(max_length=255)
    date = models.DateField("Post date")
    body = RichTextField(blank=False)
    featured_media = models.ForeignKey(
        "wagtailmedia.Media",
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        related_name="+",
    )

    content_panels = Page.content_panels + [
        FieldPanel("author"),
        FieldPanel("date"),
        FieldPanel("body"),
        MediaChooserPanel("featured_media"),
    ]

MediaChooserPanel接受media_type关键字参数（kwarg），以限制可以选择或上传的媒体类型。目前仅支持"audio"（MediaChooserPanel(media_type="audio")）和"video"（MediaChooserPanel(media_type="audio")），任何其他类型都将使选择器表现得好像没有获取任何kwarg。

与Wagtail名称冲突

请不要将字段命名为media。在渲染管理UI时，Wagtail使用一个media属性为其字段的CSS & JS资产加载。使用media作为字段名称会破坏管理UI（#54）。

在StreamField中

您可以在StreamField中使用Media。为此，您需要添加一个新的块类，它从wagtailmedia.blocks.AbstractMediaChooserBlock继承，并实现自己的render_basic方法。

以下是一个示例

from django.db import models
from django.forms.utils import flatatt
from django.utils.html import format_html, format_html_join

from wagtail import blocks
from wagtail.admin.panels import FieldPanel
from wagtail.fields import StreamField
from wagtail.models import Page

from wagtailmedia.blocks import AbstractMediaChooserBlock


class TestMediaBlock(AbstractMediaChooserBlock):
    def render_basic(self, value, context=None):
        if not value:
            return ""

        if value.type == "video":
            player_code = """
            <div>
                <video width="{1}" height="{2}" controls>
                    {0}
                    Your browser does not support the video tag.
                </video>
            </div>
            """
        else:
            player_code = """
            <div>
                <audio controls>
                    {0}
                    Your browser does not support the audio element.
                </audio>
            </div>
            """

        return format_html(
            player_code,
            format_html_join(
                "\n", "<source{0}>", [[flatatt(s)] for s in value.sources]
            ),
            value.width,
            value.height,
        )


class BlogPage(Page):
    author = models.CharField(max_length=255)
    date = models.DateField("Post date")
    body = StreamField(
        [
            ("heading", blocks.CharBlock(classname="title", icon="title")),
            ("paragraph", blocks.RichTextBlock(icon="pilcrow")),
            ("media", TestMediaBlock(icon="media")),
        ]
    )

    content_panels = Page.content_panels + [
        FieldPanel("author"),
        FieldPanel("date"),
        FieldPanel("body"),
    ]

您还可以使用音频或视频特定的选择器

# ...
from wagtail.models import Page
from wagtail.fields import StreamField
from wagtailmedia.blocks import AudioChooserBlock, VideoChooserBlock


class BlogPage(Page):
    # ...

    body = StreamField(
        [
            # ... other block definitions
            ("audio", AudioChooserBlock()),
            ("video", VideoChooserBlock()),
        ]
    )

API

要在API中公开媒体项，您可以遵循Wagtail文档指南进行API配置，其中包含针对wagtailmedia的特定说明。

# api.py
from wagtail.api.v2.router import WagtailAPIRouter
from wagtailmedia.api.views import MediaAPIViewSet


# Register the router
api_router = WagtailAPIRouter("wagtailapi")
# add any other enpoints you need, plus the wagtailmedia one
api_router.register_endpoint("media", MediaAPIViewSet)

翻译

wagtailmedia支持法语和中文翻译。欢迎更多翻译加入！

贡献

欢迎所有贡献！

升级

在升级Wagtail版本时，检查模板样式和格式是否与当前支持的Wagtail版本保持最新是一个好的做法。

以下模板需要检查：

• src/wagtailmedia/templates/wagtailmedia/media/add.html
• src/wagtailmedia/templates/wagtailmedia/media/confirm_delete.html
• src/wagtailmedia/templates/wagtailmedia/media/edit.html
• src/wagtailmedia/templates/wagtailmedia/media/index.html
• src/wagtailmedia/templates/wagtailmedia/media/media_chooser.html
• src/wagtailmedia/templates/wagtailmedia/media/media_permissions_formset.html
• src/wagtailmedia/templates/wagtailmedia/media/usage.html

安装

要修改此项目，首先克隆此存储库

git clone git@github.com:torchbox/wagtailmedia.git
cd wagtailmedia

激活您首选的虚拟环境后，安装测试依赖项

pip install -e '.[testing]' -U

pre-commit

请注意，此项目使用pre-commit。要在本地设置

# if you don't have it yet, globally
$ pip install pre-commit
# go to the project directory
$ cd wagtailmedia
# initialize pre-commit
$ pre-commit install

# Optional, run all checks once for this, then the checks will run only on the changed files
$ pre-commit run --all-files

如何运行测试

现在您可以按照以下方式运行测试

tox

或者，您可以针对特定环境运行它们 tox -e py310-dj41-wagtail41 或特定测试 tox -e py310-dj41-wagtail41 -- tests.test_views.TestMediaChooserUploadView

要交互式运行测试应用程序，使用 tox -e interactive，访问 http://127.0.0.1:8020/admin/ 并使用 admin/changeme 登录。