Histogram 属性

直方图的外观和行为

Histogram 属性控制直方图的外观和行为。通过更改属性值，您可以修改该直方图的各个方面。使用圆点表示法引用特定的对象和属性：

h = histogram(randn(10,1));
c = h.BinWidth;
h.BinWidth = 2;

bin

全部展开

`NumBins` — bin 数量
正整数

bin 数量，指定为正整数。如果不指定 NumBins，则 histogram 基于输入数据自动计算将使用多少个 bin。

如果用 BinMethod、BinWidth 或 BinEdges 指定 NumBins，则 histogram 仅采用最后一个参数。
此选项不适用于分类数据。

`BinWidth` — bin 的宽度
正标量

bin 的宽度，指定为正标量。如果指定 BinWidth，则 Histogram 最多可以使用 65,536（即 2¹⁶）个 bin。如果指定的 bin 宽度需要多个 bin，则 histogram 使用与最大 bin 数对应的较大的 bin 宽度。

对于 datetime 和 duration 数据，BinWidth 可以是标量持续时间或日历持续时间。
如果用 BinMethod、NumBins 或 BinEdges 指定 BinWidth，则 histogram 仅采用最后一个参数。
此选项不适用于分类数据。

示例: histogram(X,'BinWidth',5) 使用宽度为 5 的 bin。

`BinEdges` — bin 的边界
数值向量

bin 的边界，指定为数值向量。第一个元素指定第一个 bin 的左边界。最后一个元素指定最后一个 bin 的右边界。仅最后一个 bin 包含右边界。

如果不指定 bin 边界，则 histogram 自动确定 bin 边界。

如果 BinCountsMode 是 "manual"，则 BinEdges 必须为行向量。

如果用 BinMethod、BinWidth、NumBins 或 BinLimits 指定 BinEdges，则 histogram 只采用 BinEdges 且必须最后指定 BinEdges。
此选项不适用于分类数据。

`BinLimits` — bin 范围
二元素向量

bin 范围，指定为二元素向量 [bmin,bmax]。第一个元素指示第一个 bin 边界。第二个元素指示最后一个 bin 边界。

此选项仅使用在 bin 范围 X>=bmin & X<=bmax（包含这两个边界值）内的数据进行计算。

此选项不适用于分类数据。

示例: histogram(X,'BinLimits',[1,10]) 仅包括 X 中介于 1 与 10（含二者）之间的值。

`BinLimitsMode` — bin 范围的选择模式
`'auto'` (默认) | `'manual'`

bin 范围的选择模式，指定为 'auto' 或 'manual'。默认值是 'auto'，这样 bin 范围自动调整为该数据。

如果指定 BinLimits 或 BinEdges，则 BinLimitsMode 设置为 'manual'。将 BinLimitsMode 指定为 'auto' 可将 bin 范围重新调整为该数据。
此选项不适用于分类数据的直方图。

`BinMethod` — 分 bin 算法
`'auto'` (默认) | `'scott'` | `'fd'` | `'integers'` | `'sturges'` | `'sqrt'` | ...

分 bin 算法，指定为此表中的一个值。

值	描述
`'auto'`	默认的 `'auto'` 算法选择一个 bin 宽度，以便涵盖数据范围并显示基础分布形状。
`'scott'`	如果数据接近正态分布，则斯科特规则最佳。该规则也适用于大多数的其他分布。它使用 bin 宽度 `3.5std(X(:))numel(X)^(-1/3)`。
`'fd'`	弗里德曼-迪亚科尼斯规则对数据中的离群值不太敏感，可能更适用于重尾分布的数据。它使用的 bin 宽度为 `2iqr(X(:))numel(X)^(-1/3)`；如果 `X` 包含极端离群值，则使用 `0.2(max(X(:))-min(X(:)))numel(X)^(-1/3)`。
`'integers'`	整数规则对整数数据有用，因为它为每个整数创建一个 bin。它使用 bin 宽度 1 并将 bin 边界放在整数的中间。为避免无意间创建太多 bin，可以使用该规则创建 65536 (2¹⁶) 个 bin 的限制。如果数据范围大于 65536，则整数规则改用更宽的 bin。 `'integers'` 不支持日期时间和持续时间数据。
`'sturges'`	斯特吉斯规则因其简单性而广受欢迎。它选择的 bin 数量为 `ceil(1 + log2(numel(X)))` 或 `1`，取两者中的较大者。
`'sqrt'`	平方根规则是广泛用于其他软件包。它选择的 bin 数量为 `ceil(sqrt(numel(X)))` 或 `1`，取两者中的较大者。

histogram 稍微调整 bin 的数目，使 bin 边界落在“合适”的数字上，而不是机械遵循这些精确的公式。

对于 datetime 或 duration 数据，将分 bin 算法指定为下列时间单位之一。

值	描述	数据类型
`"second"`	每个 bin 是 1 秒。	`datetime` 和 `duration`
`"minute"`	每个 bin 是 1 分钟。	`datetime` 和 `duration`
`"hour"`	每个 bin 是 1 小时。	`datetime` 和 `duration`
`"day"`	每个 bin 表示 1 个日历日。此值将夏令时变化考虑在内。	`datetime` 和 `duration`
`"week"`	每个 bin 是 1 个日历周。	仅限 `datetime`
`"month"`	每个 bin 是 1 个日历月。	仅限 `datetime`
`"quarter"`	每个 bin 是 1 个日历季度。	仅限 `datetime`
`"year"`	每个 bin 表示 1 个日历年。此值将闰日考虑在内。	`datetime` 和 `duration`
`"decade"`	每个 bin 是 1 个十年（10 个日历年）。	仅限 `datetime`
`"century"`	每个 bin 是 1 个世纪（100 个日历年）。	仅限 `datetime`

如果为 datetime 或 duration 数据指定 BinMethod，则 histogram 最多可以使用 65,536（即 2¹⁶）个 bin。如果指定的 bin 持续时间需要多个 bin，则 histogram 使用与最大 bin 数对应的较大的 bin 宽度。
如果指定 BinLimits、NumBins、BinEdges 或 BinWidth，则 BinMethod 设置为 'manual'。
如果用 BinWidth、NumBins 或 BinEdges 指定 BinMethod，则 histogram 仅采用最后一个参数。
此选项不适用于分类数据。

示例: histogram(X,'BinMethod','integers') 将 bin 以整数为中心放置。

类别

全部展开

`Categories` — 直方图中包含的类别
字符向量元胞数组 | 分类数组 | 字符串数组 | `pattern` 标量

注意

此选项仅适用于分类直方图。

直方图中包含的类别，指定为字符向量元胞数组、分类数组、字符串数组或 pattern 标量。

如果您指定输入分类数组 C，则默认情况下，histogram 将为 C 中的每个类别绘制一个条形。在这种情况下，请改用 Categories 以指定类别的唯一子集。
如果您指定 bin 计数，Categories 将为直方图指定关联的类别名称。

示例: h = histogram(C,{'Large','Small'}) 只绘制类别 'Large' 和 'Small' 中的分类数据。

示例: histogram(C,"Y" + wildcardPattern) 对名称以字母 Y 开头的类别中的数据进行绘图。

示例: histogram('Categories',{'Yes','No','Maybe'},'BinCounts',[22 18 3]) 绘制包含三个类别及关联 bin 计数的直方图。

示例: h.Categories 查询直方图对象 h 中的类别。

数据类型: cell | categorical | string | pattern

`DisplayOrder` — 类别的显示顺序
`'data'` (默认) | `'ascend'` | `'descend'`

类别的显示顺序，指定为 'data'、'ascend' 或 'descend'。

'data' - 使用输入数据 C 中的类别顺序。
'ascend' - 显示条形高度递增的直方图。
'descend' - 显示条形高度递减的直方图。

此选项仅适用于分类数据。

`NumDisplayBins` — 要显示的类别数量
标量

要显示的类别数量，指定为标量。您可以使用 'DisplayOrder' 选项更改直方图中显示类别的顺序。

此选项仅适用于分类数据。

`ShowOthers` — 切换未显示类别的数据汇总的显示
`'off'` (默认) | on/off 逻辑值

切换未显示类别的数据汇总的显示，指定为 'on' 或 'off'，或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true，'off' 等效于 false。因此，您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

将此选项设置为 'on' 将在直方图中显示一个名为 'Others' 的附加条形。此附加条形用于统计不属于直方图中已显示类别的所有元素。
您可以使用 'NumDisplayBins' 和 'DisplayOrder' 选项更改直方图中显示的类别数量及其顺序。
此选项仅适用于分类数据。

数据

全部展开

`Data` — 要分布到各 bin 的数据
向量 | 矩阵 | 多维数组 | 分类数组

要分布到各 bin 的数据，指定为向量、矩阵、多维数组或分类数组。如果 Data 不是向量，则 histogram 将它视作单列向量 Data(:) 并绘制一个直方图。

histogram 将忽略所有 NaN、NaT 和未定义的分类值。同样，histogram 忽略 Inf 和 -Inf 值，除非 bin 边界将 Inf 或 -Inf 显式指定为 bin 边界。虽然 NaN、NaT、Inf、-Inf 和 <undefined> 值通常情况下不会绘制，但在包括所有数据元素的归一化计算（如 'probability'）中，仍然会包含这些值。

如果直方图对象最初是使用分类值创建的，则只能为 Data 指定分类值。

`Values` — bin 值
只读: 数值向量

此属性为只读。

bin 值，以数值向量形式返回。如果 Normalization 为 'count'（默认），则 Values 中的第 k 元素指定 Data 的多少个元素属于第 k 个 bin 区间（bin 计数）。最后一个 bin 包含在任一 bin 边界上的值，但所有其他的 bin 仅包含位于左边界上的值。

根据 Normalization 的值，Values 属性可以包含 bin 计数的归一化变体。

`Normalization` — 归一化类型
`'count'` (默认) | `'probability'` | `'percentage'` | `'countdensity'` | `'cumcount'` | `'pdf'` | `'cdf'`

归一化类型，指定为此表中的一个值。对于每个 bin i：

$v_{i}$ 是 bin 的值。
$c_{i}$ 是 bin 中的元素数目。
$w_{i}$ 是 bin 的宽度。
$N$ 是输入数据中的元素数目。此值可以大于分 bin 数据元素数，前提是数据中包含缺失值，例如 NaN，或者某些数据位于 bin 范围外。

值	bin 值	注释
`'count'`（默认值）	$v_{i} = c_{i}$	观测值的计数或频率。对于分类数据，bin 值之和最多为 `numel(X)` 或 `sum(ismember(X(:),'Categories'))`。仅当某些输入数据不在 bin 中时，bin 值之和才会小于此值。
`'probability'`	$v_{i} = \frac{c_{i}}{N}$	相对概率。每个 bin 中的元素数与输入数据中的总元素数之比最大为 1。
`'percentage'`	$v_{i} = 100 * \frac{c_{i}}{N}$	相对百分比。每个 bin 中的元素百分比最多为 100。
`'countdensity'`	$v_{i} = \frac{c_{i}}{w_{i}}$	按 bin 的宽度进行换算的计数或频率。对于分类数据，这与 `'count'` 相同。 `'countdensity'` 不支持 `datetime` 或 `duration` 数据。 bin 面积的总和最多为 `numel(X)`。
`'cumcount'`	$v_{i} = \sum_{j = 1}^{i} c_{j}$	累积计数，或每个 bin 及前面所有 bin 中累积的观测值数量。对于分类数据，`N(end)` 最多为 `numel(X)` 或 `sum(ismember(X(:),'Categories'))`。
`'pdf'`	$v_{i} = \frac{c_{i}}{N \cdot w_{i}}$	概率密度函数的估计值。对于分类数据，这与 `'probability'` 相同。 `'pdf'` 不支持 `datetime` 或 `duration` 数据。 bin 面积的总和最多为 `1`。
`'cdf'`	$v_{i} = \sum_{j = 1}^{i} \frac{c_{j}}{N}$	累积分布函数估算值。每个 bin 的计数等于该 bin 及前面所有 bin 中累积的相对观测值数量。 `N(end)` 最多为 1。

示例: histogram(X,'Normalization','pdf') 使用概率密度函数估计值对数据进行分 bin。

`BinCounts` — bin 计数
向量

bin 计数，指定为向量。当单独执行 bin 计数计算且不希望 histogram 执行任何数据分 bin 时，可使用此输入将 bin 计数传递给 histogram。

counts 的长度必须等于 bin 的数量。

对于数值直方图，bin 的数量为 length(edges)-1。
对于分类直方图，bin 的数量等于类别的数量。

与 Values 属性相比，BinCounts 未进行归一化。如果 Normalization 为 'count'，则 Values 等同于 BinCounts。

示例: histogram('BinEdges',-2:2,'BinCounts',[5 8 15 9])

示例: histogram('Categories',{'Yes','No','Maybe'},'BinCounts',[22 18 3])

`BinCountsMode` — bin 计数的选择模式
`'auto'` (默认) | `'manual'`

bin 计数的选择模式，指定为 'auto' 或 'manual'。默认值为 'auto'，即根据 Data 和 BinEdges 自动计算 bin 计数。

如果您指定了 BinCounts，则 BinCountsMode 自动设置为 'manual'。同样，如果您指定了 Data，则 BinCountsMode 自动设置为 'auto'。

颜色和样式

全部展开

`DisplayStyle` — 直方图的显示样式
`'bar'` (默认) | `'stairs'`

直方图的显示样式，指定为 'bar' 或 'stairs'。

'bar' - 在 A 的每个窗口上显示一个直方条形图。此方法对于减少数据中的周期性趋势很有用。
'stairs' - 显示一个阶梯图，它显示直方图的轮廓而不填充内部。

示例: histogram(X,'DisplayStyle','stairs') 绘制直方图的轮廓。

`Orientation` — 条形方向
`'vertical'` (默认) | `'horizontal'`

条形方向，指定为 'vertical' 或 'horizontal'。

示例: histogram(X,'Orientation','horizontal') 创建一个带水平条形的直方图。

`BarWidth` — 分类条形的相对宽度
`0.9` (默认) | 范围 `[0,1]` 中的标量

分类条形的相对宽度，指定为 [0,1] 范围中的一个标量值。使用此属性可控制直方图内各分类条形的间隔。默认值是 0.9，表示条形宽度占从上一条形到下一条形之间的空间的 90%，两侧各占该空间的 5%。

如果 BarWidth 为 1，则相邻条形彼此接触。

此选项仅适用于分类数据。

示例: 0.5

`FaceColor` — 直方图的条形颜色
`'auto'` (默认) | `'none'` | RGB 三元组 | 十六进制颜色代码 | 颜色名称

直方图的条形颜色，指定为下列值之一：

'none' - 条形未填充。
'auto' - 直方图条形颜色是自动选择的（默认）。

RGB 三元组、十六进制颜色代码或颜色名称 - 用指定的颜色填充条形。

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"`

下表列出了浅色和深色主题中绘图的默认调色板。

调色板调色板颜色

调色板	调色板颜色
`"gem"` - 浅色主题默认值在 R2025a 之前的版本中: 大多数绘图默认使用这些颜色。
`"glow"` - 深色主题默认值

"gem" - 浅色主题默认值

在 R2025a 之前的版本中: 大多数绘图默认使用这些颜色。

Sample of the "gem" color palette

"glow" - 深色主题默认值

Sample of the "glow" color palette

您可以使用 orderedcolors 和 rgb2hex 函数获取这些调色板的 RGB 三元组和十六进制颜色代码。例如，获取 "gem" 调色板的 RGB 三元组并将其转换为十六进制颜色代码。

RGB = orderedcolors("gem");
H = rgb2hex(RGB);

在 R2023b 之前的版本中: 使用 RGB = get(groot,"FactoryAxesColorOrder") 获取 RGB 三元组。

在 R2024a 之前的版本中: 使用 H = compose("#%02X%02X%02X",round(RGB*255)) 获取十六进制颜色代码。

如果将 DisplayStyle 指定为 'stairs'，则 histogram 不使用 FaceColor 属性。

示例: histogram(X,'FaceColor','g') 创建一个带绿色条形的直方图。

`EdgeColor` — 直方图的边界颜色
`'none'` | `'auto'` | RGB 三元组 | 十六进制颜色代码 | 颜色名称

直方图的边界颜色，指定为下列值之一：

'none' - 不绘制边。
'auto' - 每个边界的颜色都是自动选择的。

RGB 三元组、十六进制颜色代码或颜色名称 - 边使用指定的颜色。

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"`

下表列出了浅色和深色主题中绘图的默认调色板。

调色板调色板颜色

调色板	调色板颜色
`"gem"` - 浅色主题默认值在 R2025a 之前的版本中: 大多数绘图默认使用这些颜色。
`"glow"` - 深色主题默认值

"gem" - 浅色主题默认值

在 R2025a 之前的版本中: 大多数绘图默认使用这些颜色。

Sample of the "gem" color palette

"glow" - 深色主题默认值

Sample of the "glow" color palette

RGB = orderedcolors("gem");
H = rgb2hex(RGB);

在 R2023b 之前的版本中: 使用 RGB = get(groot,"FactoryAxesColorOrder") 获取 RGB 三元组。

在 R2024a 之前的版本中: 使用 H = compose("#%02X%02X%02X",round(RGB*255)) 获取十六进制颜色代码。

示例: histogram(X,'EdgeColor','r') 创建一个带红色条形边界的直方图。

`FaceAlpha` — 直方图条形的透明度
`0.6` (默认) | 范围 `[0,1]` 中的标量值

直方图条形的透明度，指定为 [0,1] 范围内的标量值。histogram 对所有的直方图条形使用相同的透明度。值 1 表示完全不透明，0 则表示完全透明（不可见）。

示例: histogram(X,'FaceAlpha',1) 创建一个带有完全不透明条形的直方图。

`EdgeAlpha` — 直方图条形边的透明度
`1` (默认) | 范围 `[0,1]` 中的标量

直方图条形边界的透明度，指定为范围 [0,1] 内的标量值。值 1 表示完全不透明，0 则表示完全透明（不可见）。

示例: histogram(X,'EdgeAlpha',0.5) 创建一个具有半透明条形边的直方图。

`LineStyle` — 线型
`"-"` (默认) | `"--"` | `":"` | `"-."` | `"none"`

线型，指定为下表中列出的选项之一。

线型	描述	表示的线条
`"-"`	实线
`"--"`	虚线
`":"`	点线
`"-."`	点划线
`"none"`	无线条	无线条

`LineWidth` — 条形轮廓的宽度
`0.5` (默认) | 正值

条形轮廓的宽度，指定为以磅为单位的正值。一磅等于 1/72 英寸。

示例: 1.5

`SeriesIndex` — 序列索引
正整数 | `"none"`

序列索引，指定为正整数或 "none"。此属性可用于重新分配 Histogram 对象的面颜色，使它们与其他对象的颜色匹配。

默认情况下，Histogram 对象的 SeriesIndex 属性是一个与其创建顺序对应的数字，从 1 开始。在您调用绘图函数时，MATLAB^® 使用该数字计算用于分配颜色的索引。索引引用存储在坐标区的 ColorOrder 属性中的数组的行。坐标区中具有相同 SeriesIndex 编号的任何对象都将具有相同的颜色。

SeriesIndex 值 "none" 对应于不参与索引方案的中性颜色。

手动颜色分配如何覆盖 `SeriesIndex` 行为

要手动控制面颜色，请将 Histogram 对象的 FaceColor 属性设置为颜色值，如颜色名称或 RGB 三元组。

当您手动设置 Histogram 对象的面颜色时，MATLAB 会禁用该对象的自动颜色选择，并允许您的颜色保持不变，而不管 SeriesIndex 属性的值如何。

要再次启用自动选择，请将 SeriesIndex 属性设置为正整数，并将 FaceColor 属性设置为 "auto"。

在某些情况下，MATLAB 会将 SeriesIndex 值设置为 0，这也会禁用自动颜色选择。

图例

全部展开

`DisplayName` — 图例使用的文本
`Data` 或 `''` 的变量名称 (默认) | 字符向量

图例使用的文本，指定为字符向量。文本显示在 histogram 的图标旁边。

示例: 'Text Description'

对于多行文本，请使用 sprintf 和换行符 \n 创建字符向量。

示例: sprintf('line one\nline two')

您也可以使用 legend 函数指定图例文本。

如果您将该文本指定为 legend 函数的输入参量，则图例将使用该指定文本，同时将 DisplayName 属性设置为与之相同的值。
如果未将该文本指定为 legend 函数的输入参量，则图例将使用 DisplayName 属性中的文本。DisplayName 的默认值是下列值之一。
- 对于数值输入，DisplayName 是一个字符向量，代表用来构建直方图的输入数据的变量名称。如果输入数据没有变量名称，则 DisplayName 为空，即 ''。
- 对于分类数组输入，DisplayName 为空，即 ''。

如果 DisplayName 属性不包含任何文本，则该图例将生成一个字符向量。该字符向量的形式为 'dataN'，其中 N 是基于 histogram 对象在图例条目列表中的位置指定给它的编号。

如果您以交互方式编辑现有图例中的字符向量，则 MATLAB 会将 DisplayName 属性更新为编辑的字符向量。

`Annotation` — 在图例中包含对象
`Annotation` 对象

在图例中包含对象，指定为 Annotation 对象。将 Annotation 对象的基础 IconDisplayStyle 属性设置为以下值之一：

"on" - 在图例中包含对象（默认值）。
"off" - 不在图例中包含对象。

例如，要从图例中排除名为 obj 的 Histogram 对象，请将 IconDisplayStyle 属性设置为 "off"。

obj.Annotation.LegendInformation.IconDisplayStyle = "off";

您也可以使用 legend 函数控制图例中的项目。将第一个输入参量指定为要包含的图形对象的向量。如果未在第一个输入参量中指定现有图形对象，则该图形对象不会显示在图例中。但在创建图例后添加到坐标区的图形对象会显示在图例中。请考虑在创建所有绘图后创建图例以避免出现额外的项。

交互性

全部展开

`Visible` — 可见性状态
`"on"` (默认) | on/off 逻辑值

可见性状态，指定为 "on" 或 "off"，或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 "on" 等效于 true，"off" 等效于 false。因此，您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

"on" - 显示对象。
"off" - 隐藏对象而不删除它。您仍然可以访问不可见对象的属性。

`DataTipTemplate` — 数据提示内容
`DataTipTemplate` 对象

数据提示内容，指定为 DataTipTemplate 对象。您可以通过修改底层 DataTipTemplate 对象的属性来控制数据提示中显示的内容。有关属性列表，请参阅 DataTipTemplate 属性。

有关修改数据提示的示例，请参阅创建自定义数据提示。

注意

findobj 或 findall 不返回 DataTipTemplate 对象，copyobj 也不复制该对象。

`ContextMenu` — 上下文菜单
空 `GraphicsPlaceholder` 数组 (默认) | `ContextMenu` 对象

上下文菜单，指定为 ContextMenu 对象。使用此属性在您右键点击对象时显示上下文菜单。使用 uicontextmenu 函数创建上下文菜单。

注意

如果 PickableParts 属性设置为 'none' 或者 HitTest 属性设置为 'off'，该上下文菜单将不显示。

`Selected` — 选择状态
`'off'` (默认) | on/off 逻辑值

选择状态，指定为 'on' 或 'off'，或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true，'off' 等效于 false。因此，您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

'on' - 已选择。如果您在绘图编辑模式下点击对象，则 MATLAB 会将其 Selected 属性设置为 'on'。如果 SelectionHighlight 属性也设置为 'on'，则 MATLAB 将在对象周围显示选择句柄。
'off' - 未选择。

`SelectionHighlight` — 是否显示选择句柄
`'on'` (默认) | on/off 逻辑值

选择时显示选择句柄，指定为 'on' 或 'off'，或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true，'off' 等效于 false。因此，您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

'on' - 在 Selected 属性设置为 'on' 时显示选择句柄。
'off' - 永远不显示选择句柄，即使 Selected 属性设置为 'on' 也是如此。

回调

全部展开

`ButtonDownFcn` — 鼠标点击回调
`''` (默认) | 函数句柄 | 元胞数组 | 字符向量

鼠标点击回调，指定为下列值之一：

函数句柄
元胞数组，包含一个函数句柄和其他参量
作为有效 MATLAB 命令或函数（在基础工作区中计算）的字符向量（不推荐）

使用此属性在您点击对象时执行代码。如果使用函数句柄指定此属性，则 MATLAB 在执行回调时将向回调函数传递两个参量：

点击的对象 - 从回调函数中访问点击的对象的属性。
事件数据 - 空参量。在函数定义中将其替换为波浪号字符 (~) 以指示不使用此参量。

有关如何使用函数句柄定义回调函数的详细信息，请参阅Create Callbacks for Graphics Objects。

注意

如果 PickableParts 属性设置为 'none' 或者 HitTest 属性设置为 'off'，则不执行此回调。

`CreateFcn` — 创建函数
`''` (默认) | 函数句柄 | 元胞数组 | 字符向量

对象创建函数，指定为下列值之一：

函数句柄。
第一个元素是函数句柄的元胞数组。元胞数组中的后续元素是传递到回调函数的参量。
包含有效 MATLAB 表达式的字符向量（不推荐）。MATLAB 在基础工作区计算此表达式。

有关将回调指定为函数句柄、元胞数组或字符向量的详细信息，请参阅Create Callbacks for Graphics Objects。

此属性指定要在 MATLAB 创建对象时执行的回调函数。MATLAB 将在执行 CreateFcn 回调之前初始化所有属性值。如果不指定 CreateFcn 属性，则 MATLAB 执行默认的创建函数。

对现有组件设置 CreateFcn 属性没有任何作用。

如果将此属性指定为函数句柄或元胞数组，则可以使用回调函数的第一个参量访问正在创建的对象。否则，使用 gcbo 函数访问该对象。

`DeleteFcn` — 删除函数
`''` (默认) | 函数句柄 | 元胞数组 | 字符向量

对象删除函数，指定为下列值之一：

函数句柄。
第一个元素是函数句柄的元胞数组。元胞数组中的后续元素是传递到回调函数的参量。
包含有效 MATLAB 表达式的字符向量（不推荐）。MATLAB 在基础工作区计算此表达式。

有关将回调指定为函数句柄、元胞数组或字符向量的详细信息，请参阅Create Callbacks for Graphics Objects。

此属性指定在 MATLAB 删除对象时要执行的回调函数。MATLAB 在销毁对象的属性之前执行 DeleteFcn 回调。如果不指定 DeleteFcn 属性，则 MATLAB 执行默认的删除函数。

如果将此属性指定为函数句柄或元胞数组，则可以使用回调函数的第一个参量访问要删除的对象。否则，使用 gcbo 函数访问该对象。

回调执行控件

全部展开

`Interruptible` — 回调中断
`'on'` (默认) | on/off 逻辑值

回调中断，指定为 'on' 或 'off'，或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true，'off' 等效于 false。因此，您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

此属性确定是否可以中断运行中回调。有以下两种回调状态要考虑：

运行中回调是当前正在执行的回调。
中断回调是试图中断运行中回调的回调。

每次执行处理回调队列的命令时，MATLAB 都会确定回调中断行为。这些命令包括 drawnow、figure、uifigure、getframe、waitfor 和 pause。

如果运行中回调不包含上述命令之一，则不会发生中断。MATLAB 首先完成执行运行中回调，然后执行中断回调。

如果运行中回调确实包含上述命令之一，则由运行中回调所属对象的 Interruptible 属性来确定是否发生中断：

如果 Interruptible 的值为 'off'，则不会发生中断。此时，由中断回调所属对象的 BusyAction 属性确定中断回调是被丢弃还是添加到回调队列中。
如果 Interruptible 的值为 'on'，则发生中断。下次 MATLAB 处理回调队列时，它会停止运行中回调的执行，并执行中断回调。在中断回调完成后，MATLAB 将继续执行运行中回调。

注意

回调的中断和执行在以下情况下会有不同的表现：

如果中断回调是 DeleteFcn、CloseRequestFcn 或 SizeChangedFcn 回调，则无论是否存在 Interruptible 属性值都会发生中断。
如果运行中回调当前正在执行 waitfor 函数，则无论是否存在 Interruptible 属性值都会发生中断。
如果中断回调由 Timer 对象所有，则回调将根据调度执行，而不考虑 Interruptible 属性值。

注意

发生中断时，MATLAB 不保存属性状态或显示内容。例如，gca 或 gcf 命令返回的对象可能会在另一个回调执行时发生改变。

`BusyAction` — 回调排队
`'queue'` (默认) | `'cancel'`

回调排队，指定为 'queue' 或 'cancel'。BusyAction 属性决定 MATLAB 如何处理中断回调的执行。有以下两种回调状态要考虑：

运行中回调是当前正在执行的回调。
中断回调是试图中断运行中回调的回调。

BusyAction 属性仅在同时满足以下两个条件时才确定回调排队行为：

运行中回调包含一个用于处理回调队列的命令，例如 drawnow、figure、uifigure、getframe、waitfor 或 pause。
运行中回调所属对象的 Interruptible 属性的值为 'off'。

在这些情况下，由中断回调所属对象的 BusyAction 属性确定 MATLAB 如何处理中断回调。以下是 BusyAction 属性的可能值：

'queue' - 将中断回调放入队列中，以便在运行中回调执行完毕后进行处理。
'cancel' - 不执行中断回调。

`PickableParts` — 捕获鼠标点击的能力
`'visible'` (默认) | `'none'`

捕获鼠标点击的能力，指定为以下值之一：

'visible' - 仅当对象可见时才捕获鼠标点击。Visible 属性必须设置为 'on'。HitTest 属性决定是 Histogram 对象响应点击还是前代响应点击。
'none' - 无法捕获鼠标点击。点击 Histogram 对象会将点击操作传递给图窗窗口的当前视图中该对象下方的对象。Histogram 对象的 HitTest 属性没有任何作用。

`HitTest` — 响应捕获的鼠标点击
`'on'` (默认) | on/off 逻辑值

对捕获的鼠标点击的响应，指定为 'on' 或 'off'，或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true，'off' 等效于 false。因此，您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

'on' - 触发 Histogram 对象的 ButtonDownFcn 回调。如果您已定义 ContextMenu 属性，则调用上下文菜单。
'off' - 触发满足以下条件之一的 Histogram 对象的最近前代的回调：
- HitTest 属性设置为 'on'。
- PickableParts 属性设置为允许前代捕获鼠标点击的值。

注意

PickableParts 属性决定 Histogram 对象是否可以捕获鼠标点击。如果无法捕获，则 HitTest 属性没有任何作用。

`BeingDeleted` — 删除状态
只读: on/off 逻辑值

此属性为只读。

删除状态，以 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值形式返回。

当 DeleteFcn 回调开始执行时，MATLAB 会将 BeingDeleted 属性设置为 'on'。BeingDeleted 属性将一直保持 'on' 设置状态，直到组件对象不再存在为止。

在查询或修改对象之前，请先检查其 BeingDeleted 属性的值，以确认它不是待删除项。

父级/子级

全部展开

`Parent` — 父级
`Axes` 对象 | `PolarAxes` 对象 | `Group` 对象 | `Transform` 对象

父级，指定为 Axes、PolarAxes、Group 或 Transform 对象。

`Children` — 子级
空 `GraphicsPlaceholder` 数组 | `DataTip` 对象数组

子级，以空的 GraphicsPlaceholder 数组或 DataTip 对象数组形式返回。使用此属性来查看在图上绘制的数据提示的列表。

不能使用 Children 属性添加或删除子级。要向此列表中添加子级，请将 DataTip 对象的 Parent 属性设置为图对象。

`HandleVisibility` — 对象句柄的可见性
`"on"` (默认) | `"off"` | `"callback"`

父级的 Children 属性中对象句柄的可见性，指定为下列值之一：

"on" - 对象句柄始终可见。
"off" - 对象句柄始终不可见。该选项用于防止另一函数无意中对其进行更改。将 HandleVisibility 设置为 "off" 可在执行该函数时暂时隐藏句柄。
"callback" - 对象句柄在回调或回调所调用的函数中可见，但在从命令行调用的函数中不可见。此选项阻止通过命令行访问对象，但允许回调函数访问对象。

如果父级的 Children 属性中未列出该对象，则通过搜索对象层次结构或查询句柄属性获取对象句柄的函数无法返回该对象。此类函数的示例包括 get、findobj、gca、gcf、gco、newplot、cla、clf 和 close 函数。

隐藏的对象句柄仍有效。将根 ShowHiddenHandles 属性设置为 "on" 以列出所有对象句柄，而不管其 HandleVisibility 属性设置如何。

标识符

全部展开

`Type` — 图形对象的类型
只读: `'histogram'` | `'categoricalhistogram'`

此属性为只读。

图形对象的类型，以 'histogram' 或 'categoricalhistogram' 形式返回。使用该属性在绘制层次结构中查找指定类型的所有对象，例如，使用 findobj 搜索该类型。

`Tag` — 对象标识符
`''` (默认) | 字符向量 | 字符串标量

对象标识符，指定为字符向量或字符串标量。您可以指定唯一的 Tag 值作为对象的标识符。如果需要访问您代码中其他位置的对象，可以使用 findobj 函数基于 Tag 值搜索对象。

`UserData` — 用户数据
`[]` (默认) | 数组

用户数据，指定为任何 MATLAB 数组。例如，您可以指定标量、向量、矩阵、元胞数组、字符数组、表或结构体。使用此属性存储对象上的任意数据。

如果您在 App 设计工具中工作，请在该 App 中创建公共或私有属性以共享数据，而不是使用 UserData 属性。有关详细信息，请参阅在用 App 设计工具创建的 App 内共享数据。

版本历史记录

在 R2014b 中推出

全部展开

R2023b: 使用百分比进行归一化

通过将 Normalization 属性设置为 'percentage'，可以在垂直轴上使用百分比创建直方图。

R2023b: 使用 `SeriesIndex="none"` 退出自动颜色选择

通过将 SeriesIndex 属性设置为 "none" 退出 Histogram 对象的自动颜色选择。当您指定 "none" 时，Histogram 对象具有中性颜色。

要再次启用自动颜色选择，请将 SeriesIndex 属性设置为一个正整数。

R2020a: 使用 `SeriesIndex` 属性控制自动颜色选择

通过设置 SeriesIndex 属性来控制 Histogram 对象的颜色变化。当您要匹配坐标区中不同对象的颜色时，此属性很有用。

R2020a: 不推荐使用 `UIContextMenu` 属性

从 R2020a 开始，不推荐使用 UIContextMenu 属性将上下文菜单分配给图形对象或 UI 组件。请改用 ContextMenu 属性。属性值是相同的。

目前没有停止支持 UIContextMenu 属性的计划。但是，UIContextMenu 属性将不再出现在对图形对象或 UI 组件调用 get 函数时所返回的列表中。

另请参阅

histogram

主题

访问属性值

Histogram 属性

bin

NumBins — bin 数量 正整数

BinWidth — bin 的宽度 正标量

BinEdges — bin 的边界 数值向量

BinLimits — bin 范围 二元素向量

BinLimitsMode — bin 范围的选择模式 'auto' (默认) | 'manual'

BinMethod — 分 bin 算法 'auto' (默认) | 'scott' | 'fd' | 'integers' | 'sturges' | 'sqrt' | ...

类别

Categories — 直方图中包含的类别 字符向量元胞数组 | 分类数组 | 字符串数组 | pattern 标量

DisplayOrder — 类别的显示顺序 'data' (默认) | 'ascend' | 'descend'

NumDisplayBins — 要显示的类别数量 标量

ShowOthers — 切换未显示类别的数据汇总的显示 'off' (默认) | on/off 逻辑值

数据

Data — 要分布到各 bin 的数据 向量 | 矩阵 | 多维数组 | 分类数组

Values — bin 值 只读: 数值向量

Normalization — 归一化类型 'count' (默认) | 'probability' | 'percentage' | 'countdensity' | 'cumcount' | 'pdf' | 'cdf'

BinCounts — bin 计数 向量

BinCountsMode — bin 计数的选择模式 'auto' (默认) | 'manual'

颜色和样式

DisplayStyle — 直方图的显示样式 'bar' (默认) | 'stairs'

Orientation — 条形方向 'vertical' (默认) | 'horizontal'

BarWidth — 分类条形的相对宽度 0.9 (默认) | 范围 [0,1] 中的标量

FaceColor — 直方图的条形颜色 'auto' (默认) | 'none' | RGB 三元组 | 十六进制颜色代码 | 颜色名称

EdgeColor — 直方图的边界颜色 'none' | 'auto' | RGB 三元组 | 十六进制颜色代码 | 颜色名称

FaceAlpha — 直方图条形的透明度 0.6 (默认) | 范围 [0,1] 中的标量值

EdgeAlpha — 直方图条形边的透明度 1 (默认) | 范围 [0,1] 中的标量

LineStyle — 线型 "-" (默认) | "--" | ":" | "-." | "none"

LineWidth — 条形轮廓的宽度 0.5 (默认) | 正值

SeriesIndex — 序列索引 正整数 | "none"

手动颜色分配如何覆盖 SeriesIndex 行为

图例

DisplayName — 图例使用的文本 Data 或 '' 的变量名称 (默认) | 字符向量

Annotation — 在图例中包含对象 Annotation 对象

交互性

Visible — 可见性状态 "on" (默认) | on/off 逻辑值

DataTipTemplate — 数据提示内容 DataTipTemplate 对象

ContextMenu — 上下文菜单 空 GraphicsPlaceholder 数组 (默认) | ContextMenu 对象

Selected — 选择状态 'off' (默认) | on/off 逻辑值

SelectionHighlight — 是否显示选择句柄 'on' (默认) | on/off 逻辑值

回调

ButtonDownFcn — 鼠标点击回调 '' (默认) | 函数句柄 | 元胞数组 | 字符向量

CreateFcn — 创建函数 '' (默认) | 函数句柄 | 元胞数组 | 字符向量

DeleteFcn — 删除函数 '' (默认) | 函数句柄 | 元胞数组 | 字符向量

回调执行控件

Interruptible — 回调中断 'on' (默认) | on/off 逻辑值

BusyAction — 回调排队 'queue' (默认) | 'cancel'

PickableParts — 捕获鼠标点击的能力 'visible' (默认) | 'none'

HitTest — 响应捕获的鼠标点击 'on' (默认) | on/off 逻辑值

BeingDeleted — 删除状态 只读: on/off 逻辑值

父级/子级

Parent — 父级 Axes 对象 | PolarAxes 对象 | Group 对象 | Transform 对象

Children — 子级 空 GraphicsPlaceholder 数组 | DataTip 对象数组

HandleVisibility — 对象句柄的可见性 "on" (默认) | "off" | "callback"

标识符

Type — 图形对象的类型 只读: 'histogram' | 'categoricalhistogram'

Tag — 对象标识符 '' (默认) | 字符向量 | 字符串标量

UserData — 用户数据 [] (默认) | 数组

版本历史记录

R2023b: 使用百分比进行归一化

R2023b: 使用 SeriesIndex="none" 退出自动颜色选择

R2020a: 使用 SeriesIndex 属性控制自动颜色选择

R2020a: 不推荐使用 UIContextMenu 属性

另请参阅

主题

`NumBins` — bin 数量
正整数

`BinWidth` — bin 的宽度
正标量

`BinEdges` — bin 的边界
数值向量

`BinLimits` — bin 范围
二元素向量

`BinLimitsMode` — bin 范围的选择模式
`'auto'` (默认) | `'manual'`

`BinMethod` — 分 bin 算法
`'auto'` (默认) | `'scott'` | `'fd'` | `'integers'` | `'sturges'` | `'sqrt'` | ...

`Categories` — 直方图中包含的类别
字符向量元胞数组 | 分类数组 | 字符串数组 | `pattern` 标量

`DisplayOrder` — 类别的显示顺序
`'data'` (默认) | `'ascend'` | `'descend'`

`NumDisplayBins` — 要显示的类别数量
标量

`ShowOthers` — 切换未显示类别的数据汇总的显示
`'off'` (默认) | on/off 逻辑值

`Data` — 要分布到各 bin 的数据
向量 | 矩阵 | 多维数组 | 分类数组

`Values` — bin 值
只读: 数值向量

`Normalization` — 归一化类型
`'count'` (默认) | `'probability'` | `'percentage'` | `'countdensity'` | `'cumcount'` | `'pdf'` | `'cdf'`

`BinCounts` — bin 计数
向量

`BinCountsMode` — bin 计数的选择模式
`'auto'` (默认) | `'manual'`

`DisplayStyle` — 直方图的显示样式
`'bar'` (默认) | `'stairs'`

`Orientation` — 条形方向
`'vertical'` (默认) | `'horizontal'`

`BarWidth` — 分类条形的相对宽度
`0.9` (默认) | 范围 `[0,1]` 中的标量

`FaceColor` — 直方图的条形颜色
`'auto'` (默认) | `'none'` | RGB 三元组 | 十六进制颜色代码 | 颜色名称

`EdgeColor` — 直方图的边界颜色
`'none'` | `'auto'` | RGB 三元组 | 十六进制颜色代码 | 颜色名称

`FaceAlpha` — 直方图条形的透明度
`0.6` (默认) | 范围 `[0,1]` 中的标量值

`EdgeAlpha` — 直方图条形边的透明度
`1` (默认) | 范围 `[0,1]` 中的标量

`LineStyle` — 线型
`"-"` (默认) | `"--"` | `":"` | `"-."` | `"none"`

`LineWidth` — 条形轮廓的宽度
`0.5` (默认) | 正值

`SeriesIndex` — 序列索引
正整数 | `"none"`

手动颜色分配如何覆盖 `SeriesIndex` 行为

`DisplayName` — 图例使用的文本
`Data` 或 `''` 的变量名称 (默认) | 字符向量

`Annotation` — 在图例中包含对象
`Annotation` 对象

`Visible` — 可见性状态
`"on"` (默认) | on/off 逻辑值

`DataTipTemplate` — 数据提示内容
`DataTipTemplate` 对象

`ContextMenu` — 上下文菜单
空 `GraphicsPlaceholder` 数组 (默认) | `ContextMenu` 对象

`Selected` — 选择状态
`'off'` (默认) | on/off 逻辑值

`SelectionHighlight` — 是否显示选择句柄
`'on'` (默认) | on/off 逻辑值

`ButtonDownFcn` — 鼠标点击回调
`''` (默认) | 函数句柄 | 元胞数组 | 字符向量

`CreateFcn` — 创建函数
`''` (默认) | 函数句柄 | 元胞数组 | 字符向量

`DeleteFcn` — 删除函数
`''` (默认) | 函数句柄 | 元胞数组 | 字符向量

`Interruptible` — 回调中断
`'on'` (默认) | on/off 逻辑值

`BusyAction` — 回调排队
`'queue'` (默认) | `'cancel'`

`PickableParts` — 捕获鼠标点击的能力
`'visible'` (默认) | `'none'`

`HitTest` — 响应捕获的鼠标点击
`'on'` (默认) | on/off 逻辑值

`BeingDeleted` — 删除状态
只读: on/off 逻辑值

`Parent` — 父级
`Axes` 对象 | `PolarAxes` 对象 | `Group` 对象 | `Transform` 对象

`Children` — 子级
空 `GraphicsPlaceholder` 数组 | `DataTip` 对象数组

`HandleVisibility` — 对象句柄的可见性
`"on"` (默认) | `"off"` | `"callback"`

`Type` — 图形对象的类型
只读: `'histogram'` | `'categoricalhistogram'`

`Tag` — 对象标识符
`''` (默认) | 字符向量 | 字符串标量

`UserData` — 用户数据
`[]` (默认) | 数组

R2023b: 使用 `SeriesIndex="none"` 退出自动颜色选择

R2020a: 使用 `SeriesIndex` 属性控制自动颜色选择

R2020a: 不推荐使用 `UIContextMenu` 属性