搜索表达式

搜索表达式允许您在搜索查询语言中添加内容来表达交叉引用多个提供程序的复杂查询，例如，搜索场景中所有使用未编译着色器的对象。

搜索表达式可以链接在一起，用于转换或对搜索项执行集合操作。

如何使用搜索表达式

在 Search 窗口中输入搜索表达式以返回结果：

创建搜索表达式

搜索表达式以根表达式开始，根表达式可以包含内部表达式。

t:shader 之类的简单查询就是表达式。它返回与项目中着色器对应的所有搜索项。

使用搜索表达式语言可将多个查询合并成单个表达式，从而创建更灵活的搜索。

搜索表达式支持以下内容：

• 查询：t:shader
• 带有嵌套表达式的查询：t:prefab ref={t:texture}
• 函数：count{t:shader}
• 字面量：3 或 "this is a string literal"
• 属性选择符：@path or @mesh（任何以 @ 开头的标识符都被视为可从搜索项中提取值的选择符。选择符可以查找对象的属性，也可以用于动态计算结果）

所有搜索表达式都返回一个搜索项集合 (IEnumerable<SearchItem>)。一般来说，搜索表达式语言使用大括号 {} 来表示一组项。即使是字面量表达式（如 3），也会在内部作为集合 {3} 进行计算。

搜索表达式可以链接在一起进行更复杂的查询：

• t:prefab ref={t:texture}
  • 查询的 t:texture 部分可查找项目中的所有纹理
  • 查询的 t:prefab ref= 部分可针对 t:texture 集合中返回的每个纹理运行查询，以查看哪些预制件引用此纹理。

• t:prefab ref={t:texture size>4000}：查找项目中纹理大小大于 4000 字节的所有预制件。

这等同于：

• 运行 t:texture size>4000 以返回项目中所有 4K 纹理（例如，armor.png、treasure.png）的列表。

• 运行 t:prefab ref=<one of the 4K textures>（例如，t:prefab ref=armor.png，然后是 t:prefab ref=treasure.png）。

• 聚合所有结果，并将其返回为单个搜索项列表。

• t:[shader, material, texture]：查找类型为 shader、material 或 texture 的所有对象。如果使用普通查询，可以表示为：

• t:shader or t:material or t:texture

函数

Unity 有一个搜索表达式函数库，用于操作和变换搜索项集合。每个函数都可以接受多个参数并返回一组项。Unity 搜索表达式使用大括号来表示函数调用。

所有函数的完整列表都在此处。

示例：计数函数将每个集合的项作为参数传递并返回一个数字。

• count{t:shader} ：返回一个集合，包含项目中着色器的数量。示例：{34}。
• count{t:shader, t:texture} ：返回一个集合，包含项目中着色器和纹理的数量。示例：{34, 2048}。

函数可以链接在一起，类似于 s-expression 在 LISP 编程语言中的用法。

注意：只能有一个根表达式。

评估的函数链示例（按操作顺序）：

print{"path=@path", first{10, sort{t:texture, @size}}}：打印项目中 10 个最大纹理的路径

1. t:texture：查找项目中的所有纹理，然后选择大小属性。
2. sort{ t:texture, @size}：根据大小属性对所有这些纹理进行排序。
3. first{10：选择排序后的前 10 个纹理。
4. print{ "path=@path"：根据格式字符串在控制台中打印此列表，其中 Unity Search 提取每个结果项的路径属性 path=@path。

函数可以有多个签名（方法名以及每个形式参数的类型和种类（值、引用或输出），类似于 C#），并且可以支持可选参数（不需要传递给函数的参数）和可变参数（可接受任意数量参数的参数）。

搜索表达式中的字面量

字面量是指想要搜索的实际单词或数字或要检索的数量，而不是查询字符串。例如，t:texture 可搜索类型名称中包含纹理的资源（例如 Texture2D），但如果加上引号变为字面量，“t:texture” 则搜索名为 t:texture 的资源。

Expression	描述
Number	字面量数字 (1,2,3, and so on)
Set	方括号 ([ ])
String	单引号或双引号（'' 或 ""）

Number

数字字面量可用作函数（例如 first）的参数。

first{10, t:shader} -> {the first 10 shaders return by the 't:shader' query}

Set

使用方括号 [] 表示一组值。集合可以包含任何类型的表达式，但搜索表达式解析器会假定集合中的元素是字面量而不是搜索查询。

示例：

[t:shader, hello, 3] -> ["t:shader", "hello", 3]

如果使用大括号 ({})，解析器会将此视为三个查询：

{t:shader, hello, 3} -> {<run a query for t:shader>, <run a query for hello>, <run a query for 3>}

String

字符串字面量可用作某些函数（例如 format）的参数。可以使用单引号或双引号来指定字符串字面量：

“hello” 或 ‘hello’

format 函数可接受一个格式字符串作为参数：

format{t:texture, '@path (@size)'}

属性选择符和搜索项值

选择符是使用 @ 前缀表示的标识符。使用选择符可以访问项的属性以便进行计算、过滤或格式化。选择符可以映射到 UnityEngine.Object 的序列化属性或自定义函数以允许访问动态数据。

任何搜索项都支持的基本选择符为：

• id：根据其搜索提供程序的此项唯一 ID。
• value：项的内部值。默认情况下，它是此项的 ID，但函数可以覆盖项的值。
• label：Search 窗口中显示的项标签
• desc 或 description：商品描述（Search 窗口的第二行）

Unity 还为搜索项定义通用选择符，例如：

• @name：UnityEngine.Object.name
• @size：资源磁盘上的文件大小
• @path：资源路径
• @extension：资源文件扩展名
• @provider：生成此项的搜索提供程序

要访问搜索项的特定属性以执行操作，请使用选择符：

• count{t={distinct{select{a:assets, @type}}}}
  • a:assets, @type 查找项目中的所有资源，并为这些对象选择 type 属性。
  • distinct 返回所有已存在类型的列表。
  • t={list of types} 返回每种类型所对应每种资源的多个列表。
  • count 计算项目中每种类型的资源数量。
• avg{@size,t:shader}
  • t:shader, @size：查找所有着色器，然后选择大小属性。
  • avg：计算项目中所有着色器的平均大小。
• print{@value, count{t:texture, t:material}}
  • 这样会在 Console 窗口中打印从 count 函数结果中提取的计数值。

@# 选择符可查找序列化属性和材质属性：

• sort{t:texture, @#height}：按照高度序列化属性对所有纹理进行排序。

名称搜索表达式（别名）

您可以命名搜索表达式，使其更方便在 Search 窗口中显示。

例如，在 Search 窗口中输入表达式 sort{count{t:audio, t:texture}, @value,desc} 时，可能很难判断哪个计数对应于哪种类型：

使用别名：sort{count{t:audio as Audio, t:texture as Texture}, desc} 会生成更可读的结果：

要动态生成别名，请使用 alias 函数。例如：

alias{[1, 2, 3], 'Title value'}

将产生具有以下标签的项：

{Title 1, Title 2, Title 3}

展开运算符

展开运算符 ... 将一组项分组为多个集合，而不是仅仅一个集合。

...{expandable expression} -> {sub expr 1} {sub expr 2} {sub expr N}

示例：

一个小项目有 3 个预制件、4 个纹理和 5 个着色器。以下表达式为所有对象提供计数：

count{t:[prefab, texture, shader]} -> {12}

搜索表达式 t:[prefab, texture, shader] 的结果是一个包含 12 个项目的统一列表，包括预制件、纹理和着色器类型。这也可以表示为：t:prefab or t:texture or t:shader。

使用展开运算符可单独计算每种类型的资源的数量：

count{...t:[prefab, texture, shader]} -> count{t:prefab, t:texture, t:shader} -> {3, 4, 5}

groupBy 函数可与展开运算符一起使用，以返回按公共键分组的项的集合。

示例：

一个项目有三种类型的资源（预制件、纹理和着色器）。对于返回搜索项类型的选择符 @type，表达式将扩展为：

count{t:prefab or t:texture or t:shader}

可以使用 groupBy 函数按类型对项进行分组，然后计算每种类型对应的项的数量：

count{...groupBy{t:prefab or t:texture or t:shader, @type}}

搜索表达式示例

这些示例演示了如何在项目中使用搜索表达式进行复杂的请求。

• 统计场景中的预制件使用情况并按最高使用率排序：

  sort{select{p: t:prefab *.prefab, @path, count{t:scene ref:@path} as count}, @count, desc}

• 对所有资源类型进行排序和计数

  sort{count{...groupby{a:assets, @type}}, @value, desc}

• 查找具有最多顶点的网格（假设 @vertices 选择符在项目中可用）。

  first{sort{t:mesh, @vertices, desc}}

• 按顶点数量对所有网格进行排序

  sort{select{h: t:mesh, @path, @vertices}, @vertices, desc}

• 计算所有网格的顶点数

  sum{select{h:t:mesh, @vertices}}

• 查找引用网格的所有资源

  ref=select{p:t:mesh, @path}

• 列出预制件场景引用计数

  select{p: *.prefab, @path, count{p: a:sceneIndex ref="@path"} as count}

表达式评估

搜索表达式评估基于 C# 迭代器模式，并使用 yield 关键字。这样确保了评估过程以完全异步的操作方式呈现，并尽可能地避免阻塞。它允许每个搜索表达式在初始搜索项集合尚未完全计算之前开始其计算。

默认情况下，所有搜索表达式评估都在工作线程中进行，以避免阻塞编辑器。对于需要依赖非线程安全的 Unity API 的操作（例如某些选择符访问器），我们提供了一个实用程序 API，可在主线程上对这些操作进行排队，并保持搜索项的 yielding 模式。

自定义搜索表达式语言

搜索表达式语言已设计为可自定义。用于自定义框架所有部分的 API 将在未来版本中提供。