枚举显示名解析(EnumDisplay)
定位
KernLab.Loom.Display——[EnumDisplay] 枚举显示名解析器源生成:成员标注 [Description] / [Display] → 编译期物化强类型解析器 {枚举名}Display(中性显示名 + culture 回退链:指定 culture 资源 → 中性 → 成员名)。零运行时反射,NativeAOT 安全。解决:界面/日志/导出里枚举名的本地化展示——手写 switch 逐枚举爆炸、反射取 attribute 运行时开销且 AOT 不友好。
快速上手
using KernLab.Loom.Display;
[EnumDisplay] // 枚举级:声明参与解析
public enum OrderStatus
{
[Description("待支付")] // 字面量形态一:[Description]
Pending = 1,
[Display(Name = "Paid")] // 字面量形态二:[Display(Name=)](缺省中性名)
Paid = 2,
[Display(Name = "ShippedTitle", ResourceType = typeof(Messages))] // 资源形态:本地化
Shipped = 3,
}
// 解析(零反射 switch 直出——#80:Display(value) 感知 ambient culture)
OrderStatusDisplay.Display(OrderStatus.Pending); // ambient:CurrentUICulture 资源 → 中性
OrderStatusDisplay.DisplayNeutral(OrderStatus.Pending); // "待支付"(显式中性,不查资源)
OrderStatusDisplay.Display(OrderStatus.Shipped, culture); // culture 资源 → 中性 → 成员名 回退链
OrderStatusDisplay.Display(OrderStatus.Shipped, null); // null = ambient(CurrentUICulture)
OrderStatusDisplay.Description(OrderStatus.Pending); // [DisplayDescription] 描述通道
OrderStatusDisplay.Composite(a, b, " / "); // 组合显示(两值 ambient 名拼接)
生成物 {枚举名}Display 静态类——同名即得,无需注册。
概念与术语
- 中性显示名:不查 culture 资源的标注名(
[Description]/[Display(Name)]),未标注 = 成员名;经DisplayNeutral(value)显式取。 - ambient 显示名:
Display(value)缺省走CultureInfo.CurrentUICulture(#80——线程 culture 感知);Display(value, null)等价。 - 回退链:
Display(value, culture)的求值序——指定 culture 资源 → 中性显示名 → 成员名。 - 资源形态:
[Display(Name = "键", ResourceType = typeof(Xxx))]——ResourceType 须有ResourceManager属性: public(跨程序集)或 internal(同程序集——标准 resx 强类型资源开箱兼容,修 KLSG101,见 #80)。 - 描述通道:
[DisplayDescription("...")]独立于显示名(tooltip/详情);未标注 = 成员名回退。 - 组合:
Composite(value1, value2, separator)按 ambient 显示名拼接。 - culture 方法恒发射:无论是否有资源形态成员,
Display(value, CultureInfo?)均生成(ambient 语义需要; 无资源时等价于中性面)。
怎么选
| 方案 | 优势 | 代价 | 适用场景 |
|---|---|---|---|
| [EnumDisplay] 生成器 | 编译期物化零反射;AOT 安全;强类型 {枚举名}Display 直调 |
枚举标注学习面;新增枚举须生成器在场 | 界面/日志/导出的枚举展示(本组件) |
| 手写 switch | 零依赖 | 逐枚举逐成员爆炸;漂移无防护 | 一两处一次性展示 |
| 反射取 [Description] | 无生成器 | 运行时开销;AOT 不友好;缓存自管 | 不在 AOT 面的次要场景 |
决策:AOT 面/热路径的枚举展示选本组件;一次性零散展示手写即可。
怎么用
中性显示名
Display(value)——switch 表达式直出,未匹配成员回 value.ToString()(运行期新增成员不炸)。
culture 本地化
Display(value)——ambient culture(CurrentUICulture)资源 → 中性名 → 成员名;DisplayNeutral(value) 显式中性;Display(value, culture) 指定 culture(null = ambient)。资源文件与 ResourceType 按标准 RESX 机制维护(internal ResourceManager 同程序集可用)。
与查询规则字典翻译的配合
枚举字段的显示名→存储码翻译(查询规则字典翻译缝)可消费同一解析器的中性名——一处标注两处消费;缝接口见查询规则引擎(EF)。
反模式
| 症状 | 为什么错 | 正确形态 |
|---|---|---|
| 解析器类找不到 | 枚举没标 [EnumDisplay] 或生成器未引用 | 枚举打标 + 包引用(analyzer 形态自动生效) |
| culture 方法不存在 | Display(value, culture) 恒存在;无资源时等价中性面 |
|
| 资源形态声明后编译报错 | ResourceType 缺 ResourceManager 属性(跨程序集须 public;同程序集 internal 可用) | 补 ResourceManager 属性(标准 resx 强类型类开箱可用——#80) |
| 期望 Display(null) 有缺省文案 | null 不是枚举成员 | 调用侧判空 |
想深入
- API 参考:docs.kernlab.dev/loom/api
- 诊断:KLSG Layout/Cli 段位注册表见家族 RULES.md;本面用法诊断全部默认 Error、随包
AnalyzerReleases分发。
性能
量化基线:enum-display-baseline.md。