Ignite 生成器模板完全指南从 ignite 目录到自定义脚手架【免费下载链接】igniteInfinite Reds battle-tested React Native project boilerplate, along with a CLI, component/model generators, and more! 9 years of continuous development and counting.项目地址: https://gitcode.com/GitHub_Trending/ig/igniteignite目录是 Infinite Red 的 Ignite 项目样板boilerplate中存放生成器模板的核心位置。本文围绕 docs/boilerplate/ignite.md 展开系统讲解该目录的组织方式、内置的五大生成器组件、屏幕、导航器、App 图标、启动屏的用法与配置参数并结合仓库源码src/tools/generators.ts、src/commands/generate.ts揭示生成器底层的 EJS 渲染、Front Matter 解析与图片变换原理。读完本文你将能熟练使用 Ignite CLI 快速搭建应用骨架并学会定制或从零创建属于自己的生成器模板。一、ignite 目录是什么在通过 Ignite CLI 创建的新应用里会有一个ignite目录其中包含一组初始生成器模板generator templates用于帮助你快速搭建新的屏幕screen、组件component、上下文context、App 图标app icon等。在本文档所属的仓库中这些模板的源头位于 boilerplate/ignite/templates/包含四个子目录component/—— 组件模板NAME.tsx.ejsnavigator/—— 导航器模板NAMENavigator.tsx.ejsscreen/—— 屏幕模板NAMEScreen.tsx.ejsapp-icon/—— App 图标模板android-adaptive-background.png、android-adaptive-foreground.png、android-legacy.png、ios-universal.pngsplash-screen/—— 启动屏模板logo.png需要说明的是当你npx ignite-cli new一个新项目时CLI 会把这套模板复制到你的项目./ignite/templates/*目录下之后生成器都从你项目内的这份模板读取内容。因此修改自己项目里的模板即可改变后续所有生成结果。生成器被官方称为the true gem of IgniteIgnite 真正的宝石无论是做概念验证、Demo 还是生产应用它都能帮你节省大量时间、保持代码风格一致、快速搭建基础结构。相关完整说明见 docs/concept/Generators.md 与 docs/concept/Generator-Templates.md。二、生成器工作流先认识命令入口所有生成器都通过 Ignite CLI 的统一命令触发npx ignite-cli generate --listgenerate的简写别名是g也支持generator/generators见 src/commands/generate.ts--list会列出当前项目已安装的生成器清单。在源码中showGeneratorHelp 还展示了--update、--dir、--case等选项的帮助信息以及每个已安装生成器的推荐用法普通生成器npx ignite-cli generator Demoapp-iconnpx ignite-cli app-icon all|ios|android|exposplash-screennpx ignite-cli splash-screen #191015 [--android-size180 --ios-size212]从 src/tools/generators.ts 的isIgniteProject可以看出CLI 通过检查当前目录下是否存在ignite目录来判断是否处于 Ignite 项目根目录所以请始终在项目根目录执行这些命令。三、五大内置生成器详解3.1 Component 生成器使用最频繁这是你使用最多的生成器npx ignite-cli generate component MyAwesomeButton它会基于 boilerplate/ignite/templates/component/NAME.tsx.ejs 生成一个新的组件函数。模板的 Front Matter 指定了输出目录--- destinationDir: app/components/% props.subdirectory % ---生成的组件自带项目约定的代码骨架Props接口、useAppTheme()主题 Hook、ThemedStyle样式的$container/$text常量与 app/components 下其他组件保持一致的书写风格。3.2 Screen 生成器生成一个启用 Hooks的屏幕npx ignite-cli generate screen Settings屏幕模板 boilerplate/ignite/templates/screen/NAMEScreen.tsx.ejs 值得一提它的 Front Matter 中不仅指定了destinationDir: app/screens还带有一个patches配置自动把新屏幕注册到导航类型里--- destinationDir: app/screens patches: - path: app/navigators/navigationTypes.ts replace: // IGNITE_GENERATOR_ANCHOR_APP_STACK_PARAM_LIST insert: % props.pascalCaseName %: undefined\n // IGNITE_GENERATOR_ANCHOR_APP_STACK_PARAM_LIST ---生成器会定位 app/navigators/navigationTypes.ts 中的锚点注释// IGNITE_GENERATOR_ANCHOR_APP_STACK_PARAM_LIST在其上方插入新的路由参数类型同时保留锚点以便下次继续插入。这就是生成器同时更新关联文件的典型例子也是 Ignite 让脚手架一次生成、处处连通的关键设计。3.3 Navigator 生成器创建一个基于 React Navigation 的导航器到app/navigators目录npx ignite-cli generate navigator OrderPizza模板 boilerplate/ignite/templates/navigator/NAMENavigator.tsx.ejs 会生成一个createNativeStackNavigator导航器包含NavigatorParamList类型定义和默认的Demo屏幕。导航器的深入用法参见 docs/boilerplate/app/navigators/Navigation.md。3.4 App Icon 生成器特殊类型App 图标很棘手——尺寸形状繁多、配置文件与存放位置各异。为此 Ignite 提供了一个特殊生成器它不仅渲染模板还会直接修改原生工程目录把输入图片缩放、变换后输出到对应位置。同时它的第二个参数只接受预定义选项之一ios、android、expo或all。npx ignite-cli generate app-icon ios模板文件夹ignite/templates/app-icon源头见 boilerplate/ignite/templates/app-icon/包含四个可自定义的输入文件模板文件用途android-adaptive-background.png用于生成 Android 8.0 所需的全部自适应启动图标背景层更新目录与旧版图标一致android-adaptive-foreground.png用于生成 Android 8.0 所需的全部自适应启动图标前景层更新目录与旧版图标一致android-legacy.png用于生成 Android 7.1 及以下的全部旧版启动图标会自动添加必要的内边距与圆角——自定义输入文件时不要自带内边距或圆角。vanilla更新./android/app/src/main/res/包含mipmap-anydpi-v26/ic_launcher.xmlexpo更新./assets/images/与根文件./app.jsonios-universal.png用于生成 iOS 所需的全部 App 图标。vanilla更新./ios/**/Images.xcassets/AppIcon.appiconset/含Content.jsonexpo更新./assets/images/与根文件./app.json更新模板文件时请注意文件名必须保持不变尺寸必须是 1024x1024px。从源码 src/tools/generators.ts 的APP_ICON_RULESET可以看到底层生成逻辑的细节例如旧版 Android 图标会使用sharp库做二次变换ic_launcher.png先缩放至 812x812、圆角 64、四边内边距 106ic_launcher_round.png缩放至 944x944、圆角 472、内边距 40随后按照各 DPImdpi 48 / hdpi 72 / xhdpi 96 / xxhdpi 144 / xxxhdpi 192分别输出。iOS 侧则覆盖 iphone / ipad / ios-marketing 三种 idiom 下的多尺寸与倍率组合。源码级安全校验默认情况下如果模板文件夹中的输入文件与 Ignite 自带图标的 MD5 签名一致生成器会直接退出——这是为了鼓励你先把图标改成自己的内容。校验逻辑见 validateAppIconGenerator它会依次检查文件是否存在、尺寸是否为 1024x1024、MD5 是否与默认模板相同。如果你确实想用 Ignite 自带的图标覆盖应用图标可以分两步先执行npx ignite-cli g app-icon --update重置模板文件夹再用--skip-source-equality-validation标志重新生成。3.5 Splash Screen 生成器启动屏同样因平台和系统版本差异而难以手工配置因此 Ignite 样板默认预配置好启动屏并附带生成器方便定制。与 App 图标生成器不同启动屏生成器只需一个输入文件logo.png位于ignite/templates/splash-screen源头见 boilerplate/ignite/templates/splash-screen/logo.png。生成器要求一个必填参数启动屏背景色十六进制格式。npx ignite-cli generate splash-screen FF0000 # 或 npx ignite-cli generate splash-screen #FF0000 # 或 npx ignite-cli generate splash-screen fff从 src/commands/generate/splash-screen.ts 可以看出背景色缺省时会提示用法并退出传入的色值若不以#开头会被自动补上同时支持--android-size与--ios-size两个可选参数默认值分别是androidSize 180与iosSize 212。生成器会修改./assets/images/并尝试更新./app.json。但如果项目使用app.config.js或app.config.tsExpo 动态配置配置变更会输出到控制台需要你手动同步源码在检测到app.json缺失且存在app.config.*文件时触发该提示见 src/tools/generators.ts。Logo 尺寸变换按平台预置默认值在多数场景可用但你可以用标志自定义npx ignite-cli generate splash-screen FF0000 --ios-size150 --android-size180关于尺寸的注意事项iOS 无上限取值需谨慎Android 上限为 288源码校验androidSize 288会报错见 validateSplashScreenGenerator同时要求是大于 0 的数值ExpoAndroid 与 iOS会遵循自定义尺寸但由于 Expo 配置的要求启动屏资源会带有内边距并尽量铺满屏幕。源码中 Expo 侧实际生成多套资源generateSplashScreensplash-logo-ios-mobile.png1284x27783x、splash-logo-ios-tablet.png2048x27322x、splash-logo-android-universal.png1440x25604x、Web 端 1920x1080以及一张 1242x2436 的通用图随后将splash/android.splash/ios.splash/web.splash配置合并写入app.json。与 App 图标生成器相同若输入文件未经修改源码比对 MD5启动屏生成器也会退出鼓励你先完成自定义。四、CLI 选项--case 与 --dir4.1 --case控制生成文件名的大小写格式默认情况下生成文件的文件名采用PascalCase--case auto或--case pascal。--case开关用于指定模板文件名中NAME占位符被替换成何种格式。例如npx ignite-clilatest g screen log-in按不同模板名会得到如下输出--case模板文件名生成的文件名auto, pascalNAMEScreen.tsx.ejsLogInScreen.tsxcamelNAMEScreen.tsx.ejslogInScreen.tsxsnakeNAMEScreen.tsx.ejslog_in_screen.tsxkebabNAMEScreen.tsx.ejslog-in-screen.tsxnoneNAMEScreen.tsx.ejslog-in.tsxauto, pascalNAME.tsx.ejsLogIn.tsxcamelNAME.tsx.ejslogIn.tsxsnakeNAME.tsx.ejslog_in.tsxkebabNAME.tsx.ejslog-in.tsxnoneNAME.tsx.ejslog-in.tsx注意--case none时NAMEScreen.tsx.ejs生成log-in.tsx此时NAME被替换为log-in后缀Screen不再自动拼接。对应逻辑在 src/tools/generators.ts 的formattedName计算中实现名称的pascalCase/kebabCase/camelCase/snakeCase四种变形由 src/commands/generate.ts 预先计算。4.2 --dir覆盖输出路径--dir指定生成文件的输出路径优先级高于模板默认路径当前为app/以及 Front Matter 中的destinationDirnpx ignite-cli g model Episodes --dir src/context这一选项对于使用文件路由的导航体系如 Expo Router特别有用。从源码 src/tools/generators.ts 可以看到优先级顺序options.dirCLI 传入 Front Matter 的destinationDir 默认的app/generator复数/。此外在 src/commands/generate.ts 中当检测到项目使用expo-router时route生成器还会交互式询问目标目录默认给出src/app或app并支持自动创建不存在的目录。4.3 其他实用行为子目录支持名称中带/时会把/之前的部分解析为子目录并传入props.subdirectory见 src/commands/generate.ts组件模板的destinationDir: app/components/% props.subdirectory %正是消费该值自动去重后缀如果传入的名称以生成器名结尾如MyButtonComponentCLI 会自动剥离Component后缀并提示你无需手动添加见 src/commands/generate.ts--overwrite目标文件已存在时默认跳过加--overwrite才会覆盖见 src/commands/generate.ts。五、模板语法EJS 与 Props模板使用 EJS 编写——一种基于 JavaScript 的模板语言。你可以随意书写模板用% foo %执行并输出 JS 表达式用% if (condition) { %...% } %做条件控制。生成器向模板注入一个props对象包含以下属性props.filename // string正在生成的文件名如 UserModel.tsx props.pascalCaseName // string传入名称的 PascalCase 版本如 UserModel props.camelCaseName // stringcamelCase 版本如 userModel props.kebabCaseName // stringkebab-case 版本如 user-model props.subdirectory // string目标文件所在子目录路径如 my/sub/path/源码 generateFromTemplate 中还会额外注入snakeCaseName并把name、originalName、overwrite等选项一并并入props。在模板中使用示例type % props.pascalCaseName %Props { some: string } export function % props.pascalCaseName %(props: % props.pascalCaseName %Props) { return Text{props.some} in a % props.pascalCaseName % component!/Text }5.1 目录与文件命名约定模板放在./ignite/templates目录下文件夹名需与生成器名一致。例如想运行npx ignite-cli generate header Pizza就把模板放在./ignite/templates/header/文件夹该文件夹内所有文件都会被复制并按传入的名称渲染。模板文件名中全大写的NAME会被替换为传入名称的 PascalCase 版本。例如NAMEScreen.ts在npx ignite-cli generate screen Pizza时生成PizzaScreen.ts。如果想自定义文件名可在模板 Front Matter 中提供filename--- filename: % props.camelCaseName %.tsx ---六、Front Matter模板的元数据配置Front Matter 是写在模板最开头的元数据块用上下各三个横线---分隔生成时会被剥离、不会出现在产物文件中。解析逻辑在 src/tools/generators.ts它按---切分内容前半部分按 YAML 解析成数据后半部分才是真正渲染进文件的模板正文。支持以下 Front Matter 选项6.1 destinationDir定制模板的输出目标目录。例如在./ignite/templates/navigator/*中--- destinationDir: app/navigation --- import { StackNavigator } from react-navigation // ...这样文件会输出到./app/navigation/*而不是默认的./app/navigators/*。6.2 patch / patches允许对另一个文件打补丁例如导出索引文件。单个patch的示例--- patch: path: app/screens/index.ts append: export * from \./% props.kebabCaseName %/% props.kebabCaseName %-screen\\n ---也可以使用数组形式的patches屏幕模板即用此形式见上文 3.2 节。源码 handlePatches 支持三种动作append向目标文件末尾追加内容prepend在目标文件开头插入内容replaceinsert把目标文件中replace指定的文本替换为insert的内容屏幕模板的锚点插入正是这种用法。补丁只在目标文件尚不存在时执行见 src/tools/generators.ts避免重复插入。七、自定义与自建生成器完全可以把提供的模板改成自己的直接修改./ignite/templates/*下的文件之后所有生成结果都会使用你更新后的文件。自建生成器同样简单你的生成器就存放在应用的./ignite/templates/*里。新建生成器时参考项目里已有的模板——它们都是*.ejs文件生成时会被 EJS 解释。新建一个文件夹如./ignite/templates/header/并放入模板文件运行npx ignite-cli generate header Pizza即可立即生效无需任何额外注册。详细指引见 docs/concept/Generator-Templates.md。八、更新生成器想把自己的生成器更新到 Ignite 最新版本时在项目根目录运行npx ignite-cli update type # 或更新全部 npx ignite-cli update --all这会从 Ignite 把最新的生成器复制覆盖到你的项目。--update也可以直接附加在生成命令后如npx ignite-cli g model --update源码 updateGenerators 支持按名称更新单个或全部。⚠️注意这会清除你所有的自定义修改请务必先提交一次 commit以便随时回滚另外CLI 的--list帮助信息showGeneratorHelp也提示若某个生成器未安装但 Ignite 自带会提示你先npx ignite-cli generate generator --update再重试——即--update也可用于补齐缺失的生成器。九、Windows 用户的注意事项如果在 Windows 上生成源文件如 screen 或 model时发现新文件里 Front Matter 没有被剥离很可能是换行符End of Line配置不当导致的。Ignite 会尽力自行处理但有时你的机器缺少unix2dos之类的命令行工具该工具通常随 Git 一起安装。此时可以打开 VS Code或其他 IDE把ignite/templates目录下所有ejs文件的换行符统一转换如统一为 LF 或 CRLF然后重新运行生成命令新文件就会正常生成。十、源码级原理速览最后从实现层面总结生成器的完整链路便于你深入阅读 src/tools/generators.ts命令入口npx ignite-cli generate type name进入 src/commands/generate.ts解析生成器类型、名称、子目录、--dir、--case、--overwrite等参数模板发现installedGenerators()扫描项目ignite/templates下的子目录得到可用生成器列表EJS 渲染generateFromTemplate()读取每个*.ejs文件计算名称的四种大小写变形渲染 EJS 并把props注入模板Front Matter 解析按---切分解析destinationDir/filename/patch/patches确定目标路径并执行文件补丁写入产物目标不存在则创建存在则按overwrite决定覆盖或跳过最终打印 Generated new files 清单特殊生成器app-icon与splash-screen走 src/commands/generate/app-icon.ts 与 src/commands/generate/splash-screen.ts用sharp做图片缩放/圆角/内边距变换并按平台写入原生资源目录或 Expo 的assets/images与app.json。围绕生成器的 CLI 总览含new、cache、doctor、rename、remove-demo等命令可继续阅读 docs/cli/Ignite-CLI.md模板机制的完整阐述见 docs/concept/Generators.md 与 docs/concept/Generator-Templates.md。【免费下载链接】igniteInfinite Reds battle-tested React Native project boilerplate, along with a CLI, component/model generators, and more! 9 years of continuous development and counting.项目地址: https://gitcode.com/GitHub_Trending/ig/ignite创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考