matplotlib.text

用于在图形中包含文本的类。

class matplotlib.text.Text(x=0, y=0, text='', *, color=None, verticalalignment='baseline', horizontalalignment='left', multialignment=None, fontproperties=None, rotation=None, linespacing=None, rotation_mode=None, usetex=None, wrap=False, transform_rotates_text=False, parse_math=None, antialiased=None, **kwargs)

基类: Artist

处理在窗口或数据坐标系中存储和绘制文本。

在 x, y 处创建一个包含字符串 text 的 Text 实例。

文本相对于锚点 (x, y) 进行对齐，对齐方式由 horizontalalignment（默认：'left'）和 verticalalignment（默认：'baseline'）决定。另请参阅 文本对齐。

虽然 Text 接受 'label' 关键字参数，但默认情况下它不会添加到图例的句柄中。

有效的关键字参数有：

属性	描述
agg_filter	一个过滤函数，它接受一个 (m, n, 3) 浮点数组和一个 dpi 值，并返回一个 (m, n, 3) 数组以及图像左下角的两个偏移量
alpha	浮点数或 None
animated	布尔值
antialiased	布尔值
backgroundcolor	color
bbox	包含 FancyBboxPatch 属性的字典或 None
clip_box	未知
clip_on	未知
clip_path	未知
color 或 c	color
figure	Figure 或 SubFigure
fontfamily 或 family 或 fontname	{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}
fontfeatures	字符串列表、字符串元组或 None
fontproperties 或 font 或 font_properties	font_manager.FontProperties 或 str 或 pathlib.Path
fontsize 或 size	float 或 {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}
fontstretch 或 stretch	{0-1000 范围内的数值, 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}
fontstyle 或 style	{'normal', 'italic', 'oblique'}
fontvariant 或 variant	{'normal', 'small-caps'}
fontweight 或 weight	{0-1000 范围内的数值, 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}
gid	str
horizontalalignment 或 ha	{'left', 'center', 'right'}
in_layout	布尔值
label	object
language	str 或 None
linespacing	'normal' 或浮点数，默认：'normal'
math_fontfamily	str
mouseover	布尔值
multialignment 或 ma	{'left', 'right', 'center'}
parse_math	布尔值
path_effects	AbstractPathEffect 的列表
picker	None 或 布尔值 或 浮点数 或 可调用对象
position	(浮点数, 浮点数)
rasterized	布尔值
rotation	float 或 {'vertical', 'horizontal'}
rotation_mode	{None, 'default', 'anchor', 'xtick', 'ytick'}
sketch_params	(scale: 浮点数, length: 浮点数, randomness: 浮点数)
snap	布尔值或 None
text	object
transform	变换
transform_rotates_text	布尔值
url	str
usetex	布尔值，默认：rcParams["text.usetex"]（默认：False）
verticalalignment 或 va	{'baseline', 'bottom', 'center', 'center_baseline', 'top'}
visible	布尔值
wrap	布尔值
x	浮点数
y	浮点数
zorder	浮点数

contains(mouseevent)

返回鼠标事件是否发生在文本的轴对齐边界框内。

draw(renderer)

使用给定的渲染器绘制 Artist（及其子对象）。

如果美工对象不可见（Artist.get_visible 返回 False），则此操作无效。

参数:

rendererRendererBase 子类。

备注

此方法在 Artist 子类中被覆盖。

get_antialiased()

返回是否使用抗锯齿渲染。

get_bbox_patch()

返回边界框补丁，如果尚未创建 patches.FancyBboxPatch，则返回 None。

更多详细信息请参阅 Text.set_bbox。

get_c()

get_color 的别名。

get_color()

返回文本颜色。

get_family()

get_fontfamily 的别名。

get_font()

get_fontproperties 的别名。

get_font_properties()

get_fontproperties 的别名。

get_fontfamily()

返回用于字体查找的字体族列表。

另请参阅

font_manager.FontProperties.get_family

get_fontfeatures()

返回要启用的字体特性标签元组。

get_fontname()

返回字体名称字符串。

另请参阅

font_manager.FontProperties.get_name

get_fontproperties()

返回 font_manager.FontProperties。

get_fontsize()

返回以整数表示的字号。

另请参阅

font_manager.FontProperties.get_size_in_points

get_fontstyle()

返回字体样式字符串。

另请参阅

font_manager.FontProperties.get_style

get_fontvariant()

返回字体变体字符串。

另请参阅

font_manager.FontProperties.get_variant

get_fontweight()

返回字符串或数字形式的字体粗细。

另请参阅

font_manager.FontProperties.get_weight

get_ha()

get_horizontalalignment 的别名。

get_horizontalalignment()

返回水平对齐方式字符串。可选值为 'left'、'center' 或 'right'。

get_language()

返回此文本所属的语言。

get_linespacing()

获取行间距。

get_math_fontfamily()

返回由 Matplotlib 渲染的数学文本的字体族名称。

默认值为 rcParams["mathtext.fontset"]（默认：'dejavusans'）。

另请参阅

set_math_fontfamily

get_name()

get_fontname 的别名。

get_parse_math()

返回是否为此 Text 考虑解析数学文本。

get_position()

返回文本的 (x, y) 位置。

get_rotation()

返回范围为 [0, 360) 之间的文本角度（以度为单位）。

get_rotation_mode()

返回文本旋转模式。

get_size()

get_fontsize 的别名。

get_stretch()

返回字符串或数字形式的字体拉伸程度。

另请参阅

font_manager.FontProperties.get_stretch

get_style()

get_fontstyle 的别名。

get_text()

返回文本字符串。

get_tightbbox(renderer=None)

获取美工对象在显示空间中的边界框，考虑裁剪。

参数:

rendererRendererBase, 可选

用于绘制图形的渲染器（即 fig.canvas.get_renderer()）。

返回:

Bbox or None

闭合的边界框（图形像素坐标），如果裁剪导致无交集则返回 None。

另请参阅

Artist.get_window_extent

获取美工边界框，忽略裁剪。

get_transform_rotates_text()

返回变换的旋转是否影响文本方向。

get_unitless_position()

返回文本的无单位 (x, y) 位置。

get_usetex()

返回此 Text 对象是否使用 TeX 进行渲染。

get_va()

get_verticalalignment 的别名。

get_variant()

get_fontvariant 的别名。

get_verticalalignment()

返回垂直对齐方式字符串。可选值为 'top'、'center'、'bottom'、'baseline' 或 'center_baseline'。

get_weight()

get_fontweight 的别名。

get_window_extent(renderer=None, dpi=None)

返回以显示单位表示的、包围文本的 Bbox。

除了内部使用外，这对于在网页上的 png 文件中指定可点击区域也很有用。

参数:

renderer渲染器，可选

需要渲染器来计算边界框。如果 Artist 对象已经被绘制，渲染器会被缓存；因此，只有在第一次绘制之前调用 get_window_extent 时才需要传递此参数。在实践中，通常更容易先触发绘制，例如调用 draw_without_rendering 或 plt.show()。

dpifloat, 可选

计算 bbox 的 dpi 值，默认为 self.get_figure(root=True).dpi（不是渲染器 dpi）；如果需要匹配使用自定义 dpi 值保存的图形区域，则应设置该值。

get_wrap()

返回文本是否可以换行。

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, antialiased=<UNSET>, backgroundcolor=<UNSET>, bbox=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, color=<UNSET>, fontfamily=<UNSET>, fontfeatures=<UNSET>, fontproperties=<UNSET>, fontsize=<UNSET>, fontstretch=<UNSET>, fontstyle=<UNSET>, fontvariant=<UNSET>, fontweight=<UNSET>, gid=<UNSET>, horizontalalignment=<UNSET>, in_layout=<UNSET>, label=<UNSET>, language=<UNSET>, linespacing=<UNSET>, math_fontfamily=<UNSET>, mouseover=<UNSET>, multialignment=<UNSET>, parse_math=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, position=<UNSET>, rasterized=<UNSET>, rotation=<UNSET>, rotation_mode=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, text=<UNSET>, transform=<UNSET>, transform_rotates_text=<UNSET>, url=<UNSET>, usetex=<UNSET>, verticalalignment=<UNSET>, visible=<UNSET>, wrap=<UNSET>, x=<UNSET>, y=<UNSET>, zorder=<UNSET>)

一次性设置多个属性。

a.set(a=A, b=B, c=C)

等同于

a.set_a(A)
a.set_b(B)
a.set_c(C)

除全名属性外，还支持别名，例如 set(lw=2) 等同于 set(linewidth=2)，但同时传入两者会报错。

各个 setter 的调用顺序与 set() 中的参数顺序一致。然而，大多数属性并不相互依赖，因此顺序通常无关紧要。

支持的属性包括：

属性	描述
agg_filter	一个过滤函数，它接受一个 (m, n, 3) 浮点数组和一个 dpi 值，并返回一个 (m, n, 3) 数组以及图像左下角的两个偏移量
alpha	浮点数或 None
animated	布尔值
antialiased	布尔值
backgroundcolor	color
bbox	包含 FancyBboxPatch 属性的字典或 None
clip_box	未知
clip_on	未知
clip_path	未知
color	color
figure	Figure 或 SubFigure
fontfamily 或 fontname	{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}
fontfeatures	字符串列表、字符串元组或 None
fontproperties	font_manager.FontProperties 或 str 或 pathlib.Path
fontsize	float 或 {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}
fontstretch	{0-1000 范围内的数值, 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}
fontstyle	{'normal', 'italic', 'oblique'}
fontvariant	{'normal', 'small-caps'}
fontweight	{0-1000 范围内的数值, 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}
gid	str
horizontalalignment	{'left', 'center', 'right'}
in_layout	布尔值
label	object
language	str 或 None
linespacing	'normal' 或浮点数，默认：'normal'
math_fontfamily	str
mouseover	布尔值
multialignment	{'left', 'right', 'center'}
parse_math	布尔值
path_effects	AbstractPathEffect 的列表
picker	None 或 布尔值 或 浮点数 或 可调用对象
position	(浮点数, 浮点数)
rasterized	布尔值
rotation	float 或 {'vertical', 'horizontal'}
rotation_mode	{None, 'default', 'anchor', 'xtick', 'ytick'}
sketch_params	(scale: 浮点数, length: 浮点数, randomness: 浮点数)
snap	布尔值或 None
text	object
transform	变换
transform_rotates_text	布尔值
url	str
usetex	布尔值，默认：rcParams["text.usetex"]（默认：False）
verticalalignment	{'baseline', 'bottom', 'center', 'center_baseline', 'top'}
visible	布尔值
wrap	布尔值
x	浮点数
y	浮点数
zorder	浮点数

set_antialiased(antialiased)

设置是否使用抗锯齿渲染。

参数:

antialiasedbool

备注

抗锯齿由 rcParams["text.antialiased"]（默认：True）决定，如果文本包含数学表达式，则参数 antialiased 无效。

set_backgroundcolor(color)

设置文本背景颜色。

这是通过 bbox（请参阅 set_bbox）实现的，必要时创建 bbox 补丁。

参数:

color颜色

另请参阅

set_bbox

更改边界框的位置

set_bbox(rectprops)

在文本后/周围绘制一个框。

这可以用来设置文本的背景和/或边框。它是通过文本后的 FancyBboxPatch 实现的（另请参阅 Text.get_bbox_patch）。默认情况下 bbox 补丁为 None，仅在需要时创建。

参数:

rectprops包含 FancyBboxPatch 属性的字典或 None

默认的 boxstyle 为 'square'。patches.FancyBboxPatch 的突变比例（mutation scale）设置为字号大小。

传递 None 可彻底移除 bbox 补丁。

示例

t.set_bbox(dict(facecolor='red', alpha=0.5))

set_c(color)

set_color 的别名。

set_clip_box(clipbox)

设置艺术家的裁剪Bbox。

参数:

clipboxBboxBase 或 None

通常由 TransformedBbox 创建。例如，TransformedBbox(Bbox([[0, 0], [1, 1]]), ax.transAxes) 是添加到 Axes 的 Artist 对象的默认裁剪方式。

set_clip_on(b)

设置艺术家是否使用裁剪。

当为False时，艺术家将会在Axes外部可见，这可能导致意外结果。

参数:

bbool

set_clip_path(path, transform=None)

设置艺术家的裁剪路径。

参数:

pathPatch 或 Path 或 TransformedPath 或 None

裁剪路径。如果提供 Path，则必须同时提供 transform。如果为 None，则移除先前设置的裁剪路径。

transformTransform, 可选

仅在 path 为 Path 时使用，此时给定的 Path 将使用 transform 转换为 TransformedPath。

备注

为了效率，如果 path 是 Rectangle，此方法将裁剪框设置为对应的矩形，并将裁剪路径设置为 None。

出于技术原因（支持 set），也接受元组 (path, transform) 作为单个位置参数。

set_color(color)

设置文本的前景色

参数:

color颜色

set_family(fontname)

set_fontfamily 的别名。

set_font(fp)

set_fontproperties 的别名。

set_font_properties(fp)

set_fontproperties 的别名。

set_fontfamily(fontname)

设置字体族。可以是单个字符串，也可以是按优先级递减的字符串列表。每个字符串可以是真实的字体名称，也可以是通用字体类名称。如果是后者，则将在相应的 rcParams 中查找特定字体名称。

如果构建 Text 实例时使用 fontfamily=None，则字体将设置为 rcParams["font.family"]（默认：['sans-serif']），在对现有 Text 实例调用 set_fontfamily() 时也会执行相同的操作。

参数:

fontname{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}

另请参阅

font_manager.FontProperties.set_family

set_fontfeatures(features)

设置要在字体上启用的特性标签。

参数:

features字符串列表、字符串元组或 None

要与关联字体一起使用的特性标签列表。这些字符串最终会传递给 HarfBuzz，因此支持 hb_feature_from_string() 支持的所有字符串格式。但请注意，明确不支持子范围，行为可能会在未来发生变化。

例如，如果您想要的字体包含启用各种排版替代项的样式集，包括您不想使用的一种（例如，上下文连字），那么您可以传递以下内容来启用一个而不启用另一个

fp.set_features([
    'ss01',  # Use Stylistic Set 1.
    '-clig',  # But disable Contextural Ligatures.
])

可用的字体特性标签可在 https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist 找到。

set_fontname(fontname)

set_fontfamily 的别名。

仅单向别名：getter 不同。

参数:

fontname{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}

另请参阅

font_manager.FontProperties.set_family

set_fontproperties(fp)

设置控制文本的字体属性。

参数:

fpfont_manager.FontProperties 或 str 或 pathlib.Path

如果为 str，则将其解释为由 FontProperties 解析的 fontconfig 模式。如果为 pathlib.Path，则将其解释为字体文件的绝对路径。

set_fontsize(fontsize)

设置字号。

参数:

fontsizefloat 或 {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}

如果是浮点数，则为以点为单位的字号。字符串值表示相对于默认字号的大小。

另请参阅

font_manager.FontProperties.set_size

set_fontstretch(stretch)

设置字体拉伸（水平压缩或扩展）。

参数:

stretch{0-1000 范围内的数值，'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}

另请参阅

font_manager.FontProperties.set_stretch

set_fontstyle(fontstyle)

设置字体样式。

参数:

fontstyle{'normal', 'italic', 'oblique'}

另请参阅

font_manager.FontProperties.set_style

set_fontvariant(variant)

设置字体变体。

参数:

variant{'normal', 'small-caps'}

另请参阅

font_manager.FontProperties.set_variant

set_fontweight(weight)

设置字体粗细。

参数:

weight{0-1000 范围内的数值，'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}

另请参阅

font_manager.FontProperties.set_weight

set_ha(align)

set_horizontalalignment 的别名。

set_horizontalalignment(align)

设置相对于锚点的水平对齐方式。

另请参阅 文本对齐。

参数:

align{'left', 'center', 'right'}

set_language(language)

设置文本语言。

参数:

languagestr 或 None

以 libraqm 接受的格式（即 BCP47 语言代码）指定的文本语言。

如果为 None，则默认为 rcParams["text.language"]（默认：None）。

set_linespacing(spacing)

设置行间距。

参数:

spacing'normal' 或浮点数，默认：'normal'

如果是 'normal'，则行间距由每一行的字体度量自动确定。

如果是浮点数，则每一行的行间距将固定为字号的该倍数。

set_ma(align)

set_multialignment 的别名。

set_math_fontfamily(fontfamily)

设置由 Matplotlib 渲染的数学文本的字体族。

这仅影响 Matplotlib 自身的数学渲染器。在使用 TeX 渲染时（usetex=True）没有影响。

参数:

fontfamilystr

字体族名称。

可用的字体族在 默认 matplotlibrc 文件 中定义。

另请参阅

get_math_fontfamily

set_multialignment(align)

设置多行文本的对齐方式。

所有行的边界框布局由 horizontalalignment 和 verticalalignment 属性决定。此属性控制文本行在该框内的对齐方式。

参数:

align{'left', 'right', 'center'}

set_name(fontname)

set_fontname 的别名。

set_parse_math(parse_math)

覆盖开关以禁用此 Text 的任何数学文本解析。

参数:

parse_mathbool

如果为 False，此 Text 将永远不会使用数学文本。如果为 True，且存在偶数个未转义的美元符号，则将使用数学文本。

set_position(xy)

设置文本的 (x, y) 位置。

参数:

xy(float, float)

set_rotation(s)

设置文本旋转。

参数:

sfloat 或 {'vertical', 'horizontal'}

以数学正方向（逆时针）表示的旋转角度（以度为单位）。'horizontal' 等于 0，'vertical' 等于 90。

set_rotation_mode(m)

设置文本旋转模式。

参数:

m{None, 'default', 'anchor', 'xtick', 'ytick'}

如果为 "default"，文本将先旋转，然后根据水平和垂直对齐方式进行对齐。如果为 "anchor"，则对齐发生在旋转之前。"xtick" 和 "ytick" 会调整水平/垂直对齐方式，使文本在视觉上指向其锚点。这主要用于旋转的刻度标签，并使它们很好地指向其刻度。传递 None 将把旋转模式设置为 "default"。

set_size(fontsize)

set_fontsize 的别名。

set_stretch(stretch)

set_fontstretch 的别名。

set_style(fontstyle)

set_fontstyle 的别名。

set_text(s)

设置文本字符串 s。

它可以包含换行符 (\n) 或 LaTeX 语法中的数学公式。

参数:

s对象

任何对象都将转换为其 str 表示形式，但 None 除外，它会被转换为空字符串。

set_transform_rotates_text(t)

变换的旋转是否影响文本方向。

参数:

tbool

set_usetex(usetex)

参数:

usetexbool 或 None

是否使用 TeX 进行渲染，None 表示使用 rcParams["text.usetex"]（默认值：False）。

set_va(align)

set_verticalalignment 的别名。

set_variant(variant)

set_fontvariant 的别名。

set_verticalalignment(align)

设置相对于锚点的垂直对齐方式。

另请参阅 文本对齐。

参数:

align{'baseline', 'bottom', 'center', 'center_baseline', 'top'}

set_weight(weight)

set_fontweight 的别名。

set_wrap(wrap)

设置文本是否可以换行。

换行可确保文本被限制在（子）图框内。它不考虑任何其他艺术家（artist）。

参数:

wrapbool

备注

换行功能无法与 savefig(..., bbox_inches='tight') 同时使用（IPython/Jupyter 中的 %matplotlib inline 内部也使用了该功能）。'tight' 设置会在换行之前重新调整画布大小以容纳所有内容。

set_x(x)

设置文本的 x 位置。

参数:

x浮点数

set_y(y)

设置文本的 y 位置。

参数:

y浮点数

update(kwargs)

[不推荐] 从字典 props 更新此 Artist 的属性。

不建议使用

此方法因历史原因保留。请改用 Artist.set。artist.update(props) 目前几乎等同于 artist.set(**props)，唯一的区别在于 set 会额外检查属性是否通过别名重复指定。

参数:

propsdict

属性（键）及其新值的字典。

返回:

list

来自配置的设置器的返回值列表。

update_bbox_position_size(renderer)

更新边框（bbox）的位置和大小。

当需要在绘制边框之前更新其位置和大小时，应使用此方法。

update_from(other)

从other复制属性到self。

zorder = 3

class matplotlib.text.Annotation(text, xy, xytext=None, xycoords='data', textcoords=None, arrowprops=None, annotation_clip=None, **kwargs)

基类：Text, _AnnotationBase

Annotation 是一种可以引用特定位置 xy 的 Text。还可以选择绘制一个从文本指向 xy 的箭头。

属性：

xy

被标注的位置。

xycoords

xy 的坐标系。

arrow_patch

一个用于从 xytext 指向 xy 的 FancyArrowPatch。

用文本 text 注释点 xy。

最简单的形式是，文本放置在 *xy* 处。

可选地，文本可以显示在另一个位置 *xytext*。然后可以通过定义 *arrowprops* 来添加一个从文本指向被标注点 *xy* 的箭头。

参数:

textstr

标注的文本内容。

xy(float, float)

要标注的点 *(x, y)*。坐标系统由 *xycoords* 决定。

xytext(float, float)，默认值: *xy*

放置文本的位置 *(x, y)*。坐标系统由 *textcoords* 决定。

xycoordsstr 或 Artist 或 Transform 或可调用对象的单个值或双元组，默认值：'data'

给出 *xy* 的坐标系统。支持以下类型的值：

• 以下字符串之一

  值	描述
  'figure points'	从图形左下角开始的点
  'figure pixels'	从图形左下角开始的像素
  'figure fraction'	从图形左下角开始的比例
  'subfigure points'	从子图左下角开始的点
  'subfigure pixels'	从子图左下角开始的像素
  'subfigure fraction'	从子图左下角开始的比例
  'axes points'	从坐标系左下角开始的点
  'axes pixels'	从坐标系左下角开始的像素
  'axes fraction'	从坐标系左下角开始的比例
  'data'	使用被标注对象的坐标系统（默认）
  'polar'	如果不是原生 'data' 坐标，则为 *(theta, r)*

  请注意，对于父图形，'subfigure pixels' 和 'figure pixels' 是相同的，因此希望代码可在子图中使用的用户可以使用 'subfigure pixels'。

• 一个 Artist：xy 被解释为该艺术家 Bbox 的一部分。例如，(0, 0) 是边框的左下角，(0.5, 1) 是边框的中心顶部。

• 一个用于将 xy 转换为屏幕坐标的 Transform。

• 具有以下签名之一的函数

  def transform(renderer) -> Bbox
  def transform(renderer) -> Transform
  

  其中 renderer 是 RendererBase 的子类。

  该函数的结果解释方式与上述 Artist 和 Transform 情况相同。

• 一个元组 *(xcoords, ycoords)*，为 *x* 和 *y* 指定独立的坐标系统。*xcoords* 和 *ycoords* 都必须是上述类型之一。

更多详细信息，请参阅 高级标注。

textcoordsstr 或 Artist 或 Transform 或可调用对象的单个值或双元组，默认值：xycoords 的值

给出 *xytext* 的坐标系统。

所有 *xycoords* 值均有效，以及以下字符串：

值	描述
'offset points'	与 *xy* 值之间的偏移量（单位：点）
'offset pixels'	与 *xy* 值之间的偏移量（单位：像素）
'offset fontsize'	与 *xy* 值之间的偏移量（相对于字体大小）

arrowpropsdict，可选

用于在位置 xy 和 xytext 之间绘制 FancyArrowPatch 箭头的属性。默认为 None，即不绘制箭头。

出于历史原因，有两种不同的方式指定箭头：“简单”和“花式”

简单箭头

如果 *arrowprops* 不包含键 'arrowstyle'，则允许的键为：

键	描述
width	箭头的宽度（单位：点）
headwidth	箭头头部底部的宽度（单位：点）
headlength	箭头头部的长度（单位：点）
shrink	从两端收缩的总长度比例
?	任何 FancyArrowPatch 属性

箭头附着在文本框的边缘，确切位置（角或中心）取决于其指向。

花式箭头

如果 *arrowprops* 中提供了 'arrowstyle'，则使用此选项。

有效键为以下 FancyArrowPatch 参数

键	描述
arrowstyle	箭头样式
connectionstyle	连接样式
relpos	见下文；默认值为 (0.5, 0.5)
patchA	默认为文本的包围盒
patchB	默认为 None
shrinkA	单位：点。默认值：2 点
shrinkB	单位：点。默认值：2 点
mutation_scale	默认为文本大小（单位：点）
mutation_aspect	默认值为 1
?	任何 FancyArrowPatch 属性

箭头的精确起点由 relpos 定义。它是文本框的相对坐标元组，(0, 0) 为左下角，(1, 1) 为右上角。支持 <0 和 >1 的值，用于指定文本框外部的点。默认值为 (0.5, 0.5)，因此起点位于文本框的中心。

annotation_clip布尔值或 None，默认值: None

当标注点 *xy* 在坐标系区域之外时，是否剪裁（即不绘制）标注。

• 如果为 *True*，当 *xy* 在坐标系之外时，标注将被剪裁。

• 如果为 *False*，标注将始终被绘制。

• 如果为 *None*，当 *xy* 在坐标系之外且 *xycoords* 为 'data' 时，标注将被剪裁。

**kwargs

额外的 kwargs 被传递给 Text。

返回:

Annotation

另请参阅

注解

property anncoords

用于 Annotation.xyann 的坐标系。

contains(mouseevent)

返回鼠标事件是否发生在文本的轴对齐边界框内。

draw(renderer)

使用给定的渲染器绘制 Artist（及其子对象）。

如果美工对象不可见（Artist.get_visible 返回 False），则此操作无效。

参数:

rendererRendererBase 子类。

备注

此方法在 Artist 子类中被覆盖。

get_anncoords()

返回用于 Annotation.xyann 的坐标系。

另请参阅 Annotation 中的 xycoords。

get_tightbbox(renderer=None)

获取美工对象在显示空间中的边界框，考虑裁剪。

参数:

rendererRendererBase, 可选

用于绘制图形的渲染器（即 fig.canvas.get_renderer()）。

返回:

Bbox or None

闭合的边界框（图形像素坐标），如果裁剪导致无交集则返回 None。

另请参阅

Artist.get_window_extent

获取美工边界框，忽略裁剪。

get_window_extent(renderer=None)

返回以显示单位表示的、包围文本的 Bbox。

除了内部使用外，这对于在网页上的 png 文件中指定可点击区域也很有用。

参数:

renderer渲染器，可选

计算边框需要渲染器。如果艺术家已经被绘制，渲染器会被缓存；因此，只有在第一次绘制之前调用 get_window_extent 时才需要传递此参数。实际上，通常更容易先触发绘制，例如调用 draw_without_rendering 或 plt.show()。

dpifloat, 可选

计算 bbox 的 dpi 值，默认为 self.get_figure(root=True).dpi（不是渲染器 dpi）；如果需要匹配使用自定义 dpi 值保存的图形区域，则应设置该值。

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, anncoords=<UNSET>, annotation_clip=<UNSET>, antialiased=<UNSET>, backgroundcolor=<UNSET>, bbox=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, color=<UNSET>, fontfamily=<UNSET>, fontfeatures=<UNSET>, fontproperties=<UNSET>, fontsize=<UNSET>, fontstretch=<UNSET>, fontstyle=<UNSET>, fontvariant=<UNSET>, fontweight=<UNSET>, gid=<UNSET>, horizontalalignment=<UNSET>, in_layout=<UNSET>, label=<UNSET>, language=<UNSET>, linespacing=<UNSET>, math_fontfamily=<UNSET>, mouseover=<UNSET>, multialignment=<UNSET>, parse_math=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, position=<UNSET>, rasterized=<UNSET>, rotation=<UNSET>, rotation_mode=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, text=<UNSET>, transform=<UNSET>, transform_rotates_text=<UNSET>, url=<UNSET>, usetex=<UNSET>, verticalalignment=<UNSET>, visible=<UNSET>, wrap=<UNSET>, x=<UNSET>, y=<UNSET>, zorder=<UNSET>)

一次性设置多个属性。

a.set(a=A, b=B, c=C)

等同于

a.set_a(A)
a.set_b(B)
a.set_c(C)

除全名属性外，还支持别名，例如 set(lw=2) 等同于 set(linewidth=2)，但同时传入两者会报错。

各个 setter 的调用顺序与 set() 中的参数顺序一致。然而，大多数属性并不相互依赖，因此顺序通常无关紧要。

支持的属性包括：

属性	描述
agg_filter	一个过滤函数，它接受一个 (m, n, 3) 浮点数组和一个 dpi 值，并返回一个 (m, n, 3) 数组以及图像左下角的两个偏移量
alpha	浮点数或 None
animated	布尔值
anncoords	未知
annotation_clip（标注裁剪）	布尔值或 None
antialiased	布尔值
backgroundcolor	color
bbox	包含 FancyBboxPatch 属性的字典或 None
clip_box	BboxBase 或 None
clip_on	布尔值
clip_path	Patch 或 (Path, Transform) 或 None
color 或 c	color
figure	未知
fontfamily 或 family 或 fontname	{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}
fontfeatures	字符串列表、字符串元组或 None
fontproperties 或 font 或 font_properties	font_manager.FontProperties 或 str 或 pathlib.Path
fontsize 或 size	float 或 {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}
fontstretch 或 stretch	{0-1000 范围内的数值, 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}
fontstyle 或 style	{'normal', 'italic', 'oblique'}
fontvariant 或 variant	{'normal', 'small-caps'}
fontweight 或 weight	{0-1000 范围内的数值, 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}
gid	str
horizontalalignment 或 ha	{'left', 'center', 'right'}
in_layout	布尔值
label	object
language	str 或 None
linespacing	'normal' 或浮点数，默认：'normal'
math_fontfamily	str
mouseover	布尔值
multialignment 或 ma	{'left', 'right', 'center'}
parse_math	布尔值
path_effects	AbstractPathEffect 的列表
picker	None 或 布尔值 或 浮点数 或 可调用对象
position	(浮点数, 浮点数)
rasterized	布尔值
rotation	float 或 {'vertical', 'horizontal'}
rotation_mode	{None, 'default', 'anchor', 'xtick', 'ytick'}
sketch_params	(scale: 浮点数, length: 浮点数, randomness: 浮点数)
snap	布尔值或 None
text	object
transform	变换
transform_rotates_text	布尔值
url	str
usetex	布尔值，默认：rcParams["text.usetex"]（默认：False）
verticalalignment 或 va	{'baseline', 'bottom', 'center', 'center_baseline', 'top'}
visible	布尔值
wrap	布尔值
x	浮点数
y	浮点数
zorder	浮点数

set_anncoords(coords)

设置用于 Annotation.xyann 的坐标系。

另请参阅 Annotation 中的 xycoords。

set_figure(fig)

设置美工对象所属的 Figure 或 SubFigure 实例。

警告

此函数通常不应由用户调用。

这是一个低级 API，仅修改美工对象的内部状态。仅修改此项是不够的，通常会导致不一致的状态，因为图形的状态也必须相应更改。

用户通常应该调用高级 API，即 Figure.add_artist 或坐标轴方法 Adding artists 之一。

参数:

figFigure 或 SubFigure

update_positions(renderer)

更新标注文本和箭头路径的像素位置。

property xyann

文本位置。

另请参阅 Annotation 中的 xytext。

property xycoords

class matplotlib.text.OffsetFrom(artist, ref_coord, unit='points')

基类： object

用于配合 Annotation 使用的可调用辅助类。

参数:

artistArtist 或 BboxBase 或 Transform

用于计算偏移量的对象。

ref_coord(float, float)

如果 artist 是 Artist 或 BboxBase，此值即为以 artist 边框分数为单位的偏移原点位置。

如果 artist 是变换（transform），则偏移原点即为应用于此值的变换。

unit{'points', 'pixels'}, 默认值：'points'

用于偏移量输入的屏幕单位（像素或点）。

get_unit()

返回 __call__ 使用的变换的输入单位。

set_unit(unit)

设置 __call__ 使用的变换的输入单位。

参数:

unit{'points', 'pixels'}

class matplotlib.text.TextPath(xy, s, size=None, prop=None, _interpolation_steps=1, usetex=False)

基类：Path

根据文本创建路径。

根据文本创建路径。请注意，它仅仅是一个路径，而不是一个艺术家（artist）。您需要使用 PathPatch（或其他艺术家）将此路径绘制到画布上。

参数:

xy元组或两个浮点值的数组

文本位置。如果不偏移，使用 xy=(0, 0)。

sstr

要转换为路径的文本。

sizefloat, 可选

字体大小（以点为单位）。默认为通过字体属性 prop 指定的大小。

propFontProperties, 可选

字体属性。如果不提供，将使用具有来自 rcParams 参数的默认 FontProperties。

_interpolation_stepsint, 可选

（当前被忽略）

usetexbool, 默认值：False

是否使用 tex 渲染。

示例

以下代码根据字符串“ABC”（Helvetica 字体）创建一个路径；并根据 LaTeX 分数 1/2 创建另一个路径。

from matplotlib.text import TextPath
from matplotlib.font_manager import FontProperties

fp = FontProperties(family="Helvetica", style="italic")
path1 = TextPath((12, 12), "ABC", size=12, prop=fp)
path2 = TextPath((0, 0), r"$\frac{1}{2}$", size=12, usetex=True)

另请参阅 将文本用作路径。

property codes

返回代码。

get_size()

获取文本大小。

set_size(size)

设置文本大小。

property vertices

在必要时更新后返回缓存的路径。

class matplotlib.text.TextToPath

基类： object

一个将字符串转换为路径的类。

DPI = 72

FONT_SCALE = 100.0

get_glyphs_mathtext(prop, s, glyph_map=None, return_new_glyphs_only=False)

解析 mathtext 字符串 s 并将其转换为 (顶点, 代码) 对。

get_glyphs_tex(prop, s, glyph_map=None, return_new_glyphs_only=False)

使用 usetex 模式将字符串 s 转换为顶点和代码。

get_glyphs_with_font(font, s, glyph_map=None, return_new_glyphs_only=False, *, features=None, language=None)

使用提供的 ttf 字体将字符串 s 转换为顶点和代码。

get_text_path(prop, s, ismath=False, *, features=None, language=None)

将文本 s 转换为路径（matplotlib.path.Path 的顶点和代码元组）。

参数:

propFontProperties

文本的字体属性。

sstr

要转换的文本。

ismath{False, True, "TeX"}

如果为 True，使用 mathtext 解析器。如果为 "TeX"，使用 tex 进行渲染。

languagestr, 可选

以 libraqm 接受的格式（即 BCP47 语言代码）指定的文本语言。

返回:

vertslist

包含顶点 (x, y) 坐标的数组列表。

codeslist

路径代码列表。

示例

从文本创建顶点和代码列表，并据此创建 Path。

from matplotlib.path import Path
from matplotlib.text import TextToPath
from matplotlib.font_manager import FontProperties

fp = FontProperties(family="Comic Neue", style="italic")
verts, codes = TextToPath().get_text_path(fp, "ABC")
path = Path(verts, codes, closed=False)

另请参阅 TextPath，了解从文本创建路径的更直接方式。

get_text_width_height_descent(s, prop, ismath)