Итак, самый простой путь понять, как работает инструмент, это посмотреть на код и результат. Поэтому, без долгих предисловий, я привожу пример самого распространенного применения. И, также, хочу заметить, что подобное применение уже достаточно активно используется в моем рабочем проекте iOS СберБизнес, и на данный момент побочных эффектов к счастью не замечено 😊.

Тут у нас HStack с иконкой и вложенным VStack. И мы выравниваем иконку по центру второго текста в HStack (голубая стрелка показывает направление горизонтальной выравнивающей). Читать подобный код надо с того места, где расположен вызов .alignmentGuide.

Тогда смысл этого кода звучит примерно так: Text("Sorting keys..") задает кастомный горизонтальный центр customHorizontalCenter для HStack(alignment: .customHorizontalCenter).

Код

struct HorizontalCenterExample: View {
    
    var body: some View {
        
        HStack(alignment: .customHorizontalCenter, spacing: 16) {
            Image(systemName: "sun.min.fill" )
            VStack(alignment: .leading, spacing: 16) {
                
                Text("Theme")
                    .font(.title)
                    .border(.green)
                
                Text("Sorting keys for json encoding")
                    .font(.title2)
                    .border(.green)
                    .alignmentGuide(.customHorizontalCenter, computeValue: {
                        $0[VerticalAlignment.center]
                    })
                
                Text("The JsonObject representation will preserve insertion order, whether you build the object with empty and add or with from or fromIterable ")
                    .border(.green)
         
            }
        }
        .border(Color.red)

    }
}

extension VerticalAlignment {
    
    private enum CustomHorizontalCenter: AlignmentID {
        static func defaultValue(in context: ViewDimensions) -> CGFloat {
            context[VerticalAlignment.center]
        }
    }
    static let customHorizontalCenter = VerticalAlignment(CustomHorizontalCenter.self)
}

Второй пример практически аналогичен первому, кроме того, что тут используется вертикальное выравнивание, вместо горизонтального. И, кстати, тут довольно много путаницы с горизонталями и вертикалями, поэтому нужно быть аккуратным в нейменге, чтобы не запутался самому и не запутать других.

Смысл этого кода звучит примерно так: Зеленый прямоугольник задает кастомный вертикальны центр customVerticalCenter для VStack(alignment: .customVerticalCenter).

Код

struct VerticalCenterExample: View {

    var body: some View {

        VStack(alignment: .customVerticalCenter, spacing: 16) {
            
            Image(systemName: "sun.min.fill")
                .foregroundStyle(.green)
            
            HStack(alignment: .top, spacing: 16) {
                
                Rectangle()
                    .foregroundStyle(.yellow)
                    .frame(width: 50, height: 100)
                Rectangle()
                    .foregroundStyle(.blue)
                    .frame(width: 120, height: 100)
                Rectangle()
                    .foregroundStyle(.green)
                    .frame(width: 100, height: 100)
                    .alignmentGuide(.customVerticalCenter, computeValue: {
                        $0[HorizontalAlignment.center]
                    })
            }
        }
        .border(Color.red)
    }
}

extension HorizontalAlignment {
    
    struct CustomVertivalCenter: AlignmentID {
        
        static func defaultValue(in context: ViewDimensions) -> CGFloat {
            context[HorizontalAlignment.center]
        }
    }
    static let customVerticalCenter = HorizontalAlignment(CustomVertivalCenter.self)
}

Modifier AlignmentGuide

Надеюсь, приведенные примеры и комментарии помогли понять как работает модификатор AlignmentGuide, и теперь посмотрим на его синтаксис:

func alignmentGuide(_ g: HorizontalAlignment, computeValue: @escaping (ViewDimensions) -> CGFloat) -> some View

func alignmentGuide(_ g: VerticalAlignment, computeValue: @escaping (ViewDimensions) -> CGFloat) -> some View

Используйте модификатор alignmentGuide(_:computeValue:) чтобы рассчитать специфические смещения Views относительно друг друга. Смещение рассчитывается в замыкании computeValue через параметр типа ViewDimensions.

Тип ViewDemensions

public struct ViewDimensions {
    
    var width: CGFloat
    var height: CGFloat

    /// Implicit guides
    subscript(guide: HorizontalAlignment) -> CGFloat
    subscript(guide: VerticalAlignment) -> CGFloat

    /// Explicit guides
    subscript(explicit guide: HorizontalAlignment) -> CGFloat?
    subscript(explicit guide: VerticalAlignment) -> CGFloat?
}

ViewDemensions - это тип, который передается в замыкание и представляет метрики локального View в системе его локальных координат. Структура ViewDemensions имеет параметры width и height, а также сабскрипты для доступа к горизонтальному и вертикальному alignment-ам. Вот так это выглядит в коде:

Rectangle()
    .alignmentGuide(.customVerticalCenter, computeValue: { dimension in
         dimension[HorizontalAlignment.center] - dimension.width / 4]
     })

Сабскрипты ViewDimensions в модификаторе alignmentGuide могут вызываться для явных и неявных alignment guide:

subscript(guide: HorizontalAlignment) // неявный (Implicit) alignment
subscript(explicit guide: HorizontalAlignment) // явный (Explicit) alignment

Давайте на простом примере разберемся, что это означает.

Implicit & Explicit Alignments

Каждый контейнер имеет выравнивание (alignment), который отвечает за расположение дочерних элементов. И дочерние элементы неявно (Implicit) получают этот alignment. Метод .alignmentGuide задает явный (Explicit) alignment у элемента.

Давайте посмотрим это на простом как работают Implicit и Explicit Alignments.

Код

VStack(alignment: .leading) {

    // Смотрим различия между значениями dimension в 1-м и 2-м замыкании 
    Rectangle()
        .foregroundColor(.yellow)
        .frame(width: 120, height: 50)
        .alignmentGuide(.leading, computeValue: { dimension in
            // dimension[.leading] == 0
            // dimension[explicit: .leading]) == nil
            dimension[.trailing]
        })
        .alignmentGuide(.leading, computeValue: { dimension in
            // после добавления .alignmentGuide выше, появилось значение 120
            // dimension[.leading] == 120
            // dimension[explicit: .leading]) == Optional(120.0)
            dimension[.trailing]
        })

    // Значения dimension не накапливаются, относятся только к локальному View
    Rectangle()
        .foregroundColor(.red)
        .frame(width: 100, height: 50)
        .alignmentGuide(.leading, computeValue: { dimension in
            // dimension[.leading] == 0
            // dimension[explicit: .leading]) == nil
            dimension[.trailing]
        })
        .alignmentGuide(.leading, computeValue: { dimension in
            // после добавления .alignmentGuide выше, появилось значение 100
            // dimension[.leading] == 100.0
            // dimension[explicit: .leading]) == Optional(100.0)
            dimension[.trailing]
        })

     // explicit nil != implicit 0 (так только в .leading)
     Rectangle()
        .foregroundColor(.yellow)
        .frame(width: 120, height: 50)
        .alignmentGuide(.leading, computeValue: { dimension in
            // dimension[.trailing] == 120
            // dimension[explicit: .trailing]) == nil
            dimension[.trailing]
        })
    }
}

Здесь нужно обратить внимание на несколько моментов:

Явный (Explicit) alignment опционален. Он получает значения только, если перед его вызовом явно указан модификатор alignmentGuide.
Неявный (Implicit) alignment не опционален. Если Explicit alignment определен, то значения Implicit и Explicit равны. Иначе, неявный alignment отдает значения выравнивания, вычисленное от родительского контейнера.
Значения alignments у дочерних прямоугольников не зависимы, не происходит накопление смещения в нашем примере, хотя такое поведение могло бы показаться логичным. Таким образом, с помощью этих значений нельзя построить "ступеньки" с нарастающим отступом.
Для контейнера можно задать только один alignment. Нельзя, например, использовать одновременно .leading и .trailing выравнивание, что ограничивает применение инструмента. Замечу, что система выравнивания в ZStack более сложная, тем не менее там тоже один alignment, хотя и композитный.

AlignmentGuid другие примеры использования:

Еще один интересный пример, вероятно, вы уже видели в разных источниках (в конце статьи я приведу весь список источников, которые были мне полезны).

Здесь у нас нет вложенных стеков, только один HStack, с пятью прямоугольниками. И каждый черный прямоугольник, вернее его .bottom, задает новый .top в HStask (голубая стрелка), от которого выравниваются все цветные прямоугольники в этом стеке

Код

struct DiagramHorizontalExample: View {
    
    var body: some View {

        HStack(alignment: .top, spacing: 0) {
            
            Rectangle()
                .frame(width: 50, height: 100)
                // The Rectangle define new top guide for HStack
                // other Rectangles will start from it
                .alignmentGuide(.top, computeValue: { dimension in
                    dimension[.bottom] + 10
                })
            
            Rectangle()
                .foregroundStyle(.blue)
                .frame(width: 60, height: 40)
            
            Rectangle()
                .frame(width: 70, height: 50)
                .alignmentGuide(.top, computeValue: { dimension in
                    dimension[.bottom] + 10
                })
            
            Rectangle()
                .foregroundStyle(.red)
                .frame(width: 50, height: 50)
            
            Rectangle()
                .frame(width: 80, height: 40)
                .alignmentGuide(.top, computeValue: { dimension in
                    dimension[.bottom] + 10
                })
        }
        .padding()
        .border(.red)
    }
}

Допустим, мы хотим немного модифицировать данный пример, и добавить голубой дивайдер между черными и цветными прямоугольниками. Для этого придется создать новую направляющую выравнивания middleLine, в которую мы сохраним top-значение синего прямоугольника (можем и красного: любого цветного). А также добавим код:

.overlay(alignment: .init(horizontal: .center, vertical: .middleLine))

Overlay работает по аналогии с ZStack. Немного ранее я упоминала, что ZStack имеет композитное выравнивание, и именно так оно выглядит. Голубой горизонтальный разделитель мы выравниваем по вертикали по алигнменту, который задал синий прямоугольник. А по горизонтали он занимает всю длину, поэтому тут параметр особого значения не будет иметь, и я указала .center.

Код

struct DiagramHorizontalDivided: View {
    
    var body: some View {
        
        HStack(alignment: .top, spacing: 0) {
            
            Rectangle()
                .frame(width: 50, height: 100)
                .alignmentGuide(.top, computeValue: { dimension in
                    dimension[.bottom] + 10
                })
           
            Rectangle()
                .foregroundStyle(.blue)
                .frame(width: 60, height: 40)
                .alignmentGuide(.middleLineTop, computeValue: { dimension in
                    dimension[.top]
                })
            
            Rectangle()
                .frame(width: 70, height: 50)
                .alignmentGuide(.top, computeValue: { dimension in
                    dimension[.bottom] + 10
                })
            
            Rectangle()
                .foregroundStyle(.red)
                .frame(width: 50, height: 50)
            
            Rectangle()
                .frame(width: 80, height: 40)
                .alignmentGuide(.top, computeValue: { dimension in
                    dimension[.bottom] + 10
                })
            
        }
        .overlay(alignment: .init(horizontal: .center, vertical: .middleLine)) {
            Rectangle()
                .foregroundStyle(.cyan)
                .frame(height: 2)
        }
        .padding()
        .border(.red)
    }
}

extension VerticalAlignment {
    
    private enum MiddleLine: AlignmentID {
        static func defaultValue(in context: ViewDimensions) -> CGFloat {
            context[VerticalAlignment.bottom] + 4
        }
    }
    static let middleLine = VerticalAlignment(MiddleLine.self)
}

AlignmnetGuide и альтернативы

Несмотря на то, что инструмент имеет достаточно многословный синтаксис, пока я увидела ограниченное количество задач, где он бесспорно полезен. Это я к тому, что не торопитесь прикручивать AlignmentGuide там, где можно найти решения попроще. Нашла вот такой пример: верстка с помощью Grid выглядит лучше, а код - понятнее. Оба решения привожу.

Код с AlignmentGuid

struct TwoTextColumns: View {
    
    var body: some View {
        
        VStack(alignment: .custom, spacing: 16) {
            
            HStack {
                Text("Username").font(Font.body.bold())
                // trailing of the second text will be a leading for children of VStack
                Text("Tatyana")
                    .alignmentGuide(.custom) { $0[.leading] }
            }
            HStack {
                Text("Password").font(Font.body.bold())
                Text("•••••••••••••••••")
                    .alignmentGuide(.custom) { $0[.leading] }
            }
            HStack {
                Text("Email").font(Font.body.bold())
                Text("black@mail.ru")
                    .alignmentGuide(.custom) { $0[.leading] }
            }
        }
        .padding(.all, 16)
        .border(.blue)
    }
}

Код с Grid

struct TwoTextColumnsGrid: View {
    
    var body: some View {
        
        Grid(alignment: .leading, verticalSpacing: 8) {
            GridRow() {
                Text("Username").font(Font.body.bold())
                Text("Tatyana")
            }
            GridRow {
                Text("Password").font(Font.body.bold())
                Text("•••••••••••••••••")
            }
            GridRow() {
                VStack(alignment: .leading) {
                    Text("Email").font(Font.body.bold())
                    Text("Обязательное поле")
                        .font(Font.caption)
                        .foregroundColor(.gray)
                }
                Text("black@mail.ru")
            }
        }
        .padding(.all, 16)
        .border(.blue)
    }
}

И вот такой пример, возможно, полезен для понимания работы .alignmentGuide, но на мой взгляд, реализация через .padding выглядит гораздо понятнее.