Shiny 定时刷新实战：用 invalidateLater 与 reactiveTimer 实现周期性更新的响应式应用

导读

本文围绕 Shiny 官方示例 inst/examples/11_timer 展开，系统讲解 invalidateLater() 与 reactiveTimer() 的定时失效机制：它们可以在指定毫秒数后自动使 observer 或 reactive 表达式失效并重新执行，从而实现"每秒更新当前时间"这类周期性刷新需求。读完本文，你将掌握定时刷新的标准写法、停止定时循环的边界控制、session 参数对生命周期管理的必要性，以及底层调度器的工作原理，可直接用于实现实时时钟、轮询数据源、定时重绘图表等常见场景。

一、示例概览：一个每秒刷新的时钟

inst/examples/11_timer 是 Shiny 官方示例之一，它的说明文档（Readme.md）明确指出：

invalidateLater() 可以在给定毫秒数之后使一个 observer 或 reactive 表达式失效。在本示例中，输出 currentTime 每隔一秒更新一次，因此它展示的是以秒为粒度的当前时间。

对应的完整应用代码位于 app.R，全量如下：

library(shiny)

# Define UI for displaying current time ----
ui <- fluidPage(

  h2(textOutput("currentTime"))

)

# Define server logic to show current time, update every second ----
server <- function(input, output, session) {

  output$currentTime <- renderText({
    invalidateLater(1000, session)
    paste("The current time is", Sys.time())
  })

}

# Create Shiny app ----
shinyApp(ui, server)

在本地运行该示例有两种方式：

# 方式一：直接运行示例（推荐，无需手动创建文件）
shiny::runExample("11_timer")

# 方式二：source 示例目录下的 app.R 后运行
source("inst/examples/11_timer/app.R")

运行后在浏览器中即可看到页面标题每秒跳变一次，展示 The current time is <当前时间>。

这段代码的核心逻辑只有两行，却蕴含了 Shiny 定时刷新的完整机制：

1. invalidateLater(1000, session)：在 1000 毫秒后使当前正在执行的响应式上下文（即 renderText 对应的输出）失效；
2. 失效会触发 renderText 重新执行，而重新执行又再次调用 invalidateLater(1000, session)，从而形成"等待 1 秒 → 重新执行 → 再等待 1 秒"的持续循环。

二、invalidateLater 的核心用法与语义

invalidateLater() 是本文主角，其函数签名与注释定义在 R/reactives.R：

invalidateLater <- function(millis, session = getDefaultReactiveDomain())

参数说明（依据源码注释 R/reactives.R 与 man/invalidateLater.Rd）：

参数	含义	注意事项
millis	等待多少毫秒后使当前响应式上下文失效，默认以整数毫秒计	官方注释明确为"近似时间"（Approximate milliseconds），实际触发时间受事件循环调度影响，不保证精确
session	会话对象，默认取当前响应式域（getDefaultReactiveDomain()）	用于在用户结束会话后取消已排定的失效任务；若为 NULL，则失效仍会发生，但不再与会话绑定

其核心语义为：如果它被放置在一个 observer 或 reactive 表达式内部，则该对象会在指定间隔后失效并重新执行。重新执行会重置失效标记，因此典型用法中对象会持续"执行 → 等待 → 失效 → 再执行"。要停止这种循环，必须加入条件逻辑，使后续执行不再调用 invalidateLater。

以官方文档中的另一个完整示例（见 R/reactives.R）为例，可以看到两种典型用法：

if (interactive()) {
  ui <- fluidPage(
    sliderInput("n", "Number of observations", 2, 1000, 500),
    plotOutput("plot")
  )

  server <- function(input, output, session) {
    observe({
      # 1000 毫秒后重新执行这个 observer
      invalidateLater(1000, session)
      # 每次失效时都执行这里。
      # isolate() 使得该 observer 不会因 input$n 变化而被失效重跑。
      print(paste("The value of input$n is", isolate(input$n)))
    })

    output$plot <- renderPlot({
      # 2000 毫秒后重新执行这个渲染表达式
      invalidateLater(2000)
      hist(rnorm(isolate(input$n)))
    })
  }

  shinyApp(ui, server)
}

这个示例传达了两个关键实战技巧：

• 定时与输入解耦：通过 isolate(input$n) 读取输入值，使定时循环只由 invalidateLater 驱动，而不会因为滑杆数值变化而被打断重跑；反之，input$n 的变化也依赖下一个定时周期才被读取。
• interval 不共享：observe 与 output$plot 各自拥有独立的间隔（1000ms 与 2000ms），互不影响，说明定时失效是"按响应式上下文独立排定"的。

三、底层原理：调度器如何实现定时失效

invalidateLater 之所以能生效，依赖 Shiny 的"调度器（scheduler）"抽象。其实现可分两层来看。

3.1 会话级调度优先

源码 R/reactives.R 中，invalidateLater 首先通过 defineScheduler(session) 选择调度器，然后排定一个回调：到达时间后调用 ctx$invalidate() 使当前响应式上下文失效。若绑定会话且会话未关闭，则通过 session$cycleStartAction() 在下一个刷新周期开始时执行失效，保证失效发生在安全的刷新边界。

defineScheduler 的定义位于 R/timer.R，其选择逻辑是：若会话存在且提供了 session$.scheduleTask，则优先使用会话级调度器；否则回退到全局调度器 scheduleTask。

3.2 全局 TimerCallbacks 调度队列

全局调度器 scheduleTask（R/timer.R）内部使用一个名为 TimerCallbacks 的 R6 类（R/timer.R）维护定时队列：

• schedule(millis, func)：记录"当前时间 + millis"作为触发时刻，并按触发时刻排序插入队列，返回一个 id；
• timeToNextEvent()：返回距下一个定时事件的时间，无事件时为 Inf；
• takeElapsed()：取出所有已到期的任务；
• executeElapsed()：逐个执行到期任务的回调函数。

Shiny 的主循环会在每个刷新周期调用这些方法，把到期回调放入响应式刷新流程中执行。值得说明的是，源码 R/timer.R 中留有注释 TODO: Horribly inefficient, use a heap instead，即当前实现是按时间排序的简单数据帧，属于可读性优先的实现，读者不必将其视作性能优化方案。

3.3 会话清理与防泄漏

当 invalidateLater 绑定会话时，源码 R/reactives.R 会做两件重要的事：

• 通过 session$onEnded() 注册清理回调：用户结束会话时取消尚未执行的定时任务；
• 通过 session$onDestroy() 注册清理回调：模块（module）被销毁时取消待执行定时器。

且二者交叉去注册（clear_on_ended_callback / clear_on_destroy_callback），注释明确说明这是为了防止 onEnded 回调不断累积造成内存泄漏。这正是文档强调"session 参数用于在用户结束会话后取消排定的失效"的原因——在 output$currentTime <- renderText({...}) 中显式传入 session，可以保证浏览器关闭后定时任务被及时回收。

四、reactiveTimer：一个更简洁的替代方案

官方文档在 man/invalidateLater.Rd 中注明：reactiveTimer() 是"一个稍微不够安全（slightly less safe）的替代方案"。它同样定义在 R/reactives.R，函数签名为：

reactiveTimer(intervalMs = 1000, session = getDefaultReactiveDomain())

与 invalidateLater 的"调用即排定本次失效"不同，reactiveTimer 返回一个可调用的函数：每次调用该函数会注册一个依赖者，并返回当前时间戳。典型用法如下：

timer <- reactiveTimer(1000, session)

observe({
  # 每次 observer 执行时都会依赖 timer
  timer()
  # 下面代码每秒执行一次
  print(Sys.time())
})

从源码看，reactiveTimer 内部维护一张依赖者表（dependents <- Map$new()），到期回调会逐个使依赖者失效；与 invalidateLater 相同，它也会优先使用会话级调度器，并在会话结束（session$onEnded）时取消定时器。其"不够安全"的一面在于：它默认持续周期性触发，不易像 invalidateLater 那样通过条件分支精确控制单次/按需触发，因此需要自己确保定时器在不需要时被销毁。

五、实战扩展：从定时刷新到数据轮询

5.1 通过条件逻辑停止定时循环

官方注释（R/reactives.R）特别强调：可以通过条件逻辑阻止 invalidateLater 被运行来终止循环。例如：

observe({
  # 仅在前 5 秒内持续刷新
  if (as.numeric(Sys.time()) - start_time < 5) {
    invalidateLater(1000, session)
  }
  print(Sys.time())
})

当条件不再满足时，observer 不再排定下一次失效，循环自然终止。

5.2 结合 isolate 控制触发来源

如第二节示例所示，在定时循环内读取输入、数据源时，应使用 isolate() 包裹：

observe({
  invalidateLater(1000, session)
  # 只读当前值，不建立依赖，避免输入变化打断定时节奏
  current <- isolate(input$n)
  cat("current:", current, "\n")
})

5.3 与 reactivePoll 的定位差异

Shiny 还提供了 reactivePoll（定义于 R/reactives.R），它通过"廉价 check 函数 + 昂贵取值函数"配对实现数据变化驱动的轮询：check 函数周期执行，仅当其返回值变化时才重新执行取值函数。与 invalidateLater/reactiveTimer 的"无条件周期性执行"相比，reactivePoll 更适合昂贵的后端轮询场景，而定时刷新类任务（实时时钟、状态指示器）则应使用前两者。选择依据是：你需要"每 N 秒必定执行一次"，还是"数据变了才重新加载"。

六、测试与实现验证

仓库测试为上述机制提供了直接佐证：

• tests/testthat/test-reactivity.r 在 debounce/throttle 测试中，用一个 observe 每 300ms 通过 invalidateLater(300) 递增 reactiveValues，验证定时失效驱动状态更新的链路；
• tests/testthat/test-reactivity.r 的 test_that("invalidateLater prefers session$scheduleTask", ...) 构造一个只提供 .scheduleTask 的伪会话，断言 invalidateLater(10, session) 确实委托给了会话级调度器，且 millis 参数被正确透传；
• 紧随其后的 test_that("reactiveTimer prefers session$scheduleTask", ...)（tests/testthat/test-reactivity.r）对 reactiveTimer(10, session) 做了同样的验证，确认两个 API 共享同一调度优先级规则。

这些测试同时印证了第三节中的结论：会话存在时优先走 session$.scheduleTask，否则回退全局调度器。

七、小结

• 定时刷新首选 invalidateLater：在 observer 或渲染表达式中调用，指定毫秒数后自动失效重跑，形成周期循环；显式传入 session 可确保会话结束时任务被清理，避免泄漏。
• reactiveTimer 是简化替代：返回可调用函数，适合持续周期触发；但控制粒度不如 invalidateLater 灵活。
• 停止循环靠条件分支：官方文档明确，只要后续执行不再调用 invalidateLater，循环即终止。
• 底层是统一的调度器抽象：会话级 session$.scheduleTask 优先，全局 TimerCallbacks 兜底，到期回调统一在刷新周期内执行，并有 onEnded/onDestroy 双向清理机制。

如果你需要继续深入研究，建议阅读 R/reactives.R（两个函数的完整实现）、R/timer.R（调度队列实现）以及 tests/testthat/test-reactivity.r（调度优先级测试），也可以参考官方文档 man/invalidateLater.Rd 与 man/reactiveTimer.Rd。