Main Content

dataTipTextRow

向数据提示添加行

说明

使用 dataTipTextRow 函数创建具有特定标签、值源和值格式的新数据提示行。创建新数据提示行后,必须将其附加到绘图对象的 DataTipTemplate 属性。

创建对象

说明

示例

r = dataTipTextRow(label,value) 使用指定的标签和值源创建新数据提示行。

r = dataTipTextRow(label,value,format) 另外还指定显示值的格式。

属性

全部展开

标签,指定为字符向量或字符串标量。

示例: 'My Label'

值源,指定为字符向量或字符串标量,其中包含数据属性(如 'XData')的名称、工作区或表变量的名称、向量或函数句柄。源值的数量必须与数据点的数量相匹配。

示例: 'XData' 将值源指定为绘图对象的 XData 属性。

示例: [1 2 3 4 5] 将值源指定为向量。

示例: @(x)sin(x) 指定函数句柄,其中 x 是对象的 XData 值。

示例: @(x,y)sin(y) 指定函数句柄,其中 y 是对象的 YData 值。

值格式,指定为 'auto' 或具有数值、日期时间或持续时间格式的字符向量或字符串标量。您指定的格式类型必须与 Value 属性中的值类型匹配。

示例: r = dataTipTextRow(label,value,'usd') 指定美元的预定义数值格式。

示例: r = dataTipTextRow(label,value,'%#4.4g') 指定一种数值格式。

示例: r = dataTipTextRow(label,value,'yyyy-MM-dd') 指定日期时间格式。

示例: r = dataTipTextRow(label,value,'hh:mm:ss') 指定持续时间格式。

数值格式

您可以指定下表中列出的预定义格式之一。您也可以指定自定义数值格式。

预定义格式说明
'usd'

美元。此选项等同于使用 '$%,.2f'。如果标签使用科学记数法,则此选项将指数值设置为 0。

'eur'

欧元。此选项等同于使用 '\x20AC%,.2f' 和指数值 0。

'gbp'

英镑。此选项等同于使用 '\x00A3%,.2f' 和指数值 0。

'jpy'

日元。此选项等同于使用 '\x00A5%,d' 和指数值 0。

'degrees'

在值之后显示度符号。此选项等同于使用 '%g\x00B0' 和默认指数值。

'percentage'

在值之后显示百分号。此选项等同于使用 '%g%%' 和默认指数值。

'auto'

'%g' 的默认格式和默认指数值。

如果上表中列出的格式都不是您需要的格式,则可以创建一个带标识符的自定义字符向量或字符串。

Sample custom character vector with required and optional identifiers

标识符是可选的,百分比符号和转换字符除外。按以下顺序构造格式:

  • 百分号

  • 一个或多个标志 - 用来指示在正值之前添加加号之类的选项。要查看完整的选项列表,请参阅可选标志的表。

  • 字段宽度 - 刻度标签上要打印的最小字符数。请将字段宽度指定为整数值。如果刻度值中的有效位数小于字段宽度,则在标签上用空格填充。

  • 精度 - 小数点右侧的位数或有效位数,具体取决于转换字符。将精度指定为一个整数值。

  • 转换字符 - 值的类型。要查看完整的选项列表,请参阅转换字符的表。如果指定的转换不适合数据,MATLAB® 将覆盖指定的转换并使用 %e

您还可以在格式的开头或末尾指定字面文本。要打印单引号,请使用 ''。要打印百分比字符,请使用 %%

  • '$%.2f' - 在每个值前面显示美元符号,并使用具有两位小数的定点记数法。

  • '%.3f Million' - 在每个值后面显示 Million,并使用具有三位小数的定点记数法。

可选标志说明数值格式示例
+为正值打印符号字符 (+),例如 '+100''%+4.4g'
0用前导零而不是空格填充字段宽度,例如 '0100''%04.4g'
左对齐,在值的末尾而不是开头用空格填充。例如,如果字段宽度为 4,则此标志将标签格式化为 '100 ',而不是 ' 100''%-4.4g'
#

对于 %f%e%g 转换字符,即使精度为 0,也会打印小数点,例如 '100.'。对于 %g,不会删除尾随零。

'%#4.4g'
转换字符说明示例
di底数为 10 的有符号整数。精度值指示有效位数。 '%.4d' 将 π 显示为 0003
f定点记数法。精度值指示小数位数。'%.4f' 将 π 显示为 3.1416
e指数记数法。精度值指示小数位数。'%.4e' 将 π 显示为 3.1416x100
g更精简版本的 ef,不带尾随零。精度值指示最大小数位数。'%.4g' 将 π 显示为 3.1416

日期时间格式

下表显示了几种常见的格式,还包括纽约市 2014 年 4 月 19 日星期六晚上 9:41:06.12345 的格式化输入示例。

Format 的值示例
'yyyy-MM-dd'2014-04-19
'dd/MM/yyyy'19/04/2014
'dd.MM.yyyy'19.04.2014
'yyyy年 MM月 dd日'2014年 04月 19日
'MMMM d, yyyy'April 19, 2014
'eeee, MMMM d, yyyy h:mm a'Saturday, April 19, 2014 9:41 PM
'MMMM d, yyyy HH:mm:ss Z'April 19, 2014 21:41:06 -0400
'yyyy-MM-dd''T''HH:mmXXX' 2014-04-19T21:41-04:00

下表显示了可用于构造日期时间格式的字母标识符。可以使用连字符、空格、冒号或任何非 ASCII 字符等非字母字符来分隔字段。这些标识符遵从日期的 Unicode® 区域数据标记语言 (LDML) 标准。

使用下表中的标识符指定日期和时间字段的显示格式。

字母标识符说明显示
G年代CE
y年份,没有前导零。请参阅紧随此表后的“注释”。2014
yy年份,使用最后两位数。请参阅紧随此表后的“注释”。14
yyyyyyy ...年份,至少使用 'y' 实例数指定的位数对于年份 2014,'yyy' 显示 2014,而 'yyyyy' 则显示 02014
uuu、...ISO 年份。单个数字来指定年份。ISO 年份值将正数值分配给 CE 年份,将负数值分配给 BCE 年份,1 BCE 表示年份 0。2014
Q季度,使用一位数2
QQ季度,使用两位数02
QQQ季度,缩写2 季度
QQQQ季度,全名第二季度
M月份,使用一位或两位数字4
MM月份,使用两位数字04
MMM月份,缩写名称四月
MMMM月份,全名四月
MMMMM月份,首字母大写A
W一月中的第几周1
d一月中的第几天,使用一位或两位数5
dd一月中的第几天,使用两位数05
D一年中的第几天,使用一位、两位或三位数95
DD一年中的第几天,使用两位数95
DDD一年中的第几天,使用三位数095
e一周中的星期几,使用一位或两位数的数值。7,星期日是一周中的第一天。
ee一周中的星期几,使用两位数字07
eee星期几,缩写名称周六
eeee星期几,全名星期六
eeeee星期几,使用一位大写数字
a一天中的时段(上午或下午)下午
h小时,采用 12 小时制格式,使用一位或两位数9
hh小时,采用 12 小时制格式,使用两位数09
H小时,采用 24 小时制格式,使用一位或两位数21
HH小时,采用 24 小时制格式,使用两位数21
m分钟,使用一位或两位数41
mm分钟,使用两位数41
s秒,使用一位或两位数6
ss秒,使用两位数06
S, SS, ..., SSSSSSSSS小数秒,使用 'S' 个数所指定的位数(最多 9 位)。'SSS' 将 6.12345 秒截断为 123

一些提示和注意事项:

  • 如果您读取两位年数并将格式指定为 yyy,则基准年份确定该年所属的世纪。

  • 使用一个或多个 u 字符而非 y 字符在使用接近零的年数时解释年份。

  • 公元 144683 年之后或公元前 140743 年之前的日期时间值仅显示年份数字,而不管指定的格式值为何。

使用下表中的标识符指定时区偏移量的显示格式。时区偏移量是指具体日期时间与 UTC 之间相差的时间量。这不同于时区,时区包含确定一年特定时间的偏移量的规则。若要确保明确地显示时间,请加上时区偏移量标识符。

字母标识符说明显示
z时区偏移量的缩写名称。如果此值不可用,则时区偏移量使用短 UTC 格式,例如 UTC-4EDT
ZISO 8601 基本格式,带有小时、分钟和可选的秒字段。-0400
ZZZZ长 UTC 格式。UTC-04:00
ZZZZZISO 8601 扩展格式,带有小时、分钟和可选的秒字段。以 ISO 8601 标准规定的 UTC 指示符 "Z" 的形式来显示与零时区的偏移量。-04:00
xXISO 8601 基本格式,带有小时字段和可选的分钟字段。如果您指定 X,则以 ISO 8601 标准规定的 UTC 指示符 "Z" 的形式来显示与零时区的偏移量。-04
xxXXISO 8601 基本格式,带有小时和分钟字段。如果您指定 XX,则以 ISO 8601 标准规定的 UTC 指示符 "Z" 的形式来显示与零时区的偏移量。-0400
xxxXXXISO 8601 扩展格式,带有小时和分钟字段。如果您指定 XXX,则以 ISO 8601 标准规定的 UTC 指示符 "Z" 的形式来显示与零时区的偏移量。-04:00
xxxxXXXXISO 8601 基本格式,带有小时、分钟和可选的秒字段。如果您指定 XXXX,则以 ISO 8601 标准规定的 UTC 指示符 "Z" 的形式来显示与零时区的偏移量。-0400
xxxxxXXXXXISO 8601 扩展格式,带有小时、分钟和可选的秒字段。如果您指定 XXXXX,则以 ISO 8601 标准规定的 UTC 指示符 "Z" 的形式来显示与零时区的偏移量。-04:00

持续时间格式

持续时间格式可以是一个带有时间单位的数字(例如 '0.5 yrs'),也可以是一个数字计时器(例如 'hh:mm:ss',表示天数、小时数、分钟数和秒数)。

对于带有时间单位的数字,请指定下列单位之一:

  • 'y' - 固定长度的年,一年等于 365.2425 天

  • 'd' - 固定长度的天,一天等于 24 小时

  • 'h' - 小时

  • 'm' - 分钟

  • 's' - 秒

对于数字计时器格式,请指定下列格式之一:

  • 'dd:hh:mm:ss'

  • 'hh:mm:ss'

  • 'mm:ss'

  • 'hh:mm'

  • 前三种格式中的任何一种,再加上最多九个 S 字符指示秒的小数位,例如 'hh:mm:ss.SSSS'

示例

全部折叠

加载样本事故数据并创建散点图。然后在默认数据提示中添加第三行。对于标签,使用 State。对于值源,使用 statelabel 工作区变量。创建新行后,将其添加到 Scatter 对象的 DataTipTemplate 属性。

load('accidents.mat','hwydata','statelabel')
s = scatter(hwydata(:,5),hwydata(:,4));
row = dataTipTextRow('State',statelabel);
s.DataTipTemplate.DataTipRows(end+1) = row;

以交互方式或使用 datatip 函数创建数据提示。

dt = datatip(s,11246.7,1493);

Figure contains an axes object. The axes object contains an object of type scatter.

创建正弦值的线图。在默认数据提示中添加第三行以显示余弦值。为显示的余弦值指定数值格式。在本例中,使用 '%+4.4g' 以包含符号字符 (+) 来表示正值。创建新行后,将其添加到 Line 对象的 DataTipTemplate 属性。

x = linspace(0,10);
y1 = sin(x);
y2 = cos(x);
p = plot(x,y1);
row = dataTipTextRow('Cosine',y2,'%+4.4g');
p.DataTipTemplate.DataTipRows(end+1) = row;

以交互方式或使用 datatip 函数创建数据提示。

dt = datatip(p,6.56566,0.27873);

Figure contains an axes object. The axes object contains an object of type line.

版本历史记录

在 R2019a 中推出