Pine Script 中的时间周期变量总览

Pine Script 提供了几个内置变量，用于返回关于时间周期的信息。它们能告诉我们，我们的指标或策略当前正在何种时间周期上运行，例如是在周线K线图上，还是在分钟级别的分辨率上。

知道了这些信息后，我们的脚本就可以根据图表的时间周期来执行不同的操作。我们也可以利用当前的时间周期信息来加载其他周期的背景数据。

我们可以将 Pine Script 的时间周期变量分为三组：

1. 特定时间周期变量：这些变量能精确地告诉我们图表使用的是哪种基础类型的时间周期，例如是日线还是周线。
2. 通用时间周期变量：通过这些变量，我们可以大致区分图表是日线及以上周期，还是日内周期。
3. 时间周期数值变量：它们能返回时间周期的具体数值（时间间隔），例如对于30分钟图，它会返回30。

接下来，让我们逐一了解每个组。

检查特定时间周期的变量

第一组变量用于判断脚本是否运行在某种特定的时间周期上。例如，这些变量可以测试脚本是否运行在日线图上，或者是否使用了秒级别的数据。

这些变量包括：

这组变量中比较特殊的是 timeframe.isminutes。这个变量不仅在分钟图上为 true，在小时图和等量图 (Range) 上也同样为 true。其原因是 TradingView 使用分钟数据来构建小时图和等量图。

检查通用时间周期的变量

有时我们不需要知道图表的精确时间周期，只需大致区分日内图和日线及以上的大周期图即可。第二组时间周期变量正是用于提供此类信息：

时间周期信息变量

上面的时间周期变量说明了脚本运行在何种类型的时间周期上。但有时，知道时间周期的具体间隔数值也同样重要。

下面这两个 Pine Script 变量，可以告诉我们时间周期所使用的具体数值（时间间隔）：

要了解更多关于处理时间周期的信息，请参阅 Pine Script 的时间周期章节。

timeframe.period：获取图表的时间周期

Pine Script 的 timeframe.period 变量，会以一段文本字符串的形式，返回当前图表的时间周期及其周期数值（时间间隔）。

例如，对于一个3日图，timeframe.period 会返回 "3D"；对于一个2小时的时间周期，该变量的值是 "120"；而在一个30秒图上，它的值是 "30S"。

timeframe.period 在不同时间周期上的返回值

timeframe.period 返回的值取决于我们的脚本当前运行在哪个时间周期上。下表展示了该变量针对不同时间周期的返回值：

需要澄清的是，上表中的双引号 (") 只是为了表明 timeframe.period 返回的是一个字符串值，引号本身并非该变量值的一部分。因此，例如当我们在一个文本标签中包含该变量时，是不会看到这些引号的。

timeframe.period 返回值的模式

timeframe.period 返回一个包含了图表时间周期信息的字符串。这个值可能是一个数字（如 "60"），一个单字母（如 "D"），也可能是数字和字母的组合（如 "2W"）。这些不同返回值背后的规则是什么呢？

timeframe.period 使用的规则如下：

• 分钟级别的时间周期总是用一个数字表示，不带字母。
• 单位为1的时间周期（除分钟外）只使用一个字母。
• 间隔大于1的时间周期会将数字与一个字母组合起来。

下表展示了这些规则如何应用于 TradingView 的各种时间周期：

不依赖于图表类型

timeframe.period 返回的是图表的时间间隔，这个值并不依赖于图表的类型。

即使是像折线图 (Line Break) 这样不常见的图表类型，也是基于一个具有特定时间间隔的数据来构建的。因此，对于一个1日的折线图，timeframe.period 同样会返回 "D"。

在棒图、K线图、平均K线图、砖块图、折线图、卡吉图和点数图上，timeframe.period 变量都会返回其底层基于时间的数据的周期。

注意：timeframe.period 不会返回一个非标准图表类型的参数，例如砖块图的ATR周期或砖块大小。

完整示例脚本

让我们通过一个完整的脚本来看看如何使用 timeframe.period 变量。下方的指标会创建一个文本标签，用以显示图表的时间间隔和时间周期类型：

//@version=5
indicator(title="Time frame period example", overlay=true)

// 在图表的最后一根已确认的历史K线上，创建一个新的文本标签
if barstate.islastconfirmedhistory
    // 判断图表类型（用于标签文本）
    chartType = timeframe.isintraday ? "intra-day" : "daily or higher"

    // 创建文本标签
    label.new(x=bar_index + 1, y=close, style=label.style_label_left, 
         size=size.large, color=#ffeecc, textcolor=color.black,
         text="This " + chartType + " chart has\n" + 
             "a time frame period of:\n" + timeframe.period)

代码解析

这个指标首先调用 indicator() 函数，这会为脚本命名并在与主图相同的图表区域显示它。

然后，我们使用一个 if 语句来评估 barstate.islastconfirmedhistory 变量。该变量只在图表的最后一根已确认的历史K线上才为 true。在这个脚本中，这是一种只创建一个标签，而不是重复创建多个的有效方法。

在 if 代码块中，我们首先判断图表的大致时间周期类型。为此，条件运算符 (?:) 会评估 timeframe.isintraday 变量。该变量在日内图上为 true。在这种情况下，我们为 chartType 变量赋予 "intra-day"（日内）这个文本。对于非日内的时间周期，我们则将 "daily or higher"（日线或更高）存入该变量。

接着，我们使用 label.new() 函数来创建标签。这个标签会显示在K线的收盘价 (close) 处，并向右移动一根K线 (bar_index + 1) 的位置。它的箭头指向左边 (label.style_label_left)，并设为大号字体 (size.large)。背景色是 #ffeecc，即淡橘色的十六进制颜色代码，标签的文字则以黑色 (color.black) 显示。

我们通过 + 运算符将几个字符串片段组合起来，以创建标签的最终内容。这样，我们既包含了 chartType 变量，也包含了 timeframe.period 变量。由于后者本身返回的就是一个字符串，它能与其他文本片段直接兼容（无需进行字符串转换）。

让我们看看脚本的效果。在一个1小时的图表上，标签会识别出这是日内时间周期，并且 timeframe.period 显示的值为‘60’：

如果我们切换到一个3日的图表，脚本会识别出这是更高的时间周期，并且 timeframe.period 显示为‘3D’：

如何应用 timeframe.period

有以下几种方式可以应用 timeframe.period 变量：

• 自动加载更高时间周期：利用 Pine Script 的背景数据功能。例如，我们可以编写一条规则，当 timeframe.period 等于 "1"（分钟）时，就加载60分钟数据作为下一个时间周期；当变量是 "D"（日）时，加载周线数据；对于 "W"（周），则获取月线数据。
• 与 time() 函数结合：明确表示该函数应该使用图表自身的时间周期，而不是某个自定义的分辨率。（虽然向 time() 传入一个空字符串有同样的效果，但使用 timeframe.period 意图更清晰。）
• 与 request.security() 结合：这是最常见的用法，用于加载与当前图表时间周期相同的背景数据。

顺便一提，一个分辨率输入项返回的字符串，与 timeframe.period 使用的格式是相同的。因此，在我们的代码中使用这类输入项的地方，我们也可以用 timeframe.period 来替代（反之亦然）。 如果我们想以数字形式来评估图表的时间间隔，我们应该改用 timeframe.multiplier 变量。通过那个变量，我们可以判断时间周期的间隔是小于60还是大于1。

timeframe.period vs. timeframe.multiplier 的区别

Pine Script 有两个变量可以返回图表的当前时间周期：

• timeframe.multiplier 变量：返回一个数字，代表时间周期的间隔。
  • 例如，对于1分钟、1天和1周的图表，它都返回 1。在一个30秒和30分钟的图表上，该变量则返回 30。
• timeframe.period 变量：返回一个字符串，包含了时间周期的间隔和类型。
  • 一个字母用于指示时间周期的类型："S" 代表秒，"D" 代表日，"W" 代表周，而 "M" 代表月。基于分钟的时间周期不使用字母。
  • 例如，对于30秒图，它的值是 "30S"；对于3日图，则是 "3D"。

下表清晰地展示了这两个变量针对不同时间周期的返回值差异：

从表中可以看出，timeframe.multiplier 返回的间隔数值并不是唯一的：好几种不同的时间周期可能拥有相同的周期数值（例如，1分钟图、1日图和1月图都返回 1）。

相比之下，timeframe.period 变量则能唯一地识别时间周期。一个1分钟图的值是 "1"，一个1日图是 "D"，而一个1月图是 "M"。

timeframe.period 的特性

• 因为 timeframe.period 结合了时间周期和其间隔，所以该变量的值对于所有基于时间的图表都是唯一的。然而，对于等量图 (Range)，它返回的值与1分钟图相同（因为 TradingView 使用1分钟数据来构建等量图）。因此，timeframe.period 无法区分1分钟图和任何等量图。
• 我们可以将 timeframe.period 用于任何 TradingView 的指标和策略。并且这个变量在 TradingView 提供的任何时间周期上都可用。
• 虽然我们可以对 timeframe.period 使用历史引用运算符 ([])，但这毫无意义，因为该变量在每一根K线上返回的值都是相同的。
• 在 Pine Script 第3版及更早版本中，timeframe.period 变量曾被命名为 period。

内容总结

• timeframe.period 变量以一段文本字符串的形式，返回时间周期的间隔和类型。
• 对于分钟和小时图，timeframe.period 返回一个只包含数字的字符串。但对于秒、日、周和月图，返回的值会分别包含字母 "S"、"D"、"W" 或 "M"。
• timeframe.period 的返回值不依赖于图表类型。像折线图和点数图这样不常见的图表，仍然是基于时间K线（例如1小时或1天）来构建的。

timeframe.multiplier：获取时间周期的数值部分

Pine Script 的 timeframe.multiplier 变量，会以一个整数的形式，返回当前图表时间周期的周期数值。

当我们的指标或策略在一个10分钟的图表上计算时，timeframe.multiplier 会返回 10。而在一个1日的时间周期上，该变量则会返回 1。

timeframe.multiplier 在不同时间周期上的返回值

timeframe.multiplier 的值可以告诉我们，我们的脚本当前运行在何种时间间隔的图表上。下表展示了该变量针对不同时间周期的返回值：

timeframe.multiplier 返回的是 TradingView 用来构建当前图表的底层数据的时间间隔。大多数情况下，这个间隔与我们选择的时间周期设置是一致的。

但对于等量图 (Range) 是个例外。在这种图表上，timeframe.multiplier 总是返回 1。这是因为 TradingView 使用1分钟数据来构建所有的等量图，所以其底层的时间间隔就是‘1’。

无法唯一确定时间周期

timeframe.multiplier 返回的间隔数值并不是唯一或特定的，多种不同的时间周期可能会共享相同的间隔数值。例如，一个30秒、30分钟和30日的图表，其 timeframe.multiplier 的值都是 30。

因此，我们不能单独使用 timeframe.multiplier 来准确判断脚本运行在哪种时间周期上。为此，我们需要结合使用其他的时间周期变量：

• timeframe.ismonthly (判断是否为月线图)
• timeframe.isweekly (判断是否为周线图)
• timeframe.isdaily (判断是否为日线图)
• timeframe.isminutes (判断是否为分钟图)
• timeframe.isseconds (判断是否为秒图)

timeframe.multiplier 的一个替代方案是 timeframe.period 变量。该变量会返回一个同时包含了时间间隔和周期类型的字符串，这种组合在不同的时间周期之间是唯一的。例如，它对30秒图返回 "30S"，对30分钟图返回 "30"，对30日图则返回 "30D"。

不依赖于图表类型

timeframe.multiplier 的值是基于时间周期的间隔，但它并不依赖于图表的类型。

即使是像点数图 (Point & Figure) 这样的特殊图表，仍然是基于一个具有特定间隔的时间周期来构建的。因此，对于一个1小时的点数图，timeframe.multiplier 会返回 1。

对于棒图、K线图、平均K线图、砖块图、折线图、卡吉图和点数图，timeframe.multiplier 变量都会返回其图表底层基于时间的数据的周期数值。

这也意味着，我们无法使用 timeframe.multiplier 来返回一个非标准图表类型的特定参数，例如砖块图的砖块大小或ATR周期。

完整示例脚本

让我们通过一个完整的脚本来看看 timeframe.multiplier 变量的应用。下方的指标会通过一个文本标签，显示图表的时间间隔以及其他时间周期信息：

//@version=5
indicator(title="Time frame multiplier example", overlay=true)

// 在图表的最后一根已确认的历史K线上创建一个文本标签
if barstate.islastconfirmedhistory
    // 判断图表类型（用于标签文本）
    chartType = timeframe.isdwm ? "daily or higher" : "intra-day"

    // 创建实际的文本标签
    label.new(x=bar_index + 1, y=hl2, style=label.style_label_upper_left,
         size=size.large, color=#b3d1ff, textcolor=color.black,
         text="This " + chartType + " chart has\n" + 
             "a time frame multiplier of:\n" + 
             str.tostring(timeframe.multiplier))

代码解析

代码首先使用 indicator() 函数来设置脚本的属性，这行为脚本命名，并将其叠加显示在主图的交易品种上。

然后，一个 if 语句检查脚本当前是否正在处理图表的最后一根已确认的历史K线。当条件成立时，barstate.islastconfirmedhistory 变量为 true。通过这个条件，我们的标签只会在图表的末尾被创建一次，而不是重复创建。

在 if 语句内部，我们首先创建了 chartType 变量。这个变量用于说明脚本是运行在日线及以上的大周期图上，还是在日内时间周期上。条件运算符 (?:) 通过评估 timeframe.isdwm 变量来决定这个信息。

该变量在日线、周线和月线时间周期上为 true。如果是这种情况，运算符会将变量设为 "daily or higher"（日线或更高）这个文本。否则，对于其他时间周期，变量的值则会变为 "intra-day"（日内）。

之后，label.new() 函数创建了实际的文本标签。这个绘图对象会显示在K线的中点 (hl2) 处，并向右移动一根K线 (bar_index + 1) 的位置。它的箭头指向左上方 (label.style_label_upper_left)，并拥有一个淡蓝色的背景，这是通过十六进制颜色值 #b3d1ff 设置的。标签的文字是黑色的 (color.black)，并使用了大号字体 (size.large)。

标签的消息内容由几个用 + 运算符连接的字符串片段组成。我们包含了 chartType 变量，并使用了几个带有换行符 (\n) 的文本。同时，我们也添加了 timeframe.multiplier 变量。由于该变量返回的是一个数字，而这里我们需要拼接文本，所以我们首先使用 str.tostring() 函数将这个数字转换为文本。

让我们看看脚本在图表上的效果。当我们在一个2小时的图表上运行它时，标签会显示其乘数为120（分钟）：

如果我们把图表换成别的时间周期，比如2周，标签也会随之改变：

如何应用 timeframe.multiplier

timeframe.multiplier 是一个有用的时间周期变量，但它并非在所有情况下都是最佳选择。

我们主要使用 timeframe.multiplier 来测试代码是否运行在一个高于或低于某个数值的时间周期上。基于这个判断，我们就可以为特定的时间周期范围运行特定的代码逻辑。

由于 timeframe.multiplier 无法区分时间周期的类型（例如，无法区分15分钟和15天），我们常常需要将它与其他时间周期变量结合使用。例如，要判断脚本是否运行在2小时（120分钟）或以上的时间周期，我们可以这样编码：

// 判断脚本是否运行在2小时或以上的时间周期
isTwoHoursOrMore = timeframe.multiplier >= 120 and 
	 timeframe.isminutes

提示：如果我们的目标是加载与当前图表时间周期相同的背景数据，我们不应使用 timeframe.multiplier，而应使用 timeframe.period 变量。后者会返回一个包含了周期类型信息的字符串，能更准确地指定时间周期。

timeframe.multiplier 的特性

• timeframe.multiplier 可以被 TradingView 的指标和策略使用。并且，我们可以在任何可能的时间周期和图表类型上访问这个变量。
• 虽然我们可以对 timeframe.multiplier 使用历史引用运算符 ([])，但这没有必要，因为该变量在每一根K线上的返回值都是相同的。
• 在 Pine Script 第3版及更早版本中，timeframe.multiplier 变量曾被命名为 interval。

内容总结

• timeframe.multiplier 变量以一个整数的形式，返回时间周期的间隔数值。
• 该变量说明了 TradingView 用来构建图表的时间周期数值，例如，对于5分钟图和5日图，它都会返回 5。
• timeframe.multiplier 的返回值不依赖于图表类型。像卡吉图 (Kagi) 和折线图 (Line Break) 这样不常见的图表，仍然是基于具有特定间隔的数据来构建的。

timeframe.isseconds：判断是否为秒级时间周期

Pine Script 的 timeframe.isseconds 变量，可以告诉我们一个指标或策略当前是否运行在一个基于秒的时间周期上。

该变量会返回以下两个值之一：

• true：当脚本使用一个基于秒的时间周期时，例如15秒或30秒图。
• false：当脚本运行在除秒级以外的任何其他时间周期上时。

timeframe.isseconds 在不同时间周期上的返回值

timeframe.isseconds 的值取决于图表的时间周期。下表展示了该变量针对不同时间周期的返回值：

基于时间间隔，而非图表类型

timeframe.isseconds 的值是基于图表的时间间隔。当K线是由秒级别的数据构成时，timeframe.isseconds 就为 true。

但该变量的值并不依赖于绘制这些K线的图表样式。即便是像点数图这样不常见的图表，也仍然可以使用一个基于秒的时间间隔。

因此，对于 timeframe.isseconds 而言，图表类型并不重要。无论是在棒图、K线图、平均K线图、砖块图、折线图、卡吉图还是点数图上，timeframe.isseconds 变量都会如上表所示，返回 true 或 false。

与其他时间周期变量的比较

Pine Script 中还有其他几个时间周期变量。当我们的脚本在一个秒级图表上运行时，这些其他变量会返回如下的值：

总结一下，在一个秒级时间周期上（即 timeframe.isseconds 为 true 时），timeframe.isintraday 变量也同样为 true。但所有其他的时间周期布尔变量在秒级K线上都为 false。

完整示例脚本

让我们通过一个完整的脚本来看看如何应用 timeframe.isseconds。下方的指标会创建一个文本标签，用以说明关于秒级时间周期的一些信息：

//@version=5
indicator(title="Seconds time frame example", overlay=true)

// 在最后一根已确认的历史K线上，绘制一个标签，
// 用以说明图表是否使用了秒级时间周期。
if barstate.islastconfirmedhistory
    // 判断要在标签中显示的文本
    labelText = if timeframe.isseconds
        "Yep, this is a seconds chart!"
    else
        "This chart is slower\nthan a seconds chart."

    labelText += "\n\nChart period:\n" + timeframe.period

    // 创建实际的文本标签
    label.new(x=bar_index, y=high, style=label.style_label_down,
         color=color.new(color.lime, 40), textcolor=color.black,
         size=size.large, text=labelText)

代码解析

这个指标首先使用 indicator() 函数来定义其设置。这行代码为脚本命名，并将其叠加显示在主图的交易品种上。

接下来，一个 if 语句检查 barstate.islastconfirmedhistory。该变量只在图表的最后一根已确认的历史K线上才为 true。我们使用这个条件，是为了让标签只被创建一次，而不是在多根K线上重复创建。

在 if 语句内部，我们首先确定标签的文本内容。我们创建了 labelText 变量，并通过一个 if/else 语句为其赋值。判断的条件是 timeframe.isseconds。当其为 true 时，我们使用一段文本来确认这是一个秒级图表。对于其他时间周期，else 部分的代码则会生成一段文本，说明当前时间周期比秒级要慢。

然后，我们为 labelText 变量追加更多信息。加法赋值运算符 (+=) 会将 timeframe.period 变量的值（它能告诉我们图表的具体周期，例如30秒图对应"30S"）添加到现有文本的后面。这样，标签也能显示出确切的时间周期。

最后，我们使用 label.new() 函数来创建实际的标签。它会出现在当前K线的最高价处 (bar_index, high)，并指向下方 (label.style_label_down)。背景是青柠绿色 (color.lime)，我们通过 color.new() 函数为其添加了透明度。标签的文字以黑色 (color.black) 和大号字体 (size.large) 显示。对于标签的文本内容，我们使用了 labelText 变量。

当该指标在一个基于秒的图表上运行时，例如下面的比特币 (BTC/USD) 图表，它会确认这是一个秒级时间周期：

如果我们切换到一个不同的时间周期，该标签会识别出新的K线间隔并相应地更新其内容：

如何应用 timeframe.isseconds

有以下几种方式可以应用 timeframe.isseconds 变量：

• 根据时间周期自定义脚本设置。例如，在一个秒级图表上，我们可能希望使用比分钟图上更长的移动平均线周期。
• 检查脚本运行环境。确保脚本运行在适合其交易逻辑的时间周期上。例如，如果我们编写的是一个波段交易策略，我们很可能不希望它在秒级和分钟级的分辨率上生成信号。
• 根据时间周期改变计算逻辑。例如，在一个秒级图表上，止损点位可以设置得比在小时图上更贴近入场价。
• 自动获取更高时间周期的数据。当脚本运行在秒级数据上时，我们可以让它自动加载分钟数据，以进行更高时间周期的分析。

通常，我们会将 timeframe.isseconds 变量与其他时间周期变量结合起来。这样，我们就能在例如秒级、分钟级和日线级等不同的时间周期上，实现不同的脚本行为。

timeframe.isseconds 的特性

• timeframe.isseconds 只告诉我们脚本是否运行在秒级K线上，但它并不会告诉我们这些K线具体是多少秒。要获取这个信息，我们需要使用 timeframe.multiplier 变量。当 timeframe.isseconds 为 true 时，timeframe.multiplier 就会告诉我们图表分辨率所使用的秒数，例如对于15秒和30秒图，它会分别返回 15 或 30。
• 通过 timeframe.period 变量，我们可以获取图表的周期及其类型。对于秒级时间周期，该变量会返回一个以‘S’字母结尾的字符串，例如对于15秒图，它会返回 "15S"。我们常常使用这个变量来加载与当前图表相同时间周期的背景数据。
• 虽然我们可以对 timeframe.isseconds 使用历史引用运算符 ([])，但这没有任何区别，因为该变量在每一根K线上的返回值都是相同的。
• 每一个 TradingView 指标和策略都可以使用 timeframe.isseconds。并且，这个变量在每一个时间周期上都可用。
• 在 Pine Script 的第3版及更早版本中，timeframe.isseconds 变量曾被命名为 isseconds。

内容总结

• 当脚本运行在一个基于秒的时间周期上时（例如15秒和30秒图），timeframe.isseconds 变量返回 true。
• 当脚本运行在一个分钟或更高的时间周期上时，timeframe.isseconds 返回 false。
• timeframe.isseconds 的判断结果不受图表类型的影响，它同样也适用于像卡吉图 (Kagi) 和砖块图 (Renko) 这样不太常见的图表。