核心概念
画布即图层列表
Canvas 拥有指定尺寸和一组有序图层列表。每个图层方法都会追加一个图层并返回画布实例,因此支持链式调用:
from quickthumb import Canvas
canvas = (
Canvas(1280, 720)
.background(color="#0F172A")
.text(content="Hello", size=64, color="#FFFFFF", align="center")
.outline(width=8, color="#22D3EE")
)
canvas.render("hello.png")
图层严格按照添加顺序依次绘制。先添加的图层位于底层,最后添加的图层位于顶层。因此构建图像的过程就像作画:先画背景,最后绘制细节。
图层类型
| 方法 | 添加内容 | 参考文档 |
|---|---|---|
.background() |
全画布纯色、渐变或图片 | 背景 |
.text() |
普通文本或带样式的 TextPart 列表 |
文字 |
.image() |
指定位置的图片,支持可选的抠图去背景 | 图像 |
.shape() |
矩形、椭圆、胶囊形、三角形、星形或多边形 | 形状 |
.svg() |
SVG 文件,如图标或徽标(需要 svg 额外依赖) |
SVG |
.video() |
视频片段,用于动效导出 | 视频 |
.chart(), .qr_code() |
柱状图、折线图或二维码 | 数据可视化 |
.counter() |
从一个数值过渡到另一个数值的动态计数器 | Canvas |
.group() |
自动排列子图层的行或列容器 | 分组(自动布局) |
.outline() |
围绕画布边缘的描边线框 | 描边 |
.custom(fn) |
自定义绘图函数,可直接在 Pillow 图像上绘制 | Canvas |
位置与对齐
position 是一个 (x, y) 坐标对。每个坐标值可以是像素数或画布百分比,两者支持混用:
canvas.shape(shape="rectangle", position=(64, 64), width=200, height=80, color="#CC0000")
canvas.text(content="Hello", size=72, color="#FFFFFF", position=("8%", 360))
align 决定了图层的哪个基准点落在该坐标位置上。默认值为左上角。设置 align=("center", "middle") 会将图层中心对齐到该坐标;设置 align=("right", "bottom") 并配合 position=(1280, 720),则无论图层自身尺寸多大,都能将其固定在 1280×720 画布的右下角。
align 支持多种写法:
align=("center", "middle") # (horizontal, vertical)
align="center" # same as ("center", "middle")
align="bottom-right"
align=Align.BOTTOM_RIGHT
水平方向的有效值为 left、center 和 right;垂直方向为 top、middle 和 bottom。如果文本图层设置了 align 但未指定 position,画布会根据对齐规则自动定位,例如 align="center" 会将其水平居中。
效果
效果(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),
],
)
并非所有效果都适用于所有图层:
| 图层 | 支持的效果 |
|---|---|
| Background(背景) | Filter, Grain |
| Text(文字) | Stroke, Shadow, Glow, Background(文字背景框) |
| Shape(形状) | Stroke, Shadow, Glow, InnerShadow, BackdropBlur |
| Image, SVG, Video(图像、SVG、视频) | Stroke, Shadow, Glow, Filter, Grain, Duotone, InnerShadow, BackdropBlur |
为图层传入不支持的效果会触发 ValidationError。各效果的完整参数请参阅效果参考。
富文本
当文本样式完全统一时,传入普通字符串即可。如果需要为不同文字片段应用不同样式,可传入 TextPart 列表:
from quickthumb import TextPart
canvas.text(
content=[
TextPart(text="5 ", color="#FBBF24"),
TextPart(text="WAYS TO WIN", color="#FFFFFF"),
],
size=80,
weight=900,
position=("8%", "55%"),
align=("left", "middle"),
)
图层级别的设置(本例中的 size 和 weight)会应用于每个文字片段,除非片段自身进行了单独覆盖。TextPart 支持单独覆盖 color、size、font、weight、bold、italic、letter_spacing、line_height 以及 effects。
渐变、混合模式与填充方式
背景除了纯色和图片外,还支持传入 gradient 渐变:
from quickthumb import LinearGradient, RadialGradient
canvas.background(gradient=LinearGradient(angle=135, stops=[("#FF5733", 0.0), ("#3333FF", 1.0)]))
canvas.background(gradient=RadialGradient(center=(0.5, 0.5), stops=[("#FF5733", 0.0), ("#3333FF", 1.0)]))
渐变色标(stops)中的颜色支持 Alpha 通道(例如 "#00000080"),常用于压暗文字下方的照片区域。
背景或图像图层的 blend_mode 用于控制其与下层内容的混合模式:normal、multiply、screen、overlay、darken 或 lighten。
fit 决定了图片如何填充其边界框:cover 会填满整个区域并裁剪多余部分(背景图层的默认值),contain 会完整容纳整张图片,fill 则会拉伸填充。
自动布局
手动指定绝对位置的文字,在文案变长时容易产生重叠或溢出。group 容器会自动测量其子图层,并将它们排列为行或列;你只需定位该容器一次,容器就会自动为其子图层计算排版:
canvas.group(
children=[
{"type": "shape", "shape": "pill", "width": 120, "height": 36, "color": "#E94560"},
{"type": "text", "content": "AUTO LAYOUT", "size": 96, "color": "#FFFFFF", "weight": 900},
{"type": "text", "content": "Longer copy pushes the rest down", "size": 40, "color": "#A2A8D3"},
],
direction="column",
gap=24,
position=("8%", "50%"),
align=("left", "middle"),
)
子图层无需设置 position,且分组支持嵌套。详情参阅分组(自动布局)。
JSON 规范
上述所有内容均可使用 JSON 编写来代替 Python 代码,画布支持双向转换:
唯一的例外是 .custom(fn),因为 Python 函数无法序列化为 JSON。
JSON 规范还支持在 theme 块中统一定义颜色和尺寸,并通过 $theme.<path> 引用:
{
"kind": "canvas",
"width": 1280,
"height": 720,
"theme": { "colors": { "primary": "#B8FF00" }, "sizes": { "title": 96 } },
"layers": [
{ "type": "text", "content": "Hello", "size": "$theme.sizes.title", "color": "$theme.colors.primary" }
]
}
详情参阅 JSON Schema 与 AI 工作流。
路径动效
Canvas.path() 支持 SVG 路径数据、填充(包含渐变)以及虚线描边。路径具有固定的 width/height 视口,不仅用于裁切局部绘制,还在旋转和缩放期间定义其归一化的 anchor 锚点:
from quickthumb import AnimationSpec, Canvas, KeyframeSpec, ScaleTrack, TimingSpec
canvas = Canvas(320, 240).path(
"M2 20C2 2 38 2 38 20C38 38 2 38 2 20Z", (100, 80), 40, 40,
"#38B6A080", anchor=(0.5, 0.5),
animation=AnimationSpec.timeline(
ScaleTrack(keyframes=[KeyframeSpec(time=0, value=1), KeyframeSpec(time=1, value=4)]),
timing=TimingSpec(duration=1), easing="linear",
),
)
frame = canvas.render_frame(0.75)
使用轨道时间轴为路径制作动效。不同导出格式对路径动效的支持程度不同;路径暂不支持预设动效、错峰(stagger)、作为 Group 子元素以及变换父级关联。动画和导出详情请参阅 Path API。
错误与检查
添加图层时会立即校验参数,此时尚未开始绘制:
from quickthumb import ValidationError
try:
canvas.text(content="Hello", size=64, color="#FFF")
except ValidationError as error:
print(error) # /color: invalid hex color: #FFF
仅在绘制期间暴露的问题(例如网络下载失败)会抛出 RenderingError;本地文件不存在则会抛出 MissingAssetError。所有错误均包含结构化的 details 属性;详情参阅结构化错误。
画布即便参数合法,也可能在视觉上存在排版问题。canvas.diagnose() 无需实际渲染文件即可检测文本过小、文字溢出画布、对比度不足、图层被完全遮挡等常见缺陷。详情参阅诊断与 CLI。