# UILint **Repository Path**: codelint/uilint ## Basic Information - **Project Name**: UILint - **Description**: Swift UI Tools - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2022-11-10 - **Last Updated**: 2026-11-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # UILint > A SwiftUI component library and design-system toolkit for iOS. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) UILint 是一个 **SwiftUI 组件库 + 设计规范库**:把重复实现的语义色、字号档位、按钮样式、抽屉、滑动操作、加载占位等收敛成一套命名统一、可直接复用的 API。 ## 这是什么 - 绝大多数公开类型以 `Lint` 开头(`LintColor`、`LintButton`、`LintToggle` …),少数按功能命名(`WeightedStack`、`LazyLoadView`、`ButtonDefine` …);View 扩展以 `lint` 开头(`.lintFont`、`.lint(overlay:)`、`.lazyloading` …)。调用处一眼能看出哪些能力来自本库。 - **`Lint` 只是组件的统一命名前缀,与代码检查、静态分析没有任何关系**——UILint 不是 linter。 - 无第三方依赖,只用 Apple 系统框架(Foundation / SwiftUI / UIKit / CoreText / CoreImage / Vision / CryptoKit / Combine);语义色与字号都是**有档位的**(走 `LintColor` / `LintFont` 这一层,不写死十六进制值),方便整体换肤。 ## 特性 - **主题体系**:`LintColor` 38 个语义色、`LintFont` 13 档字号、asset catalog 回退、运行期主题覆盖(`Color.LINT_COLORS`)。 - **交互组件**:`LintButton`、`.buttonStyle(.lint)`、`LintToggle`、`LintSwipeButton`(滑动操作)、`LintGestureButton`(可拖拽按钮)、`LintMask`、`LintOverlay`(抽屉浮层)。 - **布局**:`WeightedStack` / `WeightedGrid`(按权重切分主轴)、`LintLineWrapper`(自动换行的流式布局)、`LintLeftOrRight` / `LintFlop` / `LintFlopCard` / `LintFlopView`(左右切换与 3D 翻面)、`LintCenter` / `LintSquare`。 - **加载与占位**:`LazyLoad` / `LazyLoadWith` / `LazyLoadVElse` / `LazyLoadView` / `.lazyloading()`;配套的展示组件 `LintProgressCircle`、`LintTimeCircle`、`LintFavIcon`、`LintShareSheet`、`LintTimer`。 - **扩展修饰符**:数十个 `View.lint(...)`,覆盖条件渲染、平台分支、UserDefaults 读取、居中布局、尺寸测量、边框、生命周期、定时刷新;另有 `LintEdgeBorder` / `DynamicRoundedCorners` / `CircleOffsetEffect` 等形状与几何工具。 ## 环境要求 | 项 | 要求 | | --- | --- | | 平台 | **iOS 15.0+** | | Swift | 5.7+(`Package.swift` 的 `swift-tools-version: 5.7`) | | 第三方依赖 | 无 | > **本库目前只支持 iOS。** `Package.swift` 里虽然同时声明了 `.macOS(.v12)`,但源码大量直接使用 `UIColor` / `UIImage` / `UIRectCorner` / `UIActivityViewController` 等 UIKit 类型,且没有 `#if canImport(UIKit)` 守卫,macOS 上 `swift build` 会直接编译失败。macOS 的平台声明目前是「有声明、不可用」,详见「已知限制」。 下列 API 是 **iOS 16+ 专有**,iOS 15 上不可用: - `View.lintFont(_:with:)`、`View.lintFont(size:family:)`(`Extension/Font.swift:118-155`) - `View.withLintColors` / `.withLintFont` / `.withLintPage`(`UILint.swift:12-16`) - `Color.lint(base64:)`(`Component/LintColor.swift:148`)、`LintTimeCircle`(`Component/LintTimeCircle.swift:40`)、`LintShareSheet`(`Component/LintShareSheet.swift:25`) - `UIImage.barcodes` / `.lint(languages:strings:)` / `.md5`(`Extension/UIImage.swift:101` 起) - `WeightedStack` / `WeightedGrid` / `.lintWeight(_:)` / `.lintFixed(_:)`(`Layout/WeightedStack.swift:32`、`Layout/WeightedGrid.swift:24`) 其余公开 API 在 iOS 15 上均可直接使用。 ## 安装 **本地 path 依赖**(已实测可用,推荐): ```swift // Package.swift dependencies: [ .package(path: "../UILint") // 换成你本地 UILint 的相对路径 ], targets: [ .target(name: "MyApp", dependencies: [ .product(name: "UILint", package: "UILint") ]) ] ``` > 消费端包需要声明 `platforms: [.iOS(.v15), .macOS(.v12)]`。UILint 声明了 `.macOS(.v12)`,如果消费端沿用 SwiftPM 默认的 macOS 10.13,解析阶段就会报 `the library 'MyApp' requires macos 10.13, but depends on the product 'UILint' which requires macos 12.0`。 **远程依赖**(有风险,谨慎使用): ```swift dependencies: [ .package(url: "", from: "1.0.0") ] ``` > ⚠️ UILint 的 target 带了 `swiftSettings: [.unsafeFlags(["-enable-library-evolution"])]`(`Package.swift:25-29`)。SwiftPM 不允许把**带 unsafe build flags 的包**作为版本化依赖引入。本地 path 依赖不受这条限制(已实测可正常编译);仓库当前也没有任何 tag,走远程版本化依赖还需要先补 tag。 ## 快速开始 ```swift import SwiftUI import UILint struct ContentView: View { var body: some View { VStack(spacing: 16) { Text("Hello, UILint") .font(.lint(.title)) .foregroundColor(Color.lint(c: .primary_font)) Button { print("tapped") } label: { Text("点我") .frame(width: 160, height: 44) .background(Color.lint(c: .primary)) .foregroundColor(Color.lint(c: .primary_font)) .cornerRadius(8) } .buttonStyle(.lint) } .padding() .background(Color.lint(c: .background)) } } ``` 说明:`.frame` 必须写在 label **内部**,否则不计入命中区(见下文 `.buttonStyle(.lint)`)。 ## 设计体系 ### 语义色 `LintColor` `LintColor` 是一个 `String` 枚举,共 **38** 个取值: | 组 | 取值 | | --- | --- | | 基础 / 页面 | `primary`、`primary_font`、`background`、`block`、`font`、`secondary` | | 按钮 | `btn_font`;`LintColor.buttonColors` 收录 `primary`、`blue`、`yellow`、`red`、`orange`、`green`、`cyan`、`gray`、`purple`、`success`、`danger`、`warning` | | 列表 | `listBackground`、`listItemBackground`、`listItemFont` | | 状态 | `success`、`danger`、`warning`(以及各自的 `*_font`) | | 彩色 | `blue`、`yellow`、`red`、`orange`、`green`、`purple`、`cyan`、`gray`、`pink` | | 金属 | `golden`、`silver`、`bronze` | | 前景色 | `success_font`、`danger_font`、`warning_font`、`secondary_font`、`blue_font`、`yellow_font`、`red_font`、`orange_font`、`green_font`、`purple_font`、`cyan_font`、`gray_font`、`pink_font` | **取色只有一条入口:`Color.lint(c:)`**(`Sources/UILint/Component/LintColor.swift:117`),优先级为: 1. **asset catalog**:先找名为 `c_` 的颜色资源(如 `c_primary`、`c_listItemBackground`),找到就用它。 2. **内置默认表**:找不到资源时退回 `LintColor.defaults` 里的十六进制值,例如 `.primary` → `#0e4471`、`.background` → `#000000`、`.block` → `#1c1c1c`、`.font` → `#bdbdbd`、`.listItemBackground` → `#1e1e1e`、`.btn_font` → `#ffffff`。 3. **运行期主题覆盖**:`Color.LINT_COLORS` 非空时,优先使用表里的十六进制字符串。 ```swift // 启动时一次性设置整张主题表:key 是 LintColor 本身,value 是十六进制字符串 Color.LINT_COLORS = [ .primary: "#0A84FF", .background: "#000000", .font: "#EBEBF5" ] ``` > `LintColor.defaultsKey`(形如 `"lint.theme.primary"`)目前**没有任何调用点**,不要拿它当 UserDefaults 的键用;主题覆盖请写 `Color.LINT_COLORS`。该表是全局可变状态,不是线程安全的。 ### 字体 `LintFont` `LintFont` 是 13 档字号(`Sources/UILint/Extension/Font.swift:83-110`): | 档位 | 字号 | weight | | --- | --- | --- | | `largeTitle` | 32 | `.regular` ⚠️ | | `title` / `title2` / `title3` | 28 / 22 / 20 | `.semibold` | | `headline` / `body` | 17 / 17 | `.semibold` / `.regular` | | `callout` / `subheadline` / `footnote` | 16 / 15 / 13 | `.regular` | | `caption` / `caption2` / `caption3` | 12 / 11 / 8 | `.regular` | > ⚠️ `largeTitle` 的 weight 是 `.regular`,与系统 `Font.largeTitle`(粗体)不一致。 三种取字体的方式:`Font.lint(_:with:)` → `Font`(`Extension/Font.swift:160`);`View.lintFont(_:with:)` → View(**iOS 16+**);`View.lintFont(size:family:)` → View(**iOS 16+**,按任意字号取字体)。未配置自定义字体时,档位直接映射到系统字体;配置了自定义字体时按档位字号渲染。 ### 自定义字体 - 字体名从 `UserDefaults.standard.string(forKey: "LINT_FONT")` 读取(`Extension/Font.swift:120`)。 - **必须是 PostScript name**(如 `PingFangSC-Semibold`),不是字体全名。`CGFont.lint(fontName:)`(`Extension/Font.swift:36`)返回的是 `kCTFontFullNameKey` 对应的**全名**,不能直接拿来用。 - 字体要先注册到系统,二选一:把字体文件加进 App 并在 `Info.plist` 的 `UIAppFonts` 数组里登记;或运行时调用 `CGFont.lint(register: url)`(`Extension/Font.swift:52`)注册。 - 也可以在调用处直接传名字:`Font.lint(.body, with: "MyFontPSName")`、`View.lintFont(.body, with: "MyFontPSName")`。 ### `.buttonStyle(.lint)` `LintPlainButtonStyle`(`Component/LintButtonStyle.swift:17`)视觉与 `.plain` 完全一致,唯一区别是**把整个布局矩形纳入命中区**:SwiftUI 默认只对「画出来的内容」做命中测试,label 里用 `.padding` / `.frame` 撑出来的空白点不到。 ```swift Button { submit() } label: { Image(systemName: "paperplane.fill") .frame(width: 40, height: 40) // .frame 必须写在 label 内部 .background(Color.lint(c: .primary)) } .buttonStyle(.lint) ``` > 命中形状按 **label 自身**的布局矩形计算。写在 `Button { } label: { }` **外面**的 `.frame` 不属于 label,仍然不参与命中。 ### 页面级修饰符(iOS 16+) | 修饰符 | 作用 | | --- | --- | | `.withLintColors` | 前景色设为 `.font`,背景设为 `.background` | | `.withLintFont` | 应用 `.lintFont(.body)` | | `.withLintPage` | `.withLintColors` + `.withLintFont` + `.buttonStyle(.lint)` | ## 组件清单 | 组件 | 用途 | 平台可用性 | | --- | --- | --- | | `LintColor` | 38 个语义色枚举;`defaults` 内置色表、`buttonColors`、`fonts(background:)` 辅助 | iOS 15+ | | `LintFont` / `Font.lint(_:with:)` | 13 档字号 + weight 规则;`Font.lint` 按档位取 `Font` | iOS 15+ | | `Color.lint(c:)` / `Color.LINT_COLORS` | 取色唯一入口(asset catalog → 内置表 → 主题覆盖);`LINT_COLORS` 是运行期主题覆盖表(`[LintColor: String]`) | iOS 15+ | | `View.lintFont(_:with:)` / `View.lintFont(size:family:)` | 按档位 / 任意字号设置字体 | **iOS 16+** | | `View.withLintColors` / `.withLintFont` / `.withLintPage` | 页面级主题修饰符 | **iOS 16+** | | `LintPlainButtonStyle` / `.buttonStyle(.lint)` | 与 `.plain` 同视觉、命中区覆盖完整布局矩形 | iOS 15+ | | `LintToggle` | 多段分段开关(`.fill` 等分 / `.fit` 自适应),含 `LintToggleSizing`、`LintToggle.Item` | iOS 15+ | | `LintOverlayModifier` / `View.lint(overlay:…)` | 抽屉浮层实现体与入口;含 `LintOverlayPosition`(leading/trailing/top/bottom)与 `LintOverlaySizing` | iOS 15+ | | `LintSwipeButton` | 行滑动露出操作按钮;`LintSwipeGesturePriority`(`.highPriority` / `.simultaneous` / `.directionGated`)、`LintSwipeDirection` | iOS 15+(`.directionGated` 仅 iOS 生效) | | `ButtonDefine` | 滑动按钮定义:`common` / `quick` / `custom` / `simple` / `icon` / `icon2` 六个静态工厂 | iOS 15+ | | `LintLineWrapper` | 按容器宽度自动换行的流式布局,`Direction.ltr` / `.rtl` | iOS 15+ | | `LintButton` | 带防连点 / 延迟 / 回调接管的按钮(内部使用 `.buttonStyle(.lint)`) | iOS 15+ | | `LintCenter` / `LintSquare` | 在容器内居中(可拿到容器宽高);把内容裁成正方形(取宽高中较小者) | iOS 15+ | | `LintTimer` | 定时把当前 `Date` 推给内容闭包 | iOS 15+ | | `LintLeftOrRight` | 左右两套内容的淡入淡出 + 横向缩放切换 | iOS 15+ | | `LintMask` | 可点击的半透明遮罩层 | iOS 15+ | | `LintProgressCircle` | 环形进度圈(注意 `percent` 语义,见「已知限制」) | iOS 15+ | | `LintTimeCircle` | 仿机械表盘的时间组件 | **iOS 16+** | | `LintFavIcon` | 抓取网页 favicon 并转 base64 展示 | iOS 15+ | | `LintShareImage` | `UIActivityViewController` 的 `UIViewControllerRepresentable` 包装 | iOS 15+ | | `LintShareSheet` | 内容快照 + 分享面板 | **iOS 16+** | | `LintFlopView` / `LintFlop` / `LintFlopCard` | 3D 翻面切换;前者托管 `Binding`,后两者接收布尔值 | iOS 15+ | | `LintGestureButton` | 可拖拽按钮:`direct(_:)` 限定方向,`onMove` / `onMoveEnd` 回调 | iOS 15+ | | `LintHorizontalWheel` | 横向滚轮选择器(左右拖动滚轮) | iOS 15+(iOS 15 上不可交互) | | `WeightedStack` | 按权重切分主轴的 `Layout`;配 `.lintWeight(_:)` / `.lintFixed(_:)` | **iOS 16+** | | `WeightedGrid` | 按「每段格数」分配空间的网格容器 | **iOS 16+** | | `CircleOffsetEffect` / `DynamicRoundedCorners` | 沿圆周偏移的几何效果(`.offset(thetha:radius:)`);指定角圆角的 `Shape`(基于 `UIRectCorner`) | iOS 15+ | | `LintSheet` | 协议:`associatedtype V: View` + `@ViewBuilder var sheet: V` | iOS 15+ | | `LintEdgeBorder` | 只描指定边的 `Shape`;配合 `.border(width:edges:color:)` 使用 | iOS 15+ | | `LazyLoad` / `LazyLoadWith` / `LazyLoadVElse` / `LazyLoadView` | 延迟渲染、延迟取数、占位视图与完整加载视图(`Mode.fixed` / `.flex` / `.vif`,可按 `refreshInterval` 定时刷新) | iOS 15+ | | `View.lazyloading()` | 一行加延迟加载 / 占位视图 | iOS 15+ | ## 常用 View 扩展速查 | 分类 | 扩展 | | --- | --- | | 条件渲染 | `lint(bool:view:)`、`lint(vif:)`、`lint(velse:)`、`lint(notNil:view:)`、`lint(with:view:)`、`lint(without:)`、`whether(_:transform:)`、`whether(_:opacity:)`、`opacityIf(_:opacity:)`、`ifNotNil(_:transform:)`、`with(_:transform:)`、`tap(_:)` | | overlay / background | `lint(bool:overlay:)`、`lint(bool:overlay:velse:)`、`lint(with:overlay:)`、`lint(bool:background:)`、`lint(with:background:)` | | 平台分支 | `lintIOS`、`lintMacOS`、`lintTvOS`、`lintWatchOS`;`lint(iOS:velse:)`、`lint(macOS:velse:)` 等 | | UserDefaults | `lint(userKey:vif:velse:)`、`lint(userKey:vif:)`、`lint(userKey:velse:)` | | 布局 | `lint(horizontal:)`、`lint(vertical:)`、`lint(center:)`、`lint(scroll axis:showsIndicators:)` | | 尺寸 | `lintSize(_:)`、`readSize(_:)`、`snapshot()`(iOS) | | 边框与圆角 | `border(width:edges:color:)`、`border(width:edge:color:)`、`borderRadius(radius:color:width:)`、`lint(border:width:radius:)`、`roundedPartialBorder(progress:color:placeholder:lineWidth:radius:)` | | 生命周期 | `onAppear(after:perform:)`(同步 / async 两个重载)、`onDisappear(after:perform:)`、`loop(delay:transform:)` | | 定时与变更 | `lint(refresh interval:)`、`lint(changeOf:perform:)` | ## 使用示例 ### 1. 主题取色与整体换肤 ```swift import SwiftUI import UILint struct ThemeDemo: View { var body: some View { VStack(spacing: 12) { Text("主色").foregroundColor(Color.lint(c: .primary)) Text("正文色").foregroundColor(Color.lint(c: .font)) Text("危险色").foregroundColor(Color.lint(c: .danger)) } .font(.lint(.body)) .padding() .background(Color.lint(c: .background)) // 启动时一次性写入:Color.LINT_COLORS = [.primary: "#0A84FF"] } } ``` 说明:只有 `Color.lint(c:)` 会走「asset catalog → 内置表 → 主题覆盖」的完整链路,直接用 `Color(.primary)` 不会。 ### 2. `LintButton` 与 `.buttonStyle(.lint)` ```swift struct ButtonDemo: View { @State private var count = 0 var body: some View { VStack(spacing: 12) { // label 只接受单个 View;.frame 必须写在 label 内部 LintButton(delay: 0.3, action: { count += 1 }) { Text("\(count)") .frame(width: 120, height: 44) .background(Color.lint(c: .primary)) .foregroundColor(Color.lint(c: .primary_font)) .cornerRadius(8) } Button { count = 0 } label: { Text("清零") .padding(8) .background(Color.lint(c: .block)) .foregroundColor(Color.lint(c: .font)) .cornerRadius(6) } .buttonStyle(.lint) } } } ``` 说明:`delay` 是点击后的冷却秒数,冷却期间按钮被禁用;`LintButton` 的 `label` **没有** `@ViewBuilder`,只能返回单个 View。 ### 3. `LintToggle` 分段开关 ```swift struct ToggleDemo: View { @State private var kind = 0 var body: some View { VStack(spacing: 16) { // .fill(默认):每段等分可用宽度 LintToggle(selection: $kind, items: [ .init(0, icon: "arrow.down.circle", title: "收入"), .init(1, icon: "arrow.up.circle", title: "支出"), .init(2, title: "转账") ]) // .fit:整条宽度跟着内容走 LintToggle(selection: $kind, items: [ .init(0, title: "日"), .init(1, title: "月") ], itemSpacing: 4, sizing: .fit) .frame(maxWidth: .infinity, alignment: .leading) } } } ``` 说明:选中底色宽度按「总宽扣掉 `itemSpacing` 后再均分」计算,所以长文案不会把某一段撑宽;`.fit` 模式下由 `matchedGeometryEffect` 平移。 ### 4. `LintOverlay` 抽屉 ```swift struct OverlayDemo: View { @State private var showPanel = false var body: some View { VStack { Button("打开抽屉") { showPanel = true } } .frame(maxWidth: .infinity, maxHeight: .infinity) .background(Color.lint(c: .background)) .lint(overlay: .trailing, isPresented: $showPanel, spacing: 24) { VStack { Text("面板内容").font(.lint(.headline)) Spacer() } .padding() .frame(maxWidth: .infinity, maxHeight: .infinity) } } } ``` 说明:抽屉从出场边滑入,**在出场边的对侧**留出 `spacing` 的固定间隙,其余三边贴满容器;点遮罩收起,`onDismiss` 在收起动画播完后回调。 ### 5. `LintSwipeButton` 滑动操作 ```swift struct SwipeDemo: View { var body: some View { LintSwipeButton(defines: [ // common:需要点两次(第一次进入确认态) .common("删除", .red, { next in print("删除") next() }), // quick:点一次即执行 .quick("暂停", .orange, { next in next() }), // 右滑组:direction 默认 .left .icon("pause.fill", .blue, { next in next() }, direction: .right) ]) { HStack { Text("左滑这一行") Spacer() } .padding() .background(Color.lint(c: .block)) } } } ``` 说明:`direction` 不填即 `.left`(向左滑露出);`common` / `icon2` / `custom` / `simple` 需要点两次,`quick` / `icon` 点一次即执行;只配一个需要二次确认的按钮时,组件会自动补一张灰色 `xmark` 占位(点一次即收起)。 ### 6. `WeightedStack` + `WeightedGrid` ```swift @available(iOS 16.0, *) struct WeightedDemo: View { var body: some View { VStack(spacing: 16) { // 4:6 分配主轴空间 WeightedStack(direction: .vertical, spacing: 12) { Text("上") .frame(maxWidth: .infinity, maxHeight: .infinity) .background(Color.lint(c: .primary)) .lintWeight(4) Text("下") .frame(maxWidth: .infinity, maxHeight: .infinity) .background(Color.lint(c: .block)) .lintWeight(6) } .frame(height: 200) // 两段网格按 4:6 分配,段内格子主轴尺寸严格相等 WeightedGrid(sections: [4, 6], spacing: 12, cellSpacing: 6) { section, index in Text("\(section)-\(index)") .font(.caption) .frame(maxWidth: .infinity, maxHeight: .infinity) .background(Color.lint(c: .secondary)) } .frame(height: 240) } } } ``` 说明:这两个类型是 iOS 16+ API,调用处需要 `@available(iOS 16.0, *)` 或 `if #available` 包裹。`.lintWeight(_:)` 只对**直接子视图**生效,写在 `Group` / `ForEach` 外面无效。 ### 7. `LintLineWrapper` 自动换行 ```swift struct TagsDemo: View { private let tags = ["Swift", "SwiftUI", "iOS", "Lint"] var body: some View { // 必须放在有界宽度的容器里,否则没有换行依据 LintLineWrapper(items: tags, direction: .ltr, hs: 8, vs: 8) { tag in Text(tag) .font(.lint(.caption)) .padding(.horizontal, 8) .padding(.vertical, 4) .background(Color.lint(c: .block)) .foregroundColor(Color.lint(c: .font)) .cornerRadius(4) } .frame(width: 320) } } ``` 说明:`hs` / `vs` 只传一个时另一个取同值,两个都不传时默认 4。 ### 8. `LazyLoadView` 加载态 ```swift struct LazyDemo: View { var body: some View { LazyLoadView(mode: .fixed, refreshInterval: 2, loadData: { next in DispatchQueue.main.asyncAfter(deadline: .now() + .seconds(1)) { next(Date().description) } }) { value in Text(value ?? "尚未加载") .padding() .background(Color.lint(c: .block)) .foregroundColor(Color.lint(c: .font)) } } } ``` 说明:`mode: .fixed` 首次加载时显示 `ProgressView`,加载完变成刷新按钮并把内容铺在背景层;`loadData` 的入参是「回填数据的闭包」,调用它就代表数据就绪。 ## 构建与测试 ```bash # 编译(iOS 设备目标) xcodebuild build -scheme UILint -destination 'generic/platform=iOS' # 跑测试(iOS 模拟器) xcodebuild test -scheme UILint -destination 'platform=iOS Simulator,name=iPhone 16 Pro,OS=18.1' ``` 现有测试共 4 个文件、25 个用例,iOS 模拟器下全部通过: | 文件 | 用例 | 覆盖内容 | | --- | --- | --- | | `Tests/UILintTests/WeightedStackTests.swift` | 9 | `WeightedStack.mainLengths` 的数值断言:扣间距后的比例分配、权重 0、负数钳零、间距溢出、固定尺寸优先 | | `Tests/UILintTests/WeightedStackRenderTests.swift` | 4 | 用 `ImageRenderer` 出位图,按像素确认 4:6 分界线真的落在预期位置 | | `Tests/UILintTests/LintToggleRenderTests.swift` | 7 | 渲染断言:段宽严格等分、选中底色覆盖正确的那一段、`.fit` 不被父级宽度拉伸 | | `Tests/UILintTests/LintSwipeButtonTests.swift` | 5 | 按钮分组逻辑:单按钮二次确认自动补 `xmark` 占位、占位不参与 full-swipe、两个以上不补位 | **尚无单测覆盖**的组件:除 `WeightedStack` / `WeightedGrid` / `LintToggle` / `LintSwipeButton`(仅覆盖构造逻辑)外的绝大多数——`LintColor`、`LintFont`、`LintButton`、`LintOverlay`、`LintSwipeButton` 的手势部分、`LintHorizontalWheel`、`LintLineWrapper`、`LazyLoad*`、`LintProgressCircle`、`LintTimeCircle`、`LintFavIcon`、`LintShareSheet`、`LintGestureButton`、`LintFlop*` 等。手势与视觉类组件很难用单测稳定驱动,目前依赖人工验证。 ## 已知限制与注意事项 1. **仅 iOS 可用。** `Package.swift` 声明了 `.macOS(.v12)`,但 `Shape/DynamicRoundedCorners.swift:13-21`(`UIRectCorner` / `UIBezierPath`)、`Component/LintColor.swift:133-151`(`UIColor` / `UIImage`)、`Component/LintOverlay.swift:68`(`UIRectCorner`)、`Component/LintShareSheet.swift:10-16`(`UIActivityViewController`)、`Component/LintFavIcon.swift:178-215`(`UIImage` / `UIGraphicsImageRenderer`)、`Extension/Color.swift:70`(`UIColor`)都直接使用 UIKit 且没有 `#if canImport(UIKit)` 守卫;`Extension/View.swift:607` 的 `if #available(iOS 17, *)` 也只判了 iOS,macOS 12 上会走到需要 macOS 14 的 `onChange(of:perform:)`。**macOS 上 `swift build` 实测编译失败**。 2. **iOS 15 / iOS 16 分界。** 见「环境要求」的 iOS 16+ 清单;`WeightedStack` / `WeightedGrid` / `lintFont` / `withLint*` / `LintTimeCircle` / `LintShareSheet` 在 iOS 15 上不可用。 3. **`LintProgressCircle` 的 `percent` 是「已消耗比例」**,命名与直觉相反:`Component/LintProgressCircle.swift:39` 用的是 `.trim(from: percent, to: 1)`,所以 `percent: 0.1` 画出的是 **90%** 的弧。 4. **`LintButton` 的 `label` 没有 `@ViewBuilder`**(`Component/LintButton.swift:16`、`:36`),只能返回单个 View;传多个视图会编译失败(`type '()' cannot conform to 'View'`)。 5. **`LintLineWrapper` 必须放在有界宽度的容器内**。它靠容器宽度判断换行,宽度无界时不会换行;其高度也是先量后撑,首帧会有一次跳动。 6. **`LintSwipeButton` 的几个坑**(`Component/LintSwipeButton.swift`):`direction` 默认 `.left`(向左滑露出按钮),传 `.right` 才是向右滑露出;`common` / `icon2` / `custom` / `simple` 需要点两次(先进入确认态),`quick` / `icon` 点一次即执行;只配一个需要二次确认的按钮时会自动补一张灰色 `xmark` 占位,点一次即收起(`:296-317`);`onTap`(点击整行)**只在 `gesturePriority: .directionGated` 时生效**,其余模式该回调不会被调用;`.directionGated` 仅 iOS 生效(非 iOS 回退到 `.highPriority`)。可滚动列表页建议显式传 `gesturePriority: .directionGated`,否则默认的 `.highPriority` 会让行上的纵向滚动失效。 7. **`LintHorizontalWheel` 的边界**(`Component/LintHorizontalWheel.swift`):`tags` 不能为空——`:181` 的 `% tags.count` 会除零崩溃;`selected` 必须落在 `0..