建參報

造受參之報，自一模生多客變。

用

• 為異部、域、期生同報
• 自模造客專報
• 建濾於具子之儀
• 自定期報附異入

入

• 必：報模（Quarto 或 R Markdown）
• 必：參定（名、類、默）
• 可：批生之參值列
• 可：生報之出目

行

一：YAML 定參

Quarto（

report.qmd

）：

---
title: "Sales Report: `r params$region`"
params:
  region: "North America"
  year: 2025
  include_forecast: true
format:
  html:
    toc: true
---

R Markdown（

report.Rmd

）：

---
title: "Sales Report"
params:
  region: "North America"
  year: 2025
  include_forecast: true
output: html_document
---

得： YAML 頭含

params:

塊附名參，各有正類默值。

敗： 渲敗報「object 'params' not found」→確

params:

塊於 YAML 首縮對。Quarto

params

必於 YAML 頂，非

format:

下嵌。

二：碼中用參

```{r}
#| label: filter-data

data <- full_dataset |>
  filter(region == params$region, year == params$year)

nrow(data)
```

## Overview for `r params$region`

This report covers the `r params$region` region for `r params$year`.

```{r}
#| label: forecast
#| eval: !expr params$include_forecast

# This chunk only runs when include_forecast is TRUE
forecast_model <- forecast::auto.arima(data$sales)
forecast::autoplot(forecast_model)
```

得： 碼塊以

params$name

引參，條塊以 Quarto

#| eval: !expr params$flag

。行內 R 表如

`r params$region`

渲動文。

敗：

params$name

返 NULL→驗參名於 YAML 與碼全合（區大小）。察默值類正。

三：以客參渲

單渲：

# Quarto
quarto::quarto_render(
  "report.qmd",
  execute_params = list(region = "Europe", year = 2025)
)

# R Markdown
rmarkdown::render(
  "report.Rmd",
  params = list(region = "Europe", year = 2025),
  output_file = "report-europe-2025.html"
)

得： 單報以客參值成渲，覆 YAML 默。出檔於所述徑造。

敗： Quarto 渲敗→察

quarto

CLI 已裝且於 PATH。R Markdown 敗→驗

rmarkdown

已裝。確參名於

execute_params

（Quarto）或

params

（R Markdown）合 YAML 定。

四：批渲多報

regions <- c("North America", "Europe", "Asia Pacific", "Latin America")
years <- c(2024, 2025)

# Generate all combinations
combinations <- expand.grid(region = regions, year = years, stringsAsFactors = FALSE)

# Render each
purrr::pwalk(combinations, function(region, year) {
  output_name <- sprintf("report-%s-%d.html",
    tolower(gsub(" ", "-", region)), year)

  quarto::quarto_render(
    "report.qmd",
    execute_params = list(region = region, year = year),
    output_file = output_name
  )
})

得： 每域年組一 HTML。

敗： 察參名於 YAML 與碼全合。確諸參值有效。

五：加參驗

#| label: validate-params

stopifnot(
  "Region must be a valid region" = params$region %in% valid_regions,
  "Year must be numeric" = is.numeric(params$year),
  "Year must be reasonable" = params$year >= 2020 && params$year <= 2030
)

得： 驗碼塊於每渲始行，若參出範或類誤則以清誤止。

敗：

stopifnot()

生無益訊→換顯

if (!cond) stop("message")

呼以清診。

六：組出

# Create output directory
output_dir <- file.path("reports", format(Sys.Date(), "%Y-%m"))
dir.create(output_dir, recursive = TRUE, showWarnings = FALSE)

# Render with output path
quarto::quarto_render(
  "report.qmd",
  execute_params = list(region = region),
  output_file = file.path(output_dir, paste0("report-", region, ".html"))
)

得： 出檔書於日戳子目附述名（如

reports/2025-06/report-europe.html

）。

敗：

dir.create()

敗→察父目存且可書。Windows 上驗徑長不過 260 字。

驗

• 報以默參渲
• 報以每組客參渲
• 參處前驗
• 出檔命述
• 條段依參正渲
• 批生於諸組完

忌

• 參名不合：YAML 名必全合碼

  params$name

  引
• 類強轉：YAML 或解

  year: 2025

  為整，而碼候字元。必顯。
• 條評：Quarto 用

  #| eval: !expr params$flag

  ，非

  eval = params$flag

• 檔覆：無唯出名→每渲覆前
• 批記：久批或積記。宜用

  callr::r()

  為隔。

參

• create-quarto-report

  — 基 Quarto 文設

• generate-statistical-tables

  — 適參之表

• format-apa-report

  — 參化學術報