1. 为什么要在Shader编辑器里折腾ToolTip如果你写过自定义的ShaderGUI或者给美术同学做过Shader参数面板大概率遇到过这个场景美术跑过来问“这个滑块到底是调什么的”你只能翻出代码一行行解释。Shader的Inspector面板天生就比普通MonoBehaviour面板复杂因为大量参数是浮点、向量、纹理光看名字根本猜不出用途。Unity原生的ShaderInspector对ToolTip的支持其实很有限[Tooltip]特性在Shader属性块里根本不生效这是很多人第一次踩的坑。我在几个渲染管线项目里都遇到过这个问题尤其是做角色材质、后处理堆栈这类参数密集的Shader时一个面板上几十个属性没有提示信息简直是灾难。后来我决定在自定义ShaderEditor里把ToolTip这套机制补上让鼠标悬停就能看到参数说明。这件事听起来简单但实际做下来涉及GUIContent的构造、EditorGUILayout的布局控制、以及如何从Shader属性块里解析出注释信息这几个关键点。这篇内容就是把这套方案的完整实现思路和踩过的坑整理出来适合已经写过基础ShaderGUI、想进一步提升编辑器体验的开发者。如果你还没接触过ShaderGUI建议先补一下ShaderGUI基类和MaterialEditor的基本用法不然下面的内容会有点吃力。核心思路其实一句话就能概括把Shader属性块里的注释当作ToolTip内容在绘制每个属性时构造带tooltip的GUIContent。但魔鬼在细节里怎么解析注释、怎么保证不破坏原有布局、怎么处理不同类型的属性这些才是真正花时间的地方。2. Shader属性块里的注释到底能不能被读到2.1 Unity对Shader属性的解析机制要理解为什么[Tooltip]在Shader里不生效得先搞清楚Unity是怎么解析Shader文件的。Shader文件本质上是一段类ShaderLab的文本Unity在导入时会用内部的解析器把Properties块里的每个属性提取出来生成一个Shader对象属性信息存在Shader.GetPropertyCount()和Shader.GetPropertyName()这些API背后。关键点在于这个解析器只认属性声明本身不认C#那种特性语法。你在属性前面写[Tooltip(xxx)]Unity的Shader编译器会直接忽略甚至可能报语法警告。那注释呢//开头的注释在ShaderLab里是合法的Unity的解析器会跳过它们但不会把它们和属性关联起来。也就是说Unity本身没有提供任何从Shader文件读取属性注释的官方API。这是整个方案最大的障碍也是为什么很多人做到一半就放弃了。我试过几种绕过的思路。第一种是用ShaderUtil.GetShaderPropertyDescription之类的内部API但这些API要么不公开要么返回的信息里根本没有注释。第二种是反射读取Shader对象的私有字段实测下来不同Unity版本字段名不一样维护成本太高。第三种就是最笨但最稳的办法自己读Shader源文件手动解析Properties块。听起来土但可控性最强而且Shader文件路径可以通过AssetDatabase.GetAssetPath(shader)拿到读取完全没问题。2.2 手动解析Properties块的完整逻辑解析的核心是逐行扫描Shader文本定位Properties块的起止位置然后对每一行做模式匹配。一个典型的属性行长这样// 基础颜色控制整体色调 _BaseColor (Base Color, Color) (1,1,1,1)我的解析策略是维护一个“待定注释”变量。遇到//开头的行就把内容存起来遇到属性声明行就把存起来的注释和这个属性名绑定遇到空行或者其他内容就清空待定注释。这样能处理注释在属性上方的情况这也是最常见的写法。private Dictionarystring, string ParseTooltips(string shaderPath) { var result new Dictionarystring, string(); var lines File.ReadAllLines(shaderPath); string pendingComment null; bool inProperties false; int braceDepth 0; foreach (var rawLine in lines) { var line rawLine.Trim(); if (!inProperties) { if (line.StartsWith(Properties)) { inProperties true; braceDepth 0; } continue; } if (line.StartsWith({)) { braceDepth; continue; } if (line.StartsWith(})) { braceDepth--; if (braceDepth 0) break; continue; } if (line.StartsWith(//)) { pendingComment line.Substring(2).Trim(); continue; } // 匹配属性声明_Name (Display, Type) Default var match Regex.Match(line, ^(\w)\s*\(); if (match.Success pendingComment ! null) { result[match.Groups[1].Value] pendingComment; pendingComment null; } else if (string.IsNullOrEmpty(line)) { pendingComment null; } } return result; }这段代码有几个细节值得说。braceDepth的处理是为了应对Properties块里可能出现的嵌套结构虽然标准Shader里Properties块一般不会嵌套但有些自定义写法会加额外的花括号保险起见还是处理一下。正则^(\w)\s*\(只匹配属性名后面紧跟左括号的情况能过滤掉大部分非属性行。pendingComment在遇到空行时清空是为了避免注释和属性之间隔了太多行导致误关联。注意这个解析器假设注释紧贴在属性上方。如果你的项目里习惯把注释写在属性行末尾需要额外处理行内//的情况逻辑会复杂一些建议统一团队规范注释一律写在属性上方。2.3 缓存策略别每次重绘都读文件OnGUI在编辑器里调用频率非常高鼠标移动、窗口重绘都会触发。如果每次OnGUI都去读Shader文件、跑正则性能会很差尤其是Shader文件大的时候。我的做法是在ShaderGUI.OnShaderChanged或者第一次OnGUI时解析一次把结果缓存在字典里后续直接用。private Dictionarystring, string _tooltipCache; private Shader _cachedShader; public override void OnGUI(MaterialEditor materialEditor, MaterialProperty[] properties) { var shader materialEditor.target is Material mat ? mat.shader : null; if (shader ! _cachedShader) { _cachedShader shader; var path AssetDatabase.GetAssetPath(shader); _tooltipCache ParseTooltips(path); } // 后续绘制逻辑 }这里用_cachedShader做变更检测只有Shader换了才重新解析。注意AssetDatabase.GetAssetPath对内置Shader会返回空字符串这种情况直接跳过解析用空字典兜底不然会抛异常。3. 把注释变成ToolTip的绘制改造3.1 GUIContent的构造与EditorGUILayout的配合Unity的IMGUI体系里ToolTip是通过GUIContent的tooltip字段实现的。当你把一个带tooltip的GUIContent传给EditorGUILayout.PropertyField或者GUILayout.Label鼠标悬停时Unity会自动弹出提示框。所以核心工作就是把原来直接传property.displayName的地方改成传一个构造好的GUIContent。private GUIContent GetContent(MaterialProperty prop) { string tooltip null; _tooltipCache?.TryGetValue(prop.name, out tooltip); return new GUIContent(prop.displayName, tooltip); }看起来很简单对吧但实际用的时候会发现一个问题EditorGUILayout.PropertyField有个重载是接受GUIContent的但如果你用的是MaterialEditor.DefaultShaderProperty或者ShaderProperty它们内部对label的处理逻辑不一样有些版本会忽略你传进去的tooltip。我实测下来最稳的方式是自己用EditorGUILayout.PropertyField(prop, content)而不是依赖MaterialEditor的封装方法。public override void OnGUI(MaterialEditor materialEditor, MaterialProperty[] properties) { // ...缓存逻辑 foreach (var prop in properties) { var content GetContent(prop); EditorGUILayout.PropertyField(prop, content); } }这样每个属性都会带上tooltip。但代价是你失去了MaterialEditor默认的一些布局优化比如纹理属性会自动带缩略图、颜色属性会带拾色器。这些需要自己补回来后面会讲。3.2 不同属性类型的差异化处理Shader属性有好几种类型Float、Range、Color、Vector、Texture、Int。EditorGUILayout.PropertyField对大部分类型都能自动识别并绘制合适的控件但Texture类型有个坑默认绘制出来的纹理槽位没有缩略图预览美术同学会很不习惯。我的做法是对Texture类型单独处理用MaterialEditor.TextureProperty但它不接受GUIContent参数所以tooltip得换个方式加。if (prop.type MaterialProperty.PropType.Texture) { // TextureProperty不支持GUIContent用Label补tooltip var label new GUIContent(prop.displayName, GetTooltip(prop.name)); EditorGUILayout.LabelField(label); materialEditor.TextureProperty(prop, string.Empty); } else { EditorGUILayout.PropertyField(prop, GetContent(prop)); }这样纹理属性上方会有一个带tooltip的标签下面跟着纹理槽位。虽然不如原生PropertyField紧凑但功能上没问题。Range类型要注意EditorGUILayout.PropertyField会自动绘制成滑块tooltip也能正常显示不需要特殊处理。Color类型会弹出拾色器tooltip同样有效。属性类型推荐绘制方式ToolTip支持情况FloatEditorGUILayout.PropertyField原生支持RangeEditorGUILayout.PropertyField原生支持ColorEditorGUILayout.PropertyField原生支持VectorEditorGUILayout.PropertyField原生支持TextureLabel TextureProperty需手动补LabelIntEditorGUILayout.PropertyField原生支持3.3 分组与折叠对ToolTip的影响实际项目里Shader属性通常会分组显示用MaterialEditor的ShaderProperty配合BeginFoldoutHeaderGroup做折叠。折叠组本身也可以有tooltip这个用EditorGUILayout.BeginFoldoutHeaderGroup的GUIContent参数就能实现。但要注意折叠组内的属性在折叠状态下不会触发OnGUI绘制所以tooltip缓存必须在折叠之前就准备好不能依赖绘制时懒加载。var groupContent new GUIContent(基础设置, 控制材质的基础颜色和透明度); bool expanded EditorGUILayout.BeginFoldoutHeaderGroup(_foldoutState, groupContent); if (expanded) { foreach (var prop in groupProperties) { EditorGUILayout.PropertyField(prop, GetContent(prop)); } } EditorGUILayout.EndFoldoutHeaderGroup();这里_foldoutState需要自己维护通常用MaterialEditor的serializedObject或者一个静态字典按材质实例存储。我一般用SessionState或者EditorPrefs存折叠状态这样关闭Unity再打开还能记住上次的展开情况体验会好很多。4. 实测中遇到的几个坑和绕行方案4.1 注释解析的边界情况第一个坑是多行注释。有些Shader里属性说明比较长会写成多行// 这个参数控制高光强度 // 范围0到1越大越亮 _Specular (Specular, Range(0,1)) 0.5我的解析器只取最后一行注释前面的会丢。改进方案是用一个Liststring收集连续的注释行遇到属性时用换行符拼接。但ToolTip太长会显示不全Unity的tooltip框有最大宽度限制所以实际用的时候建议注释控制在一行内太长就精简。第二个坑是属性名大小写。Shader属性名是大小写敏感的但有些项目里注释和属性名之间可能有空格差异正则匹配时要注意\w已经涵盖了大小写字母和下划线一般没问题。但如果属性名里有数字开头虽然不合法但有人这么写\w也能匹配不过Unity本身会报错所以不用太担心。第三个坑是内置Shader。AssetDatabase.GetAssetPath对Unity内置的Shader比如Standard、Unlit返回空字符串这时候解析会失败。我的处理是加个判断路径为空就直接返回空字典绘制时tooltip为nullGUIContent会自动忽略不会报错。4.2 ToolTip不显示的几种可能原因实测下来tooltip不显示通常有这几个原因。第一是GUIContent构造时tooltip传了null或空字符串这种情况Unity不会弹提示检查一下缓存字典里有没有对应key。第二是PropertyField的重载选错了如果你用的是EditorGUILayout.PropertyField(prop)不带GUIContent参数那tooltip永远不会显示。第三是编辑器皮肤问题某些自定义皮肤或者旧版本Unity对tooltip的渲染有bug换回默认皮肤试试。还有一个比较隐蔽的原因属性被禁用disabled。如果你用EditorGUI.BeginDisabledGroup包住了属性tooltip在某些Unity版本里会失效。这个我没找到完美的解决办法只能尽量避免在禁用组里放需要tooltip的属性。提示调试tooltip是否生效可以在GetContent里加一行Debug.Log(content.tooltip)确认内容确实被构造出来了。如果日志有输出但界面不显示那就是绘制方式的问题。4.3 性能与缓存失效的处理前面提到用_cachedShader做缓存但有个场景会出问题Shader文件被修改后缓存不会自动刷新。比如你在编辑器里改了Shader的注释Inspector面板不会立即更新得手动刷新或者重新选中材质。解决办法是监听AssetDatabase的刷新事件或者用EditorApplication.update定期检查文件修改时间。private DateTime _lastWriteTime; private void CheckShaderModified() { var path AssetDatabase.GetAssetPath(_cachedShader); if (string.IsNullOrEmpty(path)) return; var writeTime File.GetLastWriteTime(path); if (writeTime ! _lastWriteTime) { _lastWriteTime writeTime; _tooltipCache ParseTooltips(path); } }在OnGUI开头调用CheckShaderModified这样Shader一保存tooltip就会更新。文件IO在编辑器里开销不大而且GetLastWriteTime比读整个文件轻量得多实测对帧率没有明显影响。5. 让这套机制更好用的几个扩展思路5.1 从注释里提取更丰富的元信息既然已经能解析注释了不妨把注释格式规范化让它携带更多信息。比如用符号标记特殊字段// group 基础设置 // tip 控制整体色调影响漫反射颜色 _BaseColor (Base Color, Color) (1,1,1,1)解析时识别group就把属性归到对应分组识别tip就作为tooltip内容。这样一套注释既能驱动分组又能驱动tooltipShader文件本身就是配置源不用额外维护C#代码里的映射表。我在一个后处理Shader项目里用了这套方案新增属性时只改Shader文件C#端完全不用动维护成本降了很多。5.2 支持富文本和快捷键提示Unity的tooltip支持简单的富文本标签比如b加粗、color改色。你可以在注释里直接写这些标签GUIContent会原样传给tooltip渲染器。实测b和i是生效的color在部分Unity版本里有效可以试试。另外如果某个参数有快捷键操作比如按住Shift拖动可以微调也可以在tooltip里写清楚美术同学会觉得很贴心。5.3 和MaterialPropertyDrawer的配合如果你已经用了MaterialPropertyDrawer来做自定义绘制tooltip的注入点会不一样。Drawer的OnGUI方法里拿不到外部的GUIContent需要自己在Drawer内部构造。我的建议是把tooltip解析逻辑抽成一个静态工具类Drawer和ShaderGUI都调这个工具类避免重复代码。public static class ShaderTooltipUtility { public static string GetTooltip(Shader shader, string propertyName) { // 缓存 解析逻辑 } }这样无论你在哪里绘制属性都能拿到tooltip内容。Drawer里用EditorGUILayout.PropertyField时传入构造好的GUIContent即可。5.4 多语言支持的可行性如果项目有出海需求tooltip可能需要多语言。我的做法是在注释里用|分隔不同语言比如// 基础颜色|Base Color解析时按当前编辑器语言选对应文本。Unity有Application.systemLanguage可以判断但编辑器语言和系统语言不一定一致更稳的方式是读EditorPrefs里的语言设置。这套方案我还没在正式项目里大规模用因为维护多语言注释本身也是成本小项目没必要。6. 一些实操中的个人体会这套ToolTip机制我在三个项目里落地过最大的感受是Shader注释的规范比代码实现更重要。代码写一次就固定了但注释是团队每个人都要写的如果规范不统一解析出来的tooltip会乱七八糟。我的建议是在项目初期就定好注释格式比如“注释必须紧贴属性上方单行不超过30字用中文描述用途”然后在Code Review里检查。另一个体会是不要过度依赖tooltip。tooltip是辅助属性名本身应该尽量自解释。如果某个参数必须靠tooltip才能看懂那可能是命名有问题。我见过一个Shader属性叫_Param1tooltip写了一大段解释这种就是典型的命名失败。好的做法是属性名用_RimPower、_SpecularIntensity这种一看就懂的词tooltip只补充取值范围和特殊行为。最后分享一个小技巧在GetContent里可以给tooltip加个前缀比如[范围0-1]这样美术一眼就能看到取值范围不用把范围写进注释里。这个前缀可以根据属性类型自动生成Range类型自动加范围Color类型加“点击选择颜色”Texture类型加“拖入纹理资源”。这种自动化的小细节用起来会觉得很顺手。这套方案的核心代码量其实不大解析加绘制加起来两三百行但带来的编辑器体验提升很明显。如果你也在做ShaderGUI强烈建议把tooltip这套加上美术同学的反馈会告诉你值不值得。 
长河君 · 2026/10/16 0:21:02 · 阅读 1.2k Unity Shader编辑器ToolTip实现：从注释解析到GUIContent绘制
1. 为什么要在Shader编辑器里折腾ToolTip如果你写过自定义的ShaderGUI或者给美术同学做过Shader参数面板大概率遇到过这个场景美术跑过来问“这个滑块到底是调什么的”你只能翻出代码一行行解释。Shader的Inspector面板天生就比普通MonoBehaviour面板复杂因为大量参数是浮点、向量、纹理光看名字根本猜不出用途。Unity原生的ShaderInspector对ToolTip的支持其实很有限[Tooltip]特性在Shader属性块里根本不生效这是很多人第一次踩的坑。我在几个渲染管线项目里都遇到过这个问题尤其是做角色材质、后处理堆栈这类参数密集的Shader时一个面板上几十个属性没有提示信息简直是灾难。后来我决定在自定义ShaderEditor里把ToolTip这套机制补上让鼠标悬停就能看到参数说明。这件事听起来简单但实际做下来涉及GUIContent的构造、EditorGUILayout的布局控制、以及如何从Shader属性块里解析出注释信息这几个关键点。这篇内容就是把这套方案的完整实现思路和踩过的坑整理出来适合已经写过基础ShaderGUI、想进一步提升编辑器体验的开发者。如果你还没接触过ShaderGUI建议先补一下ShaderGUI基类和MaterialEditor的基本用法不然下面的内容会有点吃力。核心思路其实一句话就能概括把Shader属性块里的注释当作ToolTip内容在绘制每个属性时构造带tooltip的GUIContent。但魔鬼在细节里怎么解析注释、怎么保证不破坏原有布局、怎么处理不同类型的属性这些才是真正花时间的地方。2. Shader属性块里的注释到底能不能被读到2.1 Unity对Shader属性的解析机制要理解为什么[Tooltip]在Shader里不生效得先搞清楚Unity是怎么解析Shader文件的。Shader文件本质上是一段类ShaderLab的文本Unity在导入时会用内部的解析器把Properties块里的每个属性提取出来生成一个Shader对象属性信息存在Shader.GetPropertyCount()和Shader.GetPropertyName()这些API背后。关键点在于这个解析器只认属性声明本身不认C#那种特性语法。你在属性前面写[Tooltip(xxx)]Unity的Shader编译器会直接忽略甚至可能报语法警告。那注释呢//开头的注释在ShaderLab里是合法的Unity的解析器会跳过它们但不会把它们和属性关联起来。也就是说Unity本身没有提供任何从Shader文件读取属性注释的官方API。这是整个方案最大的障碍也是为什么很多人做到一半就放弃了。我试过几种绕过的思路。第一种是用ShaderUtil.GetShaderPropertyDescription之类的内部API但这些API要么不公开要么返回的信息里根本没有注释。第二种是反射读取Shader对象的私有字段实测下来不同Unity版本字段名不一样维护成本太高。第三种就是最笨但最稳的办法自己读Shader源文件手动解析Properties块。听起来土但可控性最强而且Shader文件路径可以通过AssetDatabase.GetAssetPath(shader)拿到读取完全没问题。2.2 手动解析Properties块的完整逻辑解析的核心是逐行扫描Shader文本定位Properties块的起止位置然后对每一行做模式匹配。一个典型的属性行长这样// 基础颜色控制整体色调 _BaseColor (Base Color, Color) (1,1,1,1)我的解析策略是维护一个“待定注释”变量。遇到//开头的行就把内容存起来遇到属性声明行就把存起来的注释和这个属性名绑定遇到空行或者其他内容就清空待定注释。这样能处理注释在属性上方的情况这也是最常见的写法。private Dictionarystring, string ParseTooltips(string shaderPath) { var result new Dictionarystring, string(); var lines File.ReadAllLines(shaderPath); string pendingComment null; bool inProperties false; int braceDepth 0; foreach (var rawLine in lines) { var line rawLine.Trim(); if (!inProperties) { if (line.StartsWith(Properties)) { inProperties true; braceDepth 0; } continue; } if (line.StartsWith({)) { braceDepth; continue; } if (line.StartsWith(})) { braceDepth--; if (braceDepth 0) break; continue; } if (line.StartsWith(//)) { pendingComment line.Substring(2).Trim(); continue; } // 匹配属性声明_Name (Display, Type) Default var match Regex.Match(line, ^(\w)\s*\(); if (match.Success pendingComment ! null) { result[match.Groups[1].Value] pendingComment; pendingComment null; } else if (string.IsNullOrEmpty(line)) { pendingComment null; } } return result; }这段代码有几个细节值得说。braceDepth的处理是为了应对Properties块里可能出现的嵌套结构虽然标准Shader里Properties块一般不会嵌套但有些自定义写法会加额外的花括号保险起见还是处理一下。正则^(\w)\s*\(只匹配属性名后面紧跟左括号的情况能过滤掉大部分非属性行。pendingComment在遇到空行时清空是为了避免注释和属性之间隔了太多行导致误关联。注意这个解析器假设注释紧贴在属性上方。如果你的项目里习惯把注释写在属性行末尾需要额外处理行内//的情况逻辑会复杂一些建议统一团队规范注释一律写在属性上方。2.3 缓存策略别每次重绘都读文件OnGUI在编辑器里调用频率非常高鼠标移动、窗口重绘都会触发。如果每次OnGUI都去读Shader文件、跑正则性能会很差尤其是Shader文件大的时候。我的做法是在ShaderGUI.OnShaderChanged或者第一次OnGUI时解析一次把结果缓存在字典里后续直接用。private Dictionarystring, string _tooltipCache; private Shader _cachedShader; public override void OnGUI(MaterialEditor materialEditor, MaterialProperty[] properties) { var shader materialEditor.target is Material mat ? mat.shader : null; if (shader ! _cachedShader) { _cachedShader shader; var path AssetDatabase.GetAssetPath(shader); _tooltipCache ParseTooltips(path); } // 后续绘制逻辑 }这里用_cachedShader做变更检测只有Shader换了才重新解析。注意AssetDatabase.GetAssetPath对内置Shader会返回空字符串这种情况直接跳过解析用空字典兜底不然会抛异常。3. 把注释变成ToolTip的绘制改造3.1 GUIContent的构造与EditorGUILayout的配合Unity的IMGUI体系里ToolTip是通过GUIContent的tooltip字段实现的。当你把一个带tooltip的GUIContent传给EditorGUILayout.PropertyField或者GUILayout.Label鼠标悬停时Unity会自动弹出提示框。所以核心工作就是把原来直接传property.displayName的地方改成传一个构造好的GUIContent。private GUIContent GetContent(MaterialProperty prop) { string tooltip null; _tooltipCache?.TryGetValue(prop.name, out tooltip); return new GUIContent(prop.displayName, tooltip); }看起来很简单对吧但实际用的时候会发现一个问题EditorGUILayout.PropertyField有个重载是接受GUIContent的但如果你用的是MaterialEditor.DefaultShaderProperty或者ShaderProperty它们内部对label的处理逻辑不一样有些版本会忽略你传进去的tooltip。我实测下来最稳的方式是自己用EditorGUILayout.PropertyField(prop, content)而不是依赖MaterialEditor的封装方法。public override void OnGUI(MaterialEditor materialEditor, MaterialProperty[] properties) { // ...缓存逻辑 foreach (var prop in properties) { var content GetContent(prop); EditorGUILayout.PropertyField(prop, content); } }这样每个属性都会带上tooltip。但代价是你失去了MaterialEditor默认的一些布局优化比如纹理属性会自动带缩略图、颜色属性会带拾色器。这些需要自己补回来后面会讲。3.2 不同属性类型的差异化处理Shader属性有好几种类型Float、Range、Color、Vector、Texture、Int。EditorGUILayout.PropertyField对大部分类型都能自动识别并绘制合适的控件但Texture类型有个坑默认绘制出来的纹理槽位没有缩略图预览美术同学会很不习惯。我的做法是对Texture类型单独处理用MaterialEditor.TextureProperty但它不接受GUIContent参数所以tooltip得换个方式加。if (prop.type MaterialProperty.PropType.Texture) { // TextureProperty不支持GUIContent用Label补tooltip var label new GUIContent(prop.displayName, GetTooltip(prop.name)); EditorGUILayout.LabelField(label); materialEditor.TextureProperty(prop, string.Empty); } else { EditorGUILayout.PropertyField(prop, GetContent(prop)); }这样纹理属性上方会有一个带tooltip的标签下面跟着纹理槽位。虽然不如原生PropertyField紧凑但功能上没问题。Range类型要注意EditorGUILayout.PropertyField会自动绘制成滑块tooltip也能正常显示不需要特殊处理。Color类型会弹出拾色器tooltip同样有效。属性类型推荐绘制方式ToolTip支持情况FloatEditorGUILayout.PropertyField原生支持RangeEditorGUILayout.PropertyField原生支持ColorEditorGUILayout.PropertyField原生支持VectorEditorGUILayout.PropertyField原生支持TextureLabel TextureProperty需手动补LabelIntEditorGUILayout.PropertyField原生支持3.3 分组与折叠对ToolTip的影响实际项目里Shader属性通常会分组显示用MaterialEditor的ShaderProperty配合BeginFoldoutHeaderGroup做折叠。折叠组本身也可以有tooltip这个用EditorGUILayout.BeginFoldoutHeaderGroup的GUIContent参数就能实现。但要注意折叠组内的属性在折叠状态下不会触发OnGUI绘制所以tooltip缓存必须在折叠之前就准备好不能依赖绘制时懒加载。var groupContent new GUIContent(基础设置, 控制材质的基础颜色和透明度); bool expanded EditorGUILayout.BeginFoldoutHeaderGroup(_foldoutState, groupContent); if (expanded) { foreach (var prop in groupProperties) { EditorGUILayout.PropertyField(prop, GetContent(prop)); } } EditorGUILayout.EndFoldoutHeaderGroup();这里_foldoutState需要自己维护通常用MaterialEditor的serializedObject或者一个静态字典按材质实例存储。我一般用SessionState或者EditorPrefs存折叠状态这样关闭Unity再打开还能记住上次的展开情况体验会好很多。4. 实测中遇到的几个坑和绕行方案4.1 注释解析的边界情况第一个坑是多行注释。有些Shader里属性说明比较长会写成多行// 这个参数控制高光强度 // 范围0到1越大越亮 _Specular (Specular, Range(0,1)) 0.5我的解析器只取最后一行注释前面的会丢。改进方案是用一个Liststring收集连续的注释行遇到属性时用换行符拼接。但ToolTip太长会显示不全Unity的tooltip框有最大宽度限制所以实际用的时候建议注释控制在一行内太长就精简。第二个坑是属性名大小写。Shader属性名是大小写敏感的但有些项目里注释和属性名之间可能有空格差异正则匹配时要注意\w已经涵盖了大小写字母和下划线一般没问题。但如果属性名里有数字开头虽然不合法但有人这么写\w也能匹配不过Unity本身会报错所以不用太担心。第三个坑是内置Shader。AssetDatabase.GetAssetPath对Unity内置的Shader比如Standard、Unlit返回空字符串这时候解析会失败。我的处理是加个判断路径为空就直接返回空字典绘制时tooltip为nullGUIContent会自动忽略不会报错。4.2 ToolTip不显示的几种可能原因实测下来tooltip不显示通常有这几个原因。第一是GUIContent构造时tooltip传了null或空字符串这种情况Unity不会弹提示检查一下缓存字典里有没有对应key。第二是PropertyField的重载选错了如果你用的是EditorGUILayout.PropertyField(prop)不带GUIContent参数那tooltip永远不会显示。第三是编辑器皮肤问题某些自定义皮肤或者旧版本Unity对tooltip的渲染有bug换回默认皮肤试试。还有一个比较隐蔽的原因属性被禁用disabled。如果你用EditorGUI.BeginDisabledGroup包住了属性tooltip在某些Unity版本里会失效。这个我没找到完美的解决办法只能尽量避免在禁用组里放需要tooltip的属性。提示调试tooltip是否生效可以在GetContent里加一行Debug.Log(content.tooltip)确认内容确实被构造出来了。如果日志有输出但界面不显示那就是绘制方式的问题。4.3 性能与缓存失效的处理前面提到用_cachedShader做缓存但有个场景会出问题Shader文件被修改后缓存不会自动刷新。比如你在编辑器里改了Shader的注释Inspector面板不会立即更新得手动刷新或者重新选中材质。解决办法是监听AssetDatabase的刷新事件或者用EditorApplication.update定期检查文件修改时间。private DateTime _lastWriteTime; private void CheckShaderModified() { var path AssetDatabase.GetAssetPath(_cachedShader); if (string.IsNullOrEmpty(path)) return; var writeTime File.GetLastWriteTime(path); if (writeTime ! _lastWriteTime) { _lastWriteTime writeTime; _tooltipCache ParseTooltips(path); } }在OnGUI开头调用CheckShaderModified这样Shader一保存tooltip就会更新。文件IO在编辑器里开销不大而且GetLastWriteTime比读整个文件轻量得多实测对帧率没有明显影响。5. 让这套机制更好用的几个扩展思路5.1 从注释里提取更丰富的元信息既然已经能解析注释了不妨把注释格式规范化让它携带更多信息。比如用符号标记特殊字段// group 基础设置 // tip 控制整体色调影响漫反射颜色 _BaseColor (Base Color, Color) (1,1,1,1)解析时识别group就把属性归到对应分组识别tip就作为tooltip内容。这样一套注释既能驱动分组又能驱动tooltipShader文件本身就是配置源不用额外维护C#代码里的映射表。我在一个后处理Shader项目里用了这套方案新增属性时只改Shader文件C#端完全不用动维护成本降了很多。5.2 支持富文本和快捷键提示Unity的tooltip支持简单的富文本标签比如b加粗、color改色。你可以在注释里直接写这些标签GUIContent会原样传给tooltip渲染器。实测b和i是生效的color在部分Unity版本里有效可以试试。另外如果某个参数有快捷键操作比如按住Shift拖动可以微调也可以在tooltip里写清楚美术同学会觉得很贴心。5.3 和MaterialPropertyDrawer的配合如果你已经用了MaterialPropertyDrawer来做自定义绘制tooltip的注入点会不一样。Drawer的OnGUI方法里拿不到外部的GUIContent需要自己在Drawer内部构造。我的建议是把tooltip解析逻辑抽成一个静态工具类Drawer和ShaderGUI都调这个工具类避免重复代码。public static class ShaderTooltipUtility { public static string GetTooltip(Shader shader, string propertyName) { // 缓存 解析逻辑 } }这样无论你在哪里绘制属性都能拿到tooltip内容。Drawer里用EditorGUILayout.PropertyField时传入构造好的GUIContent即可。5.4 多语言支持的可行性如果项目有出海需求tooltip可能需要多语言。我的做法是在注释里用|分隔不同语言比如// 基础颜色|Base Color解析时按当前编辑器语言选对应文本。Unity有Application.systemLanguage可以判断但编辑器语言和系统语言不一定一致更稳的方式是读EditorPrefs里的语言设置。这套方案我还没在正式项目里大规模用因为维护多语言注释本身也是成本小项目没必要。6. 一些实操中的个人体会这套ToolTip机制我在三个项目里落地过最大的感受是Shader注释的规范比代码实现更重要。代码写一次就固定了但注释是团队每个人都要写的如果规范不统一解析出来的tooltip会乱七八糟。我的建议是在项目初期就定好注释格式比如“注释必须紧贴属性上方单行不超过30字用中文描述用途”然后在Code Review里检查。另一个体会是不要过度依赖tooltip。tooltip是辅助属性名本身应该尽量自解释。如果某个参数必须靠tooltip才能看懂那可能是命名有问题。我见过一个Shader属性叫_Param1tooltip写了一大段解释这种就是典型的命名失败。好的做法是属性名用_RimPower、_SpecularIntensity这种一看就懂的词tooltip只补充取值范围和特殊行为。最后分享一个小技巧在GetContent里可以给tooltip加个前缀比如[范围0-1]这样美术一眼就能看到取值范围不用把范围写进注释里。这个前缀可以根据属性类型自动生成Range类型自动加范围Color类型加“点击选择颜色”Texture类型加“拖入纹理资源”。这种自动化的小细节用起来会觉得很顺手。这套方案的核心代码量其实不大解析加绘制加起来两三百行但带来的编辑器体验提升很明显。如果你也在做ShaderGUI强烈建议把tooltip这套加上美术同学的反馈会告诉你值不值得。