Trac 报告

Trac 报告模块提供了一个简单而强大的报告功能，用于展示 Trac 数据库中关于工单的信息。

TracReports 不使用自己的报告定义格式，而是依赖标准的 SQL SELECT 语句进行自定义报告定义。

注意： 报告模块正在以当前形式逐步淘汰，因为它严重限制了 Trac 团队对底层数据库模式进行调整的能力。我们认为 查询模块 是一个很好的替代品，它提供了更大的灵活性和更好的可用性。虽然有些报告目前还不能由查询模块处理，但我们打算进一步增强它，以便在某个时候报告模块可以被完全移除。这也意味着报告模块将不再有重大增强。

您只需在 trac.ini 中禁用报告模块，就可以完全用查询模块替换它。

[components]
trac.ticket.report.* = disabled

这将使查询模块成为“查看工单”导航项的默认处理程序。我们鼓励您尝试此配置，并反馈您可能缺少哪些报告功能。

报告包含以下基本部分

• ID — 唯一（顺序）标识符
• 标题 — 描述性标题
• 描述 — 报告的简要描述，采用 WikiFormatting 文本格式。
• 报告正文 — 报告查询的结果列表，按以下所述方法格式化。
• 页脚 — 指向此报告替代下载格式的链接。

更改排序顺序

简单报告（具体来说，未分组的报告）可以通过点击列标题进行排序。

如果列标题是超链接（红色），点击该列即可按其排序。再次点击同一标题将反转排序顺序。

浏览工单

点击报告结果中的一个条目，将带您到该工单。您可以通过点击下一工单或上一工单上下文导航链接来浏览结果，或者点击返回报告链接回到报告页面。

您可以安全地编辑任何工单，并在保存结果后继续使用下一/上一/返回报告链接浏览结果，但当您返回报告时，不会有任何关于更改的提示，这与查询结果不同（参见 TracQuery#NavigatingTickets）。

替代下载格式

除了 HTML 视图之外，报告还可以导出为多种替代格式。在报告页面的底部，您会找到可用数据格式的列表。点击所需链接即可下载替代格式。

逗号分隔 — CSV（逗号分隔值）

将报告导出为纯文本，每行独立一行，列由单个逗号（“,”）分隔。注意：输出内容已完全转义，因此回车符、换行符和逗号将在输出中保留。

制表符分隔

与上述类似，但使用制表符（\t）而不是逗号。

RSS - XML 内容聚合

所有报告都支持使用 XML/RSS 2.0 进行聚合。要订阅 RSS 提要，请点击页面底部的橙色“XML”图标。有关 Trac 中 RSS 支持的详细信息，请参阅 TracRss。

创建自定义报告

创建自定义报告需要对 SQL 有足够的了解。

请注意，您需要授予 权限 才能看到添加或编辑报告的按钮。

报告本质上是一个命名的 SQL 查询，由 Trac 执行并呈现。报告可以直接在 Web 界面中通过自定义 SQL 表达式查看和创建。

通常，报告由对“ticket”表的 SELECT 表达式组成，使用可用列并按您希望的方式排序。

工单列

ticket 表包含以下列

• id
• type
• time
• changetime
• component
• severity
• priority
• owner
• reporter
• cc
• version
• milestone
• status
• resolution
• summary
• description
• keywords

有关列字段的详细描述，请参阅 TracTickets。

示例：所有活跃工单，按优先级和时间排序

SELECT id AS ticket, status, severity, priority, owner, time AS created, summary
FROM ticket
WHERE status IN ('new', 'assigned', 'reopened')
ORDER BY priority, time

高级报告：动态变量

为了更灵活的报告，Trac 支持在报告 SQL 语句中使用动态变量。简而言之，动态变量是特殊字符串，在查询执行前会被自定义数据替换。动态变量通过偏好设置表单输入，并且值会自动完成（自 1.3.2 版起）。

在查询中使用变量

动态变量的语法很简单，任何以 $ 开头的大写单词都被视为变量。

示例

SELECT id AS ticket,summary FROM ticket WHERE priority=$PRIORITY

动态变量的值可以在报告偏好设置表单中指定。

要在报告的 URL 中为 $PRIORITY 赋值，请省略开头的 $

 https://trac.edgewall.org/reports/14?PRIORITY=high

要使用多个变量，请用 & 分隔它们

 https://trac.edgewall.org/reports/14?PRIORITY=high&SEVERITY=critical

可以在 SQL 注释中为变量分配默认值

-- PRIORITY = high

SELECT id AS ticket,summary FROM ticket WHERE priority=$PRIORITY

特殊/常量变量

有一个动态变量的值是自动设置的（URL 无需更改），以便实现实用报告。

• $USER — 登录用户的用户名。

示例：列出所有分配给我的工单

SELECT id AS ticket,summary FROM ticket WHERE owner=$USER

高级报告：自定义格式

Trac 还能够生成更高级的报告，包括自定义布局、结果分组和用户定义的 CSS 样式。要创建此类报告，我们将使用专门的 SQL 语句来控制 Trac 报告引擎的输出。

特殊列

为了格式化报告，TracReports 会在查询结果中查找“魔术”列名。这些“魔术”名称经过处理后，会影响最终报告的布局和样式。

自动格式化列

• ticket — 工单 ID 号。将成为指向该工单的超链接。
• id — 当未设置 realm 时，与上方的 ticket 相同
• realm — 与 id 结合使用，可以创建指向除工单以外的其他资源的链接（例如，wiki 域和指向页面名称的 id 将创建指向该 wiki 页面的链接）
  • 对于某些资源，可能需要指定其父资源（例如，对于changeset，其repos），这可以通过使用 parent_realm 和 parent_id 列来实现
• created, modified, date, time — 将单元格格式化为日期和/或时间。
• description — 工单描述字段，通过 wiki 引擎解析。

示例

SELECT id AS ticket, created, status, summary FROM ticket

这些列也可以定义但标记为隐藏，请参阅下文。

有关创建除工单之外的其他领域的报告示例，请参阅 ​CookBook/Configuration/Reports。

自定义格式列

名称以两个下划线开头和结尾的列（例如 __color__）被认为是格式化提示，影响行的外观。

• __group__ — 根据此列中的值对结果进行分组。每个组将有自己的标题和表格。
• __grouplink__ — 将每个组的标题设为指向指定 URL 的链接。URL 取自每个组的第一行。
• __color__ — 应该是一个介于 1 到 5 之间的数值，用于选择预定义的行颜色。通常用于按问题优先级对行进行着色。
  默认值：颜色 1 颜色 2 颜色 3 颜色 4 颜色 5
• __style__ — 用于当前行 <tr> 元素的自定义 CSS 样式表达式。
• __class__ — 用于当前行 <tr> 元素的零个或多个空格分隔的 CSS 类名。这些类将被添加到从 __color__ 和奇偶指示符派生的类名中。

示例： 列出活跃工单，按里程碑分组，组标题链接到里程碑页面，按优先级着色

SELECT p.value AS __color__,
     t.milestone AS __group__,
     '../milestone/' || t.milestone AS __grouplink__,
     (CASE owner WHEN 'daniel' THEN 'font-weight: bold; background: red;' ELSE '' END) AS __style__,
     t.id AS ticket, summary
FROM ticket t,enum p
WHERE t.status IN ('new', 'assigned', 'reopened')
  AND p.name = t.priority AND p.type = 'priority'
ORDER BY t.milestone, p.value, t.severity, t.time

请注意，表格联接用于将工单优先级与其在枚举表中的数值表示进行匹配。

更改报告行的布局

默认情况下，HTML 报告中的每行所有列都显示在单行上，可能按照上述描述进行格式化。但是，也可以创建多行报告条目。

• column_ — 在此之后换行。通过在列名后附加下划线（“_”），其余列将继续显示在第二行。

• _column_ — 整行。通过在列名的开头和结尾都添加下划线（“_”），数据将显示在单独的行上。

• _column — 隐藏数据。在列名前添加下划线（“_”）会指示 Trac 从 HTML 输出中隐藏内容。这对于仅在下载其他格式（如 CSV 或 RSS/XML）时才可见的信息很有用。这可以用于隐藏任何类型的列，甚至是识别资源所需的重要列，例如 id as _id 将隐藏 Id 列，但指向工单的链接将仍然存在。

示例： 列出活跃工单，按里程碑分组，按优先级着色，带有描述和多行布局

SELECT p.value AS __color__,
       t.milestone AS __group__,
       (CASE owner
          WHEN 'daniel' THEN 'font-weight: bold; background: red;'
          ELSE '' END) AS __style__,
       t.id AS ticket, summary AS summary_,             -- ## Break line here
       component,version, severity, milestone, status, owner,
       time AS created, changetime AS modified,         -- ## Dates are formatted
       description AS _description_,                    -- ## Uses a full row
       changetime AS _changetime, reporter AS _reporter -- ## Hidden from HTML output
FROM ticket t,enum p
WHERE t.status IN ('new', 'assigned', 'reopened')
  AND p.name = t.priority AND p.type = 'priority'
ORDER BY t.milestone, p.value, t.severity, t.time

自定义字段报告

如果您已向工单添加了自定义字段，您可以编写 SQL 查询将其包含在报告中。您需要对 ticket_custom 表进行联接。

如果您在 trac.ini 中声明额外字段之前，数据库中已有工单，那么 ticket_custom 表中将没有相关数据。为了解决这个问题，请使用 SQL 的 LEFT OUTER JOIN 子句。有关一些示例，请参阅 ​TracIniReportCustomFieldSample。

关于 SQL 重写的注意事项

除了相对简单的动态变量替换之外，SQL 查询还会被修改以支持报告的两个功能

1. 排序
2. 分页：限制每页显示的结果数量

为了支持第一个功能，排序列被插入到 ORDER BY 子句的第一个位置，如果指定了 __group__ 列，则插入到第二个位置（如果需要，会创建一个 ORDER BY 子句）。为了支持分页，会附加一个 LIMIT ... OFFSET ... 子句。查询可能过于复杂，导致自动重写无法正常工作，从而产生错误的查询。在这种情况下，您仍然可以通过手动插入以下标记来精确控制重写方式

• @SORT_COLUMN@，将插入所选排序列名称的位置，
• @LIMIT_OFFSET@，将添加分页支持子句的位置

请注意，如果您在 SQL 注释 -- 之后编写它们，如果您希望如此，您将有效地禁用重写！

让我们举个例子，考虑以下 SQL 查询

-- ## 4: Assigned, Active Tickets by Owner ## --

--
-- List assigned tickets, group by ticket owner, sorted by priority.
--

SELECT p.value AS __color__,
   owner AS __group__,
   id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created,
   changetime AS _changetime, description AS _description,
   reporter AS _reporter
FROM ticket t,enum p
WHERE status = 'assigned'
  AND p.name = t.priority AND p.type = 'priority'
ORDER BY __group__, p.value, severity, time

自动重写将如下所示（每页 4 行，第 2 页，按 component 排序）

SELECT p.value AS __color__,
   owner AS __group__,
   id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created,
   changetime AS _changetime, description AS _description,
   reporter AS _reporter
FROM ticket t,enum p
WHERE status = 'assigned'
  AND p.name = t.priority AND p.type = 'priority'
ORDER BY __group__ ASC, `component` ASC,  __group__, p.value, severity, time
LIMIT 4 OFFSET 4

带有重写标记的等效 SQL 查询将是

SELECT p.value AS __color__,
   owner AS __group__,
   id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created,
   changetime AS _changetime, description AS _description,
   reporter AS _reporter
FROM ticket t,enum p
WHERE status = 'assigned'
  AND p.name = t.priority AND p.type = 'priority'
ORDER BY __group__, @SORT_COLUMN@, p.value, severity, time
@LIMIT_OFFSET@

如果您希望始终首先按优先级排序，然后再按用户选择的排序列排序，只需使用以下 ORDER BY 子句

ORDER BY __group__, p.value, @SORT_COLUMN@, severity, time

更改报告编号

有时您可能需要更改报告的 ID，或许是为了更好地组织报告。目前这需要更改 Trac 数据库。report 表具有以下模式

• id integer PRIMARY KEY
• author text
• title text
• query text
• description text

更改 ID 会改变可用报告列表中的显示顺序和编号，以及报告的永久链接。这可以通过运行类似以下命令来完成

UPDATE report SET id = 5 WHERE id = 3;

请记住，必须维护数据完整性，即 ID 必须是唯一的，并且您不希望超出数据库的最大限制。

您可能还需要更新或删除存储在报告或查询中的报告编号。

---

另请参阅：TracTickets、TracQuery、​SQLite 理解的查询语言