legend

在坐标区上添加图例

全页折叠

语法

legend

legend(label1,...,labelN)

legend(labels)

legend(subset,___)

legend(target,___)

legend(___,'Location',lcn)

legend(___,'Orientation',ornt)

legend(___,Name,Value)

legend(bkgd)

lgd = legend(___)

legend(vsbl)

legend('off')

说明

示例

legend 为每个绘制的数据序列创建一个带有描述性标签的图例。对于标签，图例使用数据序列的 DisplayName 属性中的文本。如果 DisplayName 属性为空，则图例使用 'dataN' 形式的标签。当您在坐标区上添加或删除数据序列时，图例会自动更新。此命令为 gca 返回的当前坐标区或图形创建图例。如果当前坐标区为空，则图例为空。如果坐标区不存在，此命令将创建坐标区。

示例

legend(label1,...,labelN) 设置图例标签。以字符向量或字符串列表形式指定标签，例如 legend('Jan','Feb','Mar')。

legend(labels) 使用字符向量元胞数组、字符串数组或字符矩阵设置标签，例如 legend({'Jan','Feb','Mar'})。

示例

legend(subset,___) 仅在图例中包括 subset 中列出的数据序列的项。subset 以图形对象向量的形式指定。您可以在指定标签之前或不指定其他输入参数的情况下指定 subset。

示例

legend(target,___) 使用由 target 指定的坐标区或图，而不是当前坐标区或图。指定 target 作为第一个输入参数。

示例

legend(___,'Location',lcn) 设置图例位置。例如，'Location','northeast' 将在坐标区的右上角放置图例。请在其他输入参数之后指定位置。

示例

legend(___,'Orientation',ornt)（其中 ornt 为 'horizontal'）并排显示图例项。ornt 的默认值为 'vertical'，即垂直堆叠图例项。

示例

legend(___,Name,Value) 使用一个或多个名称-值对组参数来设置图例属性。

示例

legend(bkgd)（其中 bkgd 为 'boxoff'）删除图例背景和轮廓。bkgd 的默认值为 'boxon'，即显示图例背景和轮廓。

lgd = legend(___) 返回 Legend 对象。可使用 lgd 在创建图例后查询和设置图例属性。有关属性列表，请参阅 Legend 属性。

legend(vsbl) 控制图例的可见性，其中 vsbl 为 'hide'、'show' 或 'toggle'。

legend('off') 删除图例。

示例

全部折叠

在当前坐标区上添加图例

打开实时脚本

绘制两个线条并在当前坐标区上添加一个图例。将图例标签指定为 legend 函数的输入参数。

x = linspace(0,pi);
y1 = cos(x);
plot(x,y1)

hold on 
y2 = cos(2*x);
plot(x,y2)

legend('cos(x)','cos(2x)')

如果您在坐标区添加或删除数据序列，图例会相应地更新。创建数据序列时，可通过将 DisplayName 属性设置为名称-值对组来控制新数据序列的标签。如果您不指定标签，则图例使用 'dataN' 形式的标签。

注意：如果您不希望在坐标区中添加或删除数据序列时自动更新图例，可将图例的 AutoUpdate 属性设置为 'off'。

y3 = cos(3*x);
plot(x,y3,'DisplayName','cos(3x)')
hold off

删除图例。

legend('off')

在特定坐标区上添加图例

打开实时脚本

从 R2019b 开始，您可以使用 tiledlayout 和 nexttile 函数显示分块图。调用 tiledlayout 函数以创建一个 2×1 分块图布局。调用 nexttile 函数以创建坐标区对象 ax1 和 ax2。在每个坐标区中对随机数据绘图。通过指定 ax1 作为 legend 的第一个输入参数，在上部绘图中添加一个图例。

tiledlayout(2,1)
y1 = rand(3);
ax1 = nexttile; 
plot(y1)

y2 = rand(5);
ax2 = nexttile; 
plot(y2)

legend(ax1,{'Line 1','Line 2','Line 3'})

在执行绘图命令的过程中指定图例标签

打开实时脚本

绘制两个线条。通过将 DisplayName 属性设置为所需的文本，在执行绘图命令的过程中指定图例标签。然后，添加一个图例。

x = linspace(0,pi);
y1 = cos(x);
plot(x,y1,'DisplayName','cos(x)')

hold on 
y2 = cos(2*x);
plot(x,y2,'DisplayName','cos(2x)')
hold off

legend

图例位置和列数

打开实时脚本

绘制四个线条。在坐标区的西北角创建一个图例。使用 NumColumns 属性指定图例的列数。

x = linspace(0,pi);
y1 = cos(x);
plot(x,y1)

hold on
y2 = cos(2*x);
plot(x,y2)

y3 = cos(3*x);
plot(x,y3)

y4 = cos(4*x);
plot(x,y4)
hold off

legend({'cos(x)','cos(2x)','cos(3x)','cos(4x)'},'Location','northwest','NumColumns',2)

默认情况下，图例项逐列从上到下排列。要逐行从左到右排列图例项，请将 Orientation 属性设置为 'horizontal'。

在分块图布局中显示共享图例

打开实时脚本

当您要在两个或多个图之间共享一个图例时，您可以在布局的一个单独图块中显示该图例。

在一个分块图布局中创建三个绘图。

tiledlayout(2,2);
nexttile
plot(rand(5))
nexttile
plot(rand(5))
nexttile
plot(rand(5))

添加一个共享图例，并将其移至第四个图块。

lgd = legend;
lgd.Layout.Tile = 4;

在图例中包含部分图形对象

打开实时脚本

如果您不想将绘制的所有图形对象都包含在图例中，可以指定要包含的图形对象。

绘制三个线条并返回创建的 Line 对象。创建只包含其中两条线的图例。将第一个输入参数指定为要包含的 Line 对象的向量。

x = linspace(0,pi);
y1 = cos(x);
p1 = plot(x,y1);

hold on
y2 = cos(2*x);
p2 = plot(x,y2);

y3 = cos(3*x);
p3 = plot(x,y3);
hold off

legend([p1 p3],{'First','Third'})

为图例添加标题

打开实时脚本

绘制两个线条并创建一个图例。然后为图例添加标题。

x = linspace(0,pi);
y1 = cos(x);
plot(x,y1)

hold on
y2 = cos(2*x);
plot(x,y2)
hold off

lgd = legend('cos(x)','cos(2x)');
title(lgd,'My Legend Title')

删除图例背景

打开实时脚本

绘制两个线条并在坐标区左下角创建一个图例。然后，删除图例的背景和轮廓。

x = linspace(0,pi);
y1 = cos(x);
plot(x,y1)

hold on
y2 = cos(2*x);
plot(x,y2)
hold off

legend({'cos(x)','cos(2x)'},'Location','southwest')
legend('boxoff')

修改图例外观

打开实时脚本

通过设置 Legend 属性来修改图例外观。创建图例时，可以在 legend 命令中使用名称-值对组来设置属性。还可以在创建图例后使用 Legend 对象来设置属性。

绘制四行随机数据。创建图例并将 Legend 对象赋给变量 lgd。使用名称-值对组设置 FontSize 和 TextColor 属性。

rdm = rand(4);
plot(rdm)

lgd = legend({'Line 1','Line 2','Line 3','Line 4'},'FontSize',12,'TextColor','blue')

lgd = 
  Legend (Line 1, Line 2, Line 3, Line 4) with properties:

         String: {'Line 1'  'Line 2'  'Line 3'  'Line 4'}
       Location: 'northeast'
    Orientation: 'vertical'
       FontSize: 12
       Position: [0.7088 0.7034 0.1778 0.1957]
          Units: 'normalized'

  Show all properties

创建图例后，通过引用 lgd 来修改图例。使用对象圆点属性名称表示法设置 NumColumns 属性。

lgd.NumColumns = 2;

输入参数

全部折叠

`label1,...,labelN` - 标签（指定为单独的参数）
字符向量 | 字符串

标签，指定为由字符向量或字符串组成的单独参数。要在标签中包括特殊字符或希腊字母，请使用 TeX 标记。要查看选项表，请参阅 Interpreter 属性。

示例： legend('Sin Function','Cos Function')

示例： legend("Sin Function","Cos Function")

示例： legend('\gamma','\sigma')

要指定关键字标签，例如 'Location' 或 'off'，请使用字符向量元胞数组、字符串数组或字符数组。

`labels` - 标签（指定为数组）
字符向量元胞数组 | 字符串数组 | 分类数组

标签，指定为字符向量元胞数组、字符串数组或分类数组。要在标签中包括特殊字符或希腊字母，请使用 TeX 标记。要查看选项表，请参阅 Interpreter 属性。

示例： legend({'Sin Function','Cos Function'})

示例： legend(["Sin Function","Cos Function"])

示例： legend({'\gamma','\sigma'})

示例： legend(categorical({'Alabama','New York'}))

`subset` - 要包含在图例中的数据序列
图形对象向量

要包含在图例中的数据序列，指定为图形对象向量。

`target` - 图例的目标
`Axes` 对象 | `PolarAxes` 对象 | `GeographicAxes` 对象 | 图形对象

图例的目标，指定为 Axes 对象、PolarAxes 对象、GeographicAxes 对象或具有 LegendVisible 属性的图形对象（例如 GeographicBubbleChart 对象）。如果您不指定目标，则 legend 函数将使用 gca 命令返回的坐标区或图形。

有些图形不支持修改图例外观（例如位置），或者不支持将 Legend 对象作为输出参数返回。

`lcn` - 图例位置
`'north'` | `'south'` | `'east'` | `'west'` | `'northeast'` | ...

图例相对于坐标区的位置，指定为下表中列出的位置值之一。

值	说明
`'north'`	坐标区中的顶部
`'south'`	坐标区中的底部
`'east'`	坐标区中的右侧区域
`'west'`	坐标区中的左侧区域
`'northeast'`	坐标区中的右上角（二维坐标区的默认值）
`'northwest'`	坐标区中的左上角
`'southeast'`	坐标区中的右下角
`'southwest'`	坐标区中的左下角
`'northoutside'`	坐标区的上方
`'southoutside'`	坐标区的下方
`'eastoutside'`	到坐标区的右侧
`'westoutside'`	到坐标区的左侧
`'northeastoutside'`	坐标区外的右上角（三维坐标区的默认值）
`'northwestoutside'`	坐标区外的左上角
`'southeastoutside'`	坐标区外的右下角
`'southwestoutside'`	坐标区外的左下角
`'best'`	创建图例时坐标区内与绘图数据冲突最小的位置。如果绘图数据发生变化，您可能需要将位置重置为 `'best'`。
`'bestoutside'`	坐标区的右上角之外（当图例为垂直方向时）或坐标区下方（当图例为水平方向时）
`'layout'`	分块图布局中的图块。要将图例移至不同图块，请设置图例的 `Layout` 属性。
`'none'`	由 `Position` 属性决定。可使用 `Position` 属性在自定义位置显示图例。

示例： legend('Location','northeastoutside')

`ornt` - 方向
`'vertical'` （默认） | `'horizontal'`

方向，指定为下列值之一：

'vertical' - 垂直堆叠图例项。
'horizontal' - 并排列出图例项。

示例： legend('Orientation','horizontal')

`bkgd` - 图例框显示
`'boxon'` （默认） | `'boxoff'`

图例框显示，指定为下列值之一：

'boxon' - 显示图例背景和轮廓。
'boxoff' - 不显示图例背景和轮廓。

示例： legend('boxoff')

`vsbl` - 图例可见性
`'hide'` | `'show'` | `'toggle'`

图例可见性，指定为下列值之一：

'hide' - 隐藏图例。
'Show' - 显示图例或创建图例（如果不存在）。
'toggle' - 切换图例可见性。

示例： legend('hide')

名称-值对组参数

指定可选的、以逗号分隔的 Name,Value 对组参数。Name 为参数名称，Value 为对应的值。Name 必须放在引号中。您可采用任意顺序指定多个名称-值对组参数，如 Name1,Value1,...,NameN,ValueN 所示。

示例： legend({'A','B'},'TextColor','blue','FontSize',12) 创建一个蓝色、12 磅字体的图例。

注意

此处所列的属性只是一部分。有关完整列表，请参阅 Legend 属性。

`'TextColor'` - 文本颜色
`[0 0 0]` （默认） | RGB 三元组 | 十六进制颜色代码 | `'r'` | `'g'` | `'b'` | ...

文本颜色，指定为 RGB 三元组、十六进制颜色代码、颜色名称或短名称。默认颜色为黑色，值为 [0 0 0]。

对于自定义颜色，请指定 RGB 三元组或十六进制颜色代码。

RGB 三元组是包含三个元素的行向量，其元素分别指定颜色中红、绿、蓝分量的强度。强度值必须位于 [0,1] 范围内，例如 [0.4 0.6 0.7]。
十六进制颜色代码是字符向量或字符串标量，以井号 (#) 开头，后跟三个或六个十六进制数字，范围可以是 0 到 F。这些值不区分大小写。因此，颜色代码 '#FF8800' 与 '#ff8800'、'#F80' 与 '#f80' 是等效的。

此外，还可以按名称指定一些常见的颜色。下表列出了命名颜色选项、等效 RGB 三元组和十六进制颜色代码。

颜色名称	短名称	RGB 三元组	十六进制颜色代码	外观
`'red'`	`'r'`	`[1 0 0]`	`'#FF0000'`
`'green'`	`'g'`	`[0 1 0]`	`'#00FF00'`
`'blue'`	`'b'`	`[0 0 1]`	`'#0000FF'`
`'cyan'`	`'c'`	`[0 1 1]`	`'#00FFFF'`
`'magenta'`	`'m'`	`[1 0 1]`	`'#FF00FF'`
`'yellow'`	`'y'`	`[1 1 0]`	`'#FFFF00'`
`'black'`	`'k'`	`[0 0 0]`	`'#000000'`
`'white'`	`'w'`	`[1 1 1]`	`'#FFFFFF'`
`'none'`	不适用	不适用	不适用	无颜色

以下是 MATLAB^® 在许多类型的绘图中使用的默认颜色的 RGB 三元组和十六进制颜色代码。

RGB 三元组	十六进制颜色代码	外观
`[0 0.4470 0.7410]`	`'#0072BD'`
`[0.8500 0.3250 0.0980]`	`'#D95319'`
`[0.9290 0.6940 0.1250]`	`'#EDB120'`
`[0.4940 0.1840 0.5560]`	`'#7E2F8E'`
`[0.4660 0.6740 0.1880]`	`'#77AC30'`
`[0.3010 0.7450 0.9330]`	`'#4DBEEE'`
`[0.6350 0.0780 0.1840]`	`'#A2142F'`

示例： [0 0 1]

示例： 'blue'

示例： '#0000FF'

`'FontSize'` - 字体大小
大于 0 的标量值

字体大小，指定为大于 0 的标量值（以磅为单位）。默认字体大小取决于具体操作系统和区域设置。

如果您更改坐标区字体大小，MATLAB 会自动将颜色栏的字体大小设置为坐标区字体大小的 90%。如果手动设置了颜色栏的字体大小，则更改坐标区字体大小不会影响颜色栏的字体。

`'NumColumns'` - 列数
`1` （默认） | 正整数

列数，指定为正整数。如果没有足够的图例项填充指定数量的列，则显示的列数可能会少一些。

使用 Orientation 属性控制图例项是逐列还是逐行依序显示。

示例： lgd.NumColumns = 3

输出参数

全部折叠

`lgd` - `Legend` 对象
`Legend` 对象

Legend 对象。可使用 lgd 在创建图例之后查看或修改图例属性。

plot(rand(3))
lgd = legend('line1','line2','line3');
lgd.FontSize = 12;
lgd.FontWeight = 'bold';

提示

要为图例中 20 个以上的对象添加标签，必须为每个对象指定一个标签。否则，legend 仅描绘图表中的前 20 个对象。

算法

重新调用 legend 函数不会重置图例属性，如位置或方向。如果存在图例，legend 函数将更新现有图例。一个 Axes 对象仅可以拥有一个图例。
图例反映图形对象在坐标区上的可见性。Visible 属性设置为 'off' 的图形对象在图例中灰显。

兼容性考虑

全部展开

当属性存在时，`legend` 将参数解释为属性名称

R2018b 中的行为有变化

从 R2018b 开始，如果向 legend 函数传递的参数与图例的属性名称相匹配，则函数会将该参数解释为一个名称-值对组的名称。在以前的版本中，legend 函数仅在第一个参数是元胞数组时才会将其识别为名称-值对组。

自此更改后，大多数情况下，使用名称-值对组时都不必再将第一个参数指定为元胞数组。但是，如果您希望在图例中使用一个与图例属性名称相匹配的标签，例如 Position 或 NumColumns，则必须在一个元胞数组中指定所有标签。否则，legend 函数会将参数解释为名称-值对组，而非标签。

说明建议代码

说明	建议代码
如果希望在图例中使用一个与图例属性名称相匹配的标签，例如 `'NumColumns'`，需在一个元胞数组中指定所有标签。如果在元胞数组外指定 `'NumColumns'`，则 `legend` 函数会将其解释为名称-值对组。	legend({'Label1','NumColumns','Label3','Label4'},'NumColumns',2)
如果没有任何标签与图例属性的名称匹配，则不需要将标签放入元胞数组。	legend('Label1','Label2','Label2')

如果希望在图例中使用一个与图例属性名称相匹配的标签，例如 'NumColumns'，需在一个元胞数组中指定所有标签。如果在元胞数组外指定 'NumColumns'，则 legend 函数会将其解释为名称-值对组。

legend({'Label1','NumColumns','Label3','Label4'},'NumColumns',2)

如果没有任何标签与图例属性的名称匹配，则不需要将标签放入元胞数组。

legend('Label1','Label2','Label2')

在坐标区尚不存在时，使用 `legend` 将创建坐标区

R2017b 中的行为有变化

从 R2017b 开始，如果坐标区不存在，legend 函数将创建坐标区。

添加或删除数据时，图例会自动更新

R2017a 中的行为有变化

从 R2017a 开始，当您在坐标区上添加或删除数据序列时，图例会自动更新。如果您不希望自动更新图例，可将图例的 AutoUpdate 属性设置为 'off'。

lgd = legend;
lgd.AutoUpdate = 'off';

不建议返回多个输出

从 R2014b 起不建议使用

不再推荐使用以下语法返回多个输出：

[lgd,icons,plots,txt] = legend(__)

通过此语法创建的图例存在限制，不支持 R2014b 或更高版本中引入的一些功能。例如，您不能为图例添加标题或指定图例列的数量。此外，当您在坐标区上添加或删除数据序列时，图例不会自动更新。

建议您返回 Legend 对象并设置 Legend 属性。

lgd = legend(__)

另请参阅

在 R2006a 之前推出

legend

语法

说明

示例

在当前坐标区上添加图例

在特定坐标区上添加图例

在执行绘图命令的过程中指定图例标签

图例位置和列数

在分块图布局中显示共享图例

在图例中包含部分图形对象

为图例添加标题

删除图例背景

修改图例外观

输入参数

label1,...,labelN - 标签（指定为单独的参数） 字符向量 | 字符串

labels - 标签（指定为数组） 字符向量元胞数组 | 字符串数组 | 分类数组

subset - 要包含在图例中的数据序列 图形对象向量

target - 图例的目标 Axes 对象 | PolarAxes 对象 | GeographicAxes 对象 | 图形对象

lcn - 图例位置 'north' | 'south' | 'east' | 'west' | 'northeast' | ...

ornt - 方向 'vertical' （默认） | 'horizontal'

bkgd - 图例框显示 'boxon' （默认） | 'boxoff'

vsbl - 图例可见性 'hide' | 'show' | 'toggle'

名称-值对组参数

'TextColor' - 文本颜色 [0 0 0] （默认） | RGB 三元组 | 十六进制颜色代码 | 'r' | 'g' | 'b' | ...

'FontSize' - 字体大小 大于 0 的标量值

'NumColumns' - 列数 1 （默认） | 正整数

输出参数

lgd - Legend 对象 Legend 对象

提示

算法

兼容性考虑

当属性存在时，legend 将参数解释为属性名称

在坐标区尚不存在时，使用 legend 将创建坐标区

添加或删除数据时，图例会自动更新

不建议返回多个输出

另请参阅

函数

属性

主题

MATLAB 文档

支持

Introducing Deep Learning with MATLAB

WeChat

`label1,...,labelN` - 标签（指定为单独的参数）
字符向量 | 字符串

`labels` - 标签（指定为数组）
字符向量元胞数组 | 字符串数组 | 分类数组

`subset` - 要包含在图例中的数据序列
图形对象向量

`target` - 图例的目标
`Axes` 对象 | `PolarAxes` 对象 | `GeographicAxes` 对象 | 图形对象

`lcn` - 图例位置
`'north'` | `'south'` | `'east'` | `'west'` | `'northeast'` | ...

`ornt` - 方向
`'vertical'` （默认） | `'horizontal'`

`bkgd` - 图例框显示
`'boxon'` （默认） | `'boxoff'`

`vsbl` - 图例可见性
`'hide'` | `'show'` | `'toggle'`

`'TextColor'` - 文本颜色
`[0 0 0]` （默认） | RGB 三元组 | 十六进制颜色代码 | `'r'` | `'g'` | `'b'` | ...

`'FontSize'` - 字体大小
大于 0 的标量值

`'NumColumns'` - 列数
`1` （默认） | 正整数

`lgd` - `Legend` 对象
`Legend` 对象

当属性存在时，`legend` 将参数解释为属性名称

在坐标区尚不存在时，使用 `legend` 将创建坐标区