在量化交易中，时间就是一切。但程序眼里的时间（一个从1970年开始计算的巨大毫秒数，我们称之为时间戳）和我们人类习惯的年月日时分秒完全是两码事。更头疼的是，不同交易所还处于不同的时区。 如何把难懂的时间戳，转换成我们想要看的、特定时区的具体时间呢？PineScript为此提供了一个专门的str.format_time()函数。它的两大绝技就是：精确的时间格式化和智能的时区转换。

str.format_time()函数

它的基本语法是：str.format_time(time_value, format, timezone)

• time_value (必需)：一个PineScript的时间戳值，比如当前K线的开盘时间time。
• format (可选)：一个格式模板字符串，用来规定最终文本的样子。
• timezone (可选)：你希望看到的目标时区。这是这个函数最强大的功能。

它的第三个参数timezone是它的核心武器。你可以用两种方式告诉它你想看哪个时区的时间：

1. 直接写UTC+8（东八区）或UTC-5（美东冬令时）。这种方法简单，但不会自动处理夏令时。
2. 使用标准的地理名称，比如Asia/Shanghai、America/New_York。强烈推荐这种方式，因为它会自动帮你处理烦人的夏令时问题。

自定义时间格式

要自定义时间格式，你需要学会使用下面这些模式字母作为密码，来组合成你的format模板字符串：

实战案例：创建一个跨时区的数据看板

下面的指标脚本完美地展示了str.format_time()的综合能力。它会计算图表上从第一根K线到最后一根K线的价格变动，并把开始和结束的时间，都统一转换成我们指定的“欧洲/阿姆斯特丹”时区的时间来显示。

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

// 1. var确保变量只在脚本加载时初始化一次
var firstBarTime = time
var firstPrice = open

// 2. 执行逻辑
if barstate.islast
    // 计算百分比
    percentChange = (close - firstPrice) / firstPrice

    // 3. 使用 str.format_time() 对“首末”时间进行格式化和时区转换
    targetTimezone = "Europe/Amsterdam" // 设定目标时区
    timeFormat = "HH:mm dd-MM-yyyy z"  // 设定我们想要的时间格式
    firstTimeFormatted = str.format_time(firstBarTime, timeFormat, targetTimezone)
    lastTimeFormatted  = str.format_time(time_close,   timeFormat, targetTimezone)

    // 4. 使用 str.format() 将所有信息整合到一个字符串中
    labelText = str.format(
         "{0}n首个K线: {1,number,currency} ({2})n" +
         "最新K线: {3,number,currency} ({4})n价格变动: {5,number,percent}",
         syminfo.description,    // {0} - 品种描述
         firstPrice,             // {1} - 第一个K线的价格
         firstTimeFormatted,     // {2} - 格式化后的第一个K线的时间
         close,                  // {3} - 最新收盘价
         lastTimeFormatted,      // {4} - 格式化后的最新K线的时间
         percentChange           // {5} - 价格变动百分比
    )
    // 5. 创建标签
    label.new(bar_index, hl2, text=labelText,
         style=label.style_label_left, color=color.new(color.teal, 15),
         textcolor=color.white, size=size.large)

将此指标添加到图表后，会在图表最右侧显示一个信息标签，其中包含了经过时区转换和特定格式化的首末K线时间，以及相关的价格数据。值得注意的是，由于我们使用了IANA时区名称，函数会自动处理夏令时的调整，比如五月的日期会显示CEST（欧洲中部夏令时间），而十一月则会显示CET（欧洲中部时间）：

总结

总结一下，str.format_time()是你处理所有与时间相关的文本显示问题的终极工具。我们可以通过一个包含特定模式字母的模板字符串，来精确控制时间值的显示格式。该函数最重要的功能是时区转换，当提供目标时区参数时，它会将时间值转换为指定时区的时间。使用IANA标准的地理时区名称（如"America/New_York"），函数会自动处理夏令时，最后str.format_time()的输出结果（一个字符串），常常会作为str.format()的参数，来构建包含更丰富信息的最终文本。

相关文章阅读

• Pine Script（32）：字符串格式化函数 – str.format()
• Pine Script（34）：占位符的工作原理 – str.format()