Pine Script（31）：将值转换为文本函数- str.tostring()

在PineScript中，我们经常需要把各种计算结果，比如当前的价格、指标值，显示在图表的标签里，或者包含在警报消息中。但这里有一个基本规则：文本（字符串）不能直接和数字、布尔值等其他类型的数据“拼接”。

要解决这个问题，我们就需要一个万能的“翻译官”——str.tostring()函数。它的核心任务就是，把任何非字符串的值，转换成它对应的文本形式。它是连接数据与显示之间的关键桥梁。

str.tostring()函数详解

它的基本语法是：str.tostring(value, format)

• value (必填)：任何你想转换成文本的值，比如close、volume、true/false等等。
• format (可选)：一个专门用来打扮数字的格式模板。如果value是数字，你可以通过这个参数来精确控制它显示的样子。

函数会返回一个转换后的字符串。如果你给它一个na值，它会返回字符串"NaN"。

格式化（一）：预定义模板

PineScript为我们内置了三种最常用的格式模板，可以直接使用，非常方便。

1. format.mintick：按品种最小精度显示。 这非常适合用来显示价格。它会自动匹配当前交易品种的报价精度。比如对于EURUSD（精度0.00001），它会保留五位小数；对于股票（精度0.01），它会保留两位小数。
2. format.percent：显示为百分比。 它会自动在数字后面加上百分号%，并四舍五入到两位小数。注意：它不会帮你把数值乘以100。
3. format.volume：显示为易读的成交量。 它会自动给大数值加上K（千）、M（百万）、B（十亿）的后缀，并保留三位小数，让数字一目了然。

格式化（二）：自定义模板

如果内置模板无法满足你精细化的要求，比如你想控制千位分隔符、小数位数，那就需要自定义格式模板。你需要学会几个暗号（模式占位符）：

重要提示：使用这些模板时，函数会自动进行四舍五入。例如，str.tostring(1712.585, "0.0")的结果是"1712.6"。

实战案例

下面的指标脚本完美地展示了如何在同一个标签中，综合运用str.tostring()的不同格式化功能，来创建一个信息丰富的数据面板。

//@version=6
indicator(title="str.tostring() 案例", overlay=true)

// 1. 绘制EMA
emaValue = ta.ema(close, 20)
plot(emaValue, color=color.orange, linewidth=2, title="EMA")

// 2. 创建信息标签
if barstate.islast
    // 计算百分比差异
    priceDiff = (close / emaValue) - 1

    // 3. 构建标签的显示文本
    labelText = syminfo.description +                 // 品种描述
         "\n最新价: " + str.tostring(close, "#,###.00") + // 格式化价格：带千位符，强制保留2位小数
         "\n均线价: " + str.tostring(emaValue, format.mintick) + // 格式化均线：小数位数自动匹配报价精度
         "\n差异: " + str.tostring(priceDiff, "0.00%")    // 格式化百分比

    // 4. 创建标签
    label.new(bar_index, close, style=label.style_label_left,
         color=color.navy, textcolor=color.white, size=size.large,
         text=labelText)

此脚本运行后，会在图表的最右侧显示一个包含详细格式化信息的标签，充分展示了str.tostring()的强大功能：

避坑指南

1. str.tostring()适合一次转换一个值，而str.format()在一个模板里格式化多个值。但str.tostring()独有format.volume和format.mintick这两个方便的格式，有时我们会把str.tostring()的结果作为str.format()的参数来组合使用。
2. str.tostring()不能格式化时间戳。处理时间请使用专门的str.format_time()函数。
3. 如果你想在格式模板里显示0或#这些特殊字符本身，而不是让它们作为占位符，需要用单引号' '把它们括起来。例如str.tostring(close, "'Price:' #.##")。
4. PineScript不会帮你自动转换类型。需要字符串的地方，必须用str.tostring()手动转。
5. format参数只能用于数字。如果你对一个字符串或布尔值使用format参数，程序会报错。

总结

str.tostring()函数用于将数字、布尔值（true/false）或na值转换成其对应的文本字符串，是实现动态文本输出的必备工具。

数字格式化有两种方式来控制数字的显示格式：预定义格式使用format.mintick、format.percent和format.volume进行快速格式化；自定义模板通过组合0, #, ., ,等模式占位符来创建精确的输出模板。