企业官网建设流程全解析

• 移动开发
• UI组件

QMUI iOS 是由腾讯出品的开源 iOS UI 解决方案，核心目标是通过「一份全局配置表统一管理全 App 样式」+「大量 UIKit 拓展与开箱即用的控件」+「高效的工具方法集合」，让开发者从重复的基础 UI 代码中解放出来，专注于业务逻辑本身。读完本文，你将掌握 QMUI iOS 的定位与功能全貌、全局样式配置表（QMUIConfigurationTemplate）的工作原理与接入方式、CocoaPods 安装步骤、版本兼容性边界以及 AutoLayout / xib / Swift 等场景的使用注意事项，并能顺着仓库源码继续深入每个组件。

一、项目定位：为「设计还原」与「开发效率」而生

仓库根目录的 README.md 开宗明义：QMUI iOS 是一个致力于提高项目 UI 开发效率的解决方案，其设计目的是用于辅助快速搭建一个具备基本设计还原效果的 iOS 项目，同时利用自身提供的丰富控件及兼容处理，让开发者能专注于业务需求而无需耗费精力在基础代码的设计上。无论是新项目的创建，还是已有项目的维护，均可使开发效率和项目质量得到大幅度提升。

需要强调的是，它不是一个「换肤框架」或「单一组件库」，而是覆盖全局样式管理、UIKit 兼容性、常用控件、工具方法四个维度的成套方案。从 QMUIKit.podspec 可以看出，框架以 subspec 形式被拆分为 QMUICore、QMUIMainFrame、QMUIResources 以及按组件粒度划分的 QMUIComponents 系列子模块，业务项目可以按需依赖，这从侧面印证了其「既能整包使用、也能按需裁剪」的设计取向。

二、四大功能特性及其源码依据

1. 全局 UI 配置：一份配置表，全局生效

README 描述：「只需要修改一份配置表就可以调整 App 的全局样式，包括颜色、导航栏、输入框、列表等。一处修改，全局生效。」

这套机制的实现链路在源码中非常清晰，由三个文件协作完成：

• 配置表协议：QMUIConfiguration.h 定义了QMUIConfigurationTemplateProtocol，要求配置表必须实现applyConfigurationTemplate方法（应用配置），并提供可选方法shouldApplyTemplateAutomatically（返回 YES 表示 App 启动时自动应用这份配置表；启动时自动应用的配置表最多只允许一份，多份时其余会被忽略）。
• 配置表模板：QMUIConfigurationTemplate/QMUIConfigurationTemplate.h 与 QMUIConfigurationTemplate/QMUIConfigurationTemplate.m 是框架自带的示例配置表。使用方式是把该目录下所有文件复制进业务项目并保证被编译到即可——不需要手动 import，也不需要手动运行。其头文件注释特别强调了两条规则：更新 QMUIKit 版本时留意 Release Log 中关于配置表的更新提醒；配置表的 class 名必须以QMUIConfigurationTemplate开头并实现QMUIConfigurationTemplateProtocol，这是 QMUI 识别「一份配置表」的唯一条件。
• 配置单例与宏：QMUIConfiguration.h 中的QMUIConfiguration单例负责维护全局 UI 配置的取值；业务代码则通过 QMUIConfigurationMacros.h 中的宏（如QMUICMI、UIColorWhite、NavBarTintColor、TableViewSeparatorColor等）来读取这些值。

配置表的自动应用逻辑位于 QMUIConfiguration.m 的applyInitialTemplate：它会遍历项目里所有类，找出类名包含QMUIConfigurationTemplate且遵循QMUIConfigurationTemplateProtocol的类，然后应用第一个shouldApplyTemplateAutomatically返回 YES 的配置表，并将active置为 YES 以标记配置表已生效。从源码结构看，这样设计的好处是：Swift 中类名带有项目前缀也能被containsString命中；而「只应用第一份」的约束则保证了多配置表场景下的确定性。另注意 QMUIConfigurationMacros.h 中的警告：不要在+ load方法里使用这些宏，那个时机过早可能导致 crash。

以 QMUIConfigurationTemplate.m 为参照，配置表实际可以控制的样式维度非常全面，按组列举如下：

模板末尾的 shouldApplyTemplateAutomatically 返回 YES，表示 App 启动时自动应用这份配置表；若业务存在多份配置表，需要把除默认配置表外的其他配置表返回值改为 NO。

2. UIKit 拓展及版本兼容

README 提到：「拓展多个 UIKit 的组件，提供更加丰富的特性和功能，提高开发效率；解决不同 iOS 版本常见的兼容性问题。」

仓库的 UIKitExtensions 目录集中存放了大量 Category，覆盖UIView+QMUI、UIColor+QMUI、UIButton+QMUI、UITableView+QMUI、UINavigationController+QMUI、NSString+QMUI、NSAttributedString+QMUI等几十个扩展（完整列表见 QMUIKit.h 中按__has_include条件导入的头文件）。这些扩展通过给系统类追加便捷方法，让开发者在处理颜色转换、布局辅助、富文本、键盘、设备适配等高频场景时少写大量样板代码。

兼容性方面，QMUICommonDefines.h 提供了从 iOS 9 SDK 到 iOS 18 SDK 的IOS9_SDK_ALLOWED～IOS18_SDK_ALLOWED编译期宏，以及IS_NOTCHED_SCREEN、IS_DYNAMICISLAND_DEVICE、IS_ZOOMEDMODE等设备判断宏；QMUIConfigurationTemplate.m 中针对 iOS 15 的navBarUsesStandardAppearanceOnly、tabBarUsesStandardAppearanceOnly、toolBarUsesStandardAppearanceOnly等开关，正是为了解决 iOS 15 之后「standardAppearance 与 scrollEdgeAppearance 默认不一致」这一典型兼容问题而设计的。

3. 丰富的 UI 控件

README 描述：「提供丰富且常用的 UI 控件，使用方便灵活，并且支持自定义控件的样式。」

框架在 QMUIComponents 目录下提供了大量可直接使用的控件，与 README「代码示例」中展示的 Demo 对应，比较有代表性的包括：

• QMUITheme：QMUITheme.h 聚合了QMUIThemeManager、UIColor+QMUITheme、UIView+QMUITheme等，用于实现多主题换肤并适配 iOS 13 Dark Mode。根据 QMUIThemeManager.h 的文档，它支持「主题注册增删、currentThemeIdentifier/currentTheme 切换、监听QMUIThemeDidChangeNotification持久化」的标准流程，且通过QMUIThemeManagerCenter可支持同一项目内多个维度的主题互不影响。
• QMUIConsole / QMUILog：QMUIConsole.h 提供在设备屏幕上直接显示的控制台（支持按 Level/Name 过滤、搜索），默认仅在 DEBUG 下显示窗口；QMUILog.h 提供QMUILog、QMUILogInfo、QMUILogWarn三档宏，可按 logName/logLevel 维度控制日志是否打印。
• QMUITips：QMUITips.h 对QMUIToastView做了简单封装，一行代码即可弹出纯文本、loading、succeed、error、info 五类提示，且支持类方法自动 addSubview/removeFromSuperView 的一次性使用场景。
• QMUIMarqueeLabel：QMUIMarqueeLabel.h 是跑马灯 Label，文字超宽时自动滚动，支持speed、pauseDurationWhenMoveToEdge（默认 2.5s）、fadeWidthPercent、shouldFadeAtEdge等属性，并针对 UITableViewCell 等可复用视图提供了requestToStartAnimation等手动启停接口。
• QMUIImagePickerViewController：QMUIImagePickerViewController.h 提供完整相册选择流程（配合 QMUIAssetsManager 等相册库），通过 delegate 控制照片排序（QMUIAlbumSortTypePositive/Reverse）、多选完成回调等。
• 此外还有 QMUIButton / QMUIAlertController / QMUIDialogViewController / QMUIEmptyView / QMUICheckbox / QMUIPopupMenuView / QMUIEmotionView / QMUIBadge 等大量控件，均可在 QMUIComponents 目录中逐一查阅其头文件。

这些控件普遍带有UI_APPEARANCE_SELECTOR样式属性和 QMUIAppearance 机制支持，正是 README 所说「支持自定义控件的样式」的实现基础。

4. 高效的工具方法及宏

README 描述：「提供高效的工具方法，包括设备信息、动态字体、键盘管理、状态栏管理等，可以解决各种常见场景并大幅度提升开发效率。」

核心载体是 QMUIHelper.h，它以多个分类形式组织工具能力：

• 设备信息（Device）：deviceModel（如 iPhone12,5）、deviceName、isIPad/isIPhone/isSimulator、isNotchedScreen、isDynamicIslandDevice、各英寸屏幕判断（is67InchScreen、is61InchScreen…）、statusBarHeightConstant、navigationBarMaxYConstant等。
• 动态字体（DynamicType）：preferredContentSizeLevel（返回当前「字体大小」设置的 level，辅助功能里的「更大字体」统一按最大值处理）、heightForDynamicTypeCell:（传入 7 个数值的数组，按系统版本选择合适值）。
• 键盘管理（Keyboard）：isKeyboardVisible、keyboardHeightWithNotification:inView:（可换算到指定 view 坐标、自动处理横竖屏与外接键盘问题）、keyboardAnimationDurationWithNotification:等。
• 状态栏/系统（UIApplication / SystemVersion）：dimmedApplicationWindow/resetDimmedApplicationWindow（浮层弹出时把主 window 置灰）、numbericOSVersion、compareSystemVersion:toVersion:、isCurrentSystemAtLeastVersion:等。
• 其他：executeBlock:oncePerIdentifier:（同一 identifier 的 block 只执行一次）、pixelOne（一像素尺寸）、baselineOffsetWhenVerticalAlignCenterInHeight:withFont:（文本垂直居中基准偏移）等。

与宏配合使用时，QMUICommonDefines.h 还提供了一整套开发期便捷宏：IS_DEBUG、IOS_VERSION_NUMBER、SCREEN_WIDTH/HEIGHT、DEVICE_WIDTH/HEIGHT、PixelOne、PreferredValueForXXX系列，以及BeginIgnoreClangWarning/EndIgnoreClangWarning等编译器告警屏蔽宏，可显著减少日常开发中的重复代码。

三、支持版本：随版本演进的历史兼容梯度

README 明确给出了各版本对最低 iOS 版本的要求（以当前仓库实际内容为准）：

与这一梯度相对应，当前仓库中 QMUIKit.podspec 声明的s.platform = :ios, '13.0'、s.version = "4.8.0"，以及 QMUIKit.h 中QMUI_VERSION = @"4.8.0"相互印证：当前版本的部署目标已收敛到 iOS 13+。若你的业务仍需支持更低版本，需要对应选择 4.6.1 之前的 QMUIKit 版本。

四、使用方法：CocoaPods 集成

README 给出的安装方式为标准 CocoaPods 接入：

pod 'QMUIKit'

在Podfile中加入上述一行并执行pod install即可。结合 QMUIKit.podspec 的实现细节，有几点值得注意：

• 主 spec 的source_files仅指向QMUIKit/QMUIKit.h这个伞头文件，真正的代码以QMUICore、QMUIMainFrame、QMUIResources、QMUIComponents（及其下数十个子组件）等 subspec 形式组织，QMUICore是其他所有组件的基础依赖。
• 框架依赖Foundation、UIKit、CoreGraphics系统框架；QMUICore额外使用CoreImage、ImageIO；图片选择与缩放相关组件还会引入Photos、PhotosUI、AVFoundation、QuartzCore等（见各 subspec 的ss.frameworks声明）。
• 资源通过QMUIResourcessubspec 以 resource bundle 形式打包（QMUIKit.podspec），并包含PrivacyInfo.xcprivacy（见下文「隐私」一节）。
• 框架自带requires_arc = true，使用 ARC 即可。

仓库还提供了 Xcode 工程 qmui.xcodeproj 与单元测试 targetQMUIKitTests，包含 QMUIThemeTests.m（验证主题色 UIColor 的动态行为）、QMUICommonDefinesTests.m（验证CGFloatEqualToFloat等浮点比较宏）以及 NSObject / NSString / UIButton / UIColor 等扩展测试，可直接在本地打开工程跑通。

五、代码示例与配套 Demo

README 指出：完整的代码示例请参考独立的 QMUI Demo 工程（项目名为 QMUIDemo_iOS，是一个独立仓库，不在当前仓库内）。QMUI Demo 与 QMUIKit 的关系在「设计资源」一节也有说明——QMUIDemo_iOS 拥有自己另外一套设计，两者是相互独立的项目。

对于想快速体验控件效果的开发者，建议直接运行当前仓库的 Xcode 工程配合阅读 QMUIKit.h 中按组件聚合的公开头文件，并结合 QMUIComponents 下各控件源码查看具体用法；Demo 工程则提供了一站式的交互演示（README 展示了 Launch、QMUITheme、QMUIPopup、QMUIMarqueeLabel 等效果的示例动图）。

六、注意事项：AutoLayout、xib/storyboard、Swift 与 UIScene

README 列出的使用注意事项对集成决策有直接影响：

• AutoLayout：通常可以配合 Masonry 等常见的 AutoLayout 框架使用；若遇到不兼容的个案，建议到项目 issue 区反馈。QMUI 内部同时兼容 frame 布局与 AutoLayout 场景。
• xib / storyboard：现已全面支持，可以放心在 Interface Builder 中使用 QMUI 控件。
• Swift：可以正常使用。QMUI 的 class 命名与containsString式的配置表识别逻辑（见 QMUIConfiguration.m）也考虑了 Swift 类名带项目前缀的情况。
• UIScene：暂不支持 Multiple Window（多窗口场景）。如果你的 App 使用 UIScene 的多窗口能力，需要评估相关限制。

七、隐私政策

README 指向了《QMUI iOS SDK 个人信息保护规则》作为隐私说明（规则原文位于 QMUI_iOS 的 Wiki 文档中）。从当前仓库的代码层面看，框架自带了一份 Apple 隐私清单 PrivacyInfo.xcprivacy，其中声明：

• NSPrivacyAccessedAPITypes：仅包含NSPrivacyAccessedAPICategoryUserDefaults，使用理由为CA92.1（用于 App 功能）。
• NSPrivacyCollectedDataTypes：空数组，即框架本身不收集用户数据。
• NSPrivacyTracking：false，无跟踪行为。

这也意味着框架内置的 UserDefaults 类 API 访问（例如日志配置的持久化）均已按 Apple 要求进行了合规声明，业务接入后无需再为框架本身额外补充隐私说明（但仍应遵守自己的合规审查流程）。

八、设计资源

README 说明：QMUIKit 框架内自带图片资源的组件主要是QMUIConsole、QMUIEmotion、QMUIImagePicker、QMUITips。对照仓库中的 QMUIResources/Images.xcassets，可以确认：

• QMUI_console_clear / filter / logo等 → QMUIConsole 控制台
• QMUI_emotion_delete→ QMUIEmotionView 表情面板
• QMUI_pickerImage_*、QMUI_hiddenAlbum→ 图片选择器
• QMUI_tips_done / error / info→ QMUITips 提示
• QMUI_checkbox16_*→ QMUICheckbox 复选框

而 QMUI Demo 项目（独立仓库）拥有自己的另一套设计资源。也就是说，框架自带资源只服务于上述框架组件，业务 UI 素材仍需自行准备。框架内图片可通过 QMUIHelper.h 的imageWithName:从QMUIKit.framework的 Images.xcassets 中按名获取。

九、配套生态：Code Snippets 与文件模板

README 的「其他」一节建议搭配 QMUI 专用的 Code Snippets 及文件模板使用：

1. QMUI_iOS_CodeSnippets：为 Xcode 提供 QMUI 相关代码片段，加快常用代码的录入。
2. QMUI_iOS_Templates：提供 QMUI 风格的文件模板（如 ViewController 子类模板），保证新建文件时即遵循 QMUI 的代码组织约定。

这两个配套仓库与 QMUI Demo 一样，是独立于当前仓库的辅助资源，接入 QMUIKit 后按各自说明安装即可。

十、仓库导航：从入口文件开始继续深入

若想进一步研读源码，推荐以下入口路径（均相对于仓库根目录）：

• 统一入口：QMUIKit.h —— 全部公开头文件的伞文件，按__has_include条件聚合，可作为模块清单索引。
• 核心层：QMUICore.h 聚合QMUIHelper、QMUICommonDefines、QMUIRuntime、QMUILab、QMUIConfiguration、QMUIConfigurationMacros六个核心文件，是理解框架底层的第一站。
• 页面基类：QMUICommonViewController.h —— 自带QMUINavigationTitleView（标题控件，支持 loading、副标题、下拉菜单）、QMUIEmptyView（空界面），并统一约定初始化 subview、设置 navigationItem、响应动态字体等方法，保证同类型代码集中管理。
• 组件清单：QMUIComponents 目录下的每个子目录/文件即一个可独立阅读的控件模块。
• 测试用例：QMUIKitTests 下的Components/QMUIThemeTests.m、Core/QMUICommonDefinesTests.m与UIKitExtensions系列测试，可用来验证关键宏与扩展行为。

结语

综合 README.md 的官方描述与仓库源码可以看到，QMUI iOS 的价值不在于某一个单一能力，而在于「配置表驱动全局样式 + 系统性 UIKit 拓展 + 成套常用控件 + 高效工具宏」的组合拳。对新建项目，它可以快速搭建出具备设计还原效果的 UI 骨架；对已有项目，它也能在样式统一、兼容性修复与开发提效上持续提供收益。接入时只要对照本文的配置表机制、版本兼容梯度与注意事项逐项落实，就能以较低的学习成本获得较高的效率回报。

• 移动开发
• UI组件