用 JQL 搜索 RowCraft 表格

每个 RowCraft 表格的每一列都可以用 JQL 搜索。这些搜索可以像其他 JQL 一样用在 Jira 的工作项搜索、已保存的过滤器、看板、仪表板和自动化中。

两个函数

issue in rowcraftField("<table field>", "<column> <operator> <value>", ...)
issue in rowcraftPanel("<panel table>", "<column> <operator> <value>", ...)
issue not in rowcraftField("<table field>", "<conditions>")

两个函数互不干扰，因此表格字段和面板表格可以同名。它们可以和任何其他 JQL 组合：

project = PUR AND issue in rowcraftField("Purchase items", "Qty > 1") AND issue in rowcraftPanel("Vendor quotes", "Accepted = false")

编写条件

每个条件的格式是 <列名> <运算符> <值>：

• 列名：表格中显示的列名，不区分大小写。含空格的列名不需要加引号：Unit price > 100。列名中含有运算符字符时，用方括号括起来：[A > B] ~ x。
• 值：数字直接写；文本、选项和日期可以加引号也可以不加；多个词不用引号（Item ~ dell laptop）；列表写在括号里：IN ("Hardware", "Software")。
• 值中可以使用 Jira 函数：currentUser()、membersOf("finance")、startOfMonth()、endOfWeek()、now()，以及 -7d 这样的相对日期。
• 复选框 写 true 或 false。

组合条件

多个参数之间是 AND 关系。一个参数内可以像 JQL 一样使用 AND、OR、NOT 和括号（NOT 优先于 AND，AND 优先于 OR）：

issue in rowcraftField("Purchase items", "Category = Hardware", "Unit price >= 1000")
issue in rowcraftField("Purchase items", "Category = Hardware AND Unit price >= 1000")
issue in rowcraftField("Purchase items", "Category = Hardware OR Unit price >= 5000")
issue in rowcraftField("Purchase items", "(Category = Hardware OR Category = Software) AND NOT Owner = currentUser()")

前两个搜索的效果相同。一次调用最多 10 个条件。

各列类型的运算符

每种列类型支持的运算符与对应的 Jira 字段相同。

• 文本 按词 搜索，与 Jira 的文本字段一样：~ lap 找不到 laptop，~ lap* 可以。带引号的短语会找到包含其中所有词的行，不检查词序。
• 选项精确匹配，区分大小写：= Office 找不到 Office supplies。
• 人员请使用 currentUser()、membersOf() 或账号 ID；不能按显示名称搜索（与 Jira 自带的用户字段相同）。

整列统计

比较整列的一个数值，而不是“任意一行”：

issue in rowcraftField("Purchase items", "SUM(Amount) > 10000")
issue in rowcraftField("Purchase items", "AVG(Unit price) >= 100")
issue in rowcraftField("Expense lines", "COUNT(Receipt attached) >= 3")
issue not in rowcraftField("Purchase items", "MAX(Unit price) >= 7000")

统计方式始终是你写的那一个，与该列合计行的设置无关。

Total 和 RowCount

有两个名称代表整张表格（英文，不区分大小写）：

• Total 是表格设置中 JQL 中 Total 对应的列 的合计，等同于 SUM(该列)。没有设置这一列时搜索会报错，请改用 SUM(列)。
• RowCount 是行数。

issue in rowcraftField("Purchase items", "Total > 10000")
issue in rowcraftField("Purchase items", "RowCount >= 3")

Amount > 10000 表示“有一行超过 10,000”；Total > 10000 表示“各行加起来超过 10,000”。如果表格中真的有一列叫 Total，以该列为准。

not in 和 NOT

not in 返回 in 的精确反面，包括没有表格或该列为空的工作项。条件中的 NOT 对单个条件起同样的作用。

列上的范围比较（>、>=、<、<=）不能取反：表格有很多行，“没有任何一行达到 7,000”并不等于“有一行低于 7,000”。请用 in 加相反的条件，或改用统计值，统计值在 not in 中也可以使用范围比较：

issue in rowcraftField("Purchase items", "Unit price < 7000")
issue not in rowcraftField("Purchase items", "MAX(Unit price) >= 7000")

第二个搜索会找到没有任何一行达到 7,000 的工作项，包括没有表格的工作项。

指定表格

如果有两个同名的表格，请使用 ID。

面板表格：rowcraftPanel()

rowcraftPanel() 的条件写法与 rowcraftField() 相同：

issue in rowcraftPanel("Onboarding tasks", "Done = false", "Owner = currentUser()")

• 保存行后几秒钟即可搜到。
• 一个工作项上最多可以搜索 10 个面板表格。
• 面板表格的人员列支持 currentUser() 和账号 ID，但不支持 membersOf()：Jira 不允许在面板表格所用的位置使用它。需要按用户组搜索时，请使用表格字段。

表格字段的搜索属性

表格字段还有可以直接在 JQL 中使用的搜索属性，例如在只支持字段路径的工具中：

注意字段名称和属性必须写在同一对引号内。各列的值保存在按编号命名的属性中（"Purchase items.Number2"、"Purchase items.Option1"……），编号取决于列的创建顺序；rowcraftField() 会替你把列名翻译成这些属性，因此建议使用函数。

搜索报错时

对于所有应用提供的 JQL 函数，出错时 Jira 只显示一条通用消息：JQL is invalid. Validation of field by customJqlFunctionExpansion failed。请检查：

• 表格名称是否正确，表格字段是否用了 rowcraftField()、面板表格是否用了 rowcraftPanel()；
• 列名、运算符（见上表）和值（含特殊字符的文本加引号，列表放在括号里）；
• 是否对列的范围比较取了反；
• 你是否有 RowCraft 应用的访问权限。

搜索助手会在输入时校验搜索，并在 JQL 输入框下方显示 Jira 的错误信息。

修改何时反映到搜索中

• 新增和修改的行在工作项保存后即可搜到（面板表格在保存后几秒钟）。
• 管理员保存列设计器、给表格字段改名或修改字段上下文后，RowCraft 会立即刷新 JQL 函数，已保存的过滤器继续有效。
• 修改公式或 Total 列后，已有工作项会在后台重新计算，通常几秒到几分钟完成。
• 搜索结果始终遵循 Jira 权限：你无权浏览的工作项不会出现。