跳转至
quickthumb
全部文档

效果

效果(Effects)用于改变单个图层的绘制外观。每种图层类型支持其特定的效果集合,传入不支持的效果将抛出 ValidationError。

效果 文本(Text) 图像、SVG、视频 形状(Shape) 背景(Background)
Stroke ✓ ✓ ✓ —
Shadow ✓ ✓ ✓ —
Glow ✓ ✓ ✓ —
Filter — ✓ — ✓
Background ✓ — — —
Grain — ✓ — ✓
Duotone — ✓ — —
InnerShadow — ✓ ✓ —
BackdropBlur — ✓ ✓ —

将效果以列表形式传递给任意图层的 effects 参数:

from quickthumb import Shadow, Stroke

canvas.text(
    content="CLICK NOW",
    size=96,
    color="#FFFFFF",
    effects=[
        Stroke(width=4, color="#000000"),
        Shadow(offset_x=4, offset_y=4, color="#000000", blur_radius=8),
    ],
)

Stroke

围绕文本字形、图像边缘或形状轮廓绘制描边。

from quickthumb import Stroke

Stroke(width=4, color="#000000")
参数 类型 说明
width int 描边粗细(像素)。必须为正整数。
color str 描边颜色。十六进制字符串("#RRGGBB" 或 "#RRGGBBAA")。

示例

from quickthumb import Stroke, TextPart

canvas.text(
    content=[
        TextPart(text="BIG TEXT", color="#FFFFFF", effects=[Stroke(width=6, color="#000000")]),
    ],
    size=108,
    position=("8%", "50%"),
    align=("left", "middle"),
)

Shadow

为图层添加带偏移的外阴影(投影)。

from quickthumb import Shadow

Shadow(offset_x=4, offset_y=8, color="#000000", blur_radius=12)
参数 类型 默认值 说明
offset_x int 必填 水平阴影偏移量(像素)。可为负数。
offset_y int 必填 垂直阴影偏移量(像素)。可为负数。
color str 必填 阴影颜色。十六进制字符串。
blur_radius int 0 模糊扩散半径(像素)。非负整数。

示例

from quickthumb import Shadow

canvas.image(
    path="portrait.png",
    position=("74%", "54%"),
    width=420,
    height=520,
    effects=[Shadow(offset_x=0, offset_y=14, color="#000000", blur_radius=24)],
)

Glow

围绕图层边缘添加柔和的彩色光晕外发光。

from quickthumb import Glow

Glow(color="#B8FF00", radius=16, opacity=0.35)
参数 类型 默认值 说明
color str 必填 发光颜色。十六进制字符串。
radius int 必填 发光扩散半径(像素)。正整数。
opacity float 1.0 发光强度,取值范围 0.0 到 1.0。

示例

from quickthumb import Glow

canvas.text(
    content="ELECTRIC",
    size=96,
    color="#FFFFFF",
    effects=[Glow(color="#22d3ee", radius=24, opacity=0.5)],
)

Filter

应用图像处理调整滤镜。适用于背景图层和图像图层。

from quickthumb import Filter

Filter(blur=4, brightness=0.75, contrast=1.1, saturation=0.9)
参数 类型 默认值 说明
blur int 0 高斯模糊半径。非负整数。
brightness float 1.0 亮度倍数。正浮点数。1.0 = 原始亮度,0.5 = 半亮度。
contrast float 1.0 对比度倍数。正浮点数。1.0 = 原始对比度。
saturation float 1.0 饱和度倍数。非负浮点数。0.0 = 灰度黑白,1.0 = 原始饱和度。

所有参数默认值均为中性无调整,因此只需指定你希望更改的参数。

示例

from quickthumb import Filter

canvas.background(
    image="hero.jpg",
    fit="cover",
    effects=[Filter(blur=6, brightness=0.6, saturation=0.8)],
)

Background(文本背景框)

在文本块下方绘制填充的圆角矩形背景框。仅适用于文本图层。

from quickthumb import Background

Background(color="#111827CC", padding=(16, 24), border_radius=14, opacity=1.0)
参数 类型 默认值 说明
color str 必填 填充颜色。十六进制字符串("#RRGGBB" 或 "#RRGGBBAA")。
padding int \| tuple 0 内边距。单个 int 表示四边统一,(vertical, horizontal) 或 (top, right, bottom, left)。
border_radius int 0 圆角半径(像素)。非负整数。
opacity float 1.0 填充不透明度,取值范围 0.0 到 1.0。

示例

from quickthumb import Background

canvas.text(
    content="BREAKING NEWS",
    size=72,
    color="#FFFFFF",
    position=("8%", "50%"),
    align=("left", "middle"),
    effects=[
        Background(color="#CC0000", padding=(12, 20), border_radius=8),
    ],
)

说明

作为效果的 Background 与 .background() 全局背景图层构建器相互独立。该效果仅包裹紧贴文本块呈现;而全局背景图层则覆盖整个画布。


Grain

为背景或图像图层添加胶片噪点颗粒。

from quickthumb import Grain

Grain(intensity=0.12, monochrome=True, blend_mode="overlay", opacity=1.0)
参数 类型 默认值 说明
intensity float 必填 噪点强度幅度,取值从 0.0(无噪点)到 1.0(最大值)。
monochrome bool True True = 单色亮度噪点(灰阶颗粒);False = 各通道独立的彩色噪点。
blend_mode str "overlay" 噪点与图层的混合模式。可选 "overlay"、"screen"、"multiply"、"normal" 之一。
opacity float 1.0 整体颗粒透明度,取值从 0.0(不可见)到 1.0(完全可见)。
seed int \| None None 用于生成确定性输出的随机数种子。None 表示每次渲染生成不同随机噪点。

intensity=0.0 表示不添加任何噪点。

示例

from quickthumb import Canvas, Grain

canvas = (
    Canvas(1280, 720)
    .background(
        color="#1A1A2E",
        effects=[Grain(intensity=0.12, monochrome=True)],
    )
    .image(
        path="portrait.png",
        position=("70%", "50%"),
        width=400,
        height=500,
        align=("center", "middle"),
        effects=[Grain(intensity=0.08, monochrome=False, blend_mode="overlay", opacity=0.6)],
    )
)

说明

Grain 适用于背景、图像、SVG 及视频图层,不支持文本或形状图层。


Duotone

根据亮度将图层重新映射为两种指定颜色:暗部区域映射为 shadows 阴影颜色,亮部区域映射为 highlights 高光颜色,中间色阶平滑过渡。非常适合将摄影照片快速融入品牌专属配色。

from quickthumb import Duotone

Duotone(shadows="#0A1730", highlights="#7FADFF", opacity=1.0)
参数 类型 默认值 说明
shadows str 必填 映射图像最暗区域的颜色。
highlights str 必填 映射图像最亮区域的颜色。
opacity float 1.0 替换原始色彩的效果强度,取值从 0.0 到 1.0。

InnerShadow

在图层边缘内部绘制的内阴影,呈现凹陷内嵌的视觉质感。

from quickthumb import InnerShadow

InnerShadow(offset_x=0, offset_y=6, color="#00000080", blur_radius=12)
参数 类型 默认值 说明
color str 必填 阴影颜色;支持颜色自带的 Alpha 透明通道。
offset_x int 0 水平偏移量(像素)。
offset_y int 0 垂直偏移量(像素)。
blur_radius int 0 模糊半径(像素)。
opacity float 1.0 整体强度,取值从 0.0 到 1.0。

BackdropBlur

对图层形状所遮盖的下方已有绘制内容进行模糊处理,产生类似于毛玻璃(磨砂玻璃)的半透明质感。通常与半透明填充色搭配使用,使图层仍呈现为清晰的面板:

from quickthumb import BackdropBlur, Canvas

canvas = (
    Canvas(1280, 720)
    .background(image="photo.jpg", fit="cover")
    .shape(
        shape="rectangle",
        position=(80, 440),
        width=640,
        height=200,
        color="#FFFFFF33",
        border_radius=24,
        effects=[BackdropBlur(radius=24)],
    )
)
参数 类型 默认值 说明
radius int 必填 模糊半径(像素)。
opacity float 1.0 背景模糊呈现强度,取值从 0.0 到 1.0。