Matplotlib colorbar() 函数

colorbar() 用于在图表中添加颜色条（色标），将颜色映射到数值范围。

颜色条是与 colormap 配合使用的必要元素，让读者能将颜色映射回原始数据值。

函数定义

matplotlib.pyplot.colorbar(mappable=None, cax=None, ax=None, **kwargs)
Figure.colorbar(mappable=None, cax=None, ax=None, use_gridspec=True,
    **kwargs)

参数说明

参数	说明
mappable	可映射颜色的对象，如 imshow()、scatter()、contourf() 的返回值（必填）
ax	颜色条所附属的 Axes（推荐使用，自动调整布局）
cax	专用的颜色条 Axes（精细控制时使用）
shrink	颜色条相对于 Axes 的缩放比例，默认 1.0，常用 0.8
aspect	颜色条的宽高比，默认 20
label	颜色条的标签文本
orientation	'vertical'（默认）或 'horizontal'
ticks	自定义刻度位置
extend	'neither'/'both'/'min'/'max'，超出范围的颜色指示
pad	颜色条与 Axes 之间的间距

使用 fig.colorbar(im, ax=ax) 是推荐写法，会自动调整子图布局为颜色条腾出空间。

使用示例

示例 1：imshow + 垂直颜色条

实例

import matplotlib.pyplot as plt
import numpy as np

data = np.random.rand(10, 10)

fig, ax = plt.subplots(figsize=(6, 5), layout='constrained')

im = ax.imshow(data, cmap='viridis', aspect='auto')

# 添加垂直颜色条
cbar = fig.colorbar(im, ax=ax, label='Value', shrink=0.8)

ax.set_title('imshow with Colorbar')
ax.set_xlabel('Column')
ax.set_ylabel('Row')
plt.show()

示例 2：水平颜色条 + 自定义刻度

实例

import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(-3, 3, 100)
y = np.linspace(-3, 3, 100)
X, Y = np.meshgrid(x, y)
Z = np.sin(X) * np.cos(Y)

fig, ax = plt.subplots(figsize=(7, 5), layout='constrained')

im = ax.contourf(X, Y, Z, levels=15, cmap='coolwarm')

# 水平颜色条（在 Axes 下方）
cbar = fig.colorbar(im, ax=ax,
orientation='horizontal',
label='Amplitude',
shrink=0.8,
pad=0.08,
ticks=[-0.8, -0.4, 0, 0.4, 0.8])

ax.set_title('Horizontal Colorbar')
ax.set_xlabel('X')
ax.set_ylabel('Y')
plt.show()

示例 3：scatter + 颜色条

实例

import matplotlib.pyplot as plt
import numpy as np

np.random.seed(42)
n = 100
x = np.random.rand(n) * 10
y = np.random.rand(n) * 10
values = np.random.rand(n) * 100 # 颜色映射的数据

fig, ax = plt.subplots(figsize=(7, 5), layout='constrained')

sc = ax.scatter(x, y, c=values, cmap='YlOrRd',
s=100, edgecolors='white', linewidth=0.5)

# scatter 返回的 PathCollection 也能传给 colorbar
cbar = fig.colorbar(sc, ax=ax, label='Score', shrink=0.8)

ax.set_title('Scatter with Colorbar')
ax.set_xlabel('X')
ax.set_ylabel('Y')
plt.show()

常见问题

颜色条导致子图大小不一致？

使用 layout='constrained' 参数可自动处理。

或在 Figure 上调用 fig.colorbar(im, ax=axes) 传入所有受影响的 Axes 列表。

多个子图如何共享一个颜色条？

将一个 colorbar 关联到多个子图时，传入 ax=axes_list。

Matplotlib 参考文档

返回顶部

菜鸟教程