Table of Contents

枚举显示名解析(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。