ix4n33's Blog

制作一个照片预览视图

Tue, 13 Apr 2021 00:00:00 +0000

照片预览视图是挺常见的视图，在即时通讯、媒体查看器、文档编辑器等带有照片预览功能的程序中都能看到照片预览视图的身影。本文将讲解一些制作照片预览视图时会遇到的核心技术。

了解滑动视图的原理

在开始之前，我想简略的说说滑动视图的原理，从而让我们有一个共同的出发点。

首先，在滑动视图里，真正实现滑动跟缩放功能的是它的一个 NSClipView 子视图，我们可以把它叫做裁剪视图。而被滑动或缩放的视图，是裁剪视图下的 NSView 子视图，我们姑且把它叫做文件视图。

Scroll view
+ Clip view             <- View that actually provide scroll services.
  + Documnet view       <- View that scroll view provide scrolling services to.

想要搞懂裁剪视图怎么实现滑动的，我们只需要搞懂视图的 框架 (frame) 与 界限 (bounds) 这两个概念。

框架定义的是视图在其父视图坐标系统内的一个矩形的位置与大小，而界限是视图在它自己的坐标系统中的位置与大小。改变视图的框架带来的是它在父视图坐标系中的位置和大小的变化，而改变视图的界限带来的是该视图绘制的自身坐标系的区域变化。

听起来有抽象，我们可以用一个现实的比喻来更好理解这一理念。

我们将视图视作摄像机跟监视器的组合，那么，摄像机捕获到的画面就是视图的界限。摄像机的平移、拉近拉远，带来最直观的变化就是捕捉到的画面位置以及画面远近的变化。而连接到摄像机的外部监视器 (框架) 是不会随着摄像机的移动而移动的，改变的只是它显示的内容。监视器的位置只取决于现实中你怎么摆放它，跟摄像机的移动毫无关系。

Your browser does not support the video tag.

如果你需要用一种比较官方的语言来理解它们，请查阅视图编程指南以及 NSView 中 frame 与 bounds 的开发文档。

了解视图的框架与界限以后，你其实就理解裁剪视图中的滑动跟缩放是怎么个回事了：通过监听来自鼠标滑轮、触摸板等设备的事件来修改裁剪视图的界限，从而实现滑动与缩放。再用一个视图作为容器将裁剪视图、文件视图以及我们没有提及到的滚动条、标尺封装成我们所熟知的 NSScrollView 滑动视图。

如果你想对滑动视图有一个系统的了解，可以查阅 Cocoa 滑动视图编程指南。此外，更多关于手势滑动与缩放的知识，可以观看优化 OS X 绘制与滑动。

有了对滑动视图的大致理解，我们可以开始制作我们的照片预览视图了。在下文，我们将使用一个纯色视图充当文件视图为例子来进行讲解：

class MyDocumentView: NSView {
    override var wantsUpdateLayer: Bool { true }

    override func updateLayer() {
        layer?.backgroundColor = NSColor.blue.cgColor
    }
}

在实际上，你可以使用任何你想要的视图。唯一的要求是该视图应该有一个明确的尺寸，不管是视图自身提供的，还是你后期赋予它的。

文章会略过项目的创建、添加视图，设置工具栏等步骤，这些并不是文章的重点。

在裁剪视图里居中文件视图

在默认情况下，文件视图在裁剪视图内是紧靠左下角放置的（也就是视图原点）。在进行缩放时，裁剪视图的 constrainBoundsRect(_:) 方法会被不断调用，用来将文件视图限制在裁剪视图的视野中：

Your browser does not support the video tag.

知道了这个以后，居中的方法也很明朗了：我们可以重写裁剪视图的 constrainBoundsRect(_:) 方法，在它原方法的基础上，将结果进行位移，使得文件视图在裁剪视图中居中显示。

我们还可以做更多，当文件视图大于裁剪视图的时候，如果滑动到文件视图边缘，我们也想避免文件视图与裁剪视图的边界之间留空（也就是避免过度滑动）。

下面是我们重写的 constrainBoundsRect(_:) 方法：

override func constrainBoundsRect(_ proposedBounds: NSRect) -> NSRect {
    var clipBounds = super.constrainBoundsRect(proposedBounds)
            
    // ➊ Process only when document view exist, and has a valid size.
    guard let documentView = documentView, documentView.frame.width > 0 && documentView.frame.height > 0 else {
        return clipBounds
    }
    
    // ➋ Calculate the scaled content insets.
    let scaleFactor = bounds.width > 0 ? (clipBounds.width / bounds.width) : 1
    var insets = contentInsets.forEach { $0 * scaleFactor }
    
    // ➌ Swap insets on y asix, if the view geometry is flipped.
    if isFlipped { (insets.top, insets.bottom) = (insets.bottom, insets.top) }

    // ➍ Calculate the document view's frame, outseted by the scaled content insets.
    let x = documentView.frame.minX - insets.left
    let y = documentView.frame.minY - insets.bottom
    let w = documentView.frame.width + insets.left + insets.right
    let h = documentView.frame.height + insets.top + insets.bottom
    let documentFrame = NSMakeRect(x, y, w, h)
    
    // ➎ If the clip bounds width is larger that the document, center the bounds around the document.
    // Otherwise, make sure that the clip rect stays within the document frame.
    if clipBounds.width > documentFrame.width {
        clipBounds.origin.x = documentFrame.minX - (clipBounds.width - documentFrame.width) / 2
    } else if clipBounds.width < documentFrame.width {
        clipBounds.origin.x = max(documentFrame.minX, min(clipBounds.origin.x, documentFrame.maxX - clipBounds.width))
    }
    
    if clipBounds.height > documentFrame.height {
        clipBounds.origin.y = documentFrame.minY - (clipBounds.height - documentFrame.height) / 2
    } else if clipBounds.height < documentFrame.height {
        clipBounds.origin.y = max(documentFrame.minY, min(clipBounds.origin.y, documentFrame.maxY - clipBounds.height))
    }

    // ➏ Return the backing store pixel-aligned rectangle in local view coordinates.
    return backingAlignedRect(clipBounds, options: .alignAllEdgesNearest)
}

➊ 我们只在文件视图存在，且拥有有效尺寸时才继续。
➋ 计算缩放后的内填充。这里的 forEach 表示将 contentInsets 中的 top, left, bottom, right 分别进行某种计算。在上面的例子中是共同乘以 scaleFactor。
➌ 根据 isFlipped 属性翻转 Y 轴上的内填充量。
➍ 计算应用内填充后的文件视图的位置与尺寸。
➎ 根据需要修改裁剪视图的界限。在文件视图的框架小于裁剪视图的界限时，添加位移来使文件视图位于裁剪视图界限的中心。而在文件视图的框架大于裁剪视图的界限时，将裁剪视图的界限限制在文件视图的框架内部。纵横两个方向分开执行。
➏ 最后返回一个像素对齐的矩形。

这样，我们的文件视图就能够居中于裁剪视图了：

Your browser does not support the video tag.

修复初滑动的跳动问题

在我们重写了裁剪视图的 constrainBoundsRect(_:) 方法后，我们的滑动会出现一点问题。

在向上或向左滑动的时候，视图的位置会在一开始出现明显的跳动，而非平滑过度。这看似好像是滑动事件的前几个事件没有调用裁剪视图的 scroll(to:) 方法：

Your browser does not support the video tag.

有意思的是，这个问题可以通过一种近乎奇妙的方法来修复：重写裁剪视图的 scrollWheel(with:) 方法，并只调用它的 super 方法。

// A weird fix to the scrolling glitch.
// These three lines make no sence, but I have no idea why this work.
override func scrollWhell(with event: NSEvent) {
    super.scrollWheel(with: event)
}

你可能跟我想的一样，重写一个方法却只调用它的 super 方法跟不重写没有什么区别。但这看似无用的三行代码却能让滑动变得顺滑起来：

Your browser does not support the video tag.

希望这个问题能在未来的 macOS 版本中得到修复。

放大、缩小与自适应缩放

现在我们可以实现具体的放大、缩小功能了。因为滑动视图本身已经做好了手势缩放，所以我们这里特指的是通过按钮触发的放大、缩小。

在滑动视图中，比较重要的与缩放相关的属性有下面这些：

allowsMagnification: 是否启用缩放功能。
magnification: 当前的缩放比。
minMagnification: 最小缩放比。
maxMagnification: 最大缩放比。

此外也提供了像 setMagnification(_:centeredAt:) 的方法来让我们设定缩放比。该方法同时也可以通过动画代理来动态改动。我们可以编写一个方便的方法：

private func setMagnification(_ magnification: CGFloat, animated: Bool) {
    // Center point of clip view. Since this function is only called by button, menu item 
    // or keyboard action, we don't need to consider the mouse location.
    let center = NSPoint(x: scrollView.contentView.frame.minX, y: scrollView.contentView.frame.minY)

    if animated {
        scrollView.animator().setmagnification(magnification, centeredAt: center)
    } else {
        scrollView.setmagnification(magnification, centeredAt: center)
    }
}

在往下的代码中，我们会直接调用这个方法来方便的进行缩放。

我们事先设定一组缩放比，每次触发放大、缩小时，就缩放到这些预设的缩放比去。下面列举的是与自带 Preview 对应的一组缩放比：

let zoomScales: [CGFloat] = [0.1, 0.15, 0.2, 0.3, 0.4, 0.5, 0.75, 1, 1.5, 2, 3, 4, 6, 8, 10, 15, 20, 30]

除了这些缩放比以外，还有一个需要我们动态计算的缩放比，就是 自适应缩放比。它指的是在当前环境下，刚好能够使裁剪视图显示整个文件视图而不被裁剪的缩放比。

Preview 中也会将该缩放比添加到预设的缩放比集合里。这样，在通过按钮缩放照片时，它可以将照片在不被遮挡的前提下尽可能的填满整个窗口。

此外，在 Preview 中，如果当前缩放比是自适应缩放比时，那么在改变 Preview 窗口大小的时候，该缩放比也会动态变化，从而使得照片一直填满窗口。

我们用一个 fitScale 变量来存储这个缩放比。同时编写一个 currentFitScale() 方法来计算最适合当前环境的自适应缩放比：

/// The scale ratio that can fit the document view.
private(set) var fitScale: CGFloat = 1

/// Calculate the magnification that fit the document view into the clip view.
func currentFitScale() -> CGFloat {
    guard let documentView = scrollView.documentView else { return 1 }
    
    // Get the width & height ratio of document view and clip view.
    let documentRatio = documentView.bounds.width / documentView.bounds.height
    let     clipRatio = clipView.bounds.width / clipView.bounds.height
    
    // Compare to see which asix is critical to fit the document view.
    // Return the scale of that asix.
    if documentRatio < clipRatio {
        return clipView.frame.height / documentView.bounds.height
    } else {
        return clipView.frame.width / documentView.bounds.width
    }
}

这里将 fitScale 的存放与计算分开，而不直接使用计算属性 (computed property) 是因为我们在后面会遇到需要用到先前的最佳缩放比的情况。

我们的 zoomIn 放大方法要做的事情很简单，找到比当前缩放比大一档的缩放比，然后调用 setMagnification(_:animated:) 即可：

func zoomIn() {
    // Update fit scale.
    fitScale = currentFitScale()
    
    // Combine default zoom scales and the fit scale.
    let availableZoomScales = zoomScales + [fitScale]

    // Find the smallest zoom scale in the array that grather than the current zoom scale.
    // And apply that scale with animation.
    if let zoomScale = availableZoomScales.filter({ $0 > scrollView.magnification }).min() {
        setMagnification(zoomScale, animated: true)
    }
}

类似的，我们可以编写 zoomOut() 方法。只需稍微改动在数组中寻找下一个缩放比的代码即可：

let zoomScale = availableZoomScales.filter({ $0 < scrollView.magnification }).max()

Your browser does not support the video tag.

而缩放到原比例，只需要在调用 setMagnification(_:animated:) 时传入 1 即可。

下面我们来实现缩放至自适应的功能。有了上面的基础，我们只需要在调用 setMagnification(_:animated) 时传入我们的 fitScale 即可：

func zoomToFit() {
    fitScale = currentFitScale()
    setMagnification(fitScale, animated: true)
}

Your browser does not support the video tag.

不过怎么去响应窗口的大小的变化而改变缩放比才是我们这里的重点。首先我们需要判断当前的缩放比是不是自适应缩放比：

/// Is current magnification match the fit scale.
var isDocumentFit: Bool {
    scrollView.magnification == fitScale
}

然后我们需要在窗口尺寸发生变化的时候得到通知。这个问题，以开发者的思维去思考的时候的话，应该是去监听视图层级上最近的发生框架变化的视图。在我们这个例子中，是裁剪视图的框架变化：

// Posts notifications when clip view frame rectangle changes.
scrollView.contentView.postsFrameChangedNotifications = true

// Observe the changes.
NotificationCenter.default.addObserver(self, selector: #selector(clipViewFrameDidChange(_:)), 
                                                 name: NSView.frameDidChangeNotification,
                                               object: scrollView.contentView)

// When clip view's frame changes
@objc func clipViewFrameDidChange(_ notification: Notification) {
    let newFitScale = currentFitScale()
    
    if isDocumentFit { // more like "wasDocumentFit", because we haven't update `fitScale` yet.
        // set magnification without animation, because we are in live resize.
        setMagnification(newFitScale, animated: false)
    }
    
    fitScale = newFitScale
}

Your browser does not support the video tag.

好了，我们这就完成了一个基础预览视图的制作。在更复杂的需求下，你可能会需要用页面控制器来添加在非缩放状态下的左右滑动切换照片的功能，或者是缩放时在角落显示一个小地图。再有了上面的基础，这些需求应该难不倒你。

还有一点是我想要指出的，你可能会发现在 Preview 里，通过手势缩放时，缩放到最佳缩放比时会有一点吸附，我在这里并没有讲到怎么实现。不是因为我不知道这个小功能，而是在我的知识范围内，实现这个需要重写 magnify(with:)，光是想想就头皮发麻。

又谈 NSVisualEffectView

Fri, 25 Sep 2020 00:00:00 +0000

似乎从 Catalina 开始，在最近几个版本的 macOS 中，使用一些系统控件的时候，系统会自动在视图层级中插入 NSVisualEffectView 来充当控件的背景，如 NSScrollView 这些容器视图。

你也许跟我一样，压根就没注意到有这一变动，直到在某些需求下需要修改背景颜色、实现类边栏的半透明效果时，才发现在视图层级中多出了一个不透明的 NSVisualEffectView。

被插入的 NSVisualEffectView 拥有不透明的材料

按照以前的方法，我们想都不用想就直接把 NSScrollView、NSClipView 以及顶层的 NStableView 或者 NSCollectionView 的背景颜色设置为透明色，或者设置 drawBackground 来隐藏掉背景的绘制。

当你满怀欣喜的编译运行，等着透明背景出现的时候，却发现背景还在：

然而，什么都没有发生

让事情更加懊恼的是，查文档也好，改属性也罢，你找不到任何公开的方法来修改或隐藏它。

变通方法

作为一个合格的 AppKit 开发者，我们自然而然的会想到重写。didAddSubview(_:) 也许是最佳的隐藏它的地方:

class ScrollView: NSScrollView {
    override func didAddSubview(_ subview: NSView) {
        super.didAddSubview(subview)

        if subview is NSVisualEffectView {
            subview.isHidden = true
        }
    }
}

但别在这里用 removeFromSuperView() 方法将其移除，你会发现他会重新被插入到视图层级中。

可算是透明了

但是，这么做的效果看起来总是差了什么，特别是你要在上面显示某些选中项的时候：

发现了吗？左边的选中高亮是纯色不透明的，而右边系统 Spotlight 的高亮却带有一丝通透。

如果我们要实现这种通透效果，我们需要自行重写高亮的绘制，禁用掉默认的绘制，然后通过插入一个 material 为 selection，并且 isEmphasized 为 true 的 NSVisualEffectView 来实现这种效果。

还记得 App Store 以及 Finder 侧边栏高亮选中项的效果吗？其实他们也是通过同样的 NSVisualEffectView 实现的，只不过，它们的 isEmphasized 属性被设置成了 false。

其实我们有个更好的方法

在大多数情况下，我们会实现这种半透明效果往往是在侧边栏上，或者这种可以使用 NSTableView 实现的列表型视图。这种时候，我们其实可以直接使用 NSTableView 自带的 source list 样式来实现上面说到的所有内容：

// for macOS 11 Big Sur
tableView.style = .sourceList

// for macOS 10.15 Catalina and older
tableView.selectionHighlightStyle = .sourceList

这么做的时候，我们甚至都不需要去隐藏掉上面说的被插入的 NSVisualEffectView，也不用自己去实现选中项的高亮通透效果，这些都是 source list 的默认效果。

可惜的是，如果你的设计带有头部或者尾部视图，又想用 NSTableView 来实现的话，你在数据源的处理上将会非常的痛苦。在这种情况下，也许用一开始的方法搭配 NSCollectionView 会更加容易。

搭配标签栏控制器使用分栏视图控制器

Sat, 27 Jun 2020 00:00:00 +0000

有一种不太常见的场景，类似 Telegram、微信这类内容比较多的程序，会使用 UITabBarController 和 UISplitViewController 来管理实现整体的视图结构。这里主分栏有两种实现思路，一种是用导航控制器嵌套标签栏控制器，另一种是用标签栏控制器嵌套多个导航控制器。

前者是比较常见也比较容易实现的，但随着你的程序功能的不断增加，需求的不断变更，你可能会发现，公用一个导航控制器并不是一个好的主意。

本文我们就来用一个例子，讲讲另一种使用分栏视图控制器的思路。

从 iOS 14 / iPadOS 14 起，苹果介绍了新的 UISplitViewController API，您应该查看新的设计规范来进行设计与实现。

概念

主分栏为使用标签栏控制器嵌套多个导航栈的分栏结构

我们这次的例子会以标签栏控制器管理的所有子控制器都为 UINavigationController 类对象的前提进行。

在我们的设计中，除了基本的分栏行为以外，我们认为，详情分栏应该总是显示导航控制器，且导航控制器的根视图总是某个占位用的视图控制器。也就是说，我们允许回退到无选中项的状态。这么做的好处是，在这个基础上，我们可以通过设置导航栏返回按钮的显隐，很容易地在允许或不允许这一行为之间进行切换。

此外，在切换主分栏标签页时，详情分栏的视图应该可以跟随切换。

我们下面会逐个来实现。

创建 `UISplitViewController` 子类

出于开发 macOS 的习惯，对于这种需要比较多代码进行定制的类，我一般都会使用创建子类进行封装的方法。当然，本文更多的是给大家参考，重写并不是强制的。

我们来创建一个 SplitViewController 子类：

class SplitViewController: UISplitViewController {
    init(primary: UITabBarController, placeholderProvider: @escaping () -> Placeholder) {
        self.makePlaceholder = placeholderProvider
        super.init(nibName: nil, bundle: nil)
        self.delegate = self
        self.viewcontrollers = [primary, makeSecondaryStack()]
    }

    private let makePlaceholder: () -> Placeholder

    private func makeSecondaryStack() -> UINavigationController {
        UINavigationController(rootViewController: makePlaceholder())
    }
}

在这里，我们提供了一个 init(primary:placeholderProvider:) 构造方法。primary 参数传入的是一个用在主分栏的视图控制器，我们将参数的类型固定为 UITabBarController，因为我们这个例子只针对主分栏为 UITabBarController 的情况。placeholderProvider 传入的是一个创建占位视图控制器的闭包，我们使用这个闭包来在必要的时候创建详情页的根占位视图控制器。

而 Placeholder 类是一个 UIViewController 子类，我们在后面会对它进行一些小定制。

extension SplitViewController {
    class Placeholder: UIViewController { }
}

在 makeSecondaryStack() 方法中，示例的代码直接将闭包的结果作为根视图来创建导航控制器。在实际的代码中，你应该稍加判断，避免将导航控制器推入导航控制器的情况发生而造成异常抛出。

变更默认显示详情视图控制器的行为

我们首先会遇到一个问题：在使用 showDetailViewController(_:sender:) 方法显示详情视图的时候，分栏情况下它会直接替换我们的导航栏，而单栏情况下却是直接用 page sheet 的形式显示出来。

我们先来讲讲 showDetailViewController(_:sender:) 方法具体都做了些什么。这个方法会自动选择一种最适合当前界面的方式来显示传入的视图控制器：

在紧凑环境下，如果主视图控制器是一个 UINavigationController 或其子类，它会将该视图控制器推入这个导航控制器，否则，就调用 present(_:animated:completion:) 来显示。而在分栏环境下，它会直接替换详情栏的顶级视图控制器。

很显然，我们的需求完美的绕过了这些情况。因此，我们需要修改它的默认行为。

在调用 showDetailViewController(_:sender:) 的时候，它会先调用分栏视图的代理方法 splitViewController(_:showDetail:sender:)，允许我们提供质自定义实现：

func splitViewController(_ splitViewController: UISplitViewController, showDetail vc: UIViewController, sender: Any?) -> Bool {
    if splitViewController.isCollapsed {
        guard
            let tabBarController = viewControllers.first as? UITabBarController,
            let navController = tabBarController.selectedViewController as? UINavigationController
        else { return false }
        
        navController.pushViewController(vc, animated: true)
    } else {
        guard
            let navController = viewControllers.last as? UINavigationController
        else { return false }
        
        let isPlaceholderTop = navController.topViewController is Placeholder
        
        if !isPlaceholderTop {
            navController.popToRootViewController(animated: false)
        }
        
        navController.pushViewController(vc, animated: isPlaceholderTop)
    }
    
    return true
}

在紧凑环境下，我们尝试找到主栏中标签栏控制器显示的当前导航栏控制器，并将视图控制器推入改导航栈。

而在分栏环境下，我们判断详情栏的导航栈当前显示的是不是占位用的控制器，如果是，我们直接推入这个栈，否则就将所有非占位的控制器推出，替换为新的控制器。

注意我们做了一个当前控制器是否为占位控制器的判断，并且根据结果将已有控制器弹出。更重要的是，我们在弹出时和弹出后的推入时将动画关闭。这在我们稍后发送 placeholderWillAppear 通知的时候可以避免不必要的触发，同时在视觉上也更加合理。

最后，返回 true 告知分栏视图无需再进行任何操作，否则我们返回 false，表示让分栏视图进行它的默认实现。

同步取消选中项

在分栏模式下，我们在详情分栏推出视图控制器的时候，主栏中的选中项没有跟随着取消选中：

一般来讲，我们会想监听 UINavigationController 的推出事件来及时更新选中项，但其实我们有一个更好的方法。仔细看的话，你会发现，我们需要反选选中项的时候，总是在详情栏回退到占位视图控制器的时候。我们其实可以在 Placeholder 的 viewWillAppear(_:) 方法中发出通知来提供一个事件点：

 extension SplitViewController.Placeholder {
    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        
        if let splitViewController = splitViewController as? SplitViewController {
            NotificationCenter.default.post(name: SplitViewController.placeholderWillAppearNotification,
                                          object: splitViewController,
                                        userInfo: ["placeholder": self])
        }
    }
}

extension SplitViewController {
    static let placeholderWillAppearNotification = NSNotification.Name("SplitViewControllerPlaceholderWillAppearNotificationName")
}

在发布通知的时候，我们传入的对象是 splitViewController 而不是 placeholder，这是因为当创建监听的时候，拿到 placeholder 对象比 splitViewController 对象要复杂不少，这样做可以方便我们未来的使用。

发送通知只是消息传递的其中一种方法，您可以选用您认为合适的来替换它。您也可以同时附加一些其他的信息，如当前分栏视图的主视图等信息，方便监听者在接收到事件后进行进一步的筛选。

这样，在我们需要取消选中项的控制器中，可以监听我们的 placeholderWillAppearNotification 事件来取消选中：

NotificationCenter.default.addObserver(self, selector: #selector(placeholderWillAppear(_:)), 
                                                 name: SplitViewController.placeholderWillAppearNotification, 
                                               object: splitViewController)

@objc func placeholderWillAppear(_ notification: Notification) {
    // when placeholder appears, deselect selection
    tableView.selectRow(at: nil, animated: true, scrollPosition: .none)
}

在分栏视图布局变化时重新分配控制器

接下来我们要来解决分栏视图最重要的功能。我们现在的分栏视图在宽度环境发生变化的时候，各个栈里的视图控制器并不会移动到它们应该处于的位置：

这里我们必须先讲讲分栏视图在变换布局的时候做了些什么事情：

在折叠的时候：

它调用 splitViewController(_:collapseSecondary:onto:) 代理方法
- 如果该方法返回 false，则分栏视图进一步调用 primaryViewController 的 collapseSecondaryViewController(_:for:) 方法
- 如果该方法返回 true，则跳过不做任何事情
分栏视图将 secondaryViewController 从子控制器中移除

在扩展的时候：

它调用 splitViewController(_:separateSecondaryFrom:) 代理方法
- 如果该方法返回 nil，则分栏视图进一步调用 primaryViewController 的 separateSecondaryViewController(for:) 方法
- 如果该方法返回有效的 UIViewController 对象，则分栏视图将该对象作为详情栏的根视图控制器显示

在默认情况下，splitViewController(_:collapseSecondary:onto:) 返回 false ，splitViewController(_:separateSecondaryFrom:) 返回 nil。也就是说，它总会调用其主视图控制器，也就是我们的 UITabBarController 对象的 collapseSecondaryViewController(_:for:) 以及 collapseSecondaryViewController(_:for:) 方法。

这两个方法是每个视图控制器都有的，他们大多数都是不做任何事情。只有 UINavigationController 会将详情页的视图控制器推入它的视图栈中，或者从中推出。

我们可以通过重写 UITabBarController 的 collapseSecondaryViewController(_:for:) 以及 separateSecondaryViewController(for:) 方法，在里边调用嵌套的 UINavigationController 对象的对应方法来得到预期的效果。

但是，为了完全的控制（也为了更加符合重写的习惯），我们可以直接实现 splitViewController(_:collapseSecondary:onto:) 与 splitViewController(_:separateSecondaryFrom:) 代理方法并提供我们自己的实现：

func splitViewController(_ splitViewController: UISplitViewController, collapseSecondary secondaryViewController: UIViewController, onto primaryViewController: UIViewController) -> Bool {
    // 1. find navigation controller on both primary and secondary
    guard
        let tabBarController = primaryViewController as? UITabBarController,
        let primary = tabBarController.selectedViewController as? UINavigationController,
        let secondary = secondaryViewController as? UINavigationController
    else { return false }
    
    // 2. pop view controller from secondary and push to primary
    secondary.popToRootViewController(animated: false)?.forEach {
        primary.pushViewController($0, animated: false)
    }
    
    return false
}

func splitViewController(_ splitViewController: UISplitViewController, separateSecondaryFrom primaryViewController: UIViewController) -> UIViewController? {
    // 1. find navigation controller on primary
    guard
        let tabBarController = primaryViewController as? UITabBarController,
        let primary = tabBarController.selectedViewController as? UINavigationController
    else { return nil }
    
    // 2. make a new navigation controller with placeholder
    let secondary = makeSecondaryStack()
    
    // 3. pop view controller from primary and push to secondary
    secondary?.viewControllers += primary.popToRootViewController(animated: false) ?? []

    return secondary
}

做的事情很简单，简单的说就是三个步骤：

得到各个分栏的导航控制器对象
转移导航栈中的视图控制器
按需返回结果

注意我们在 splitViewController(_:separateSecondaryForm:) 方法中将 primary 中的视图控制器弹出并推入 secondary 的时候，没有使用 pushViewController(_:animated:) 方法，而是直接对 viewControllers 数组进行操作。这是因为此时，secondary 还没有显示在屏幕上，使用前者会提前触发一些视图上的刷新，伴随一些恼人的报错出现。

这样，我们就得到如下图的效果：

解决选中项丢失的问题

在紧凑环境切换到分栏环境时，或者在分栏状态下来回切换标签页时，我们的 UITableViewController 或者 UICollectionViewController 会丢失选中项：

选中项丢失

这是因为，这两个类默认会在 viewWillAppear(_:) 被调用的时候清空选中项。我们平时在导航栏控制器中弹出视图控制器的时候，选中项会自动取消选中就是得益于此。为了在保留原始行为的前提下解决使用分栏时出现的问题，我们可以重写 UITableViewController 或者 UICollectionViewController 的 viewWillAppear(_:) 方法，在调用 super 前，根据当前分栏情况来更新该值：

override func viewWillAppear(_ animated: Bool) {
    clearsSelectionOnViewWillAppear = splitViewController?.isCollapsed ?? true
    super.viewWillAppear(animated)
}

这样，我们就可以在分栏环境下，禁用自动清空选中项了。

选中项得以保留

在切换便签页时切换详情栏内容

在分栏环境下切换便签页的时候，你会发现详情栏中的内容并没有跟随变化：

这里有个分歧，有的人认为不跟随是正确的，也有的人认为跟随才是正确的。我们这里讲一下跟随应该怎么实现，因为不跟随的话，你基本上什么都不需要做。

很明显，我们应该在标签页切换的前将当前详情栏的控制器保存起来，然后用新便签页的视图控制器替换详情栏中显示的控制器。问题就是，我们应该将这些控制器保存在哪？

我们可以在 SplitViewController 类中创建一个字典来存储这些对应控制器，但是，其实我们有一个更好的地方来存放它们，而且，这是我们已经有过的对象 – 主栏的导航控制器。我们提供两个方法，一个是将详情栏的控制器推入到主栏控制器中，另一个是反过来推入到详情栏中：

func collapse() {
    guard
        let tabBarController = viewControllers.first as? UITabBarController,
        let primary = tabBarController.selectedViewController as? UINavigationController,
        let secondary = viewControllers.last as? UINavigationController
    else { return }
    
    secondary.popToRootViewController(animated: false)?.forEach {
        primary.pushViewController($0, animated: false)
    }
}

func separate(completion: ((UIViewController?, UIViewController?) -> Void)? = nil) {
    guard
        let tabBarController = viewControllers.first as? UITabBarController,
        let primary = tabBarController.selectedViewController as? UINavigationController,
        let secondary = viewControllers.last as? UINavigationController
    else { return }
    
    let viewControllers = primary.popToRootViewController(animated: false) ?? []
    viewControllers.forEach {
        secondary.pushViewController($0, animated: false)
    }
    
    completion?(primary.topViewController, viewControllers.first)
}

注意我们在 separate 方法中添加了一个回调，传入的是主栏导航控制器的顶视图控制器和弹出栈的第一个视图控制器。我们可以在该闭包被调用的时候更新改顶层视图控制器的选中项。

在标签页切换的时候，我们在下面的代理方法中手动调用这两个方法即可：

tabBarController(_:shouldSelect:)
tabBarController(_:didSelect:)

得益于此，当我们将分栏视图置于紧凑环境下时，主栏其他标签页的控制器都能够得以保留，而无需进一步的操作。

AppKit 中的窗口释放策略

Tue, 11 Feb 2020 00:00:00 +0000

在 Cocoa 开发中，窗口对象的释放策略也许并不如您预先中的一样。在本文中，我们可以稍微提一提这些不同情况下的释放策略。

通过 Storyboard Segue 打开的窗口

这类窗口指的是在 Storyboard 中通过 Segue 动作创建的窗口对象，在 Storyboard 中通过连线表示。如视图中的某个按钮动作是打开一个由窗口控制器控制的窗口，我们认为被打开的窗口属于该类型的窗口。

这类会在窗口关闭时被自动释放。但是，它们并不严格地遵循 ARC 来进行自动释放。

Segue 通过 Storyboard 创建并持有窗口控制器对象，随后它设置窗口控制器对象的私有属性 retainedSelf 为 true。这在窗口被关闭时，窗口控制器会将因 Segue 持有而增加的计数视作为自身持有自身，因为再无其他强引用，所以释放控制器对象。

您可以在 Xcode 中添加 Symbolic Breakpoint -[NSWindowController _setRetainedSelf:] 来进行调试。

通过 Storyboard Entry Point 打开的窗口

通过 Storyboard 初始控制器打开的窗口，它们的窗口控制器由程序对象持有。

与 Segue 打开的窗口不同，通过 Entry Point 打开的窗口的控制器并不会设置 retainedSelf 属性。因此，在这种窗口被关闭时，因为存在由程序对象持有而增加的计数，ARC 不会释放窗口以及窗口控制器。

由于 NSApplication 对象没有提供任何修改这一持有对象的方法，因此，我们断言，通过这种方法创建的窗口，除了随着程序对象的消亡而被释放以外，无法被手动释放。

通过纯代码创建由窗口控制器管理的窗口

我们对通过纯代码创建的窗口控制器拥有完全的控制权，这其中就包括了窗口对象与控制器对象的释放。

窗口对象的生命周期由其窗口控制器管理。窗口控制器持有窗口对象的强引用，且不能为 nil。也就是说，窗口对象是跟随窗口控制器对象的释放而释放的。

为了让窗口控制器可以被释放，我们首先要将窗口控制器改成可选性的变量：

var windowController: NSWindowController?

然后，我们可以监听 NSWindow.willCloseNotification 事件，或者在窗口对象的代理方法 windowShouldClose(:) 中，将 windowController 设置为 nil。

这样一来，在确保窗口控制器对象再无其他强引用以后，窗口和窗口控制器就可以在窗口被关闭时被释放了。

在使用监听或代理方法释放窗口控制器时，您应该确保监听该事件的对象或者代理对象不是需要被释放的窗口对象或窗口控制器对象本身。

通过纯代码创建的窗口

如果您是通过纯代码来创建一个没有控制器的窗口，与上一节类似，你可以使用同样的方法来释放该窗口对象：

使用可选性变量，监听 NSWindow.willCloseNotification 事件或者在窗口对象的代理方法 windowShouldClose(:) 中将窗口对象变量设置为 nil。

在使用监听或代理方法释放窗口时，您应该确保监听该事件的对象或者代理对象不是需要被释放的窗口对象本身。

Sidenote: 关于 `isReleasedWhenClosed`

在 isReleasedWhenClosed 为 true 的场合下，NSWindow 并不遵循普通的内存管理策略。这使得 isReleasedWhenClosed 这一属性在使用 ARC 的现代 Cocoa 开发中变得特别尴尬。

当它释放时，它并没有非常干净的释放，而是留下了个空的 NSMapTable。也就是说，就算它释放了，它也不是 nil。

即使是从苹果自家的开发者邮箱列表中，你也只能找到将 isReleaseWhenClosed 设置为 false 的答复。并且在 NSWindowController 出现后，isReleasedWhenClosed 属性甚至被直接忽略。但是直到今日，isReleaseWhenClosed 仍然存在，没有过期。

就目前来说，我觉得 isReleasedWhenClosed 这个属性没有任何意义。

我的建议是：用 NSWindowController 来管理窗口，避免单独使用 NSWindow。如果你要单独使用 NSWindow，请务必将 isReleasedWhenClosed 属性设置为 false。

侧边栏菜单设计

Fri, 03 Jan 2020 00:00:00 +0000

侧边栏菜单与 iOS / iPadOS 中的 Tab Bar 类似，一般都用来管理一个单选型界面，而选中项决定了当前应该显示的视图。在 macOS 中，我们一般使用 Tab View 或者 Tab View Controller 来搭配 Table View 等视图来实现这一界面。本文将使用 Tab View Controller 与 Table View 的搭配来展示这类界面的实现。

在 App Store 中，左侧的侧边栏菜单控制右侧不同内容页之间的切换

我们一般会将侧边栏菜单与常规侧边栏进行区分。

侧边栏菜单往往是固定宽度且内容固定的，而常规侧边栏往往是宽度可变且内容是动态变化的。这些特性决定了常规侧边栏需要使用 Split View Controller 来实现，而侧边栏菜单不需要。

当然，这一区分并不是严格的，它们的运作原理都是一样的，你也不需要非得限制自己使用 Split View Controller 与否。

实现基本框架

我们将创建一个如下的视图结构：

+ Window
  + Content View Controller
    + Sidebar Container View (Hosting Sidebar View Controller)
      + Table View
    + Tab View Container View (Hosting Tab View Controller)
      + Tab View

数据交流方面，Sidebar View Controller 与 Tab View Controller 都将是 Content View Controller 的子视图控制器，我们可以使用代理模式在 Content View Controller 中连接代理对象即可。

出于个人习惯，文章会使用纯代码进行构建，你同样可以稍作修改来使用可视化实现同样的效果。

我们从 Content View Controller 开始。我们需要在 Content View Controller 中添加两个视图，这两个视图将成为我们侧边栏视图控制器和标签视图控制器的视图容器。因为方法是一样的，为了更好的展示代码，下面只展示侧边栏部分的实现：

class ContentViewController: NSViewController {
    // The view controller that manages sidebar.
    let sidebarViewController = SidebarViewController()

    // This will be the root view to host sidebar view controller's view.
    let sidebarContainer = NSView()
    
    override func viewDidLoad() {
        // add `sidebarViewController` as a child view controller.
        addChild(sidebarViewController)
        // Host `sidebarViewController`'s view in `sidebarContainer`.
        sidebarViewController.view.translatesAutoresizingMaskIntoConstraints = false
        sidebarContainer.addSubview(sidebarViewController.view)

        // `sidebarContainer` need to be a subview of this view controller's view.
        sidebarContainer.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(sidebarContainer)

        // Some constraints setup codes here...
    }
}

给两个视图控制器一点颜色，我们可以看到如下图的界面:

这里略去了关于窗口样式的定制代码。关于修改窗口标题栏高度的相关内容，你可以查看 修改标题栏高度 来获取更多详情。

侧边栏视图控制器

我们来创建侧边栏视图控制器 SidebarViewController。首先是根视图，我们希望侧边栏的背景是半透明毛玻璃效果的，因此，我们在 loadView 方法中创建一个 NSVisualEffectView 对象，并将其赋给 view：

class SidebarViewController: NSViewController {
    override func loadView() {
        let visualEffectView = NSVisualEffectView()
        visualEffectView.material = .sidebar
        visualEffectView.blendingMode = .behindWindow
        view = visualEffectView
    }
}

接下来我们来创建侧边栏中最关键的表格视图：

let tableView: NSTableView = {
    let view = NSTableView()
    // add a column to table view
    view.addTableColumn(NSTableColumn(identifier: NSUserInterfaceItemIdentifier("kSidebarColumn")))
    // remove table header
    view.headerView = nil
    // clear background
    view.backgroundColor = .clear
    // remove cell spacing
    view.intercellSpacing = .zero
    return view
}()

上面的代码中，我们给表格添加了一个列，这是因为纯代码创建的表格视图默认是没有列的。此外，我们还去除了表头，设置了透明背景，并且去掉了表格项直接的默认空隙。

这里省略了表格代理和数据源的设置，请记得设置 delegate 和 dataSource 对象引用，并完成表格项的配制。

有了表格视图，我们还需要创建一个能够装载它的容器：

lazy var scrollView: NSScrollView = {
    let view = NSScrollView()
    // set up document view
    view.documentView = tableView
    // add content inset to the top of table view, so the table view is not covered by window control buttons.
    view.automaticallyAdjustsContentInsets = false
    view.contentInsets = NSEdgeInsets(top: 52, left: 0, bottom: 0, right: 0)
    // clear background
    view.contentView.drawsBackground = false
    // remove vertical bounce effect
    view.verticalScrollElasticity = .none
    view.translatesAutoresizingMaskIntoConstraints = false
    return view
}()

表格视图本身并不包含滚动功能，滑动是通过嵌套的滑动视图实现的。你在可视化中添加的表格之所以是能够滑动，也是因为 Xcode 帮你嵌套了一个滑动视图在外边。

严格来说，这里的滑动视图并不是必须的，因为这类侧边栏菜单项目较少，往往不需要滑动。此外，我们往往也会将窗口的最小高度设置为一个至少高过表格高度的值来避免需要滑动的情况。

现在，配制完代理和数据源，并给定一个表格项视图后，你的侧边栏应该就是如下图的效果：

需要注意的是，如果你希望使用毛玻璃效果的侧边栏，那么，你应该确保你的表格项视图中的图片是使用模版形式渲染的。在 Assets 中，你可以在右侧属性栏中的 Render As 一项中设置为 Template Image，在代码中，你通过 NSImage 的 isTemplate 属性进行设置。而对于文本视图，确保你重写了 allowsVibrancy 属性。

标签视图控制器

右侧的标签视图的配制要简单许多，因为有现成的标签视图控制器。你在这里设置标签页中需要显示的各个视图控制器，并设置它们的标题和图标。方便起见，下面使用了一个循环来设置这些视图控制器：

class TabViewController: NSTabViewController {
    override func viewDidLoad() {
        // hide tab inside tab view
        tabStyle = .unspecified

        for index in 0..<4 {
            let item = NSTabViewItem(viewController: NumberedViewController())
            item.label = /* Some label here... */
            item.image = /* Some image here... */
            addTabViewItem(item)
        }
    }
}

我们通过将 tabStyle 设置为 .unspecified 来隐藏默认的标签控件，因为我们想要使用侧边栏中的表格来控制标签的切换。在这里设置视图控制器的标题和图片，可以允许我们在后面将这些数据传递给侧边栏。这只是帮助我们数据传递的其中一个方法，你可以根据你的偏好来修改上面的代码。

（为了更好的进行演示，图中的标签页并未隐藏）

上面配制标签项的方法并不是一个好办法，这会在一开始就把所有的视图都加载到内存中。你可以在这里使用一些懒加载的方法来推迟视图控制器的创建和添加，不过这并不是本文的重点。

视图控制器之间的数据交流

现在我们要将侧边栏的表格视图与标签页视图关联起来，来实现点击左侧表格项切换右侧标签页。

我们可以通过编写数据源的方法来从外部，也就是标签页视图控制器中获取标签数据：

protocol SidebarViewControllerDataSource: class {
    func sidebarViewControllerNumberOfItems(_ controller: SidebarViewController) -> Int
    func sidebarViewController(_ controller: SidebarViewController, titleForItemAt index: Int) -> String
    func sidebarViewController(_ controller: SidebarViewController, imageForItemAt index: Int) -> NSImage?
}

类似的，通过编写代理的方法来通知标签页视图进行标签切换：

protocol SidebarViewControllerDelegate: class {
    func sidebarViewController(_ controller: SidebarViewController, didSelectItemAt index: Int)
}

在 SidebarViewController 中，我们在对应的方法内调用这些数据源和代理的方法：

class SidebarViewController {
    weak var dataSource: SidebarViewControllerDataSource?
    weak var delegate: SidebarViewControllerDelegate?

    func numberOfRows(in tableView: NSTableView) -> Int {
        // ask data source for number of items
        dataSource?.sidebarViewControllerNumberOfItems(self) ?? 0
    }

    func tableView(_ tableView: NSTableView, viewFor tableColumn: NSTableColumn?, row: Int) -> NSView? {
        let cell = /* dequeue cell */
        // ask data source for title and image
        cell.image = dataSource?.sidebarViewController(self, imageForItemAt: row)
        cell.label = dataSource?.sidebarViewController(self, titleForItemAt: row)
        return cell
    }

    func tableViewSelectionDidChange(_ notification: Notification) {
        // notify delegate when selection has changed
        delegate?.sidebarViewController(self, didSelectItemAt: tableView.selectedRow)
    }
}

而在 TabViewController 中，实现 SidebarViewControllerDataSource 与 SidebarViewControllerDelegate 协议，并在协议方法中填入相应的内容即可。

此外，窗口即将显示出来时，在侧边栏表格加载完成并向数据源请求数据的时候，数据源（也就是标签页）有可能还没完成加载。这会造成一开始两个视图控制器的数据没有正确同步。我们可以用类似的方法为标签页写一个代理，用来在完成加载以后对代理对象进行通知：

protocol TabViewControllerDelegate: class {
    func tabViewControllerDataSourceDidChange(_ controller: TabViewController)
}

每当我们修改标签页视图中的 tabViewItems 时，我们调用 mainTabViewControllerDataSourceDidChange(_:) 来通知代理对象需要进行数据更新。

现在我们可以在 Content View Controller 中将这些代理和数据源连接起来：

class ContentViewController: NSViewController {
    override func viewDidLoad() {
        // ...

        // Setup delegate & data source objects.
        sidebarViewController.delegate = tabViewController
        sidebarViewController.dataSource = tabViewController
        tabViewController.delegate = sidebarViewController
    }
}

到这里，我们就完成了基本的侧边栏菜单的实现。

附加内容

在下面的几个小节中，我们会做一些细微的修改来提高用户体验。

效果更佳的高亮效果

默认情况下，我们的表格视图高亮选中某一行时，会用蓝色的高亮背景色来进行区分。这在普通侧边栏下的效果很好，但是在侧边栏菜单中就显得有点突兀了。

眼尖的你应该会发现 App Store 以及 Finder 这样的侧边栏并没有使用这种蓝色高亮，而是使用了更加通透的毛玻璃背景。

我们也是可以通过重写来实现这一效果的。在表格视图中，我们需要重写行视图的一个属性，来禁用默认的蓝色高亮：

class SidebarRowView: NSTableRowView {
    override var isEmphasized: Bool {
        get { false }
        set { }
    }
}

然后，我们在表格视图的代理中的 tableView(_:rowViewForRow:) 方法中返回这个行视图即可。

效果更佳的侧边栏分割线

仔细看一下 App Store 的侧边栏，你会发现在侧边栏边缘有一条分割线，这条分割线的样式跟分栏视图中的分割线还有点不同。它在明亮模式下，是带有模糊效果的半透明的灰色，而在暗黑模式下是纯黑色:

我们可以在侧边栏中添加一个 NSVisualEffectView 类，加上一个 NSView 来当颜色覆盖：

class VisualSeparatorView: NSVisualEffectView {
    var backgroundColor: NSColor?
    
    private lazy var _overlay: NSView = {
        let view = NSView()
        view.wantsLayer = true
        view.layer?.backgroundColor = backgroundColor?.cgColor
        view.translatesAutoresizingMaskIntoConstraints = false
        return view
    }()

    private func commonInit() {
        blendingMode = .withinWindow
        material = .selection

        addSubview(_overlay)

        NSLayoutConstraint.activate([
            _overlay.topAnchor.constraint(equalTo: topAnchor),
            _overlay.leadingAnchor.constraint(equalTo: leadingAnchor),
            _overlay.trailingAnchor.constraint(equalTo: trailingAnchor),
            _overlay.bottomAnchor.constraint(equalTo: bottomAnchor)
        ])
    }

    override func updateLayer() {
        super.updateLayer()
        _overlay.layer?.backgroundColor = backgroundColor?.cgColor
    }
    
    override init(frame frameRect: NSRect) {
        super.init(frame: frameRect)
        commonInit()
    }

    required init?(coder decoder: NSCoder) {
        super.init(coder: decoder)
        commonInit()
    }
}

然后设置一下掩盖层的颜色：

Appearance	RGBA (HEX)	RGBA
Light Mode	`#EBEBEB80`	`(0.92, 0.92, 0.92, 0.5)`
Dark Mode	`#000000FF`	`(0.00, 0.00, 0.00, 1.0)`

即可实现类似的效果。

你也可以直接使用分栏视图或分栏视图控制器，这是它的默认样式。

通过拖动侧边栏来拖动窗口

当你在侧边栏空白区域拖动时，你会发现窗口不会跟随拖动。这对于用户体验来说是一件非常让人沮丧的事情。

我们可以通过重写表格视图来将拖动事件传递给根视图，并在根视图中实现窗口拖动：

class TableView: NSTableView {
    override func mouseDown(with event: NSEvent) {
        let location = convert(event.locationInWindow, from: nil)

        if row(at: location) > -1 {
            // mouse down on row, call super
            super.mouseDown(with: event)
        } else {
            // mouse down on empty space
            var keepOn = true
            
            while keepOn {
                let nextEvent = window?.nextEvent(matching: [.leftMouseDragged, .leftMouseUp])

                switch nextEvent?.type {
                    case .some(.leftMouseDragged):
                        // send drag event to super
                        super.mouseDragged(with: nextEvent!)
    
                    case .some(.leftMouseUp):
                        keepOn = false
                        super.mouseUp(with: nextEvent!)
                    
                    default: ()
                }
            }
        }
    }
}

上面的代码可能跟你预想中的不太一样。NSTableView 并没有使用我们现在所熟知的 3 段式事件处理法 (mouseDown, mouseDragged, mouseUp) 来处理鼠标事件，而是使用了循环检测法来检测鼠标事件。

因此，我们需要在 mouseDown 方法中使用循环来追踪接下来我们感兴趣的事件。当事件是鼠标拖动或松开时，我们调用 mouseDragged 或 mouseUp 来将事件传递给下层视图处理，并且在 mouseUp 中及时退出循环。

更多关于这两种不同事件处理方法的内容，请查阅 Cocoa Event Handling Guide 中的 Handling Mouse Dragging Operations 部分。

而在 SidebarViewController 中，我们重写 mouseDragged 方法来实现窗口拖动：

class SidebarViewController: NSViewController {
    override func mouseDragged(with event: NSEvent) {
        view.window?.performDrag(with: event)
    }
}

你可以在表格视图的 mouseDown 中直接调用窗口的 performDrag(with:) 方法来实现拖动而无需在 SidebarViewController 中进行重写。我们之所以这样做，是为了方便以后你的侧边栏要放下去其他视图时 (如搜索栏)，可以统一在一个地方进行窗口拖动。

双击侧边栏空白区域来放大或缩小窗口

跟上面的一节类似，我们一般在窗口标题栏双击时，会使窗口放大或缩小 (不是全屏模式)。由于我们的程序隐藏了标题栏，因此，我们可以在侧边栏中实现这个功能。

方法很简单，在上面重写的表格视图中，但我们接收到鼠标松开事件时，我们进一步检测是否是双击事件，从而判断是否需要放大窗口：

case .some(.leftMouseUp):
    keepOn = false

    // zoom window if double clicked
    if nextEvent?.clickCount == 2 {
        window?.setIsZoomed(!window!.isZoomed)
    }

    super.mouseUp(with: nextEvent!)

取决与你的视图层级与样式，你可能同样需要重写上层的活动视图的 mouseUp(with:) 方法来实现拖动，从而保证有 inset 的位置也能够双击放大。

非活动窗口的快速拖动

当我们的窗口为非活动窗口时，如果你尝试拖动侧边栏来拖动窗口，你会发现窗口没有被拖动，这同样是一件很让用户沮丧的事情。

我们可以通过重写视图的 acceptsFirstMouse(for:) 方法来允许视图接收成为活动窗口时的首个事件。这里我们在滑动视图中重写这一方法：

class ScrollView: NSScrollView {
    override func acceptsFirstMouse(for event: NSEvent?) -> Bool {
        true
    }
}

现在，我们的窗口可以在非活动状态下进行拖动了。

Spotlight 式窗口设计

Tue, 31 Dec 2019 00:00:00 +0000

你可以在很多其他地方看到 Spotlight 式的设计，如意于取代 Spotlight 的功能更强大的 Alfred，又或是 Xcode 中的 Open Quickly 功能。这里我们就来讲一下这些 Spotlight 式窗口的实现。

本文只讲解 Spotlight 式窗口设计，并不会涉及到窗口内视图的变化，如显示隐藏列表，修改窗口大小等。虽说如此，文章的最后还是会稍微提供一下推荐的程序框架和键盘监听的思路。

使用 `NSPanel` 实现 Spotlight 式窗口

Spotlight 式窗口的关键在于创建一个不会成为焦点窗口的活动窗口 (non-main key window)。如果你打开了一个 Finder 窗口，然后激活了 Spotlight，你会发现，你的 Finder 窗口没有失去焦点，但是接收键盘事件的却是 Spotlight 窗口中的输入框。

Spotlight 窗口接收键盘事件，而背后的 Finder 窗口并未失去焦点

这是一个典型的面板窗口 (Panels) 的使用场景。Panels 是一种特殊的窗口，一般用于显示程序中的辅助功能。我们要实现的 Spotlight 式窗口很符合面板窗口的行为。

更多关于窗口不同状态的详情，请查看苹果官方的 Human Interface Guidelines 。

面板窗口本身不能成为焦点窗口，所以我们只需要重写 canBecomeKey 属性，便可以创建一个可以成为活动窗口但不会成为焦点窗口的面板窗口类。

class KeyablePanel: NSPanel {
    // Allow panel to become key, that is, accepts keyboard event.
    override var canBecomeKey: Bool { true }
}

我们的 Spotlight 式窗口应该是无边框的非激活面板，它的窗口控制器如下所示：

class SpotlightishWindowController: NSWindowController {
    convenience init() {
        self.init(windowNibName: "")
    }
    
    override func loadWindow() {
        // Create a boderless, non-activating panel that float above other windows.
        window = KeyablePanel(contentRect: .zero, styleMask: [.borderless, .nonactivatingPanel], backing: .buffered, defer: true)
        window?.level = .floating
    }
}

这里使用了懒加载方式来实现窗口控制器，你可以查看 懒加载视图或窗口控制器中的管理对象 来详细了解这一用法。

实际上，到这一步，我们已经拥有了 Spotlight 式的窗口。给这个窗口设置视图以后，这个窗口看起来是这样的：

不得不说，这真的很丑。

一般来说，我们会给窗口加上模糊背景，圆角，阴影等效果，来让它看起来更加漂亮。如果你有一个特定的设计要实现，你可以像普通窗口一样来自定义它的外观了。这里列举一下我个人的实现方式：

class SpotlightishViewController: NSViewController {
    override func loadView() {
        // Use visual effect view to give window a blur effect.
        let visualEffectView = NSVisualEffectView(frame: NSMakeRect(0, 0, 360, 48))
        visualEffectView.state = .active
        visualEffectView.material = .menu
        visualEffectView.blendingMode = .behindWindow
        // Use mask image to rounds window corner.
        visualEffectView.maskImage = NSImage(size: NSMakeSize(16, 16), flipped: false, drawingHandler: {
            NSColor.black.setFill()
            let path = NSBezierPath(roundedRect: $0, xRadius: 8, yRadius: 8)
            path.fill()
            return true
        })
        visualEffectView.maskImage?.capInsets = NSEdgeInsets(top: 8, left: 8, bottom: 8, right: 8)
        view = visualEffectView
    }
}

有趣的是，如果你窗口的根视图是一个 NSVisualEffectView，你可以直接在视图控制器中来实现窗口圆角，而无需再自定义窗口属性。

为了更好的展示效果，我们在视图层级中添加一个输入框，这样，我们的窗口看起来就会是下图的效果：

窗口的显示与隐藏

一般来说，当需要显示 Spotlight 式窗口的时候，要么是我们的程序拥有焦点 (如 Xcode 的 OpenQuickly)，要么没有 (如 Spotlight)。不管是哪种情况，我们显示我们的 Spotlight 式窗口的时候，我们都不希望修改当前的焦点窗口。我们只需要简单的调用 makeKeyAndOrderFront(_:) 即可:

// Make key and order front without changing the main window.
spotlightWindowController.window?.makeKeyAndOrderFront(nil)

有些特殊情况下，makeKeyAndOrderFront(_:) 无法让我们的 Spotlight 式窗口成为活动窗口。这种时候，作为备用手段，我们可以激活我们的程序来成为焦点程序:

if !window.isKeyWindow {
    // Make our application active to force our window become main, do this only when `makeKeyAndOrderFront(_:)` failed.
    NSApplication.shared.activate(ignoringOtherApps: true)
}

每次在窗口显示出来后，我们都应该给窗口设置一个第一响应者，一般来说是等待输入的搜索框。我们可以在视图控制器的 viewWillAppear 方法中进行设置：

class SpotlightishViewController: NSViewController {
    // Allow view controller to accepts first responder status.
    override var acceptsFirstResponder: Bool { true }

    override func viewWillAppear() {
        // Make search field the first responder.
        view.window?.makeFirstResponder(searchField)
    }

    // ...
}

这样一来，我们就可以保证每次我们的 Spotlight 式窗口显示的时候，窗口中的搜索栏可以马上接收键盘事件。

隐藏窗口就更加简单了，直接调用 close 方法来隐藏窗口即可:

// Simply hide window using `close`.
spotlightWindowController.close()

此外，我们一般会想要在鼠标点击窗口外的其他地方时也将窗口隐藏。我们可以在窗口代理的 windowDidResignKey(_:) 中隐藏掉:

class SpotlightWindowController: NSWindowController, NSWindowDelegate {
    override func windowDidLoad() {
        window?.delegate = self
    }
    
    // Hide window when resign key.
    func windowDidResignKey(_ notification: Notification) {
        close()
    }
}

这样，每当窗口失去活动状态时，窗口会自动隐藏。

附加内容

典型程序设计

当我们的程序想要引入 Spotlight 式的窗口时，一般只有两种情况：一种是围绕着 Spotlight 式窗口进行开发的程序，另一种是将 Spotlight 式窗口作为附属功能的程序。

围绕着 Spotlight 式窗口进行开发，意味着程序的主要入口和交互手段就是这个 Spotlight 式窗口。它是全局的，能够在任何程序中呼出。典型代表是 macOS 自带的 Spotlight，以及 Alfred。在开发这类程序时，我们往往会将 Spotlight 式窗口放置在独立的后台驻留进程 (background agent) 中，通过在 Info.plist 中设置 LSUIElement 项来实现。而程序设置等其他程序内容，放置在另外的 target 中。你通过监听全局快捷键，或者使用菜单栏按钮来触发窗口的显示。对于进程间通讯，XPC 将会是你的好伙伴。
将 Spotlight 式窗口作为附属功能，意味着它仅仅是你程序中的一个附加的功能。这种设计下，我们往往不会使用 Spotlight 式窗口来作为某些的内容和操作的唯一入口，而是作为可以提高操作效率的一种使用方法。这种时候，你将它视作普通的附属窗口来进行设计即可。

键盘事件的监听与转发

在你的输入框监听特殊按钮的输入非常简单，只需要在设置输入框的代理对象以后使用 NSTextFieldDelegate 的 control(_:textView:doCommandBy:) 方法即可监听方向键与返回键的事件：

// Set the delegate of text field or search field.
textField.delegate = self
// Delegate method to use for special key.
func control(_ control: NSControl, textView: NSTextView, doCommandBy commandSelector: Selector) -> Bool {
    switch commandSelector {
        case #selector(moveUp(_:)):
            print("pressed up")
        case #selector(moveDown(_:)):
            print("pressed down")
        case #selector(moveLeft(_:)):
            print("pressed left")
        case #selector(moveRight(_:)):
            print("pressed right")
        case #selector(cancelOperation(_:)):
            print("pressed esc")
        default: ()
    }
    // Return `false` to continue the default implementation, or `true` to override.
    return false
}

func controlTextDidChange(_ obj: Notification) {
    // Called when text field's text had changed.
}

在这之后，使用你偏好的方式来转发事件或者发送通知给相应的视图即可。

懒加载视图或窗口控制器中的管理对象

Sun, 27 Oct 2019 00:00:00 +0000

当使用可视化创建视图控制器或者窗口控制器时，它们所管理的视图或窗口对象是懒加载的，直到真正使用到的时候，才会创建它们管理的对象。然而，当你需要使用纯代码时，却失去了这种行为。怎样才能在不使用可视化的前提下同样进行懒加载呢？

我们可以借助可视化的一些方法来实现懒加载效果。这没有在开发文档中被记载，但就我们的使用情况来说，这其实是挺好的一个方法。

这个方法有两个关键点:

重写 loadWindow() 或 loadView() 方法。 虽然文档中说明了这两个方法在可视化中被用来从 storyboard 或 xib 中加载可视化对象，但我们可以重写这个方法，不从 storyboard 或 xib 中加载，而是直接创建一个对象给它们。
通过可视化的构造方法来创建控制器对象。 这保证了控制器会在必要的时候调用 laodWindow() 或 loadView() 方法，从而实现懒加载。

也就是说，我们可以这样来重写一个窗口控制器：

class WindowController: NSWindowController {
    convenience init() {
        self.init(windowNibName: "")
    }

    override func loadWindow() {
        self.window = /* initilize window object */
    }
}

使用一个无参构造方法来调用 init(windowNibName:) 并传入一个任意字符串。我们并不需要用到这个 nibName，只是借助它触发 loadWindow() 方法而已。

而对于视图控制器，调用 NSViewController 的无参构造方法会触发它的可视化构造方法，因此，你甚至都不需要特地的去调用它:

class ViewController: NSViewController {
    override func loadView() {
        self.view = /* initilize view object */
    }
}

这样一来，我们可以做到只创建窗口控制器对象，而不创建窗口对象。直到需要用到窗口对象的时候，如调用了 showWindow(_:) 方法时，窗口控制器会去检查是否有窗口对象，并自动调用 loadWindow() 方法去加载它。

你可以编写一个 Demo，通过断点或调用栈，来查看的加载情况。

如果你想要通过视频来了解这一方法，@LucasDerraugh 做了一期视频教程，值得一看。

实现程序自启动的最佳实践

Tue, 03 Sep 2019 00:00:00 +0000

在 macOS 中实现开机自启动似乎是一个特别需要技巧的事情。也许是为了解决过去遗留的问题，过去许多实现自启动的方法都被苹果标记为过时，网络上的许多教程也因此变得不怎么靠谱。

我们并不清楚未来苹果是否还会做出什么修改，不过，在面向现代的 Cocoa 程序编程中，使用 Service Management 框架来实现自启动是唯一被推荐的做法¹。并且，如果你希望在沙盒程序中实现开机自启动，使用 Service Management 框架也是你实现自启动的唯一途径²。

使用 Service Management 框架实现自启动

我们将需要一个启动项程序 (Login Item) 来帮助启动我们的主程序。下面展示了程序自启动的大概流程：

首先，你通过 Service Management 注册启动项到 launchd 中
每当用户登录时，launchd 会启动你的启动项
你的启动项被启动后，你在启动项中唤醒主程序
最后，你在适当的时机将启动项退出

下面我们通过在已有的项目中添加启动项来了解启动项的实现。

创建并配置启动项

在主程序的项目中，点击 Project Navigator → Your Project → Project and Targets List 中的 ”+” 按钮来添加一个 Application → Cocoa App 目标，它将是你的启动项程序。

你可以将它命名为任何名称，不过一般来说，我们会将它命名为 ProjectName + Helper 或 ProjectName + LoginItem。

下面我们将对主程序目标与启动项程序目标进行一些配置：

对于你的启动项程序目标:

在 Info → Custom macOS Application Target Properties 下，添加下方两个条目中的其中一条，并将其值设置为 YES，来将启动项设置为后台驻留程序:

Property List Key Source Code Key

Application is background only LSBackgroundOnly

Application is agent (UIElement) LSUIElement

将 Build Settings → Deployment → Skip Install 的值设置为 YES。

Property List Key	Source Code Key
Application is background only	`LSBackgroundOnly`
Application is agent (UIElement)	`LSUIElement`

由于我们需要将启动项注册到 launchd 中，而后者只接受后台驻留程序，因此我们需要将注册项设置为后台驻留程序。启动项唯一需要做的事情只有启动主程序，因此，启动项甚至不需要任何界面，你可以放心地在启动项项目中去除用户界面。

设置 Skip Install 为 YES 表示在打包时跳过该目标，这主要影响需要打包并上传到 Mac App Store 时的情况。默认情况下，Xcode 在打包时会将该项目下静态库、命令行等所有子目标都打包到一个档案中，而 Mac App Store 只接受上传的档案中只有单一程序包的情况。通过将 Skip Install 设置为 YES，Xcode 将在打包时跳过该目标，不会将其复制到档案中。

接下来，我们会把启动项内嵌到主程序中。对于你的主程序目标:

在 Build Phases 下，添加一个 Copy File Phase。设置其 Destination 为 Wrapper，Subpath 为 Contents/Library/LoginItems，并在下方的列表中添加你的启动项目标。

完成后，你会在 General → Embedded Binaries 下的列表中，看到你的启动项目标 (如果没有的话，请手动将它添加)。

这一操作告诉 Xcode 在打包时需要将启动项拷贝到主程序包中。Contents/Library/LoginItems 这个路径是固定的，当我们使用 Service Management API 来注册启动项时，它只会在这个目录中查找启动项。如果你使用了错误的路径，在调用 Service Management API 时，你将会遇到找不到启动项的错误。

有人建议还需要在主程序中将 Build Settings → Strip Debug Symbols During Copy 设置为 No 来避免打包时可能出现的错误，这一点我是反对的。当 Strip Debug Symbols During Copy 设置为 Yes 的时候，我并没有遇到过任何的问题 (也许是因为较新版本的 Xcode 解决了这个问题)。

将它设置为 No 没有任何的好处，反而会大幅增加打包后程序的大小，同时项目也需要花费更长的时间来编译，即便是在 Debug 环境下。所以我的建议是 - 永远将其设置为 YES。

在启动项中启动主程序

就如我们上面所说到的一样，启动项中需要进行的操作十分简单。

我们可以在 applicationDidFinishLaunching(_:) 方法中调用 NSWorkspace 的 launchApplication(at:options:configuration:) 方法来唤醒主程序，这个方法需要我们传入目标程序的路径。由于我们的启动项内嵌于主程序中，且路径是固定的，因此，我们可以通过当前启动项的路径，稍作修改，得到主程序的路径:

// getting the bundle url of main application
let url = [Int](repeating: 0, count: 4).reduce(Bundle.main.bundleURL) { (url, _) -> URL in
    url.deletingLastPathComponent()
}

上面所做的，仅仅是通过 Bundle.main.bundleURL 获取当前启动项的路径，往上回退 4 个目录，从而得到主程序的路径。这听起来似乎很荒唐，但这确实是一个可靠且简单的方法。

MyFancyApplication.app/               # Main application
+ Contents/Library/LoginItems/        # Directory that store all login items
  + MyFancyApplicationLoginItem.app/  # The login item (or helper application if you prefer)

如果你觉得这种方法不可靠，你还是可以通过其他方法来获取主程序的路径，如使用 NSWorkspace 的 urlForApplication(withBundleIdentifier:) 方法来获取指定包标识的程序路径。

得到了主程序的路径以后，我们可以开始我们的唤醒操作了:

try? NSWorkspace.shared.launchApplication(at: url, options: [.withoutActivation], configuration: [:])

倘若你的主程序是后台驻留程序，请确保 options 中的选项集中不包含 .inhibitingBackgroundOnly，否则，唤醒操作将会失败。

从 macOS 10.15 Catalina 开始，launchApplication(at:options:configuration:) 被标记为过时，请使用 openApplication(at:configuration:completionHandler:) 取代。

在完成唤醒后，你可以选择调用 terminate(_:) 方法来退出启动项程序。

在主程序中注册启动项

注册启动项非常的简单，我们只需要调用 SMLoginItemSetEnabled(_:_:) 方法即可：

import ServiceManagement

// SMLoginItemSetEnabled accept two parameters, 
// the first one is the bundle identifier of your login item, 
// the second one is a Boolean value indicate the enabled state of the login item.
SMLoginItemSetEnabled("com.your.loginItemIdentifier" as CFString, true)

你需要传入你的启动项程序的包标识，以及表示目标启动项启用状态的布尔值。这个设置仅对当前用户生效。

如果多个程序 (如多个来自通过同一开发者的程序) 所注册的启动项程序的包标识是相同的，那么系统只会启动一个包版本最新的助手程序。任何内嵌了该助手程序副本的程序都可以控制它的启用或禁用。

读取启动项状态

我们还需要在程序设置中提供一个选项来控制自启动的开启与否，这意味这我们需要获取自启动是否已经被注册到 launchd 中。

网上普遍推荐使用 Service Management 中的 SMCopyAllJobDictionaries(_:) 方法的结果来判断启动项的状态:

SMCopyAllJobDictionaries(_:) 返回指定域名下的所有注册的程序信息:
let jobs = SMCopyAllJobDictionaries(kSMDomainUserLaunchd).takeRetainedValue() as? [[String: AnyObject]]
通过在返回的结果集中判断是否存在我们的启动项标识，便可以得知我们的启动项是否被注册 (启用):
jobs.contains(where: { $0["Label"] as! String == "com.your.LoginItemIdentifier" })
尽管 SMCopyAllJobDictionaries(_:) 被标记为过时方法，据 @BlindDog 称，通过询问苹果开发者得知，它依旧是适合使用的方法。

也许是强迫症在作怪，使用一个被标记为过时的方法，并且还要自行去无视警告，对我来说是无法接受的事情。如果非得读取启动项状态，我会宁可选择直接通过 launchctl 来获取状态：

launchctl list com.your.LoginItemIdentifier

如果存在，它会返回如下启动项的信息:

{
  "EnableTransactions" = true;
  "LimitLoadToSessionType" = "Aqua";
  "MachServices" = {
    "com.your.LoginItemIdentifier" = mach-port-object;
  };
  "Label" = "com.your.LoginItemIdentifier";
  "OnDemand" = true;
  "LastExitStatus" = 0;
  "Program" = "com.your.LoginItemIdentifier";
};

而当不存在时，它会返回错误信息:

Could not find service "com.your.LoginItemIdentifier" in domain for port

在程序中使用 Process 与 Pipe 或者其他方法来执行 shell 脚本，判断返回结果字符串即可。

但实际上，我会选择放弃读取启动项的状态，取而代之的是以程序中保存的状态值为准来设置自启动的状态：

比如说，在 UserDefaults 中使用 launchAtStartup 来作为启动项是否启用的标识。在执行状态切换时，从 UserDefaults 中读取:
func toggleLaunchAtLogin() {
  // retrive from UserDefaults, which return `false` if `launchAtStartup` not exist
  let launchAtStartup = UserDefaults.standard.bool(forKey: "launchAtStartup")
  // toggle launchAtStartup with Service Management API
  SMLoginItemSetEnabled("com.your.LoginItemIdentifier" as CFString, !launchAtStartup)
  // update UserDefaults
  UserDefaults.standard.set(!launchAtStartup, forKey: "launchAtStartup")
}
而当需要读取启动项状态来初始化按钮状态时，我们从 UserDefaults 中获取 launchAtStartup 的值，并且在每次读取后重新调用 SMLoginItemSetEnabled(_:_:) 方法设置启动项状态:
let launchAtStartup = UserDefaults.standard.bool(forKey: "launchAtStartup")
SMLoginItemSetEnabled("com.your.LoginItemIdentifier" as CFString, launchAtStartup)
这样一来，启动项的状态将一直保证符合我们程序的期望。即便用户通过第三方程序将我们的启动项禁用，只要我们的程序设置窗口没有被打开，那么，启动项将维持用户在第三方程序中所设置的值，直到用户再一次打开程序的设置窗口。

这时，程序会根据 UserDefaults 中的值来重新设置启动项状态，这虽然覆盖了用户在第三方程序中所作出的修改，不过，我们程序的自启动控制按钮已经在屏幕中可见，即便需要用户重新设置，也只需要一次点击便能做到。

此外，在初始状态时，由于我们没有在 UserDefaults 中写入键为 launchAtStartup 的值，因此，UserDefaults 会返回它的默认值 false，也就是不开启自启动功能，这也符合上传到 Mac App Store 所需要的要求。

作为 macOS 中的一个良好公民，你的程序应该提供控制自启动的选项。如果你的程序有自启动功能，并且需要在 Mac App Store 中发布，你的程序必须提供该选项，并且默认关闭自启动。

小结

写下这篇速记的原因主要是为了在其他人问我应该如何实现自启动时能够直接把这边文章的链接砸到他们的脸上，然后才是作为一个记录而写下。虽然说是速记，但也花费了不少时间在考古和试验上，而且整理、排版和校对是真的难受。

一开始是想要将所有实现自启动可行的办法整合在一起，做一个总结和对比的。结果，苹果将除了文中介绍的方法以外的方法所涉及到的 API 都标记为过时，特别是 Shared File List 的方法，我个人是很喜欢能够在一个地方管理所有启动项的。

本文所展示的代码省去了对可能发生的错误所进行的处理。在你的实现中，你应该加上这些代码。

折叠或隐藏菜单中的菜单项

Tue, 20 Aug 2019 00:00:00 +0000

在 macOS 中，你会看到系统菜单有许多有意思的设计，如程序菜单中按下 ⌥ 键会出现替代菜单项，又或者在按住 ⌥ 时按下 Wi-Fi 的状态栏图标会出现额外的菜单项。这是怎么实现的呢？

使用替代菜单项来折叠菜单项

按下 (右) 与未按下 (左) option 键的 Time Machine 菜单

在菜单中，如果某个菜单项快捷键的基础键 keyEquivalent 与上一个菜单项相同，但是修饰键 keyEquivalentModifierMask 不同，那么，这些菜单项是可以折叠在一起的。

比如说有两个菜单项 Save 和 Save As…:

// `s` with `.commnad` mask
let saveItem = NSMenuItem(title: "Save", action: #selector(save:), keyEquivalent: "s")
// `s` with `.command` and `.option` mask
let saveAsItem = NSMenuItem(title: "Save As...", action: #selector(saveAs:), keyEquivalent: "S")

Save 的快捷键为 ⌘ + S，而 Save As… 的快捷键为 ⌥ + ⌘ + S。

现在，如果你将 saveAsItem 菜单项的 isAlternate 设置为 true:

saveAsItem.isAlternate = true

那么，打开菜单时，Save As… 将不会显示出来，直到你按下 ⌥ 键。这时，Save 将被 Save As… 替代显示。

这一方法同样也适用于 keyEquivalent 都为空的菜单项。因为这个情况的重点在于基础键相同且修饰键不同，而不是有没有基础键。

如果你对某个菜单项设置了 isAlternate = true，但是在它上面又没有符合条件的菜单项，那么，这个选项不会起任何作用。

按住修饰键打开菜单来显隐菜单项

当你按住 ⌥ 时按下 Wi-Fi 的状态栏图标会出现额外的菜单项，而松开 ⌥ 以后，这些菜单项并不会消失。这种要怎么做呢？

按下 (右) 与未按下 (左) option 键打开的 Volume 菜单

一个常见的思路是使用 isHidden 属性来隐藏这些需要隐藏的菜单项，当菜单打开的时候，我们检测一下 ⌥ 是否被按下，然后根据情况来修改这些菜单项是否需要取消隐藏。

首先是打开菜单时的回调。NSMenu 的代理 NSMenuDelegate 中有个 menuWillOpen(_:) 正好符合我们的需求:

optional func menuWillOpen(_ menu: NSMenu)

在这个方法中，我们可以通过 NSEvent 的 modifierFlags 来得到当前按下的修饰符的情况。

func menuWillOpen(_ menu: NSMenu) {
    if NSEvent.modifierFlags.contain(.option) {
        // show item
    } else {
        // hide item
    }
}

我们只需要在这里更新一下菜单项的显示隐藏即可。因为我们是使用 isHidden 属性来控制菜单项的显隐，所以，在菜单显示以后，松开 ⌥ 并不会影响到这些菜单项。

仅在按下修饰键时显示菜单项

有一种特殊的情况是你希望在菜单打开着的前提下，仅在按下 ⌥ 时显示菜单项，并且在松开 ⌥ 以后立即隐藏菜单项，如 Finder → Go 中的 Library 菜单项。这明显不符合上面说的两种情况。

Library 仅在按下 option 键时显示

实际上，这种情况除了使用私有方法以外别无他法 (至少以我所知)。

你将需要调用私有的 _setRequiresModifiersToBeVisible: 方法来设置菜单项是否需要按下修饰键才显示:

item.perform(NSSelectorFromString("_setRequiresModifiersToBeVisible:"), with: 1)
// in this case, a non-command modifier mask is required
item.keyEquivalentModifierMask = .option

获取人类可读的文件类型描述

Thu, 15 Aug 2019 00:00:00 +0000

在 Finder 中，当你选中某个文件时，你可以查看这个文件的类型描述。如选中 .zip 文件时，你会得到如 “Zip 归档” 的描述。这是怎么做到的？

UTIs 简介

首先我们需要简单介绍一下 UTIs。UTIs (Uniform Type Identifiers) 是用来唯一标识抽象类型的字符串。它可以用来描述文件类型、内存中数据的类型或者其他实体的类型。

对于常见格式的 UTIs，如 .png、.txt、html 等，macOS 中都有完善的预定义信息。而对于自定义的类型，UTIs 的定义会存放在程序 bundle 的 plist 里。

这些 UTIs 的定义包括了继承关系、标签、类型声明等，而类型声明中可以包括版本号、图标、技术文档链接，以及我们这里最关心的本地化描述。

更多关于 UTIs 的内容，可参阅：

UTType

Uniform Type Identifiers Overview

获取指定 UTI 的本地化描述信息

在 Core Service 里有一系列 UTIs 相关的 UTType API，其中 UTTypeCopyDescription(_:) 允许我们获取指定 UTIs 的本地化描述。

不过在此之前，我们需要将我们的文件类型字符串 (如 zip) 转换为 UTI。我们可以通过 UTTypeCreatePreferredIdentifierForTag(_:_:_:) 或 UTTypeCreateAllIdentifiersForTag(_:_:_:) 方法来进行转换：

let uti = UTTypeCreatePreferredIdentifierForTag(kUTTagClassFilenameExtension, "zip", nil)?.takeUnretainedValue()

kUTTagClassFilenameExtension 对应的是最常见的文件类型格式。如果你拥有的是 MIME 类型的文件格式，你可以使用 kUTTagClassMIMEType 来替代。

然后，我们就可以使用

let description = UTTypeCopyDescription(uti)?.takeUnretainedValue()

来得到该 UTI 的本地化描述了。

同样的，你也可以使用 NSWorkspace.shared.localizedDescription(forType:) 并传入该 uti 来获取相同的结果。

为未提供本地化描述的 UTIs 提供通用描述

UTIs 中的本地化描述是可选的，这意味着，对于某些特殊的文件类型，我们是获取不到它们的本地化描述的，因为它们根本不存在。

对于这种情况，一种方法是在找到 UTI 关联的程序后，从它的 Info.plist 文件中搜索使用可用的描述:

guard
    // `uti` is the uti string from above
    let url = LSCopyDefaultApplicationURLForContentType(uti, .all, nil)?.takeUnretainedValue() as URL?,
    // load info.plist into dictionary
    let plist = NSDictionary(contentsOf: url.appendingPathComponent("Contents/Info.plist")),
    // find the subnode of document types
    let docTypes = plist.object(forKey: "CFBundleDocumentTypes") as? [NSDictionary]
else { return }

// loop throught all document types and find if there's any match uti
for docType in docTypes {
    if let types = docType.object(forKey: "CFBundleTypeExtensions") as? [CFString], types.contains(fileType) {
        // if so, we can retrive the type name
        let description = docType.object(forKey: "CFBundleTypeName") as? String
        return description
    }
}

另一种方法是找到与该 UTI 关联的程序，使用本地化的程序名来进行描述。如 Visual Studio Code 的 .code-workspace 格式，可以 ”Visual Studio Code 文档“ 来描述:

guard
    let url = LSCopyDefaultApplicationURLForContentType(uti, .all, nil)?.takeUnretainedValue() as URL?,
    let plist = NSDictionary(contentsOf: url.appendingPathComponent("Contents/Info.plist")),
    let displayName = plist.object(forKey: "CFBundleDisplayName") as? String
else { return }

return displayName + " " + "Document"

小结

你最终获取文件类型描述的代码应该结合上面提到的多个方法。在一种办法行不通的时候，使用另一种方法来当作备选方法。

此外，上面的代码省略了固定文本的本地化处理，因为本文重点不在这。

另外，本来以为在沙盒环境下访问其他程序 Info.plist 的操作会失败的，结果实际上去尝试了以后发现是可以进行的，很奇怪。

Breakpoint Radio #057

Mon, 12 Aug 2019 00:00:00 +0000

这是一档私人电台节目，每一期都为你分享来自 ix4n33 私人播放列表的电子音乐，并以 1 到 2 个小时不间断混音呈现。

记一次 HC5661 的救砖过程

Sat, 10 Aug 2019 00:00:00 +0000

在我读大学的时候买了个 HC5661 路由器来刷 Openwrt 拨通校园网并开启无线网。大学毕业后的某一天，我试图将 Openwrt 替换为其他固件。不幸的是，它砖了，我甚至没有办法进入 Breed 后台。

最后，我使用了 RecoveryTool¹ 来恢复官方 0.9005-5384s 固件。然后我就炸了 – 我没有办法开启 SSH 访问。

之前的刷机我已经开启了开发者模式，刷入过 Breed，并且，没有保留密匙。现在恢复了官方固件，Breed 和密匙都被擦除了。这导致了一个非常尴尬的情况：

为了刷入 Breed，我必须进入云平台开启开发者模式。
由于没有密匙，云平台拒绝被访问，更别说开启开发者模式了。
从 9005 版本开始，固件禁止刷自制或第三方固件。RecoveryTool 恢复的刚好就是这个版本。
0.9007.1.7117s 之前的版本可以借助搜狐视频插件的漏洞来启动 SSH 服务，但是因为进不去云平台，没法安装插件。

我几乎放弃了所有希望，准备让我这台 HC5661 吃灰。幸运的是，我最后在 IPTV Fans 中找到了一个特殊的官方固件²。

刷入 0.9005.4778s 版本固件

0.9005.4778s 版本的原厂固件是一个神奇的存在 – 也许是由于某位开发者的疏忽，这个固件的 dropbear 服务没有被关闭。这意味着：

这个固件是官方的，它的签名可以被路由所认可。你可以借助 TFTP 直接刷入。
刷入后，你无需任何操作，就可以使用 SSH 连接路由器后台。我们可以完全绕过进入云平台开启开发者模式等繁琐步骤。这一点在我这个例子中尤为重要。

这里使用的是 macOS 系统，且已经将固件重命名为 recovery.bin。

复制 0.9005.4778s 版本固件到 /private/tftpboot
```
cp recovery.bin /private/tftpboot/recovery.bin
```

修改目录与文件权限

sudo chmod 777 /private/tftpboot
sudo chmod 777 /private/tftpboot/*

断开路由电源并使用网线将电脑与路由的任意 Lan 口连接
手动设置电脑的 IP 为以下：
- IP: 192.168.1.88
- 子网掩码: 255.255.255.0
- 网关: 192.168.1.1

启动 TFTP 服务

sudo launchctl load -F /System/Library/LaunchDeamons/tftp.plist
sudo launchctl start com.apple.tftpd

按住 Reset 按钮不放接通路由电源

你现在可以看到文件被传输到路由中去。传输完成后，路由会开始自动刷机，这需要花费几分钟的时间。

结束后，你可以修改电脑 IP 为自动获取。现在，你可以通过在浏览器访问 192.168.199.1 来访问路由后台，并且可以在后台上看到固件版本为 0.9005.4778s。同时，你也可以使用 SSH 访问到路由后台。

后续: 刷入 Breed

为了防止手贱，提前刷入由 @hackpascal 开发的 Breed Bootloader 以给未来的自己留一条后路。

我下载的是 breed-mt7620-hiwifi-hc5761.bin。为了方便起见，我将它重命名为 breed.bin。

保持路由接通电源并开机
使用 SCP 将 breed 固件复制到路由器的 /tmp 中
```
scp breed.bin root@192.168.199.1:/tmp/breed.bin
```
密码为路由后台密码，如果你没有做任何修改的话，输入 admin 。
使用 SSH 连接到路由器后台
```
ssh root@192.168.199.1
```
密码为路由后台密码，如果你没有做任何修改的话，输入 admin 。
使用 mtd 命令刷入 breed
```
mtd -r write /tmp/breed.bin u-boot
```

这样，breed 就被刷入了。你可以跟随以下步骤验证 breed 是否被成功刷入。

断开路由器电源
按住 HC5661 的 Reset 按钮不放，接通 HC5661 的电源
等待电脑获取 IP 地址后松开 Reset 按钮
通过浏览器访问 192.168.1.1

如果你看到了 Breed 后台，恭喜你，breed 已被成功刷入。

小结

最后我还是给刷入了 Gargoyle 的固件，凑合着用。讲道理，在这个年代，不支持 5 GHz 的 HC5661 基本上是拿来当有线交换机用了，当时校园网就 4 兆，觉得 2.4 GHz 够用，现在想想只能怪当初自己太年轻。

写完这篇以后有了个骚想法，感觉可以把 0.9005.4778s 的固件拷贝到 RecoveryTool 去，直接用 RecoveryTool 直接刷进去。不过我已经懒得试了，小白鼠就换你来当吧。

适用于 HC5661, HC6361, HC5361 以及其他型号的恢复工具: 小极修砖神器. ↩
适用于 HC5661 的 0.9005.4778s 固件: hc5661-0.9005.4778s-recovery.bin. ↩

获得文本框焦点回调事件

Thu, 08 Aug 2019 00:00:00 +0000

在网页开发中，我们可以轻松地使用 onFocus、onBlur 这样的事件来在文本框得到或者失去焦点时获得回调，但意外的是，在 AppKit 中却没有这样的事件回调，需要我们自行获取。

NSTextField 继承于 NSResponder，这似乎暗示着我们可以通过 becomeFirstResponder 和 resignFirstResponder 来轻松获取文本框的焦点事件。但事情并没有这么简单。

Field Editor

当你在文本框中输入文字的时候，其实你并不是将文字输入到文本框之中，而是一个隐藏的 NSTextView 对象里去。实际上，每个窗口都有一个全局共享的 NSTextView 对象来处理该窗口下所有控件的文字处理，我们称这个对象为 field editor。

对于当前活动状态的文本框而言，AppKit 会自动把 field editor 插入到这个文本框的视图层级中去，从而为这个文本框提供文本显示、输入和编辑功能。而当焦点切换到另一个文本框时，AppKit 则会自动将这个 field editor 插入到这个新的文本框中。

如果你不熟悉窗口内 field editor 的运作，你可能会感到非常困惑。因为窗口的第一响应者是这个不可见的 field editor，而非你在屏幕上看到的聚焦着的控件。

在你文本框获得焦点时 (如点击文本框)，会发生下面的一系列事情：

文本框成为第一响应者
AppKit 将 field editor 插入到文本框视图层级中
文本框卸下第一响应者
field editor 成为第一响应者

根据这些事情，我们可以通过当前文本框是否有 field editor 来判断出当前的文本框是否聚焦。

更多关于 field editor 的内容，请查阅 Cocoa Text Architecture Guide 下的 Working with the Field Editor 一节。

获取事件

对于得到焦点事件，在 NSTextField 子类中，只需要在 resignFirstResponder() 中判断当前文本框将卸下第一响应者，并且文本框还拥有 field editor 的时候，便是该文本框得到焦点的时候：

override func resignFirstResponder() -> Bool {
    let resign = super.resignFirstResponder()
    
    if resign, let _ = currentEditor() {
        // focused
    }
    
    return resign
}

而失去焦点就更简单了。失去焦点时，textDidEndEditing(_:) 会被调用，直接使用它即可：

override func textDidEndEditing(_ notification: Notification) {
    // blured
}

创建回调方法

知道了焦点事件回调的时机以后，创建回调方法就很简单了。我们可以编写一个代理协议或者 target/action 来创建回调方法，在这里，我们使用创建代理协议的方法：

@objc protocol TextFieldFocusDelegate {
    @objc optional func textFieldDidGainFocus(_ textField: NSTextField)
    @objc optional func textFieldDidLoseFocus(_ textField: NSTextField)
}

NSTextField 已经有一个代理对象引用可以使用，我们不需要再创建一个引用。直接通过借助这个代理对象即可：

class TextField: NSTextField {
    private var become: Bool = false

    override func becomeFirstResponder() -> Bool {
        become = super.becomeFirstResponder()
        return become
    }

    override func resignFirstResponder() -> Bool {
        let resign = super.resignFirstResponder()
        
        if become, resign, let _ = currentEditor() {
            (delegate as? TextFieldFocusDelegate)?.textFieldDidGainFocus?(self)
        }
        
        become = false
        return resign
    }
    
    override func textDidEndEditing(_ notification: Notification) {
        (delegate as? TextFieldFocusDelegate)?.textFieldDidLoseFocus?(self)
        super.textDidEndEditing(notification)
    }
}

在 becomeFirstResponder() 中存储结果并在 resignFirstResponder() 中判断是这个值是必要的，这可以过滤掉重复的调用。

这样，在使用的时候，只要设置了代理对象，并且这个对象同时还实现了我们的 TextFieldFocusDelegate，那么，这个对象的方法便会被调用：

extension ViewController: NSTextFieldDelegate, TextFieldFocusDelegate {
    override func viewDidLoad() {
        textField.delegate = self
    }

    func textFieldDidGainFocus(_ textField: NSTextField) {
        // do somethings
    }
    
    func textFieldDidLoseFocus(_ textField: NSTextField) {
        // do some other things
    }
}

小结

协议中的 textFieldDidLoseFocus(_:) 实际上是没必要的，因为我们可以直接使用 textDidEndEditing(_:) 方法。

这里介绍的方法同样适用于 NSSearchField 或者 NSSecureTextField 等，因为它们都是 NSTextField 的子类。

为 NSVisualEffectView 设定自定义颜色

Wed, 31 Jul 2019 00:00:00 +0000

作为一种设计语言，macOS 在 Yosemite 开始提供了 NSVisualEffectView 来允许我们方便的实现毛玻璃效果。但是，就算是到了 5 年后的现在，除了黑白两色，苹果都没有为 NSVisualEffectView 提供更多的颜色方案。当我们出于设计需要，要求对 NSVisualEffectView 进行着色时，我们就必须自己动手了。

可惜的是，macOS 并没有像 iOS 那样提供分开的 Blur Effect 以及 Vibrant Effect 来供我们自由组合，而是单纯提供一个整合了这些效果的 NSVisualEffectView，只允许我们从预定的材料中进行选择。

这也就意味着，我们只能通过一些奇怪而又特殊的技巧来得到我们期望的效果。

方法 1: 修改 Layer 背景颜色

这种方法直接在 NSVisualEffectView 的所有图层里找到某个图层并修改它的背景色。

NSVisualEffectView 使用的图层中，有一个名为 color copy 图层可以进行背景色修改，而且这个修改可以在视图中看到，且不会影响到模糊效果。

20% Alpha Blue & 20% Alpha Red

我们可以在 updateLater() 方法中进行这一修改。当然，为了防止动画造成修改延迟，我们需要在修改 backgroundColor 时禁用动画：

class TintedVisualEffectView: NSVisualEffectView {
    var tintColor: NSColor = .clear {
        didSet { needsDisplay = true }
    }
    
    override func updateLayer() {
        super.updateLayer()
        
        if let tintedLayer = layer?.sublayers?.first(where: { $0.name == "color copy" }) {
            CATransaction.begin()
            CATransaction.setDisableActions(true) // required to avoid animated color changes
            tintedLayer.backgroundColor = tintColor.cgColor
            CATransaction.commit()
        }
    }
}

在 updateLayer() 中调用 super 中的方法后再进行修改，允许我们的颜色叠加在修改材质等属性后依旧生效。

这种方法存在一些局限的地方：

颜色效果不明显。 为了保留原有的模糊效果，覆盖上去的颜色必须是透明的，这使得覆盖上去的颜色变浅。
未来可能失效。 虽然没有用到私有 API，但通过名字查找图层的方法随时可能因为 API 更新时名字的变更而导致失效。实际上，这个图层的名字在之前已经被修改过一次 (以前是 ClearCopyLayer)。

这些问题并不是特别大，因此这种方法也是推荐使用的方法。

方法 2: 添加一个颜色叠加视图

这种方法借助了 allowVarbancy 属性的特性。这个属性原本是用来调节放在 NSVisualEffectView 上的控件 (如图形按钮，文字等)，让它们叠加一层模糊的背景，在增加连贯性的同时提高辨识度。

这种效果你会在如 Finder 的侧边栏，或者 App Store 的侧边栏中看到。仔细看它们上面的文字和图标，你就会发现，它们并非纯色，而是带有一点特殊的透明效果的。

注意左下方的星星图标与 Discover 文字

使用这个方法，你只需要在创建一个重写了 draw(_:) 方法的视图，让它填充你所设定的颜色。

注意，这里使用的着色方法并非将视图修改成 Layer-Backed 视图后再设置 layer.backgroundColor 属性，而是使用绘图来填充颜色。因为不这么做的话，跟上面的方法就没什么区别了。

class ColorOverlayView: NSView {
    var backgroundColor: NSColor = .clear {
        didSet { needsDisplay = true }
    }
    
    override func draw(_ dirtyRect: NSRect) {
        backgroundColor.setFill()
        dirtyRect.fill()
    }
    
    override var allowsVibrancy: Bool { true }
}

此外，我们必须重写 allowsVibrancy 并返回 true 来加入透明效果。

使用这种方法时，你的视图层级会有如下结构：

NSVisualEffectView
+ ColorOverlayView
  + NSTextField
  + NSButton
  + ...

借助这种方法的好处在于，你不需要把颜色的透明度调得很低，就算是设置了完全不透明的颜色，它也是透明的。

60% Alpha Red

然而，这种方法的缺点非常的明显：

顶层视图的样式会受影响。 这从图中就可以看到这个问题：在 Aqua 下，位于顶层的窗口控制按钮和其他控件都变暗了，而在 Dark Aqua 下，这些控件反而变亮了。
背景颜色会被过度饱和。 allowVarbancy 属性本来就会提高背景的饱和度，在设置和较不透明度的颜色时，如果遇到背景颜色接近这个颜色，视图会变得特别鲜艳。这个问题在使用了较为通透的材质的时候尤为明显。

小结

不管你选用上面何种方法来实现，你都需要考虑一些额外的问题。

往 NSVisualEffectView 添加颜色并不难，真正难的事情在于让你的这一修改，在不同的环境下保证良好的视觉效果。如不同的壁纸、是否开启黑暗模式、窗口的激活与否、与子视图的协调性…

而这些，都是你在进行开发时应该考虑到。

使用代码打开指定偏好设置面板

Tue, 23 Jul 2019 00:00:00 +0000

有些时候，我们的程序会需要向用户请求权限。与 iOS 不同，在 macOS 上往往不会弹出确认框来向用户请求权限，而是需要用户前往系统偏好设置来开启权限。这时，我们往往会需要使用代码打开指定偏好设置面板，来引导用户进行授权操作。

找到偏好设置面板

我们要打开的偏好设置面板文件一般存储在以下路径：

# system preference panes
/System/Library/PreferencePanes/
# user-installed system-wided preference panes
/Library/PreferencePanes/
# user-installed user-wided preference panes
~/Library/PreferencePanes/

在这些位置，你可以会找到各个控制面板所对应的 .prefpane 文件。.prefpane 文件下可以找到接下来会用到的内容，如 Info.plist 里的 Bundle Identifier。

方法 1: 使用 URL Scheme 打开指定面板

部分控制面板支持通过 URL Scheme 进行访问。在各个控制面板对应的 .prefpane 文件里的 Info.plist 中，如果有下面这一键值对，则表示这个面板支持 URL Scheme:

<key>NSPrefPaneAllowsXAppleSystemPreferencesURLScheme</key>
<true/>

控制面板的 URL Scheme 格式是 x-apple.systempreferences: 前缀加上面板的 Bundle Identifier：

有些面板支持锚点，可以在 URL Scheme 后面加入锚点名称来访问控制面板的某个区域:

如 安全性与隐私 → 隐私 → 辅助功能 的 URL Scheme 为：

x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility

如何查询可用锚点？

你可以在 Script Editor 中执行
tell application "System Preferences"
  anchors of pane "com.apple.preference.network"
end tell
来查找指定面板下的所有可用锚点。

最后在代码中，通过 NSWorkspace 的 open(_:) 方法便可以打开与 URL Scheme 对应的偏好设置面板:

let url = URL(string: "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility")!
NSWorkspace.shared.open(url)

方法 2: 使用 AppleScript 打开指定面板

另一种方法是使用 AppleScript 来打开控制面板：

# reveal pane
reveal pane "com.apple.preferences.extensions"
# reveal pane with anchor
reveal anchor "dns" of pane "com.apple.preference.network"

你只需要指定特定面板的 Bundle Identifier 和锚点即可。如打开 系统偏好设置 → 网络 → 高级 → DNS 面板，可以使用下面的脚本来打开：

tell application "System Preferences"
  reveal anchor "dns" of pane "com.apple.preference.network"
  activate
end tell

如何查询可用锚点？

你可以在 Script Editor 中执行
tell application "System Preferences"
  anchors of pane "com.apple.preference.network"
end tell
来查找指定面板下的所有可用锚点。

对于一些需要输入用户密码才能进行修改的面板，你还可以通过下面的脚本来主动弹出解锁对话框：

authorize pane "com.apple.preferences.password"

在代码中执行 AppleScript 脚本非常简单，使用 NSAppleScript 即可执行脚本:

let script = /* Some AppleScript Here */

var err: NSDictionary?
if let scriptObject = NSAppleScript(source: script), let output = scriptObject?.executeAndReturnError(&err) {
    print(output.stringValue)
} else {
    // something's wrong
}

executeAndReturnError(_:) 方法是同步执行的，这意味着，你的用户界面有可能会被它锁住，特别是在执行耗时脚本的时候。在必要时，请将它放到独立的线程中执行。

在沙盒环境下，某些 AppleScript 操作需要沙盒权限才能使用，如 reveal，activate 等。
更多详情

你可以在 Entitlements 文件中添加 com.apple.secirity.scripting-targets 来请求对应权限：
<key>com.apple.security.scripting-targets</key>
<dict>
    <key>com.apple.systempreferences</key>
    <string>preferencepane.reveal</string>
</dict>
在某些时候，你也许会遇到 activate 无法将系统偏好设置窗口前置的问题。这时候，你可以选择在执行脚本前，预先通过 NSWorkspace 启动系统偏好设置：
NSWorkspace.shared.launchApplication(withBundleIdentifier: "com.apple.systempreferences", options: [], additionalEventParamDescriptor: nil, launchIdentifier: nil)
在修改 Entitlements 文件后，你有可能会遇到类似 “Entitlements was modified during the build, which is not supported” 的错误。这时，你可以尝试清空你的 Build Settings → Code Signing Entitlements 的值。

此外，从 macOS Mojave 开始，你也可以在 Info.plist 添加 NSAppleEventsUsageDescription 来申请 AppleEvent 权限：
<key>NSAppleEventsUsageDescription</key>
<string>This application needs to control other applications to launch System Preferences for you when needed.</string>

此外，在 OS X 10.8 Mountain Lion 中，苹果引入了 NSUserAppleScriptTask 来允许更安全地执行 AppleScript。如果你想了解更多，不妨看看 Craig Hockenberry 的 Scripting from a Sandbox (或者 @onevcat 的译文)。

小结

在真实环境下，并不是所有时候都能够保证你的程序拥有执行这些操作的权限。

如果你不能通过代码为你的用户打开特定的控制面板，至少你应该通过简单的文字或图片描述来引导用户如何进行下一步操作。如：“前往 系统偏好设置 -> 通知 以进行更多通知相关的设置。”

然后我就病了

Mon, 01 Jul 2019 00:00:00 +0000

嗯，就在我写完上一篇开篇，还没来得及准备下一篇博文写什么的时候，我病了。

怎么说呢，深圳有流感高发预警，但是每次预警我都没遇上，时间长了就不在意了。最近一次预警，端午节前几天的周末我还跟同学一起去吃了顿肉蟹煲，然后熬夜看了 WWDC 19 的直播。

就在隔天早上，我醒来的时候，感觉喉咙有种堵塞的感觉，维持了一整天，然而当时的我并没有在意。结果就是，这成了我最后悔的事情。

第二天醒来，喉咙的堵塞感没了，身体感觉一切正常。直到下午，整个脸有种发烫的感觉，也有点疲惫，这时候才掏出体温计量了一下体温 – 38.5℃，发烧了。不过还好，吃了退烧药，躺了一会儿，到晚上已经回到 36.4℃，感觉就跟烧着玩似的。

然而接下来的日子里，现实狠狠地抽打我的脸颊。

一早醒来就回到 38.2℃，到晚上就降到 37.4℃，持续了快一个星期，还一直咳嗽，期间一直在吃着开的西药。这个时候已经很明显是病毒性流感了。好不容易撑过了 7 天病毒存活期，我还是一直 37.2℃ 低烧，咳嗽也没见任何好转。

最后呢，还是在家人的建议下扛着病坐上了回家的高铁，这时候已经是6月中旬。回到家，去了亲戚家的诊所，开了点中药。

好的，我知道你要喷我中药没有科学依据，说我封建迷信啥的。但是，你想清楚，我西药吃了快半个月都没治好，一直低烧，整个人还累的半死，结果你猜怎么着？4 碗中药下肚，分 2 天喝完，第三天醒来体温直接 36.5℃ 正常了，咳嗽还大幅度好转，期间没有吃过一点西药。

我没有要鄙视西药推崇中药的意思，但是，作为一个病人，我 tm 才懒得去争论这些东西，它给我治好了，他就是好药。

然后就到了今天，嗯，7 月了。平时不得病，一病一个月。

绝了。

一个全新的开始

Tue, 28 May 2019 00:00:00 +0000

我从来不是一个会记录生活的人。上学的日子，每一次写日记、周记或者作文都是一次痛苦的折磨。

有一次，也不知道受了什么影响，觉得在人生走到尽头的时候回味过去写的日记是一件很浪漫的事情，于是开始了在手机上写日记的习惯。坚持了半年吧，最后还是败给了五月病以及单调的生活。

直到近几年，沉迷开发不可自拔，才开始频繁地记笔记。也许是因为技术性文章不需要感情，又或许是因为不记笔记的话每次复习都很麻烦，才坚持到了现在。只是，到现在一直没有发生变化的，是文章中苍白的形容词。

刚好这几天觉得博客旧主题看腻了，换个新主题，顺便把之前的丢人博文删掉 ~~(计划通)~~。

所以，从现在开始，博客不会有任何 CDN 加速措施 ~~(虽然以前也没有)~~，也不会有评论功能 ~~(评论是不会开评论的，这辈子都不会开)~~，倒是会在记笔记的同时写点技术无关的情感博文，瞎搞的电台也发到这来，虽然电台和博客都没有多少访问量。

这次能坚持多久呢?

为 UISearchController 添加额外的按钮

Sun, 28 Apr 2019 00:00:00 +0000

如果你在 iPad 中使用过新的 App Store，那么你应该会发现在搜索页中的搜索栏与其他搜索栏有些不同: 在你点击搜索栏后，搜索栏会收缩到中间，而左右两边出现了筛选和取消按钮。怎样才能实现这样的效果呢?

UIKit 并没有提供直接了当的 API 来实现这样的效果。但我们可以通过重写一个 UISearchController 子类来实现这样的效果。

tl;dr: 你可以在这个 Github Repo 中查看完整代码。

计划

当激活搜索栏的时候，系统进行了一次从当前的视图控制器到搜索控制器的转场。我们可以重写这个转场动画，修改最终的视图位置，并且添加我们的自定义按钮。

UISearchBar 下的 UIView 里存放了搜索输入框，这里是插入我们自定义视图的比较合理的位置。

UISearchController 实现了 UIViewControllerAnimatedTransitioning 协议，我们可以通过重写协议中的 animateTransition(using:) 方法来自定义搜索栏收缩和添加按钮的动画。

在这个方法中，我们需要:

修改搜索栏父容器的高度。搜索栏父容器的高度根据不同场景会有所变化，我们需要重现这些变化。
修改搜索栏的位置与大小。在搜索栏父容器高度发生变化的时候，适当调整搜索栏的位置。
修改搜索栏的宽度。这是我们在 iPad 设备上想要做的修改。
插入自定义视图到搜索框左右两边。这也是我们想要做的修改。此外，在 iPad 设备上，我们将左右空隙增大，以得到更好的视觉效果。
插入取消按钮。这是为了修改搜索栏宽度而需要作出的一个妥协。使用系统方法显示取消按钮会导致我们的修改被覆盖掉，因此，我们将使用一个自定义的取消按钮来模拟取消按钮。
显示 SearchResultController。搜索结果控制器的视图也是在这个时候插入到视图层级中的，我们同样需要将它添加上。

实现

重写一个自定义的 UISearchController 子类，如 CustomSearchController。

class CustomSearchController: UISearchController { /* ... */ }

我们可以通过下面这些方法来得到比较关键的视图:

// UISearchBar 下的 UIView 子视图, 姑且叫做 barContainer 吧
let barContainer = searchBar.subview.first
// 搜索栏的文本框
let searchField = barContainer?.subview.first(where: { $0.isKind(of: UITextField.self) }) as? UITextField
// 搜索栏的父视图
let palette = searchBar.superview

如上面所说，我们会重写下面这个方法:

override func animateTransition(using transitionContext: UIViewControllerContextTransitioning) {
  transitionContext.completeTransition(true)
}

实现搜索栏父视图高度变化

搜索栏容器的高度是通过约束控制的，我们可以获取到这个约束:

private let _paletteHeightConstraint = searchBar.superview?.constraints.first(where: {
  $0.firstItem?.isEqual(searchBar.superview!) ?? false && $0.firstAttribute == .height && $0.secondItem == nil
})

在 viewDidLoad 中，我们需要设置这个高度为上文表中相应的值:

_paletteHeightConstraint?.constant = paletteH

然后，在 animateTransition(using:) 里也更新这个高度:

override func animateTransition(using transitionContext: UIViewControllerContextTransitioning) {
  
  _paletteHeightConstraint?.constant = paletteH

  UIView.animate(withDuration: transitionDuration(using: transitionContext), delay: 0, options: [.curveEaseInOut], animations: {
    self._palette?.superview?.layoutIfNeeded()
  }) {
    transitionContext.completeTransition($0)
  }
}

现在，搜索栏父视图的高度已经有所改变了。

这里的 paletteH 就是上面提到了的搜索栏父容器的高度。它会根据不同场景变化，影响这个高度的变量包括搜索栏的激活状态，导航栏的隐藏与否，以及设备与其横竖屏的状态。

更多详情

当搜索栏未激活时:

Device Portrait Landscape

PaletteH TextFieldH TextFieldY PaletteH TextFieldH TextFieldY

Any 52 36 1 52 36 1

当搜索栏激活，且 hidesNavigationBarDuringPresentation 为 ture 时:

Device Portrait Landscape

PaletteH TextFieldH TextFieldY PaletteH TextFieldH TextFieldY

SE 50 36 4 44 30 7

8 50 36 4 44 30 7

8 Plus 50 36 4 50 36 4

XS 55 36 4 44 30 7

XR 55 36 5 50 36 4

XS Max 55 36 4 50 36 4

iPad 50 36 7 44 30 7

当搜索栏激活，且 hidesNavigationBarDuringPresentation 为 false 时:

Device Portrait Landscape

PaletteH TextFieldH TextFieldY PaletteH TextFieldH TextFieldY

SE 52 36 1 46 30 1

8 52 36 1 46 30 1

8 Plus 52 36 1 52 36 1

XS 52 36 1 46 30 1

XR 52 36 1 52 36 1

XS Max 52 36 1 52 36 1

iPad 52 36 1 52 36 1

其中，Palette 指搜索栏的父视图，TextField 指搜索栏中的输入框。

这里可以编写一个函数来根据情况返回特定的数值，这里就不给出代码了。

Device	Portrait	Landscape
Any	52	36	1	52	36	1

Device	Portrait	Landscape
SE	50	36	4	44	30	7
8	50	36	4	44	30	7
8 Plus	50	36	4	50	36	4
XS	55	36	4	44	30	7
XR	55	36	5	50	36	4
XS Max	55	36	4	50	36	4
iPad	50	36	7	44	30	7

Device	Portrait	Landscape
SE	52	36	1	46	30	1
8	52	36	1	46	30	1
8 Plus	52	36	1	52	36	1
XS	52	36	1	46	30	1
XR	52	36	1	52	36	1
XS Max	52	36	1	52	36	1
iPad	52	36	1	52	36	1

实现搜索栏布局

首先在 viewDidLoad 中禁用掉搜索框的自动约束转换:

searchField.translatesAutoresizingMaskIntoConstraints = false

然后，我们可以添加左右两侧的按钮容器了:

barContainer.addSubview(leftBarItemsStack)
barContainer.addSubview(rightBarItemsStack)

这里使用 Stack View 来作为左右两边按钮的容器。

现在，我们需要配置 3 套约束:

基础约束
激活时约束
非激活时约束

基础约束是一直生效的约束，它在 viewDidLoad 中激活，并且在转场过程中不会有所变化。

// We will change the constant of this two later in `animateTransition(using:)`
let _topConstraint = searchField.topAnchor.constraint(equalTo: barContainer.topAnchor, constant: fieldTop)
let _bottomConstraint = searchField.bottomAnchor.constraint(equalTo: barContainer.bottomAnchor, constant: fieldBottom).with(priority: .defaultHigh)

var _baseConstraints = [
  _topConstraint!,
  _bottomConstraint!,
  searchField.leadingAnchor.constraint(equalTo: barContainer.safeAreaLayoutGuide.leadingAnchor, constant: 20).with(priority: .defaultHigh),
  searchField.trailingAnchor.constraint(equalTo: barContainer.safeAreaLayoutGuide.trailingAnchor, constant: -20).with(priority: .defaultHigh),
  // align stack view
  leftBarItemsStack.centerYAnchor.constraint(equalTo: searchField.centerYAnchor),
  rightBarItemsStack.centerYAnchor.constraint(equalTo: searchField.centerYAnchor)
]

with(priority:) 是修改约束优先级的扩展方法。使用了这些方法的约束是需要修改优先级的。如设置 _bottomConstraint 的优先级为 defaultHigh 可以防止滑动隐藏搜索栏时造成约束错误。

这里 _topConstraint 与 _bottomConstraint 的 fieldTop 与 fieldBottom 指的是上表中的 TextFieldY 以及 PaletteH - TextFieldH - TextFieldY。

激活时约束是在搜索栏激活的时候才激活的约束:

var _presentedConstraints = [
  leftBarItemsStack.leadingAnchor.constraint(equalTo: barContainer.safeAreaLayoutGuide.leadingAnchor, constant: spacing + 20),
  rightBarItemsStack.trailingAnchor.constraint(equalTo: barContainer.safeAreaLayoutGuide.trailingAnchor, constant: -(spacing + 20)),
  searchField.leadingAnchor.constraint(greaterThanOrEqualTo: leftBarItemsStack.trailingAnchor, constant: spacing + 16),
  searchField.trailingAnchor.constraint(lessThanOrEqualTo: rightBarItemsStack.leadingAnchor, constant: -(spacing + 16)),
]

这些约束保证将 stack view 显示出来，同时搜索栏留出空间给 stack view。

spacing 是在 stack view 左右要增加的空白。

对于 iPad，我们可以添加这些约束来实现搜索栏居中，宽度缩小:

if UIDevice.current.userInterfaceIdiom == .pad, let width = maxSearchBarWidthWhenActive {
  _presentedConstraints.append(searchField.widthAnchor.constraint(lessThanOrEqualToConstant: width))
  _presentedConstraints.append(searchField.centerXAnchor.constraint(equalTo: barContainer.centerXAnchor).with(priority: .defaultHigh))
}

非激活时约束是在搜索栏非激活的时候才激活的约束:

var _dismissedConstraints = [
  leftBarItemsStack.trailingAnchor.constraint(equalTo: barContainer.leadingAnchor, constant: -20),
  rightBarItemsStack.leadingAnchor.constraint(equalTo: barContainer.trailingAnchor, constant: 20)
]

这些约束保证非激活状态时，stack view 不会显示在屏幕上。

在 viewDidLoad 中，我们事先激活基础约束和非激活约束:

NSLayoutConstraint.activate(_baseConstraints)
NSLayoutConstraint.activate(_dismissedConstraints)

每当转场发生时，我们要更新 _topConstraint 与 _bottomConstraint 的值，并且根据搜索栏激活状态启用适当的约束:

override func animateTransition(using transitionContext: UIViewControllerContextTransitioning) {
  
  // ...

  // update constant
  _topConstraint?.constant = fieldTop
  _bottomConstraint?.constant = fieldBottom

  // toggle constraints
  if isActive {
    NSLayoutConstraint.deactivate(_dismissedConstraints)
    NSLayoutConstraint.activate(_presentedConstraints)
  } else {
    NSLayoutConstraint.deactivate(_presentedConstraints)
    NSLayoutConstraint.activate(_dismissedConstraints)
  }

  // animate changes
  UIView.animate(withDuration: transitionDuration(using: transitionContext), delay: 0, options: [.curveEaseInOut], animations: {
    // ...
    self.barContainer?.layoutIfNeeded() // remember to layout
  }) {
    transitionContext.completeTransition($0)
  }
}

修复首次转场视图错位的问题

现在，第一次激活搜索栏的时候，视图会错位。

当 hidesNavigationBarDuringPresentation 为 true 的时候，首次激活搜索框前，以及激活后的第一次转场，使用的不是我们的 SearchController。这会造成首次激活搜索框的时候视图布局和动画会出现问题，而这似乎是因为苹果在这里用的是一个占位的搜索框。目前我还没有找到直接修改这个占位搜索框的方法，但是，我们可以在 viewDidAppare(animate:) 中激活一次搜索框，随即取消激活，当然是在关闭动画的前提下。

通过把最开始两次转场的时长改为 0.001 来快速跳过动画:

var skipFirstTwoTransition: Bool = false
private var _firstEver: Bool = true

let duration = skipFirstTwoTransition && _firstEver ? 0.001 : transitionDuration(using: transitionContext)

UIView.animate(withDuration: duration, delay: 0, options: [.curveEaseInOut], animations: {
  // ...
}) {
  // ...
  if self.skipFirstTwoTransition && self._firstEver && from.isKind(of: IXSearchController.self) {
      self._firstEver = false
  }
}

在使用的时候，将 skipFirstTwoTransition 设置为 true 表示我们需要跳过前两次转场，然后在视图显示后手动激活反激活一次搜索栏:

class ViewController: UITableViewController {
  override func viewDidLoad() {
    // ...
    searchController.skipFirstTwoTransition = true
  }

  override func viewDidAppear(_ animated: Bool) {
    searchController.isActive = true
    searchController.isActive = false
  }
}

如果你有更好的办法，欢迎在 Github Repo 中发起 Pull Request。

插入取消按钮

我们编写一个方法，如果开启了自动插入取消按钮的功能，那么，如果右 stack view 中没有取消按钮，我们就插入到末尾。如果有，那我们就把它移动到末尾。否着，我们把它移除。

private func updateCancelButtonInsertation() {
  if autoInsertCancelButton {
    if rightBarItemsStack.arrangedSubviews.contains(_cancelButton) {
      // check and move cancel button to last
      if !(rightBarItemsStack.arrangedSubviews.last?.isEqual(_cancelButton) ?? true) {
        rightBarItemsStack.removeArrangedSubview(_cancelButton)
        rightBarItemsStack.insertArrangedSubview(_cancelButton, at: rightBarItemsStack.arrangedSubviews.count)
      }
    } else {
      // insert cancel button
      rightBarItemsStack.insertArrangedSubview(_cancelButton, at: rightBarItemsStack.arrangedSubviews.count)
    }
  } else {
    // remove cancel button if needed
    if rightBarItemsStack.arrangedSubviews.contains(_cancelButton) {
      rightBarItemsStack.removeArrangedSubview(_cancelButton)
      _cancelButton.removeFromSuperview()
    }
  }
}

在每次搜索栏要被激活时，我们根据情况插入或移动取消按钮的位置:

override func animateTransition(using transitionContext: UIViewControllerContextTransitioning) {
  // ...
  if isActive {
    // ...
    updateCancelButtonInsertation() // insert cancel button
  } else { /* ... */ }
  // ...
}

取消按钮只是一个普通的按钮，它被按下的时候，我们要手动反激活搜索栏，并告知代理这一事件:

@objc private func _cancelButtonDown(_ sender: UIButton) {
  isActive = false
  searchBar.delegate?.searchBarCancelButtonClicked?(searchBar)
}

插入 Search Result Controller

我们还需要插入 Search Result Controller 到视图层级中：

override func animateTransition(using transitionContext: UIViewControllerContextTransitioning) {
  let from = transitionContext.viewController(forKey: .from)!
  let to = transitionContext.viewController(forKey: .to)!

  if isActive {
    // ...
    
    // add search controller's view, where search result controller's view is presented.
    transitionContext.containerView.addSubview(to.view)
    to.view.translatesAutoresizingMaskIntoConstraints = false

    NSLayoutConstraint.activate([
      to.view.topAnchor.constraint(equalTo: transitionContext.containerView.topAnchor),
      to.view.leadingAnchor.constraint(equalTo: transitionContext.containerView.leadingAnchor),
      to.view.trailingAnchor.constraint(equalTo: transitionContext.containerView.trailingAnchor),
      to.view.bottomAnchor.constraint(equalTo: transitionContext.containerView.bottomAnchor)
    ])
            
    to.view.setNeedsLayout()
  } else {
    // ...

    // remove search controller's view
    from.view.removeFromSuperview()
  }
}

解决横竖屏转换时的布局错位

在进行横竖屏转换的时候，视图会出现布局错乱的问题，我们需要手动触发布局:

override func viewWillTransition(to size: CGSize, with coordinator: UIViewControllerTransitionCoordinator) {
  super.viewWillTransition(to: size, with: coordinator)
        
  coordinator.animateAlongsideTransition(in: coordinator.containerView, animation: { _ in
    self.barContainer?.setNeedsLayout()
    self._palette?.superview?.layoutIfNeeded()
  })
}

总结

到这里，我们就完成了对 UISearchController 子类的实现。

如果你对这感兴趣，你可以在 Github 中查看已经封装好的 IXSearchController。欢迎大家 star，提出 issue，甚至发起 pull request。

Breakpoint Radio #056

Tue, 23 Apr 2019 00:00:00 +0000

这是一档私人电台节目，每一期都为你分享来自 ix4n33 私人播放列表的电子音乐，并以 1 到 2 个小时不间断混音呈现。

修改标题栏高度

Tue, 26 Mar 2019 00:00:00 +0000

为了实现一些界面，我们经常会想要修改标题栏的高度 (确切的说是修改窗口控制按钮的位置)，来实现一些比较特殊的界面，如 Notes、Chrome、或者 QQ。

借助一体式工具栏

从 Yosemite 开始，苹果允许我们将工具栏与标题栏整合在一起。它将标题栏高度从 22 点扩展到 38 点，还将控制按钮往右移动到 12 点的位置。更重要的是，你可以使用原生工具栏。

这应该是实现标题栏高度修改的最佳方法。当然缺点也很明显，标题栏的高度仍然是固定的，你没有办法将其修改为其他值。

你只需要为你的窗口添加一个工具栏，然后将窗口的标题隐藏掉即可:

window.titleVisibility = .hidden

即便你隐藏了窗口标题，你依旧应该为你的窗口设置一个合理的标题，因为你仍能在其他地方看到它。如 Dock、Mission Control、窗口菜单等。

你也可以在这基础上使用一个空的工具栏，并将标题栏的背景隐藏，这样可以让你实现新 Mac App Store 这样的窗口:

window.titlebarAppearsTransparent = true       // transparent titlebar
window.toolbar?.showsBaselineSeparator = false // hide toolbar baseline separator
window.styleMask.insert(.fullSizeContentView)  // full size content view

手动修改视图

借助 AppKit 的一些方法，我们其实是可以获取到窗口控制按钮的对象和标题栏的。正因为如此，我们可以直接修改这些视图的 frame。这样做的对于一些需求比较特殊的用户界面比较有好处，因为标题栏的高度以及按钮的位置可以完全自定义。

主要来说，我们需要在窗口控制器中做 3 件事：

修改标题栏高度
修改窗口控制按钮位置
更新按钮的追踪区域

修改标题栏高度

我们编写一个 _updateTitlebarConstraints(with:) 方法来执行标题栏高度的修改：

private func _updateTitlebarConstraints(with notification: Notification?) { /* ... */ }

首先我们需要获取标题栏的视图对象。AppKit 在 NSWindow 中提供了 standardWindowButton(_:) 方法来允许我们获取某个指定的窗口控制按钮。窗口控制按钮很明显是放在标题栏里的，也就是标题栏的子视图。我们可以通过多次调用 superview 属性来获取父视图，也就是标题栏的视图对象:

let titlebar = window.standardWindowButton(.closeButton)?.superview?.superview
let titlebarContainer = titlebar.superview

现在我们可以使用自动布局来修改它的高度了。使用自动布局的原因是它可以避免在系统样式发生变化的时候，我们修改过的标题栏布局被系统布局所覆盖，如切换黑暗模式，或者进入退出全屏幕。

由于窗口在进出全屏幕模式时，窗口标题栏的视图层级会发生变化，因此，我们需要创建两组约束，并在合适的时候启用或禁用它们：

private var _regularConstraints: [NSLayoutConstraint] = []
private var _fullScreenConstraints: [NSLayoutConstraint] = []

_regularConstraints 数组用来存放普通模式下标题栏的约束，而 _fullScreenConstraints 数组用来存放全屏模式下标题栏的约束。

对于普通情况下的约束，我们需要在即将进入全屏时禁用掉，并且在已经退出全屏后将其重新启用；而对于全屏模式下的约束，我们需要在已经进入全屏时启用它，在即将退出全屏时将其禁用。此外，在窗口一开始显示时候，我们就要激活普通情况下的约束。

下面是普通情况下的标题栏约束:

titlebar.leadingAnchor.constraint(equalTo: titlebarContainer.leadingAnchor),
titlebar.trailingAnchor.constraint(equalTo: titlebarContainer.trailingAnchor),
titlebar.topAnchor.constraint(equalTo: titlebarContainer.topAnchor),
titlebar.heightAnchor.constraint(equalToConstant: 52).with(priority: .defaultLow)

在这里，我们通过 height anchor 指定了标题栏的高度，同时，我们将该约束设置为低优先级。这可以避免在进入全屏时发生约束冲突造成烦人的报错。

而在全屏模式下:

titlebar.leadingAnchor.constraint(equalTo: titlebarContainer.leadingAnchor),
titlebar.trailingAnchor.constraint(equalTo: titlebarContainer.trailingAnchor),
titlebar.topAnchor.constraint(equalTo: titlebarContainer.topAnchor),
titlebar.heightAnchor.constraint(equalToConstant: 22)

我们强制将标题栏的高度设置为 22，这是标准情况下窗口标题栏的高度。

对上面的代码稍加整理，你现在应该有一个这样的方法：

private var _regularConstraints: [NSLayoutConstraint] = []
private var _fullScreenConstraints: [NSLayoutConstraint] = []

private func _updateTitlebarConstraints(with notification: Notification) {
  guard
    let window = window,
    let titlebar = window.standardWindowButton(.closeButton)?.superview?.superview,
    let titlebarContainer = titlebar.superview
  else { return }
  
  titlebar.translatesAutoresizingMaskIntoConstraints = false
  
  switch notification.name {
    case NSWindow.willEnterFullScreenNotification:
      NSLayoutConstraint.deactivate(_regularConstraints)
      
    case NSWindow.didEnterFullScreenNotification:
      if _fullScreenConstraints.isEmpty {
        _fullScreenConstraints = [
          titlebar.leadingAnchor.constraint(equalTo: titlebarContainer.leadingAnchor),
          titlebar.trailingAnchor.constraint(equalTo: titlebarContainer.trailingAnchor),
          titlebar.topAnchor.constraint(equalTo: titlebarContainer.topAnchor),
          titlebar.heightAnchor.constraint(equalToConstant: 22)
        ]
      }
          
      NSLayoutConstraint.activate(_fullScreenConstraints)
      
    case NSWindow.willExitFullScreenNotification:
      NSLayoutConstraint.deactivate(_fullScreenConstraints)
      
    case NSWindow.didExitFullScreenNotification:
      fallthrough
      
    default:
      if _regularConstraints.isEmpty {
        _regularConstraints = [
          titlebar.leadingAnchor.constraint(equalTo: titlebarContainer.leadingAnchor),
          titlebar.trailingAnchor.constraint(equalTo: titlebarContainer.trailingAnchor),
          titlebar.topAnchor.constraint(equalTo: titlebarContainer.topAnchor),
          titlebar.heightAnchor.constraint(equalToConstant: 52).with(priority: .defaultLow)
        ]
      }
          
      NSLayoutConstraint.activate(_regularConstraints)
  }
}

现在我们只需要在合适的地方调用它们：

func windowWillEnterFullScreen(_ notification: Notification) {
  _updateTitlebarConstraints(with: notification)
}
    
func windowDidEnterFullScreen(_ notification: Notification) {
  _updateTitlebarConstraints(with: notification)
}
    
func windowWillExitFullScreen(_ notification: Notification) {
  _updateTitlebarConstraints(with: notification)
}
    
func windowDidExitFullScreen(_ notification: Notification) {
  _updateTitlebarConstraints(with: notification)
}

func windowDidResize(_ notification: Notification) {
  _updateTitlebarConstraints(with: notification)
}

这样，标题栏的高度就完成修改了。接下来，我们来添加标题栏中按钮的约束。

修改窗口控制按钮位置

我们同样编写一个方法：

private func _updateButtonGroupConstraints() { /* ... */ }

对于按钮，我们除了希望按钮间的间距为默认的 6 点，我们还希望它们永远垂直居中与标题栏中，并且距离窗口边缘有一定的距离：

closeButton.centerYAnchor.constraint(equalTo: titlebar.centerYAnchor),
miniaturizeButton.centerYAnchor.constraint(equalTo: titlebar.centerYAnchor),
zoomButton.centerYAnchor.constraint(equalTo: titlebar.centerYAnchor),
closeButton.leadingAnchor.constraint(equalTo: titlebar.leadingAnchor, constant: 7)
miniaturizeButton.leadingAnchor.constraint(equalTo: closeButton.trailingAnchor, constant: 6),
zoomButton.leadingAnchor.constraint(equalTo: miniaturizeButton.trailingAnchor, constant: 6),

在这个基础上，我们还可以做到更多。为了视觉美观起见，我们可以将窗口控制按钮稍微往右移一点，来给按钮更多的呼吸空间，就像系统实现一体式工具栏时那样。

默认情况下，关闭按钮距离窗口左边界的距离是 7 点，而在启用一体式工具栏时是 12 点。我们可以做一些小计算，让控制按钮根据垂直方向上与标题栏边缘的距离来让它离左边界的距离在 7 到 12 点之间浮动。

let barHeight = window.styleMask.contains(.fullScreen) ? 22 : titlebarHeight
let verticalSpacing = (barHeight - closeButton.frame.height) / 2
let leadingOffset = max(7, min(verticalSpacing + 4, 12))

然后修改关闭按钮的 leading anchor 约束的定值即可。

这样下来，你应该会有一个这样的方法：

private var _buttonsConstraints: [NSLayoutConstraint] = []
private var _buttonGroupLeadingConstraint: NSLayoutConstraint?

private func _updateButtonGroupConstraints() {
  guard
    let window = window,
    let titlebar = window.standardWindowButton(.closeButton)?.superview,
    let titlebarContainer = titlebar.superview,
    let closeButton = window.standardWindowButton(.closeButton),
    let miniaturizeButton = window.standardWindowButton(.miniaturizeButton),
    let zoomButton = window.standardWindowButton(.zoomButton)
  else { return }
        
  // calculate leading spacing for button group
  let barHeight = window.styleMask.contains(.fullScreen) ? 22 : titlebarHeight
  let verticalSpacing = (barHeight - closeButton.frame.height) / 2
  let leadingOffset = max(7, min(verticalSpacing + 4, 12))
  
  let buttons = [closeButton, miniaturizeButton, zoomButton]
  
  // create constraints if needed
  if _buttonsConstraints.isEmpty {
    buttons.forEach { $0.translatesAutoresizingMaskIntoConstraints = false }
    
    _buttonGroupLeadingConstraint = closeButton.leadingAnchor.constraint(equalTo: titlebar.leadingAnchor, constant: leadingOffset)
    
    _buttonsConstraints = [
      closeButton.centerYAnchor.constraint(equalTo: titlebar.centerYAnchor),
      miniaturizeButton.centerYAnchor.constraint(equalTo: titlebar.centerYAnchor),
      zoomButton.centerYAnchor.constraint(equalTo: titlebar.centerYAnchor),
      _buttonGroupLeadingConstraint!,
      miniaturizeButton.leadingAnchor.constraint(equalTo: closeButton.trailingAnchor, constant: 6),
      zoomButton.leadingAnchor.constraint(equalTo: miniaturizeButton.trailingAnchor, constant: 6)
    ]
    
    // activate constraints
    NSLayoutConstraint.activate(_buttonsConstraints)
  }
  
  // update leading constant
  _buttonGroupLeadingConstraint?.constant = leadingOffset
  titlebarContainer.layoutSubtreeIfNeeded()
}

我们需要在下面这些代理方法中调用:

func windowDidEnterFullScreen(_ notification: Notification) {
  // ...
  _updateButtonGroupConstraints()
}
    
func windowDidExitFullScreen(_ notification: Notification) {
  // ...
  _updateButtonGroupConstraints()
}

func windowDidResize(_ notification: Notification) {
  // ...
  _updateButtonGroupConstraints()
}

更新按钮的追踪区域

最后，有一个小问题需要解决，那就是按钮的追踪区域。我们修改了按钮的位置，但是，用来实现鼠标悬浮效果的追踪区域还没有改变。

这个最终区域存放在 theme frame (也就是 titlebar 的父视图) 的 trackingAreas 里，并且，它是在数组内唯一一个包含 NSTrackingArea.Options.activeAlways 的元素。所以，我们可以获取到这个追踪区域，移除它，然后添加一个新的追踪区域。我们同样编写一个方法：

private func _updateButtonGroupTrackingArea(buttons: [NSView]) {
  let themeView = buttons.first?.superview?.superview?.superview
  
  if let trackingArea = themeView?.trackingAreas.first(where: { $0.options.contains(.activeAlways) }) {
    // create a new tracking area with latest tracking rect
    let trackingRect = buttons.reduce(NSZeroRect, { $0.union($1.frame) })
    let newTrackingArea = NSTrackingArea(rect: trackingRect, options: trackingArea.options, owner: trackingArea.owner, userInfo: trackingArea.userInfo)
    // replace the tracking area
    themeView?.removeTrackingArea(trackingArea)
    themeView?.addTrackingArea(newTrackingArea)
  }
}

你也可以通过调用
titlebar.superview?.viewDidEndLiveResize()
来让间接让系统更新 tracking area。

每当我们修改了按钮的位置，我们就更新追踪区域，也就是说，我们在 _updateButtonGroupConstraints 方法的最后调用该方法即可:

private func _updateButtonGroupConstraints() {
  // ...
  _updateButtonGroupTrackingArea(buttons: buttons)
}

小结

不出意料的话，你应该可以看到如下图这样的窗口，并且，它能够很好的兼容全屏模式与黑暗模式的切换。

需要注意的是，但你使用第二种方法来自定义窗口标题高度时:

标题栏的可拖拽范围没有变化。不管标题栏的高度怎么变，你能进行窗口拖拽的区域没有发生变化。我们仍然没能找到修改这个区域的比好的方法，但是我们的确有其他方法可以解决这一问题：
- 将窗口的 isMovableByWindowBackground 属性设置为 true。
- 提供重写了 mouseDownCanMoveWindow 属性的自定义视图。
- 提供重写了 mouseDown(with:) 并调用窗口的 performDrag(with:) 方法的自定义视图。
与工具栏的兼容性不佳。你虽然可以修改标题栏的高度，但是我们仍然没有找到修改工具栏视图位置的方法。这意味着，即便你修改了标题栏的高度，工具栏仍然会显示在标题栏顶部，而非居中。

这里将标题栏背景显示出来，只是为了更加方便的演示。在实际情况中，你几乎永远都会将它隐藏，并配合 .fullSizeContentView style mask 来添加你自己的假标题栏。你也可以直接抛弃假标题栏，充分利用这一空间来显示你的应用内容。

A Small Trick to Hide NSPopover's Arrow

Wed, 08 Aug 2018 00:00:00 +0000

A friend of mine who works as a macOS developer asked me a strange question - can you hide the arrow of a popover?

This is strange to me because IMO the arrow give you a sence of context, indicating where the popover is pop from, and imply the relation of its content. There’s no reason to hide the arrow from the first place.

Any way, back to the question. Is it possible to hide the arrow?

The anwser is yes, but this is not tweaking a knob in interface builder nor changing a variable programmatically.

Here is how it works.

Say you have a scroll view, and a button on it, which present a popover relatively to the button when clicked.

Now scroll it til the button is away from visible rect. Guess what happend? The arrow of the popover will follow the button and when the button is outside visible rect, the arrow disappear!

That is a default behvaior of popover we can make use of. The arrow of popover is always point to it’s positioning view when it’s possible, and hide itself when the positioning view is not visiable.

That means all we need to do is:

Create a different positioning view.
Create the popover.
present the popover.
Move positioning view off visible rect.

And now you have presented a popover with no arrow!

var popover: NSPopover?
var positioningView: NSView?

@IBAction func showPopover(_ sender: NSButton) {
    positioningView = NSView()
    positioningView?.frame = sender.frame
    view.addSubview(positioningView!, positioned: .below, relativeTo: sender)

    popover = NSPopover()
    // configure popover here

    popover?.show(relativeTo: .zero, of: positioningView!, preferredEdge: .maxX)

    positioningView?.frame = NSMakeRect(0, -200, 10, 10)
}

This trick also works if you want to use a popover as a statusbar menu.

In your status item button’s action callback method, simply add a positioning view as a subview of the status item button:

@IBAction func statusItemButtonDidPushed(_ sender: NSButton) {
    // add positioning view as a suview of sender, that is, `statusItem.button`.
    let positioningView = NSView(frame: sender.bounds)
    // set an identifier for positioning view, so we can easily remove it later.
    positioningView.identifier = NSUserInterfaceItemIdentifier(rawValue: "positioningView")
    sender.addSubview(positioningView)

    // show popover
    popover.show(relaticeTo: posotioningView.bounds, of: positioningView, preferredEdge: .maxY)
    // move positioning view away
    sender.bounds = sender.bounds.offsetBy(dx: 0, dy: sender.bounds.height)
}

Later, when the popover is closed, we can remove the positioning view from view hierarchy. This is often done in popover’s deelgate method popoverDidClose(_:):

func popoverDidClose(_ notification: Notification) {
    let positioningView = statusItem.button?.subviews.first { 
        $0.identifier == NSUserInterfaceItemIdnetifier(rawValue: "positioningView") 
    }
    positioningView?.removeFromSuperview()
}

You may find the gap between the statusbar and the popover is a bit large. In this case, you can also move the popover up a bit by setting its window’s frame:

if let popoverWindow = popover.contentViewController?.view.window {
    popoverWindow.setFrame(popoverWindow.frame.offsetBy(dx: 0, dy: 10), display: false)
}

配置一个可调试的偏好设置面板项目

Sat, 04 Aug 2018 00:00:00 +0000

在 Xcode 中创建一个偏好设置面板项目时，你会发现这个项目时无法运行的。你虽然可以使用 Console.app 来显示你的 NSLog 输出，但这失去了 Xcode 实时调试的优势。

其实，我们是可以为设置面板添加可执行的。

在 Xcode 中:

选择 Product → Scheme → Edit Scheme…
在弹出的面板左上角选中你的偏好设置面板 Target
在左栏选择 Run
在右栏 Info → Executable 下拉框中选择 Other…
找到并选择你的系统偏好设置，它一般位于 ~/Applications/System Preferences.app
关闭面板

现在，当你运行项目时，系统偏好设置将被打开。首次打开将会提示安装你的面板，往后，只要你进入你的面板，便可以开始使用 Xcode 进行调试。

你需要关闭系统 SIP 才能使用这一方法。

关闭或重启电脑

电脑启动时，按住 ⌘R 不松开，进入 Recovery 模式

进入 Recovery 模式后，选择语言，在上方菜单栏中的工具一项中选择终端

在终端中输入 csrutil disable

重启

你可以在开发完成后重新开启 SIP。重复上面的操作，在第 4 步时，输入 csrutil enable。

如果你不嫌烦的话，通过 Debug → Attach To Process 连上 System Preferences.app 也是可行的。当然，这也要求你关闭 SIP。

使 NSTextField 的文本垂直居中

Thu, 12 Jul 2018 00:00:00 +0000

在进行界面开发的时候，很多时候我们都会想要制作一个看起来更加现代的输入框，而这往往需要修改输入框的高度。最后，你会发现，输入框的文字是上对齐的。并且，NSTextField 没有提供现成的方法来修改文本在垂直方向上的对齐位置。

为了修改文本在垂直方向上的位置，我们将会需要自行实现一个 NSTextField，确切来说，是 NSTextFieldCell。

NSTextField 中的文字是通过绘图绘制在上面的，而实际进行的绘制是在 Cell 中进行的。NSTextFieldCell 中有几个方法值得我们的注意:

drawInterior(withFrame:in:): 这个方法绘制的是 Text Field 内部元素。主要是文字，但是不包括背景和边框。
select(withFrame:in:editor:delegate:start:length:): 这个方法绘制的是编辑状态时 Text Field 内部元素，包括文字，选中的高亮等，但是同样不包括背景和边框。

我们虽然可以直接重写这两个方法来进行自定义绘制，但是这样难免太繁琐。实际上，这两个方法都是根据传入的 frame 进行绘制的。我们可以对这个 frame 稍加修改，让系统绘制到我们所期望的位置上。

NSTextFieldCell 中有另外一个方法:

titleRect(forBounds:): 这个方法返回以传入 frame 为边界的绘制文字所需要的 frame。

我们可以借助这个方法来很方便的计算出正确的绘制文字的 frame。

首先，我们重写 titleRect(forBounds:) 方法，将绘制的 frame 往下移动一部分:

class VerticalCenteredTextFieldCell: NSTextFieldCell {
  override func titleRect(forBounds rect: NSRect) -> NSRect {
    // call super to get its original rect
    var rect = super.titleRect(forBounds: rect)
    // shift down a little so the draw rect is vertically centered in cell frame
    rect.origin.y += (rect.height - cellSize.height) / 2
    // finally return the new rect
    return rect
  }
}

然后，我们在 drawInterior(withFrame:in:) 和 select(withFrame:in:editor:delegate:start:length:) 这两个方法中传入经过我们修改的值:

class VerticalCenteredTextFieldCell: NSTextFieldCell {
  override func drawInterior(withFrame cellFrame: NSRect, in controlView: NSView) {
    // call super and pass in our modified frame
    super.drawInterior(withFrame: titleRect(forBounds: cellFrame), in: controlView)
  }

  override func select(withFrame rect: NSRect, in controlView: NSView, editor textObj: NSText, delegate: Any?, start selStart: Int, length selLength: Int) {
    // call super and pass in our modified frame
    super.select(withFrame: titleRect(forBounds: rect), in: controlView, editor: textObj, delegate: delegate, start: selStart, length: selLength)
  }
}

这样就好了，我们的 VerticalCenteredTextFieldCell 将会将文字居中绘制在 TextField 中。

现在我们可以将我们自己的 VerticalCenteredTextFieldCell 来替换 NSTextField 中的 cell 了。但是，由于我们替换了 cell，这意味着系统生成 NSTextField 的时候对 cell 进行的配置会被重制。我们还需要对这些属性进行重新配置:

let textField = NSTextField(frame: .zero)
// first replace the cell to out custom one
textField.cell = VerticalCenteredTextFieldCell(textCell: "")
// then reset the text field's default value
textField.isBordered = true
textField.backgroundColor = NSColor.controlBackgroundColor
textField.isBezeled = true
textField.bezelStyle = .squareBezel
textField.isEnabled = true
textField.isEditable = true
textField.isSelectable = true
textField.cell?.isScrollable = true

上面展示的是纯代码替换 cell。如果你使用的是 Interface Builder，你只需要将 text field 下的 cell 类改成我们重写的这个类即可。

我们通过这样的方法将文本进行垂直居中。实际上，对上面的代码稍加修改，我们可以让文本显示在任何地方，从而实现如上对齐、下对齐等效果。

这一方法同样适用于 NSSecureTextField，你只需要重写 NSSecureTextFieldCell 即可。

Rotating a View Is Simple Not Easy

Thu, 21 Dec 2017 00:00:00 +0000

So I was asked to do a easy feature recently, provide two button to rotate a image view 90 degree clockwise or counterclockwise with animation. How hard could it be?

NSView provide a handy variable called frameCenterRotation, which define the rotation angle of the view around the underlying layer’s anchorPoint.

This is also an animatable property, so all we need is to set frameCenterRotation using animator():

imageView.animator().frameCenterRotation += 90

Easy piece of cake.

Wait, what?

Let’s slow it down for a little bit:

It looks like the layer’s anchorPoint is also animated from 0 to 0.5, which should be 0.5 by default as suggested in this document:

… The default value of this property is (0.5, 0.5), which represents the center of the layer’s bounds rectangle.

Even if you change the anchorPoint manually to 0.5:

let layer = imageView.layer
print(layer.anchorPoint) // (0, 0)

layer.anchorPoint = CGPoint(x: 0.5, y: 0.5)
print(layer.anchorPoint) // (0.5, 0.5)

imageView.animator().frameCenterRotation += 90

print(layer.anchorPoint) // (0, 0)

It was changed back to 0.

This lead us to a conclusion:

The cake is a lie.

The best guess is that in the setter of frameCenterRotation, it first set its layer’s a anchor point to center, then it do the rotation, and finally set the anchor point back to zero.

But when setting it through an animator proxy, it animates everything. What it really should be is to set the anchor point with animation disabled, then animates the rotation, and then finally, in the animation completion, set anchor point back to what it was with, of course, animation disabled.

The Workaround

Calling frameCenterRotation is a death end, now we need to find a way to rotate it on our own.

Other than firing a bug report that most likely won’t be fixed, luckily, we can modify layer properties directly:

let rotation = CATransform3DMakeRotation(n * CGFloat.pi / 2, 0, 0, 1) // n is a CGFloat with an initial value of 0. 
imageView.animator().layer?.transform = rotation
n += 1

The above code rotate the layer 90 degrees counterclockwise every time it gets runs.

It rotate! But not about its center, and there’s no animation. We still need to change the anchorPoint to center:

layer.anchorPoint = CGPoint(x: 0.5, y: 0.5)

Now it do rotate about layer’s center, but it jumps to bottom left, the origin point of its frame. To fix this, we need to also change its position:

layer.position = CGPoint(x: layer.frame.midX, y: layer.frame.midY)

What about the animation? We already use animator() to animate the property changes?

That is because, by default, AppKit disables implicit animations for its layer-backed views. Since we are animating layer properties directly, we need to programmatically reenable implicit animations in current context:

NSAnimationContext.current.allowsImplicitAnimation = true

Now that’s what I called a rotation!

Complete Code

var n: CGFloat = 1

func rotate(_ sender: NSButton) {
    if let layer = imageView.layer, let animatorLayer = imageView.animator().layer {
        layer.position = CGPoint(x: layer.frame.midX, y: layer.frame.midY)
        layer.anchorPoint = CGPoint(x: 0.5, y: 0.5)

        NSAnimationContext.beginGrouping()
        NSAnimationContext.current.allowsImplicitAnimation = true
        animatorLayer.transform = CATransform3DMakeRotation(n * CGFloat.pi / 2, 0, 0, 1)
        NSAnimationContext.endGrouping()

        n += 1
    }
}

Device	Portrait			Landscape
Device	PaletteH	TextFieldH	TextFieldY	PaletteH	TextFieldH	TextFieldY
Any	52	36	1	52	36	1

ix4n33's Blog

制作一个照片预览视图

了解滑动视图的原理

在裁剪视图里居中文件视图

修复初滑动的跳动问题

放大、缩小与自适应缩放

又谈 NSVisualEffectView

变通方法

其实我们有个更好的方法

搭配标签栏控制器使用分栏视图控制器

概念

创建 UISplitViewController 子类

变更默认显示详情视图控制器的行为

同步取消选中项

在分栏视图布局变化时重新分配控制器

解决选中项丢失的问题

在切换便签页时切换详情栏内容

AppKit 中的窗口释放策略

通过 Storyboard Segue 打开的窗口

通过 Storyboard Entry Point 打开的窗口

通过纯代码创建由窗口控制器管理的窗口

通过纯代码创建的窗口

Sidenote: 关于 isReleasedWhenClosed

侧边栏菜单设计

实现基本框架

侧边栏视图控制器

标签视图控制器

视图控制器之间的数据交流

附加内容

效果更佳的高亮效果

效果更佳的侧边栏分割线

通过拖动侧边栏来拖动窗口

双击侧边栏空白区域来放大或缩小窗口

非活动窗口的快速拖动

Spotlight 式窗口设计

使用 NSPanel 实现 Spotlight 式窗口

窗口的显示与隐藏

附加内容

典型程序设计

键盘事件的监听与转发

懒加载视图或窗口控制器中的管理对象

实现程序自启动的最佳实践

使用 Service Management 框架实现自启动

创建并配置启动项

在启动项中启动主程序

在主程序中注册启动项

读取启动项状态

小结

折叠或隐藏菜单中的菜单项

使用替代菜单项来折叠菜单项

按住修饰键打开菜单来显隐菜单项

仅在按下修饰键时显示菜单项

获取人类可读的文件类型描述

UTIs 简介

获取指定 UTI 的本地化描述信息

为未提供本地化描述的 UTIs 提供通用描述

小结

Breakpoint Radio #057

记一次 HC5661 的救砖过程

刷入 0.9005.4778s 版本固件

后续: 刷入 Breed

小结

获得文本框焦点回调事件

Field Editor

获取事件

创建回调方法

小结

为 NSVisualEffectView 设定自定义颜色

方法 1: 修改 Layer 背景颜色

方法 2: 添加一个颜色叠加视图

小结

使用代码打开指定偏好设置面板

找到偏好设置面板

方法 1: 使用 URL Scheme 打开指定面板

方法 2: 使用 AppleScript 打开指定面板

小结

然后我就病了

一个全新的开始

为 UISearchController 添加额外的按钮

计划

创建 `UISplitViewController` 子类

Sidenote: 关于 `isReleasedWhenClosed`

使用 `NSPanel` 实现 Spotlight 式窗口