FZUIKit

一个包含 Swift AppKit 和 UIKit 扩展、类和实用程序的框架。

有关完整的文档，请查看位于 /Documentation 中的随附文档。打开该文件会启动 Xcode 的文档浏览器。

值得注意的扩展和类

NSContentConfiguration & NSContentView

将 UIContentConfiguration & UIContentView 移植到 AppKit。

NSHostingConfiguration

一种适用于托管 SwiftUI 视图层次结构的内容配置。

let configuration = NSHostingConfiguration() {
    Label("Your account", systemImage: "folder.circle")
}

collectionViewItem.contentConfiguration = configuration

NSBackgroundConfiguration

一种适用于背景的内容配置。

var configuration = NSBackgroundConfiguration()

configuration.backgroundColor = .controlAccentColor
configuration.cornerRadius = 6.0
configuration.shadow = .black
configuration.imageProperties.tintColor = .purple

let backgroundView = NSBackgroundView(configuration: configuration)

NSContentUnavailableConfiguration

一种用于内容不可用视图的内容配置。它是对视图的可组合描述，指示您的应用程序无法显示内容。使用内容不可用配置，您可以获得适用于各种不同空状态的系统默认样式。

let configuration = NSContentUnavailableConfiguration.loading() // A loading view that is displaying a spinning indicator.

configuration.text = "Loading…"
configuration.secondaryText = "The database is getting loaded."

let loadingView = NSContentUnavailableView(configuration: configuration)

NSView 扩展

backgroundColor: 视图的背景颜色，可在浅色/深色模式更改时自动调整，并且可以通过 animator() 进行动画处理。

view.backgroundColor = .systemRed

mask: 使用另一个视图遮盖视图，该视图的 alpha 通道用于遮罩。

view.mask = roundedView

可以通过视图的 animator() 进行动画处理的所有属性
- cornerRadius: CGFloat
- cornerCurve: CALayerCornerCurve
- roundedCorners: CACornerMask
- borderWidth: CGFloat
- borderColor: NSColor?
- center: CGPoint
- transform: CGAffineTransform
- transform3D: CATransform3D
- anchorPoint: CGPoint
- NSTextField: fontSize: CGFloat
menuProvider: 提供一个右键单击菜单。

tableView.menuProvider = { mouseLocation in
    let menu = NSMenu()
    menu.addItem(NSMenuItem(title: "\(selectedRowIndexes.count) rows selected"))
    return mneu
}

WindowHandlers:

// Some examples:
view.windowHandlers.window = { newWindow in
    // handle newWindow
}
view.windowHandlers.isKey = { isKey in
    // handle window isKey
}

MouseHandlers:

// Some examples:
view.mouseHandlers.down = { mouseDown in
    // handle mouse click
}
view.mouseHandlers.moved = { mouseMoved in
    // handle mouse move
}

ViewHandlers:

// Some examples:
view.viewHandlers.superview = { newSuperview in
    // handle superview change
}
view.viewHandlers.frame = { frame in
    // handle frame change
}
view.viewHandlers.effectiveAppearance { appearance in
    // handle appearance change
}

用于将文件拖放到视图的 DropHandlers

view.dropHandlers.canDrop = { items, mouseLocation in
    if items.images?.isEmpty == false || items.fileURLs?.isEmpty == false {
        return true
    } else {
        return false
    }
}
     
view.dropHandlers.didDrop = { items, mouseLocation in
    if let images = items.images {
        // handle dropped images
    }
    if let fileURLs = items.fileURLs {
        // handle dropped file urls
    }
}

动画视图属性的便捷方法

view.animate(duration: 0.5) {
    $0.cornerRadius = 4.0
    $0.borderWidth = 2.0
    $0.borderColor = .controlAccentColor
}

NSImage prepareForDisplay & prepareThumbnail

一个 UIImage 端口，用于生成缩略图以及准备和解码图像，从而提供更好的显示性能。它提供同步和异步（通过 asyc/await 或 completionHandler）实现。

// prepared decoded image for better performance
let preparedImage = await image.preparingForDisplay() 

// thumbnail image
let maxThumbnailSize = CGSize(width: 512, height: 512)
image.prepareThumbnail(of: maxThumbnailSize) { thumbnailImage in
    // thumbnailImage…
}

内容配置

配置视图、窗口等的多个方面。例如

VisualEffect: 将视觉效果添加到背景

window.visualEffect = .darkAqua()
view.visualEffect = .vibrantLight(material: .sidebar)

Shadow/InnerShadow

let shadow = ShadowConfiguration(color: .controlAccentColor, opacity: 0.5, radius: 3.0)
view.outerShadow = shadow

// inner shadow
view.innerShadow = shadow

Border

let border = BorderConfiguration(color: .black, width: 1.0)
view.border = border

let dashedBorder: BorderConfiguration = .dashed(color: .red)
view.border = dashedBorder

SymbolConfiguration: UIImage/NSImage.SymbolConfiguration 的简化版本。

let symbolConfiguration: ImageSymbolConfiguration = .hierarchical(color: .red)
symbolConfiguration.font = .body
symbolConfiguration.imageScaling = .large
imageView.configurate(using: symbolConfiguration)

Text

var textConfiguration = TextConfiguration()
textConfiguration.font = .body
textConfiguration.color = .systemRed
textConfiguration.numberOfLines = 1
textConfiguration.adjustsFontSizeToFitWidth = true
textField.configurate(using: textConfiguration)

NSSegmentedControl 段

配置 NSSegmentedControl 的段

let segmentedControl = NSSegmentedControl() {
    NSSegment("Segment 1").isSelected(true)
    NSSegment("Segment 2"), 
    NSSegment(NSImage(named: "myImage")!)
    NSSegment(symbolName: "photo")
}

NSTextField

adjustsFontSizeToFitWidth 和 minimumScaleFactor (UILabel 的端口)

textField.adjustsFontSizeToFitWidth = true
textField.minimumScaleFactor = 0.7

minimumNumberOfCharacters、maximumNumberOfCharacters 和 allowedCharacters

textField.maximumNumberOfCharacters = 20
textField.allowedCharacters = [.lowercaseLetters, .digits, .emojis]

actionOnEnterKeyDown、actionOnEscapeKeyDown & endEditingOnOutsideMouseDown

// Ends editing on enter/return.
textField.actionOnEnterKeyDown = .endEditing
// Cancels editing on escape and resets the text to the previous state.
textField.actionOnEscapeKeyDown = .endEditingAndReset
// Ends editing when the user clicks outside the text field.
textField.endEditingOnOutsideMouseDown = true

automaticallyResizesToFit: 自动调整文本字段大小以适应其文本。
EditingHandlers:

textField.editingHandlers.didBegin {
    // Editing of the text did begin
}
textField.editingHandlers.didEdit {
    // Text did change
}
textField.editingHandlers.shouldEdit { 
    newText in 
    return true
}

NSToolbar

配置 NSToolbar 的项目。

let toolbar = Toolbar("ToolbarIdentifier") {
        Button("OpenItem", title: "Open…")
            .onAction() { /// Button pressed }
        FlexibleSpace()
        Segmented("SegmentedItem") {
            Segment("Segment 1", isSelected: true)
            Segment("Segment 2"),
        }.onAction() { /// Segmented pressed }
        Search("SearchItem")
            .onSearch() { searchField, stringValue, state in /// Searching }
}
toolbar.attachedWindow = window

NSMenu

配置菜单的项目。

let menu = NSMenu() {
    NSMenuItem("Open…")
        .onSelect() { // Open item Pressed }
    NSMenuItem("Delete")
        .onSelect() { // Delete item Pressed }
    NSMenuItem.seperator()
    NSMenuItem() {
        HStack {
            Circle().forgroundColor(.red)
            Circle().forgroundColor(.blue)
        }
    }
}

DateTextFieldLabel

一个带有日期属性的文本字段，该属性会自动根据日期更新其字符串。它可以显示绝对或相对日期。

let textField = DateTextField(date: Date())
textField.dateDisplayMode = .relative // It displays e.g. "2 mins ago"
textField.dateDisplayMode = .absolute // It displays e.g. "04.04.2023 10:20pm"

SpacerView

一个用于 NSStackView/UIStackView 的间隔，它沿着其包含堆栈视图的主轴扩展。它就像 SwiftUI spacer 一样工作。

ResizingTextField

一个自动调整大小以适应其文本的 NSTextField。

let textField = ResizingTextField(string: "Some string")
textField.automaticallyResizesToFit = true
textField.maxWidth = 200 // The max width of the text field when resizing.

ImageView

一个高级 NSImageView，支持 scaleToFill、多个图像、gif 动画速度等。

let imageView = ImageView()
imageView.imageScaling = .resizeAspectFill
imageView.image = myGifImage
imageView.animationDuration = 3.0 /// gif animation speed
imageView.animationPlaybackOption = .mouseHover /// animation plays on mouse hover
imageView.animationPlaybackOption = .mouseDown /// toggle playback via mouse click

AVPlayer 扩展

isLooping: 轻松循环播放的项目。

player.isLooping = true

state: 播放器的当前播放状态：.isPlaying, .isPaused, .isStopped, .error(Error)
seek(toPercentage: Double)

NSMagnificationGestureRecognizer 扩展

velocity: 每秒缩放因子的放大速度。

DisplayLinkeTimer

一个更精确的 Timer，其时间间隔可以在不使计时器失效的情况下进行更改。

let timer = DisplayLinkTimer.scheduledTimer(timeInterval: .seconds(3.0), action: {
    // some action
})
timer.timeInterval = .minutes(1)

NSAlert `supressionKey`

向 NSAlert 提供一个禁止键，以允许用户通过显示禁止复选框来选择不再显示该警报。

如果用户选择退出，则不会再次显示该警报，而是返回响应 suppress。

let alert = NSAlert.informational("My Alert")
alert.supressionKey = "someKey"

let response = alert.runModal()
if response == .suppress {
    // The alert was suppressed
}