fastlane frame_screenshots(frameit)实战指南用 Framefile.json 为 iOS/macOS/Android 截图批量套上设备边框【免费下载链接】fastlane The easiest way to automate building and releasing your iOS and Android apps项目地址: https://gitcode.com/GitHub_Trending/fa/fastlane本文围绕 fastlane 的frame_screenshots动作其文档页即 frame_screenshots.md展开。frameit让你只需一条命令就能为 iOS、macOS 和 Android 截图批量套上精美的设备边框并可叠加自定义背景、标题与关键词文字用于 App Store、官网、QA 演示或邮件沟通。读完本文你将掌握frameit的命令行与 Fastfile 用法、Framefile.json全部通用/特定/文字参数的含义与取值校验、macOS 截图的offset定位机制以及--resume断点续帧、.strings本地化等实战技巧并能结合仓库源码理解设备识别、边框下载与配置合并的底层实现。一、frameit 能做什么frame_screenshots是 fastlane 内置动作作者为 KrauseFx适用于 iOS、macOS、Android 三个平台见 frame_screenshots.rb 的is_supported?定义。它直接调用独立的 frameit 组件完成实际工作frame_screenshots只是 thin wrapper进入截图目录后调用Frameit::Runner.new.run(.)见 frame_screenshots.rb。核心能力设备边框支持 iPhone、iPad、Mac 与一组 Android 设备覆盖竖屏Portrait与横屏Landscape并提供多种边框颜色高级能力为带边框截图添加自定义彩色/图片背景、设置四周留白padding、在边框上方或下方添加「关键词 标题」双行文字可自定义字体、字号、颜色、字重支持多行文本并带有智能文字排版多平台iOS/Mac 为默认平台向后兼容Android 需显式指定。首次运行frameit时设备边框模板会自动下载到本地。边框素材最初来自 Facebook Design 的设备资源并托管在 fastlane 的 frameit-frames 仓库下载器会在输出中打印一段关于素材授权与品牌使用规范的免责声明见 frame_downloader.rb。更完整的受支持设备与颜色列表请以 frameit-frames 仓库的latest版本为准。边框下载与缓存机制从源码可以看到 FrameDownloader 的行为边框统一缓存在~/.fastlane/frameit/版本/目录若存在旧路径~/.frameit/devices_frames_2/则沿用frames_version默认是latest可在Framefile.json的device_frame_version字段锁定具体版本下载流程会拉取version.txt与files.json逐个写入 PNG 边框和offsets.json并刻意把version.txt放在最后写入以便中断后能断点续传见 frame_downloader.rb版本判定逻辑在 module.rb扫描当前目录下**/Framefile.json读取其中的device_frame_version。注意不带标题无背景的frameit输出是全分辨率图片不能直接上传 App Store更适合网站、印刷和邮件场景要为 App Store 准备截图请配合下方的Framefile.json标题配置。二、基本用法命令行方式先cd到截图目录然后执行iOS 与 macOS 是默认平台fastlane frameit为 Android 截图套框fastlane frameit android使用银色白色系边框fastlane frameit silver手动重新下载最新边框fastlane frameit download_framesFastfile 方式frame_screenshots与frameit是同一动作的两个名字仓库声明的示例写法如下见 frame_screenshots.rb 的example_codeframe_screenshots frameit # alias for frame_screenshots frame_screenshots(use_platform: ANDROID) frame_screenshots(silver: true) frame_screenshots(path: /screenshots) frame_screenshots(rose_gold: true)主要选项及其环境变量定义在 options.rb 中摘录如下选项环境变量说明默认值pathFRAMEIT_SCREENSHOTS_PATH截图目录路径默认取snapshot输出的SNAPSHOT_SCREENSHOTS_PATH否则为fastlane目录动态white/silverFRAMEIT_WHITE_FRAME/FRAMEIT_SILVER_FRAME使用白色系边框silver是white的别名否rose_goldFRAMEIT_ROSE_GOLD_FRAME玫瑰金边框否goldFRAMEIT_GOLD_FRAME金色边框否force_device_typeFRAMEIT_FORCE_DEVICE_TYPE强制指定设备型号对 Mac 截图尤其有用因为其尺寸多变取值必须是受支持的设备名无use_platformFRAMEIT_USE_PLATFORM指定平台合法值IOS、ANDROID、ANY默认为 Fastfile 当前平台或IOS动态force_orientation_block—[高级] 一个 proc根据文件名强制指定截图方向见下文debug_modeFRAMEIT_DEBUG_MODE在输出图中打印调试信息falseresumeFRAMEIT_RESUME增量续帧跳过已是最新状态的截图falseuse_legacy_iphone5s等FRAMEIT_USE_LEGACY_IPHONE_5_S等一组布尔开关在 iPhone SE/7/8/XS/XR 与旧机型5s/6s/7/X/XR/XS/XS Max边框之间切换false运行器对文件还有一套过滤规则见 runner.rb_framed.png、.itmsp/包文件、device_frames/目录会被跳过Apple Watch 截图会报错提示并跳过。输出文件统一命名为原文件名_framed.png见 screenshot.rb。三、Framefile.json通用与特定参数Framefile.json应放在截图根目录即screenshots文件夹下用于定义全局与单张截图级的信息。注意 frameit 会在截图文件的上一级、上两级、以及../../../../相对位置逐级寻找Framefile.json见 runner.rb 的create_config这一行为是为了兼容 screengrab 的多层目录结构。基本 JSON 结构{ device_frame_version: latest, default: { ... }, data: [ ... ] }device_frame_version锁定边框版本缺省为latestdefault全局默认参数data数组每个元素通过filter匹配文件名实现单图覆盖。通用参数default键键说明默认值background带边框截图使用的背景图写相对路径如*.jpg。带标题时此参数必填NAkeyword可选关键词对象最多 3 个键见文字参数表NAtitle标题对象最多 3 个键见文字参数表NAstack_title同时定义 keyword 与 title 时是否让 keyword 叠放在 title 上方为false时两者并排显示falsetitle_below_image是否把标题及可选关键词放到设备边框下方为false时放在上方falseshow_complete_frame是否缩小设备边框使其完整显示为false时边框底部或title_below_image为true时的顶部可能被裁切falsepadding内容四周留白。三种写法1) 整数同时指定水平/垂直像素2) 字符串水平x垂直像素如30x603) 字符串百分比如5%x10%百分比按最小边计算。可混合如5%x40。垂直 padding 同时作用于文字与边框上/下边缘50interline_spacing多行 title/keyword 行距增/减的像素值0font_scale_factor字体缩放系数若显式指定font_size则此值对 keyword/title 无效0.1frame覆盖边框颜色合法值BLACK、WHITE、GOLD、ROSE_GOLDNAtitle_min_height为标题始终预留的高度可为高度百分比或绝对像素值保证不同截图中设备顶部或底部位置一致NAuse_platform覆盖截图平台合法值IOS、ANDROID、ANYIOSforce_device_type强制指定设备。原文档列出的合法值包括Huawei P8、Motorola Moto E、Motorola Moto G、Nexus 4、Nexus 5X、Nexus 6P、Nexus 9、Samsung Galaxy Grand Prime、Samsung Galaxy Note 5、Samsung Galaxy S Duos、Samsung Galaxy S3、Samsung Galaxy S5、S7、S8、S9、iPhone 5s、5c、SE、6s、6s Plus、7、7 Plus、8、8 Plus、X、XS、XR、XS Max、iPad Air 2、iPad Mini 4、iPad Pro、MacBook、Google Pixel 3、Pixel 3 XL、HTC One A9、HTC One M8具体设备表以源码 device_types.rb 为准可能随版本演进NA这些键在解析阶段会被逐一校验font/background路径必须真实存在、color必须含#的 HEX 值、padding必须是整数或AxB格式、show_complete_frame/title_below_image必须是布尔值、frame/use_platform/force_device_type必须属于合法枚举否则直接报错退出见 config_parser.rb 的validate_key。另外font与background的相对路径会自动改写为相对于Framefile.json所在目录的绝对路径见 config_parser.rb。特定参数data键data是数组每个元素通过filter与文件名部分匹配只把该元素内的键应用于匹配的截图键说明filter必填用文件名的一部分关联配置。例如截图名为iPhone 8-Brainstorming.png时可用Brainstorming。若多个filter同时命中将按顺序全部应用最后一个优先级最高keyword同default中的keyword但这里可以直接写text因为文案是单图特定的title同default中的title但这里可以直接写textframe覆盖边框颜色BLACK、WHITE、GOLD、ROSE_GOLDuse_platform覆盖平台IOS、ANDROID、ANYforce_device_type强制指定设备合法值同通用参数从源码看合并逻辑是先克隆default再把所有命中的data元素用深度合并fastlane_deep_merge定义在 module.rb依次叠加上去见 config_parser.rb 的fetch_value因此特定参数天然覆盖默认参数。Framefile 中 keyword 与 title 参数keyword与title在default与data中均可使用二者都由以下可选键组成键说明默认值color文字字体颜色HEX/HTML 颜色码#000000黑font文字字体族写相对字体文件路径如 OpenType 字体imagemagick默认字体依赖系统font_size字号点。未指定或为0时按可用空间自动缩放即使如此文字放不下时 frameit 仍会缩小NAfont_weight字重整数如 900遵循 ImageMagick 的 weight 语义NAtextkeyword 或 title 的文本内容。如需本地化改用下方.strings 文件NA完整示例{ device_frame_version: latest, default: { keyword: { font: ./fonts/MyFont-Rg.otf }, title: { font: ./fonts/MyFont-Th.otf, font_size: 128, color: #545454 }, background: ./background.jpg, padding: 50, show_complete_frame: false, stack_title: false, title_below_image: true, frame: WHITE, use_platform: IOS }, data: [ { filter: Brainstorming, keyword: { color: #d21559 } }, { filter: Organizing, keyword: { color: #feb909 }, frame: ROSE_GOLD }, { filter: Sharing, keyword: { color: #aa4dbc } }, { filter: Styling, keyword: { color: #31bb48 } }, { filter: Android, use_platform: ANDROID } ] }参数优先级源码视角screenshot.rb 的注释明确了三套配置的来源与优先级从低到高options.rbFastfile 选项或环境变量如FRAMEIT_USE_PLATFORM含默认值与校验最低优先级命令行位置参数如fastlane frameit android经 commands_generator 传入可覆盖第 1 层Framefile.jsondefault与data按文件名过滤最高优先级——用户为某张截图设的特定值应覆盖 CLI 与 Fastfile 全局设置。对应到代码即platform config[use_platform] || platform_command || Frameit.config[:use_platform]screenshot.rb设备检测同理force_device_type优先否则由Device.detect_device(path, platform)按分辨率自动识别screenshot.rb。四、截图方向控制默认情况下 frameit 按截图本身的方向加边框竖屏图用竖屏边框横屏图用「landscape left」Home 键在左侧边框。源码中默认 block 还识别文件名后缀以force_landscapeleft或force_landscaperight结尾的文件名会强制对应横屏方向见 options.rbscreenshot.rb 的frame_orientation则先调用该 block未返回有效值时回落到「宽高即竖屏否则 landscape_right」。force_orientation_block如果默认行为不满足需求、又不想重命名截图可以在 Fastfile 中传入force_orientation_blockproc按文件名返回:landscape_leftHome 键在左、:landscape_rightHome 键在右、:portraitHome 键在下或nil回退默认。# 根据文件名匹配对应的设备方向 frameit( path: ./fastlane/screenshots, force_orientation_block: proc do |filename| case filename when iPad Pro (12.9-inch)-01LoginScreen :landscape_right when iPhone 6 Plus-01LoginScreen :portrait # and so on end end )# 文件名包含 landscape 字样时一律横屏Home 键在右 frameit( silver: true, path: ./fastlane/screenshots, force_orientation_block: proc do |filename| f filename.downcase if f.include?(landscape) :landscape_right end end )注意block 返回nil之外的非法符号会直接报错orientation_block must return :landscape_left, :landscape_right, :portrait or nil见 screenshot.rb。五、macOS 截图frameit 同样可以为 macOS 应用截图套框但需要额外提供background一张同时包含背景与 Mac 电脑的图片相对路径offset信息告诉 frameit 把截图贴到哪里offset字符串相对背景图左上角的水平/垂直像素偏移语法水平垂直例如200150titleHeight标题占用的像素高度。{ default: { title: { color: #545454 }, background: Mac.jpg, offset: { offset: 676479, titleHeight: 320 } }, data: [ { filter: Brainstorming, keyword: { color: #d21559 } } ] }源码中runner.rb 的editor方法会判断screenshot.mac?即设备名为MacBook见 screenshot.rb是则走MacEditor否则走普通Editor两条渲染路径分开实现。六、.strings 文件本地化要为多个语言目录提供标题与关键词可在每个语言文件夹如en-US中放入两个.strings文件keyword.strings与title.strings。它们就是 iOS 应用中标准.strings文件可以直接复用现有翻译服务产出实现标题本地化。仓库内可参考的 fixture 见 title-same-dir.strings 与 Framefile.json。注意事项务必满足否则解析失败.strings文件必须是 UTF-8 或 UTF-16 BE带 BOM编码且必须以空行开头想显示标题就必须提供background没有背景时 frameit 不会添加标题。解析实现在 strings_parser.rb先用file --mime-encoding探测编码UTF-8/ASCII 直接读取其他编码则调用iconv -f UTF-16 -t UTF-8转换然后逐行解析key value;形式的条目跳过注释与空行解析结果为空时会提示检查文件是否为合法的 UTF-16 Big-endian 编码。七、实战技巧Tips生成本地化截图配合 fastlane 的snapshot动作用 UI Automation 自动生成各语言截图再交给 frameit 套框形成完整流水线。--resume 断点续帧套框是耗时操作。需要恢复中断的批次、或只对少数更新的截图重新套框时使用--resume标志Fastfile 中为resume: true环境变量FRAMEIT_RESUME。只有尚未生成、或没有最新带框图片的截图才会被处理。它基于文件修改时间判断若原截图比_framed.png新则重新套框见 screenshot.rb 的outdated?与 runner.rb 的skip_up_to_date?。上传截图生成后可用 fastlane 的deliver动作上传 iOS 截图到 App Store Connect用supply动作上传 Android 截图到 Play Store实现全自动发布。使用干净的 Status Bar在snapshot中设置override_status_bar: true可把模拟器状态栏固定为 1 月 9 日周二9:41、满电满信号需要更细粒度定制例如运营商名称时再设置override_status_bar_arguments其值会透传给xcrun simctl status_bar override可用xcrun simctl status_bar --help查看可选项。# 9:41AM满电满信号默认运营商名 Carrier capture_ios_screenshots( override_status_bar: true )# 9:41AM电量 75% 且充电中TELUS LTE 网络 capture_ios_screenshots( override_status_bar: true, override_status_bar_arguments: --time 9:41 --dataNetwork lte --cellularMode active --cellularBars 4 --batteryState charging --batteryLevel 75 --operatorName TELUS )文字周围出现灰色杂边如果渲染出现字体边缘描边等质量问题通常重装imagemagick即可解决brew uninstall imagemagick brew install imagemagickframeit 的文字渲染底层依赖 ImageMagick 命令行能力这也是font参数未指定时回落到系统默认 imagemagick 字体的原因。八、卸载- gem uninstall fastlane - rm -rf ~/.frameit第二行清理旧版边框缓存目录当前版本默认缓存已迁移至~/.fastlane/frameit/见 frame_downloader.rb如需彻底清理可一并删除。小结frame_screenshotsframeit把给截图套设备边框这件原本要靠 Photoshop 手工完成的工作收敛为一条命令命令行适合简单场景选平台、选颜色Framefile.json负责精细控制背景、padding、标题/关键词、逐图覆盖force_orientation_block处理特殊方向macOS 场景补充offset定位.strings文件则让标题随语言目录自动本地化。结合源码可以看到其核心是配置三层优先级 分辨率自动识别设备 断点续帧的组合理解 ConfigParser 的深度合并与校验、Screenshot 的方向判定、Runner 的跳过规则后遇到某张图没被套框某参数不生效之类问题时可以快速定位原因。相关规格测试位于 frameit/spec例如 editor_spec.rb、config_parser_spec.rb 与 template_finder_spec.rb可作为行为验证的参考。【免费下载链接】fastlane The easiest way to automate building and releasing your iOS and Android apps项目地址: https://gitcode.com/GitHub_Trending/fa/fastlane创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考