SwiftGen colors 模板 literals-swift4：用 colorLiteral 生成 Swift 4 颜色常量的完整指南

开发工具代码生成【免费下载链接】SwiftGenThe Swift code generator for your assets, storyboards, Localizable.strings, … — Get rid of all String-based APIs!项目地址https://gitcode.com/gh_mirrors/sw/SwiftGen点击查看免费下载本篇技术指南以 SwiftGen 仓库自带的colors/literals-swift4.stencil模板为核心讲解如何用#colorLiteral字面量生成可直接在 Xcode 中预览的 Swift 4 颜色常量涵盖配置方法、三个自定义参数enumName、forceFileNameEnum、publicAccess的完整语义并结合模板源码与测试用例解释其底层实现。读完本文你将掌握在swiftgen配置文件中引用该模板、按需定制输出以及理解生成代码背后工作原理的完整能力。模板概览literals-swift4是 SwiftGen 为Swift 4语言版本预置的颜色模板之一模板文件位于 Sources/SwiftGenCLI/templates/colors/literals-swift4.stencil对应的官方文档为 Documentation/templates/colors/literals-swift4.md。属性值模板文件名colors/literals-swift4.stencil配置示例见下方「配置文件中的引用方式」目标语言Swift 4模板作者Olivier Halligon配置文件中的引用方式在swiftgen.yml中通过templateName引用该模板colors: inputs: path/to/colors-file.txt outputs: templateName: literals-swift4 output: Colors.swift关于配置文件inputs、outputs、templateName等键的完整语法可参见 Documentation/ConfigFile.md。何时选择这个模板原文档明确给出了三条适用判据需要生成 Swift 4 代码时使用如果你的项目最低部署版本是 Swift 5则应改用literals-swift5两者输出结构一致详见 literals-swift5 文档输入文件中存在多个颜色名共用同一个色值的场景例如articleFootnote与themeCyan都对应0xff66ccff也能正确生成每个名字各自产出一个static let常量生成的常量使用#colorLiteral字面量在 Xcode 的代码编辑器中可以直接看到色块预览这是它区别于同语言的 swift4 模板后者生成ColorName(rgbaValue:)包装结构的核心特点。自定义参数详解使用该模板时可以在swiftgen调用或配置文件中通过params覆盖以下参数参数名默认值说明enumNameColorName修改承载全部颜色常量的enum类型名forceFileNameEnum无不设置设置后即使输入只有一个文件也会额外生成以文件名命名的嵌套enumpublicAccess无不设置设置后生成的常量标记为public否则为internal特殊用法直接扩展 UIColor / NSColor原文档特别强调了一个值得注意的行为如果你把enumName设为UIColoriOS/tvOS/watchOS或NSColormacOS那么颜色常量将直接生成在UIColor/NSColor类型的扩展extension中而不会再创建一个独立的enum类型来做命名空间隔离。这一点可以在模板源码中得到印证。literals-swift4.stencil 中的平台分支逻辑如下#if os(macOS) import AppKit {% if enumName ! NSColor %} {{accessModifier}} enum {{enumName}} { } {% endif %} #elseif os(iOS) || os(tvOS) || os(watchOS) import UIKit {% if enumName ! UIColor %} {{accessModifier}} enum {{enumName}} { } {% endif %} #endif也就是说只有enumName不是UIColor/NSColor时才会先声明一个空enum作为命名空间而当enumName恰好等于平台类型时该enum声明被跳过后续的extension {{enumName}}便直接作用于系统类型。在 Tests/TemplatesTests/ColorsTests.swift 中testLiteralsSwift4()正是用enumNameUIColor作为自定义参数变体suffix-customName来验证这条路径的对应的黄金文件为 Sources/TestUtils/Fixtures/Generated/Colors/literals-swift4/defaults-customName.swift。生成的代码长什么样以默认参数enumNameColorName为例模板对输入色值0x339666ffArticleBody与0xff66ccffArticleFootnote生成的核心片段为internal extension ColorName { /// 0x339666ff (r: 51, g: 150, b: 102, a: 255) static let articleBody #colorLiteral(red: 0.2, green: 0.588235, blue: 0.4, alpha: 1.0) /// 0xff66ccff (r: 255, g: 102, b: 204, a: 255) static let articleFootnote #colorLiteral(red: 1.0, green: 0.4, blue: 0.8, alpha: 1.0) }完整的生成结果包含import平台分支、swiftlint注释、文件名嵌套枚举等全部内容可查看黄金文件 Sources/TestUtils/Fixtures/Generated/Colors/literals-swift4/defaults.swift其中还包含private这类 Swift 保留字被反引号转义为private的实际样例。代码结构拆解完整生成文件遵循以下结构对应 defaults.swift头部注释// Generated using SwiftGen平台导入与命名空间声明macOS 分支import AppKitinternal enum ColorName { }iOS/tvOS/watchOS 分支import UIKitinternal enum ColorName { }// MARK: - Colors分隔与swiftlint:disable指令internal extension ColorName { ... }中逐条输出每个颜色的static let常量。使用示例生成之后在业务代码中直接按名字引用静态常量即可无需任何字符串// To reference a color, simpy reference its static instance by name: let title ColorName.articleBody let footnote ColorName.articleFootnote由于是#colorLiteral在 Xcode 里悬停或编辑时可以看到真实的色块预览。若采用了enumName: UIColor的扩展方式则可以写成UIColor.articleBody直接调用。底层实现原理源码级解析色值如何换算成字面量模板对每个颜色执行两步 Stencil 过滤器链{% macro h2f hex %}{{hex|hexToInt|int255toFloat}}{% endmacro %}hexToInt把33这样的两位十六进制字符串转成整数51int255toFloat把 0–255 的整数归一化为 0.0–1.0 的浮点数51 / 255 ≈ 0.2。随后拼装成#colorLiteral(red: ..., green: ..., blue: ..., alpha: ...)。变量名的处理链为swiftIdentifier:pretty|lowerFirstWord|escapeReservedKeywords这就是为什么ArticleBody会变成articleBody首字母小写、private会被反引号包裹。上下文数据从哪来模板消费的palettes上下文由 Sources/SwiftGenKit/Stencil/ColorsParserContext.swift 构造每个 palette 按名称排序后映射出name与colors数组每个 color 又展开为name/red/green/blue/alpha五个十六进制字符串分量。完整字段说明与 YAML 示例见 Documentation/SwiftGenKit Contexts/colors.md。多文件与 forceFileNameEnum 的分支逻辑模板核心分支literals-swift4.stencil{% if palettes.count 1 or param.forceFileNameEnum %} {% set accessPrefix %}{{accessModifier}} {% endset %} {% for palette in palettes %} enum {{palette.name|swiftIdentifier:pretty|escapeReservedKeywords}} { {% filter indent:2, ,true %}{% call enumBlock palette.colors accessPrefix %}{% endfilter %} } {% endfor %} {% else %} {% call enumBlock palettes.first.colors %} {% endif %}当输入了多个文件palettes.count 1时会自动为每个文件生成一个以文件名命名的嵌套enum分组当只有一个文件但设置了forceFileNameEnum时同样强制生成该嵌套分组否则颜色常量直接平铺在ColorName扩展里即上面「生成的代码长什么样」展示的形式。输入文件类型与颜色格式literals-swift4模板本身不负责解析输入解析由 Sources/SwiftGenKit/Parsers/Colors/ColorsParser.swift 完成。它注册了四类子解析器因此支持以下输入格式详见 Documentation/Parsers/colors.mdCLRmacOS 的 NSColorList 调色板文件JSON根对象中键为颜色名、值为十六进制色值的简单结构TXT每行名称: 色值色值可为十六进制也可引用文件内其他颜色名XMLAndroid 的colors.xml。默认过滤器为[^/]\.(?i:clr|json|txt|xml)$可通过filter选项自定义。解析选项colorFormat默认rgba每两位十六进制依次为 R/G/B/A也支持argb顺序这在ColorFormat枚举rgba/argb与Option.colorFormat定义处可以确认。测试如何保障输出稳定模板行为由 Tests/TemplatesTests/ColorsTests.swift 中的testLiteralsSwift4()守护它会对empty、defaults、multiple三种上下文跑模板并针对defaults额外生成-customNameenumNameUIColor、-publicAccess、-forceFileNameEnum三种参数变体与Sources/TestUtils/Fixtures/Generated/Colors/literals-swift4/目录下的黄金文件逐一比对。这意味着你通过参数定制输出的每一种行为都有对应的测试覆盖与可参考的完整产物示例。小结literals-swift4是 SwiftGen 为 Swift 4 项目提供的「所见即所得」颜色生成方案它以#colorLiteral让颜色在 Xcode 中直接可视化同时通过enumName含直接扩展UIColor/NSColor的特殊路径、forceFileNameEnum、publicAccess三个参数覆盖了命名空间、多文件分组与访问控制三大常见定制需求。配合 ConfigFile.md 中的params机制即可在swiftgen.yml中一键启用。赞分享开发工具代码生成【免费下载链接】SwiftGenThe Swift code generator for your assets, storyboards, Localizable.strings, … — Get rid of all String-based APIs!项目地址https://gitcode.com/gh_mirrors/sw/SwiftGen点击查看免费下载相关推荐SwiftGen colors/literals-swift5 模板实战指南用 colorLiteral 生成 Swift 5 类型安全颜色常量SwiftGen colors/literals swift5 模板实战指南用 colorLiteral 生成 Swift 5 类型安全颜色常量 本指南以 S开发工具代码生成Wagtail 2.16.1 补丁版深度解析六个关键 Bug 修复、自动重定向与批量操作源码探秘Wagtail 2.16.1 补丁版深度解析六个关键 Bug 修复、自动重定向与批量操作源码探秘 Wagtail 2.16.1 发布于 2022 年 2 月开发工具代码生成SwiftGen Core Data swift4 模板详解为 Xcode 数据模型生成类型安全的 Swift 4 代码SwiftGen Core Data swift4 模板详解为 Xcode 数据模型生成类型安全的 Swift 4 代码 导读 本文聚焦 SwiftGen 内开发工具代码生成上一篇3步掌握Cutadapt测序数据预处理完整指南下一篇130亿参数颠覆行业认知腾讯混元A13B重新定义大模型效率标准创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考