Django easy images

通过使用VIPS快速图像处理库，轻松构建响应式HTML `<img>` 标签，以缩略图化Django图像。

当生成一个 `` 时，任何尚不存在的小型图都将排队构建（如果尚未排队）并从HTML中排除。例如，从 `Img(width="md")` 构建的照片将生成

<img src="/media/img/profiles/john.jpg" alt="Profile photo for John Doe">

但在图像构建后，HTML将变为

<img
  src="/media/img/thumbs/f52fbd32b2b3b86ff88ef6c490628285.jpg"
  srcset="
    /media/img/thumbs/18183dd9009f2b7e1b44f9c4af287589.webp,
    /media/img/thumbs/fb8c2e2b85ca81eb4350199faddd983c.webp 2x
  "
  alt="Profile photo for John Doe"
>

安装和配置

要安装django-easy-images，只需运行以下命令

pip install django-easy-images

安装后，在Django设置文件中添加easy_images应用程序

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

由于这使用了pyvips，您需要在系统上安装libvips库。

使用方法

您可以使用Img类或{% img %}模板标签来渲染包含图像的Django FieldFile（或ImageFieldFile）作为响应式HTML `` 标签。

摘要

1. 在您的应用程序的images.py文件中定义您的Img类。
2. 在视图/模板中使用这些类来生成<img>标签。
3. 您可以设置一个cron作业来运行build_img_queue管理命令来构建图像，或者使用celery任务和queued_img信号在图像排队时构建图像。
4. 可选地，在 apps.py 文件中使用 Img.queue 方法，以便在上传图像后立即排队构建图像（如果需要，则构建 src/srcset 内联）。

Img 类

Img 类用于创建 HTML <img> 元素的生成器。以下是如何使用它的示例：

from easy_images import Img
thumb = Img(width="md")
thumb(profile.photo, alt=f"Profile photo for {{ profile.name }}").as_html()

如你所见，thumb 是一个用于生成 profile.photo 图像的 HTML <img> 元素的 Img 实例。输出将类似于以下内容：

<img
  src="/media/img/thumbs/f52fbd32b2b3b86ff88ef6c490628285.jpg"
  srcset="
    /media/img/thumbs/18183dd9009f2b7e1b44f9c4af287589.webp,
    /media/img/thumbs/fb8c2e2b85ca81eb4350199faddd983c.webp 2x
  "
  alt="Profile photo for John Doe"
/>

在下面的 选项部分 中，你可以看到可以向 Img 实例传递的所有不同选项。

还可以向实例传递其他可选参数

alt

图像的 alt 文本。

build

确定应该内联构建什么。有效值有：

• None：所有图像都将从请求外构建（默认）。
• "src"：基本 src 图像将内联构建，但 srcset 图像将从请求外构建。
• "srcset"：基本 src 图像和所有 srcset 图像都将内联构建。

img_attrs

一个字典，可以添加任何其他属性到 <img> 元素中。

{% img %} 标签

img 模板标签是生成响应式 HTML <img> 元素的另一种方法。

{% load easy_images %}
{% img report.image width="md" alt="" %}

你还可以将 Img 实例传递给 img 模板标签

{% load easy_images %}
{% img report.image thumb alt="" %}

模板标签永远不会内联构建图像。

构建图像。

每次请求图像时，任何尚未构建的图像版本都将排队等待构建，并从 HTML 中排除。

要构建队列中的图像，你可以

• 运行 build_img_queue 管理命令（通常在 cron 作业中），或者
• 使用 celery 或其他任务运行器（可能使用 queued_img 信号）进行处理。

选项

可以调用以下选项来调用 Img 类和 img 模板标签。

width

限制图像的宽度。可以使用整数，也可以使用以下字符串作为 Tailwind 尺寸：“xs”、“sm”、“md”、“lg”、“screen-sm”、“screen-md”、“screen-lg”、“screen-xl” 或 “screen-2xl”。

ratio

要构建的图像的宽高比。

使用表示比例的浮点数（例如 4/5）或以下字符串之一：“square”、“video”（表示 16/9）、“video_vertical”、“golden”（使用黄金比例）、“golden_vertical”。

默认为 "video"（16/9）。

crop

是否裁剪图像。

默认为 True。

使用布尔值、两个浮点数的元组，或逗号分隔的字符串等效值。将 True 替换为 (0.5, 0.5)，表示从中心裁剪图像。这些数字是图像尺寸的百分比。

还可以使用以下关键字：tl（左上角）、tr（右上角）、bl（左下角）、br（右下角）、l、r、t 或 b。这将设置百分比到 0 或 100 以适用于适当的轴。

如果 crop 为 False，则图像将被调整大小，以便覆盖请求的比例，但不会裁剪。这在使用 object-fit 在 CSS 中处理位置时很有用。

contain

在调整图像大小时（不裁剪），将图像包含在请求的比例内。这确保它始终适合请求的尺寸。它还阻止图像被放大。

默认为 False，意味着图像将被调整大小以覆盖请求的比例（这意味着图像尺寸可能大于请求的尺寸）。

focal_window

当缩小图像时，一个焦点窗口用于放大。使用四个浮点数的元组（或逗号分隔的字符串等效值），其中第一对百分比是左上角，第二对百分比是右下角。

quality

图像质量。例如，quality=90表示图像将以90的质量进行压缩。默认值为80。

密度

要创建的图像更高密度的版本列表。

默认为[2]。

尺寸

在不同媒体查询中使用的尺寸字典。键可以是表示最大宽度的整数，或表示特定媒体查询的字符串。键可以是表示宽度的整数/字符串，或包含宽度选项的字典（必须包含宽度）。

如果设置了densities，则还将构建最大尺寸（不包括'print'媒体）的更高密度版本，以便浏览器有更多的选择。

例如

img_with_sizes = Img(
    # Base size
    width=300,
    # Alternate sizes for different media queries
    sizes={
        # Print media query, larger width with higher quality
        "print": {"width": 450, "quality": 90},
        # A viewport max width of 800, smaller width.
        800: 100
    },
)
print(img_with_sizes(model_instance.image, build="srcset").as_html())

将输出

<img src="/media/img/thumbs/08efa8f7b11b7e9b24a037bb3f216369.jpg" srcset="/media/img/thumbs/18183dd9009f2b7e1b44f9c4af287589.webp 100w, /media/img/thumbs/08efa8f7b11b7e9b24a037bb3f216369.webp 300w, /media/img/thumbs/fb8c2e2b85ca81eb4350199faddd983c.webp 450w, /media/img/thumbs/cfca1aebe161e09926c86f76d4e2f1b4.webp 600w" sizes="(print) 450px, (max-width: 800) 100px" alt="">

格式

用于构建srcset版本的图像格式。有效的值是"webp" (默认)，"avif"或"jpeg"。请注意，AVIF在构建图像时使用大量内存。

基于的src图像格式将始终以JPEG格式构建，以实现向后兼容。

信号

来自模型的队列。

file_post_save 信号

此信号在模型实例保存时触发每个未提交的FileField。

它可以用于为模型实例构建和预排队像。

最简单的用法是通过Img实例的辅助方法queue。以下是在模型apps.py文件中使用该方法的示例

from django.apps import AppConfig

from my_app.images import thumbnail

class MyAppConfig(AppConfig):
    name = 'my_app'

    def ready(self):
        from my_app.models import Profile

        thumbnail.queue(Profile, build="src")

默认情况下，queue监听模型上任何ImageField的保存。使用fields参数限制要排队图像的字段

• None表示模型上的所有文件字段
• 字段必须是一个字段类或子类（默认是ImageField）
• 要匹配的字段名称列表（信号仍然只在文件字段上触发）

queued_img 信号

每当缺少图像元素且尚未排队构建时，都会触发此信号。

它可以用于使用celery或其他任务运行器在任务中处理队列。以下是一个tasks.py的示例

from easy_images.management.process_queue import process_queue

@app.task
def build_img_queue():
    process_queue()

在您的apps.py文件中，连接此接收器

from django.apps import AppConfig

from easy_images.signals import queued_img

class MyAppConfig(AppConfig):
    name = 'my_app'

    def ready(self):
        from my_app.tasks import build_img_queue

        # Kick off build task as soon as any image is queued.
        queued_img.connect(lambda **kwargs: build_img_queue.delay(), weak=False)
        # Also start the build task as soon as the app is ready in case there are already queued images.
        build_img_queue.delay()