🅿️PreferenceKey

⭐️ 重點

The PreferenceKey protocol enables a way to send data up the view hierarchy. 👉 SwiftOnTap

當一開始佈局時 (layout)，就要子視件回報一些資料給母視件才能順利完成佈局的話，就可以考慮使用 PreferenceKey。

🔸 定義

// ------------------------
//     🅿️ PreferenceKey
// ------------------------

public protocol PreferenceKey {
    // value type
    associatedtype Value
    // default value
    static var defaultValue: Self.Value { get }
    // combine values from different children
    static func reduce(
        value    : inout Self.Value, 
        nextValue: () -> Self.Value
    )
} 

// ------------------------
//     View methods
// ------------------------

// 🔸 (child view) set view preference
func preference<K: PreferenceKey>(
    key  : K.Type = K.self, 
    value: K.Value
) -> some View 

// 🔸 .onPreferenceChange()
// (parent view) react to view preference change
func onPreferenceChange<K>(
    _          key: K.Type = K.self, 
    perform action: @escaping (K.Value) -> Void
) -> some View where 
    K       : PreferenceKey, 
    K.Value : Equatable

// 🔸 .overlayPreferenceValue(key:transform:)
func overlayPreferenceValue<Key: PreferenceKey, T: View>(
    _       key: Key.Type = Key.self, 
    _ transform: @escaping (Key.Value) -> T
) -> some View 

// 🔸 .backgroundPreferenceValue(key:transform:)
func backgroundPreferenceValue<Key: PreferenceKey, T: View>(
    _       key: Key.Type = Key.self, 
    _ transform: @escaping (Key.Value) -> T
) -> some View

📘 手冊

• SwiftOnTap ⟩ PreferenceKey

• SwiftUI ⟩

  • State & Data Flow ⟩ PreferenceKey

    • .reduce(value:nextValue:)

  • Views & Controls ⟩ View ⟩ State ⟩

    • .preference(key:value:)

    • .onPreferenceChange(_:perform:)

📗 參考

• AppCoda ⟩ 透過 PreferenceKey 對齊視圖

• Ray ⟩ SwiftUI View Preferences Tutorial for iOS

• Samwise ⟩ How to Layout in SwiftUI?

• FIVE STAR ⟩

  • How to read a view size in SwiftUI

  • How SwiftUI's Preference Keys are propagated - about reduce().

• The SwiftUI Lab ⟩

  • Inspecting the View Tree – Part 1: PreferenceKey

  • Inspecting the View Tree – Part 2: AnchorPreferences

  • View Extensions for Better Code Readability

• Swift with Majid ⟩

  • The magic of view preferences in SwiftUI

  • Anchor preferences in SwiftUI

👥 相關

• can cause subtle problems, 👉 problem with .readSize().

• Preferences

• 📦 PreferenceKeys

• 📦 Anchor

• .badge()

• Adaptive Layout

範例

📦 MaxValue

// 📦 MaxValue<T: FloatingPoint>
public struct MaxValue<T: FloatingPoint>: PreferenceKey {
    // value type
    public typealias Value = T?
    // default value (nil == not set) 
    public static var defaultValue: Value { nil }
    // ⭐️ choose max value
    public static func reduce(value: inout Value, nextValue: () -> Value) {
        // ⭐️ [T?] --(compactMap)--> [T] --(max)--> T?
        value = [value, nextValue()].compactMap{ $0 }.max()
    }
}

📦 AllValues

// 📦 AllValues<T>
public struct AllValues<T>: PreferenceKey {
    // ⭐️ 收集的資料放在 [T] 裡面
    public typealias Value = [T]
    // ⭐️ 初始值：空陣列
    public static var defaultValue: Value { Value() }
    // ⭐️ 加入新資料的方法：[v1, v2, ...] + [vn]
    public static func reduce(value: inout Value, nextValue: () -> Value) {
        value += nextValue()   // nextValue() == [vn]
    }
}

📦 FirstNonNil

// 📦 FirstNonNil<T>
public struct FirstNonNil<T>: PreferenceKey {
    public typealias Value = T?
    // default value
    public static var defaultValue: Value { nil }
    // combine values from different child views
    public static func reduce(value: inout Value, nextValue: () -> Value) {
        value = value ?? nextValue()   // nil or first non-nil value
    }
}

💈 範例

• 💈 對齊欄位 (MaxWidth = MaxValue<CGFloat>)

• 💈 MonthView (Frames = AllValues<CGRect>)

• 💈 CircleText (MaxSide = FirstNonNil<CGFloat>)

👥 相關

• 🌀View + pref ⭐

• 📦 PreferenceKeys

• Anchor Preferences

• Preferences

用法

設 K 為遵循 PreferenceKey 的真實型別 (concrete type)，則使用這個 PreferenceKey 時，通常必須具備以下「三大要素」：

• K 本身：負責定義如何「處理子視件回報的值」

• 母視件的 @State 變數：通常型別與 K.Value 相同，負責「更新子視件的佈局」。

• 子視件的 @Binding 變數：負責「承接來自母視件的更新通知」。

有了這些要素後，還要依照固定的模式，才能順利完成佈局，主要是以下的「三步驟」：

• 由子視件回報值給 K：用 child.preference(key:value:) 回報

• 由 K 負責處理回報的值：用 K.reduce(value:nextValue) 處理

• 由母視件根據回報的值，更新自己的 @State：用 parent.onPreferenceChange(_:perform:) 處理

整個流程可以簡化為：

• 子視件回報 ➜ PreferenceKey 處理 ➜ 母視件更新

👉 比較：Anchor Preferences

⭐️ 取名原則

PreferenceKey 的名字最好是跟母視件的 @State 變數一致，例如： 如果我們要找的是某個子視件兩邊長中的最大邊，這時可以：

• 將母視件的 @State 變數取名為： maxSide

• 而 PreferenceKey 就取名為: MaxSide

👉 參見：💈 CircleText

👉 自製型別：📦 PreferenceKeys