文本
.text() 用于添加文本图层。内容可以是普通字符串,也可以是由 TextPart 对象组成的列表以实现分段样式定制。
方法签名
canvas.text(
content,
font=None,
font_source="auto",
font_variations=None,
emoji_style="monochrome",
size=None,
color=None,
fill=None,
position=None,
align=None,
bold=False,
italic=False,
weight=None,
max_width=None,
max_height=None,
min_size=1,
balance_lines=False,
effects=None,
line_height=None,
letter_spacing=None,
auto_scale=False,
rotation=0.0,
opacity=1.0,
)
参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
content |
str \| list[TextPart] |
必填 | 文本内容。普通字符串或用于富文本的 TextPart 列表。 |
font |
str \| None |
None |
字体家族名称、本地文件路径或远程 Web 字体 URL。 |
font_source |
"auto" \| "system" \| "google" |
"auto" |
字体查找源。"google" 会下载并缓存指定的 Google Font。 |
font_variations |
dict[str, float] \| None |
None |
OpenType 可变轴参数,例如 {"wght": 650}。 |
emoji_style |
"monochrome" \| "color" |
"monochrome" |
Emoji 表情呈现偏好。 |
size |
int \| None |
None |
字号(像素)。必须为正整数。 |
color |
str \| None |
None |
默认文本颜色。十六进制字符串("#RRGGBB" 或 "#RRGGBBAA")。 |
fill |
LinearGradient \| RadialGradient \| TextFillImage \| None |
None |
应用于字形文字的渐变或图像填充。设置后在视觉上优先于 color。参见渐变与图像填充。 |
position |
tuple \| None |
None |
(x, y) 坐标。取值可为整数(像素)或百分比字符串("50%")。 |
align |
str \| Align \| tuple \| None |
None |
文本块对齐方式。参见 Align 对齐取值。 |
bold |
bool |
False |
粗体标志。与 weight 互斥。 |
italic |
bool |
False |
斜体标志。 |
weight |
int \| str \| None |
None |
CSS 风格字重(例如 700、900、"bold")。与 bold 互斥。 |
max_width |
int \| str \| None |
None |
折行宽度(像素或百分比字符串,如 "60%")。 |
max_height |
int \| str \| None |
None |
文本块最大高度(像素或百分比字符串)。 |
min_size |
int |
1 |
自动缩放自适应时允许的最小字号。 |
balance_lines |
bool |
False |
设置 max_width 时平衡折行后的各行长度。 |
effects |
list \| None |
[] |
效果列表:Stroke、Shadow、Glow、Background。 |
line_height |
float \| None |
None |
行高倍数。正浮点数。 |
letter_spacing |
int \| None |
None |
水平字间距微调(像素)。 |
auto_scale |
bool |
False |
自动缩小字号直至文本容纳在 max_width 和/或 max_height 范围内。 |
rotation |
float |
0.0 |
旋转角度(度数)。 |
opacity |
float |
1.0 |
图层不透明度,范围为 0.0 至 1.0。 |
Align 对齐取值
align 支持以下任意一种写法:
align="center" # shorthand
align="top-left" # compound string
align=("left", "middle") # (horizontal, vertical) tuple
align=Align.BOTTOM_RIGHT # enum
| 字符串 | 枚举 | 位置说明 |
|---|---|---|
"center" |
Align.CENTER |
水平与垂直居中 |
"left" |
Align.LEFT |
左对齐,垂直居中 |
"right" |
Align.RIGHT |
右对齐,垂直居中 |
"top-left" |
Align.TOP_LEFT |
左上角 |
"top-center" |
Align.TOP_CENTER |
顶部边缘水平居中 |
"top-right" |
Align.TOP_RIGHT |
右上角 |
"bottom-left" |
Align.BOTTOM_LEFT |
左下角 |
"bottom-center" |
Align.BOTTOM_CENTER |
底部边缘水平居中 |
"bottom-right" |
Align.BOTTOM_RIGHT |
右下角 |
使用元组时:水平取值为 left、center、right;垂直取值为 top、middle、bottom。
示例
普通文本
使用 TextPart 定制富文本
from quickthumb import Stroke, TextPart
canvas.text(
content=[
TextPart(text="5 ", color="#FBBF24", weight=900),
TextPart(text="WARNING SIGNS", color="#FFFFFF", weight=900),
],
size=72,
position=("8%", "55%"),
align=("left", "middle"),
)
配合效果使用
from quickthumb import Background, Glow, Shadow, Stroke
canvas.text(
content="BREAKING",
size=96,
color="#FFFFFF",
position=("8%", "50%"),
align=("left", "middle"),
weight=900,
max_width="65%",
effects=[
Stroke(width=4, color="#000000"),
Shadow(offset_x=4, offset_y=4, color="#000000", blur_radius=8),
Glow(color="#B8FF00", radius=16, opacity=0.25),
Background(color="#111827CC", padding=(16, 24), border_radius=14),
],
)
自动缩小自适应
canvas.text(
content="This is a very long title that should fit",
size=80,
color="#FFFFFF",
max_width="70%",
auto_scale=True,
position=("8%", "50%"),
align=("left", "middle"),
)
使用 Web 字体
canvas.text(
content="Custom Font",
font="https://fonts.gstatic.com/s/inter/v13/UcCO3FwrK3iLTeHuS_fvQtMwCp50KnMw2boKoduKmMEVuLyfAZ9hiA.woff2",
size=72,
color="#FFFFFF",
align="center",
)
Web 字体 URL
当 font 为 URL 时,bold、italic 和 weight 将被忽略,因为该 URL 已经精确指向某个具体字体文件。如需不同样式,请分别使用独立的 URL,或者指定字体家族名称配合 font_source="google",让 weight 和 italic 自动为您选择匹配的文件。
渐变与图像填充
使用渐变或图像填充文本字形,而非单调纯色。向 fill 传入 LinearGradient、RadialGradient 或 TextFillImage:
from quickthumb import Canvas, LinearGradient, RadialGradient, TextFillImage, TextPart
# Linear gradient headline
canvas.text(
content="GRADIENT",
size=120,
fill=LinearGradient(angle=90, stops=[("#FF6B6B", 0.0), ("#4ECDC4", 1.0)]),
position=("50%", "50%"),
align="center",
)
# Image-filled text
canvas.text(
content="TEXTURE",
size=140,
fill=TextFillImage(path="fire_texture.jpg", fit="cover"),
position=("50%", "50%"),
align="center",
)
# Per-segment fills using TextPart
canvas.text(
content=[
TextPart(
text="HOT ",
fill=LinearGradient(angle=45, stops=[("#FF4500", 0.0), ("#FFD700", 1.0)]),
weight=900,
),
TextPart(
text="COLD",
fill=LinearGradient(angle=45, stops=[("#00BFFF", 0.0), ("#8A2BE2", 1.0)]),
weight=900,
),
],
size=110,
position=("50%", "50%"),
align="center",
)
在 TextPart 上设置的 fill 仅覆盖该片段自身的图层级 fill。fill 和 color 相互独立;二者同时设置时,fill 在视觉呈现上具有更高优先级。图像填充配置选项请参见 TextFillImage。
TextPart
TextPart 用于在同一文本图层内为不同文本片段定义独立样式。
from quickthumb import Stroke, TextPart
TextPart(
text="HOT",
color="#FF3B30",
fill=None,
size=56,
font="Impact",
font_source=None,
font_variations=None,
emoji_style=None,
weight=900,
italic=False,
line_height=None,
letter_spacing=0,
effects=[Stroke(width=3, color="#000000")],
)
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
text |
str |
必填 | 文本片段。不可为空。 |
color |
str \| None |
None |
当前片段的覆盖颜色(十六进制)。 |
fill |
LinearGradient \| RadialGradient \| TextFillImage \| None |
None |
当前片段的渐变或图像填充。仅覆盖当前片段的图层级 fill。 |
size |
int \| None |
None |
当前片段的字号覆盖值。 |
font |
str \| None |
None |
当前片段的字体覆盖值。 |
font_source |
"auto" \| "system" \| "google" \| None |
None |
字体源覆盖值。None 表示继承图层设置;显式设置将覆盖图层。 |
font_variations |
dict[str, float] \| None |
None |
可变轴参数覆盖。None 表示继承图层;{} 会显式清除继承的轴参数。 |
emoji_style |
"monochrome" \| "color" \| None |
None |
Emoji 风格覆盖。None 表示继承;"monochrome" 会显式覆盖。 |
bold |
bool \| None |
None |
粗体覆盖。与 weight 互斥。 |
italic |
bool \| None |
None |
斜体覆盖。 |
weight |
int \| str \| None |
None |
字重覆盖。与 bold 互斥。 |
line_height |
float \| None |
None |
行高倍数覆盖。 |
letter_spacing |
int \| None |
None |
字间距覆盖。 |
effects |
list[TextEffect] |
[] |
片段级效果:Stroke、Shadow、Glow、Background。 |
文本动画
使用 RangeSelector 可以实现按词或按字符的文字动画:
from quickthumb import AnimationSpec, Canvas, KeyframeSpec, PositionTrack, RangeSelector, TimingSpec
canvas = Canvas(800, 400).text(
"Words appear one by one",
size=48,
color="#FFFFFF",
position=(50, 150),
animation=AnimationSpec.timeline(
PositionTrack(keyframes=[
KeyframeSpec(time=0, value=(0, 20)),
KeyframeSpec(time=0.4, value=(0, 0)),
]),
selector=RangeSelector(
target="words", # "words", "lines", or "characters"
offset=[KeyframeSpec(time=0, value=-100), KeyframeSpec(time=2, value=100)],
),
timing=TimingSpec(duration=2),
),
)
有关选择器形态、时序及颜色过渡的详细信息,请参见文本范围选择器。
校验规则
content为必填项,且不能是空列表。TextPart.text不能为空字符串。TextLayer与TextPart中weight和bold=True均互斥。auto_scale=True要求必须设置max_width或max_height。max_width必须为正整数或类似于"60%"的正百分比字符串。position中的百分比字符串必须符合-?N%模式(负百分比有效)。fill和color为独立字段;同时设置时fill具有更高视觉优先级。TextFillImage.path支持本地文件路径和远程 URL;本地文件不存在时会在渲染时抛出FileNotFoundError。