django-thumbnails 0.8.0

设计

• 使用Django存储API
• 使用灵活的元数据存储。使用Redis作为元数据存储。
• 支持创建不同格式的缩略图，例如从JPG到WEBP以减小文件大小

支持的图像格式

• JPG/JPEG
• GIF
• PNG
• WEBP

安装

• 将缩略图添加到settings.py中的INSTALLED_APPS。
• 运行python manage.py migrate以创建数据库元数据后端。

用法

settings.py

THUMBNAILS = {
    'METADATA': {
        'BACKEND': 'thumbnails.backends.metadata.DatabaseBackend',
    },
    'STORAGE': {
        'BACKEND': 'django.core.files.storage.FileSystemStorage',
        # You can also use Amazon S3 or any other Django storage backends
    },
    'SIZES': {
        'small': {
            'PROCESSORS': [
                {'PATH': 'thumbnails.processors.resize', 'width': 10, 'height': 10},
                {'PATH': 'thumbnails.processors.crop', 'width': 80, 'height': 80}
            ],
            'POST_PROCESSORS': [
                {
                    'PATH': 'thumbnails.post_processors.optimize',
                    'png_command': 'optipng -force -o7 "%(filename)s"',
                    'jpg_command': 'jpegoptim -f --strip-all "%(filename)s"',
                },
            ],
        },
        'large': {
            'PROCESSORS': [
                {'PATH': 'thumbnails.processors.resize', 'width': 20, 'height': 20},
                {'PATH': 'thumbnails.processors.flip', 'direction': 'horizontal'}
            ],
        },
        'watermarked': {
            'PROCESSORS': [
                {'PATH': 'thumbnails.processors.resize', 'width': 20, 'height': 20},
                # Only supports PNG. File must be of the same size with thumbnail (20 x 20 in this case)
                {'PATH': 'thumbnails.processors.add_watermark', 'watermark_path': 'watermark.png'}
            ],
        }
    }
}

如果您希望使用Redis作为元数据存储后端（出于性能原因）

THUMBNAILS = {
    'METADATA': {
        'PREFIX': 'thumbs',
        'BACKEND': 'thumbnails.backends.metadata.RedisBackend',
        'db': 2,
        'port': 6379,
        'host': 'localhost',
    },
}

图像处理器

django-thumbnails附带一些内置图像处理器

    # To use the following processors, put the arguments of processors in SIZES definition
    thumbnails.processors.resize(width, height, method) ## `method` can be `stretch`, `fit` or `fill`
    thumbnails.processors.rotate(degrees)
    thumbnails.processors.flip(direction)
    thumbnails.processors.crop(width, height, center)
    thumbnails.processors.add_watermark(watermark_path)

处理器按定义顺序依次应用。

存储后端

自版本0.5.0起，每个字段都可以自定义存储后端。如果您想特定字段使用不同的存储后端，您可以在声明字段时直接指定它。例如

class Food(models.Model):
    image = ImageField(storage=FileSystemStorage(), upload_to='food')

指定字段的存储将用于而不是在设置中指定的存储。

元数据后端

如果您想特定字段使用不同的元数据后端，您可以在声明字段时直接指定它。例如

class Food(models.Model):
    image = ImageField(metadata_backend=CustomMetadataBackend(), upload_to='food')

指定字段的元数据后端将用于而不是在设置中指定的元数据后端。

在Python中

from thumbnails.fields import ImageField

class Food(models.Model):
    image = ImageField()


food = Food.objects.latest('id')
food.image.thumbnails.all()
food.image.thumbnails.small  # Generates "small" sized thumbnail
food.image.thumbnails.large  # Generates "large" sized thumbnail
food.image.thumbnails.small.url  # Returns "small" sized thumbnail URL

以下是您如何在Django模板中使用它的示例

{{ food.image.thumbnails.small.url }}  # Returns "small" sized thumbnail URL

使用resize_source_to在保存图像时调整其大小

from thumbnails.fields import ImageField

class Food(models.Model):
    image = ImageField(resize_source_to="medium")

假设“中等”是您在设置中定义的大小。通过传递“中等”，您的保存的图片将被调整到“中等”大小。

使用预生成的尺寸，在保存图片时将其缩略图保存到存储后端。

from thumbnails.fields import ImageField

class Food(models.Model):
    image = ImageField(pregenerated_sizes=["small", "large", "medium")

当删除图片时，您可以选择这样做以保留缩略图。

banner.image.delete(with_thumbnails=False)

性能

如果您需要一次性获取多个缩略图，请使用提供的fetch_thumbnails函数以提高性能。fetch_thumbnails使用Redis管道一次性检索缩略图元数据，避免多次往返Redis。

from thumbnails.field import fetch_thumbnails

food_a = Food.objects.get(id=1)
food_b = Food.objects.get(id=2)

fetch_thumbnails([food_a.image, food_b.image], ['small', 'large'])

这样，当我们获取像thumbnail1.size_small或thumbnail1.all()这样的缩略图时，我们不再需要查询Redis。此功能目前仅适用于Redis元数据后端。

管理命令

如果您更改了大小定义并想要重新生成缩略图，请使用

python manage.py delete_thumbnails --model=app.Model --size=thumbnail_size_to_delete

运行测试

要运行测试

`which django-admin.py` test thumbnails --settings=thumbnails.tests.settings --pythonpath=.

变更日志

版本 0.8.0 (2024-07-24)

• 如果不存在，自动创建一个Source图像。此功能使得将常规ImageField迁移到django-thumbnails变得更加容易。感谢@JobDoesburg！
• 添加了对Python 3.13的兼容性。感谢@nZac！
• ImageField现在支持自定义metadata后端。感谢@marsha97！

版本 0.7.0 (2022-01-03)

• 与django 4.0的兼容性。感谢@yosephbernandus！
• 改进了setup.py。感谢@Le09！

版本 0.6.0 (2021-05-28)

• 添加了对水印缩略图的支持。感谢@marsha97！

版本 0.5.0 (2021-05-1)

• 现在您可以将storage关键字参数传递给ImageField，以便为不同的字段指定不同的存储后端。感谢@marsha97！
• 调用image.delete(with_thumbnails=True)将删除原始图像以及所有缩略图。感谢@marsha97！

版本 0.4.0 (2021-01-08)

• 支持Django >= 3.0。感谢@christianciu！
• 向ImageField添加了pregenerated_sizes，允许在上传时预生成缩略图。感谢@marsha97！
• 缩略图可以生成不同的格式（例如：将JPG源图像转换为WEBP缩略图）。感谢@yosephbernandus！

版本 0.3.2

• 修复了fetch_thumbnails()中的另一个错误。感谢@marsha97！

版本 0.3.1

• 修复了fetch_thumbnails()错误。感谢@marsha97！

版本 0.3.0

• 添加了fetch_thumbnails()命令，以从Redis中获取多个缩略图元数据。感谢@marsha97！

版本 0.2.2

• 修复了可能导致过度访问Redis的RedisBackend.get_thumbnail()错误。感谢@marsha97！

版本 0.2.1

• 添加了对Django 1.11、2.0和2.1的支持

版本 0.2.0

• 改善了具有大量缩略图的字段的性能
• 添加了对Django 1.8、1.9和1.10的支持

版本 0.1.3

• 修复了Django 1.8中的弃用警告

版本 0.1.2

• 修复了Django 1.8中的弃用警告

版本 0.1.1

• 使用shortuuid代替uuid4()以提高空间效率

版本 0.1.0

• 首次公开发布

截至2015年2月，此库适用于生产使用，并在印尼的CRM/忠诚度系统Stamps中使用了超过一年。感谢Stamps！