Write UIKit UI code declaratively with Construkt

分类: 开发与编程 | 上传者: MainActorDev | 下载: 0 | 版本: v1.0（最新）

使用 Construkt 框架（UIKit 的 SwiftUI 语法）生成声明性 UIKit 代码的指南。

更新日志: Source: GitHub https://github.com/MainActorDev/Construkt

目录结构

当前层级: tree/main/

📁 .serena/
- 📁 cache/
  - 📁 swift/
    
    📄 document_symbols.pkl 2.3 MB
    
    📄 raw_document_symbols.pkl 463.1 KB
- 📁 memories/
  - 📄 project_overview.md 285 B
  - 📄 style_and_conventions.md 350 B
  - 📄 suggested_commands.md 338 B
  - 📄 task_completion_checklist.md 240 B
  - 📄 tech_stack_and_structure.md 356 B
- 📄 .gitignore 26 B
- 📄 project.local.yml 402 B
- 📄 project.yml 9.1 KB
📁 .vscode/
- 📄 settings.json 2 B
📁 Demo/
- 📁 Construkt/
  - 📁 Application/
    
    📁 Common/
    
    📁 State/
    
    📄 Builder+CollectionView+Pagination.swift 2.5 KB
    
    📄 Builder+TableView+State.swift 1.1 KB
    
    📄 LoadableState.swift 2.2 KB
    
    📄 PaginationUtils.swift 832 B
    
    📄 StateContainer.swift 6.3 KB
    
    📁 Views/
    
    📄 CustomNavigationBar.swift 3.0 KB
    
    📄 GradientView.swift 1.1 KB
    
    📄 SharedViews.swift 2.1 KB
    
    📄 WalkthroughOverlay.swift 17.0 KB
    
    📄 LeakWarningToast.swift 2.2 KB
    
    📁 Debug/
    
    📄 LifecycleDebugExport.swift 4.0 KB
    
    📄 LifecycleDebugTrigger.swift 3.4 KB
    
    📄 LifecycleDebugView.swift 12.7 KB
    
    📁 Extensions/
    
    📄 CGFloat+ScrollProgress.swift 311 B
    
    📁 Features/
    
    📁 Detail/
    
    📁 Components/
    
    📄 MovieCast.swift 2.6 KB
    
    📄 MovieDetailHero.swift 1.9 KB
    
    📄 MovieDetailNavBar.swift 2.9 KB
    
    📄 MovieMetadata.swift 1.7 KB
    
    📄 MovieSimilar.swift 1.4 KB
    
    📄 MovieStoryline.swift 519 B
    
    📄 MovieDetailView.swift 12.3 KB
    
    📁 Explore/
    
    📄 ExploreComponents.swift 5.3 KB
    
    📄 ExploreView.swift 5.4 KB
    
    📄 ExploreViewModel.swift 5.7 KB
    
    📁 Home/
    
    📁 Cells/
    
    📄 GenresCell.swift 740 B
    
    📄 PosterCell.swift 982 B
    
    📄 TopRatedCell.swift 2.8 KB
    
    📄 UpcomingCell.swift 1.5 KB
    
    📁 Components/
    
    📄 CustomPageControl.swift 1.2 KB
    
    📄 HeroContentView.swift 4.8 KB
    
    📄 HomeNavigationBar.swift 2.0 KB
    
    📁 Models/
    
    📄 HomeSection.swift 2.0 KB
    
    📁 Supplementaries/
    
    📄 StandardHeader.swift 980 B
    
    📄 HomeView.swift 15.9 KB
    
    📁 List/
    
    📁 Cells/
    
    📄 MovieGridCell.swift 2.1 KB
    
    📁 Components/
    
    📄 MovieListNavBar.swift 992 B
    
    📄 MovieListViewController.swift 5.0 KB
    
    📄 MovieListViewModel.swift 8.9 KB
    
    📁 Search/
    
    📄 SearchViewController.swift 6.2 KB
    
    📄 SearchViewModel.swift 3.4 KB
    
    📁 Shared/
    
    📄 MovieViewModel.swift 10.1 KB
    
    📁 Navigation/
    
    📄 AppCoordinator.swift 5.1 KB
    
    📄 AppRoute.swift 500 B
    
    📄 AppRouteHandler.swift 6.2 KB
    
    📄 DeepLinkMapper.swift 1.0 KB
    
    📄 ExploreCoordinator.swift 1.5 KB
    
    📄 HomeCoordinator.swift 3.3 KB
    
    📄 ScreenFactory.swift 1.6 KB
    
    📁 Profile/
    
    📄 ProfileComponents.swift 6.1 KB
    
    📄 ProfileCoordinator.swift 952 B
    
    📄 ProfileView.swift 6.5 KB
    
    📄 .DS_Store 6.0 KB
    
    📄 AppDelegate.swift 2.6 KB
    
    📄 LaunchViewController.swift 1.4 KB
    
    📄 NavigationController.swift 636 B
    
    📄 SceneDelegate.swift 5.2 KB
  - 📁 Extensions/
    
    📄 LoadableState+Binding.swift 1.9 KB
  - 📁 Models/
    
    📄 Cast.swift 982 B
    
    📄 Genre.swift 433 B
    
    📄 Movie.swift 2.4 KB
    
    📄 MovieDetail.swift 1.7 KB
  - 📁 Networking/
    
    📁 Core/
    
    📄 HTTPMethod.swift 191 B
    
    📄 NetworkClient.swift 2.1 KB
    
    📄 NetworkConfiguration.swift 513 B
    
    📄 NetworkError.swift 1.1 KB
    
    📄 TMDBConfiguration.swift 500 B
    
    📁 Interceptors/
    
    📄 LoggerInterceptor.swift 590 B
    
    📄 RequestInterceptor.swift 337 B
    
    📄 TMDBRequestInterceptor.swift 835 B
    
    📁 Request/
    
    📄 Endpoint.swift 740 B
    
    📄 MoviesEndpoint.swift 1.8 KB
    
    📄 RequestBuilder.swift 2.2 KB
  - 📁 Resources/
    
    📁 Assets.xcassets/
    
    📁 AccentColor.colorset/
    
    📄 Contents.json 123 B
    
    📁 AppIcon.appiconset/
    
    📄 100.png 11.5 KB
    
    📄 102.png 11.1 KB
    
    📄 1024 1.png 174.4 KB
    
    📄 1024.png 174.4 KB
    
    📄 108.png 11.8 KB
    
    📄 114.png 12.6 KB
    
    📄 120 1.png 13.0 KB
    
    📄 120.png 13.0 KB
    
    📄 128.png 13.6 KB
    
    📄 152.png 16.8 KB
    
    📄 16.png 775 B
    
    📄 167.png 18.3 KB
    
    📄 172.png 19.0 KB
    
    📄 180.png 20.8 KB
    
    📄 196.png 22.4 KB
    
    📄 216.png 24.3 KB
    
    📄 234.png 26.1 KB
    
    📄 256.png 28.6 KB
    
    📄 258.png 29.1 KB
    
    📄 32.png 2.2 KB
    
    📄 40.png 2.9 KB
    
    📄 48.png 4.1 KB
    
    📄 512.png 66.9 KB
    
    📄 55.png 5.0 KB
    
    📄 58 1.png 5.4 KB
    
    📄 58.png 5.4 KB
    
    📄 60.png 5.9 KB
    
    📄 64.png 6.1 KB
    
    📄 66.png 6.5 KB
    
    📄 76.png 7.9 KB
    
    📄 80 1.png 7.7 KB
    
    📄 80.png 7.7 KB
    
    📄 87 1.png 9.4 KB
    
    📄 87.png 9.4 KB
    
    📄 88.png 9.3 KB
    
    📄 92.png 10.0 KB
    
    📄 Contents.json 6.0 KB
    
    📄 Contents.json 63 B
  - 📁 Services/
    
    📄 MovieService.swift 2.3 KB
  - 📄 .DS_Store 8.0 KB
  - 📄 Info.plist 922 B
- 📁 Construkt.xcodeproj/
  - 📁 project.xcworkspace/
    
    📁 xcuserdata/
    
    📁 mac.xcuserdatad/
    
    📄 UserInterfaceState.xcuserstate 472.2 KB
    
    📄 contents.xcworkspacedata 135 B
  - 📁 xcshareddata/
    
    📁 xcschemes/
    
    📄 Construkt.xcscheme 3.3 KB
  - 📁 xcuserdata/
    
    📁 berkamain.xcuserdatad/
    
    📁 xcschemes/
    
    📄 xcschememanagement.plist 449 B
    
    📁 mac.xcuserdatad/
    
    📁 xcdebugger/
    
    📄 Breakpoints_v2.xcbkptlist 870 B
    
    📁 xcschemes/
    
    📄 xcschememanagement.plist 449 B
  - 📄 project.pbxproj 16.9 KB
- 📁 Construkt.xcworkspace/
  - 📄 contents.xcworkspacedata 176 B
- 📄 .DS_Store 8.0 KB
📁 Sources/
- 📁 Construkt/
  - 📁 Components/
    
    📁 CollectionView/
    
    📄 CellConfig.swift 6.1 KB
    
    📄 CellControllerAdapter.swift 2.6 KB
    
    📄 CustomBackgroundReusableView.swift 2.9 KB
    
    📄 DataSource.swift 6.0 KB
    
    📄 HostingReusableView.swift 2.4 KB
    
    📄 LayoutBuilder.swift 1.9 KB
    
    📄 SectionConfig.swift 3.9 KB
    
    📄 SupplementaryController.swift 3.5 KB
    
    📁 ShimmerView/
    
    📄 _Shimmer.swift 2.2 KB
    
    📄 _ShimmerConfig.swift 3.8 KB
    
    📄 _ShimmerLayer.swift 7.6 KB
    
    📄 _ShimmerView.swift 4.8 KB
    
    📁 Views/
    
    📄 ActivityIndicator.swift 1.2 KB
    
    📄 BlurView.swift 2.0 KB
    
    📄 CircleView.swift 513 B
    
    📄 LinearGradient.swift 1.0 KB
    
    📄 ProgressView.swift 2.1 KB
    
    📄 Slider.swift 1.9 KB
    
    📄 Stepper.swift 1.7 KB
    
    📄 TextEditor.swift 2.6 KB
    
    📄 Toggle.swift 1.4 KB
  - 📁 Core/
    
    📁 Builder/
    
    📁 CollectionView/
    
    📄 Builder+AnyCell.swift 7.9 KB
    
    📄 Builder+AnySection.swift 34.6 KB
    
    📄 Builder+CollectionView.swift 18.1 KB
    
    📄 Builder+Attributes.swift 7.3 KB
    
    📄 Builder+Bindings.swift 5.0 KB
    
    📄 Builder+Button.swift 5.6 KB
    
    📄 Builder+Constraints.swift 14.3 KB
    
    📄 Builder+Container.swift 5.2 KB
    
    📄 Builder+Context.swift 5.9 KB
    
    📄 Builder+Controls.swift 3.7 KB
    
    📄 Builder+Decoys.swift 5.2 KB
    
    📄 Builder+Divider.swift 3.0 KB
    
    📄 Builder+Dynamic.swift 5.4 KB
    
    📄 Builder+Extensions.swift 8.5 KB
    
    📄 Builder+ForEach.swift 2.3 KB
    
    📄 Builder+GeometryReader.swift 7.0 KB
    
    📄 Builder+Gestures.swift 6.1 KB
    
    📄 Builder+GradientLabel.swift 1.9 KB
    
    📄 Builder+Group.swift 1.8 KB
    
    📄 Builder+Image.swift 4.3 KB
    
    📄 Builder+Label.swift 6.7 KB
    
    📄 Builder+Navigation.swift 3.3 KB
    
    📄 Builder+Padding.swift 2.7 KB
    
    📄 Builder+RenderItem.swift 3.6 KB
    
    📄 Builder+Screen.swift 3.0 KB
    
    📄 Builder+ScrollView.swift 7.1 KB
    
    📄 Builder+Spacer.swift 3.4 KB
    
    📄 Builder+Stack.swift 7.6 KB
    
    📄 Builder+Styles.swift 2.3 KB
    
    📄 Builder+Switch.swift 4.0 KB
    
    📄 Builder+TableView.swift 8.8 KB
    
    📄 Builder+TextField.swift 8.1 KB
    
    📄 Builder+Variable.swift 2.3 KB
    
    📄 Builder+VerticalDivider.swift 2.7 KB
    
    📄 Builder+View.swift 8.4 KB
    
    📄 Builder+ViewController.swift 3.7 KB
    
    📄 Builder+With.swift 1.4 KB
    
    📄 Builder+ZStack.swift 1.4 KB
    
    📄 Builder.swift 15.4 KB
    
    📁 Extensions/
    
    📄 UIColor+Extensions.swift 3.0 KB
    
    📄 UIImage+Extensions.swift 848 B
    
    📄 UIImageView+Remote.swift 4.3 KB
    
    📁 Reactive/
    
    📄 Binding+Operators.swift 11.8 KB
    
    📄 Binding.swift 1.6 KB
    
    📄 CancelBag.swift 1.6 KB
    
    📄 Property.swift 3.0 KB
    
    📄 Signal.swift 2.3 KB
    
    📁 Runtime/
    
    📄 EffectPolicy+iOS16.swift 616 B
    
    📄 EffectPolicy.swift 1.9 KB
    
    📄 FeatureRuntime.swift 15.4 KB
    
    📄 FeatureSpec.swift 4.1 KB
    
    📄 FeatureStore.swift 7.4 KB
    
    📄 RuntimeJournal.swift 2.1 KB
    
    📄 RuntimeScope.swift 2.5 KB
    
    📄 .DS_Store 6.0 KB
  - 📁 Extensions/
    
    📄 Collection.swift 1.4 KB
    
    📄 NSCollectionLayout.swift 7.9 KB
    
    📄 UICollectionView.swift 3.1 KB
  - 📁 Navigation/
    
    📄 ConstruktRouteHandler.swift 2.3 KB
    
    📄 Coordinator.swift 984 B
    
    📄 EventRouting.swift 7.1 KB
    
    📄 LifecycleHostController.swift 9.0 KB
    
    📄 LifecycleHostTracker.swift 8.1 KB
    
    📄 LifecycleTrackerConfiguration.swift 2.7 KB
    
    📄 LifecycleTrackingModels.swift 4.7 KB
    
    📄 Presentable.swift 342 B
    
    📄 RouteChannel.swift 3.9 KB
    
    📄 Router.swift 9.3 KB
    
    📄 SheetConfiguration.swift 2.3 KB
    
    📄 SheetController.swift 15.5 KB
    
    📄 SheetPresentationController.swift 2.4 KB
    
    📄 SheetTransitionAnimator.swift 2.7 KB
    
    📄 SheetTransitionStyle.swift 154 B
    
    📄 ToastAnimator.swift 10.4 KB
    
    📄 ToastConfiguration.swift 6.0 KB
    
    📄 ToastItem.swift 3.5 KB
    
    📄 ToastManager.swift 10.2 KB
    
    📄 ViewPresentable.swift 810 B
  - 📄 .DS_Store 6.0 KB
📁 Tests/
- 📁 ConstruktTests/
  - 📄 AnySectionBindingTests.swift 3.1 KB
  - 📄 AnySectionSupplementaryVisibilityTests.swift 3.2 KB
  - 📄 BuilderComponentTests.swift 5.3 KB
  - 📄 ConstraintTests.swift 3.0 KB
  - 📄 EventRoutingTests.swift 6.3 KB
  - 📄 FeatureRuntimeTests.swift 13.9 KB
  - 📄 FeatureStoreTests.swift 4.7 KB
  - 📄 GeometryReaderTests.swift 6.2 KB
  - 📄 LifecycleHostControllerTests.swift 3.1 KB
  - 📄 PaddingTests.swift 1.4 KB
  - 📄 ReactiveTests.swift 13.2 KB
  - 📄 RouterLifecycleTests.swift 2.1 KB
  - 📄 ToastManagerTests.swift 1.7 KB
📄 .gitignore 278 B
📄 construkt_banner.webp 216.9 KB
📄 LICENSE 1.1 KB
📄 Package.swift 455 B
📄 README.md 29.0 KB
📄 SKILL.md 21.6 KB

SKILL.md

---
name: "Write UIKit UI code declaratively with Construkt"
description: "Guidelines for generating declarative UIKit code using the Construkt framework (SwiftUI syntax for UIKit)."
---

# Write Construkt UI Code

You are an expert iOS developer specialized in **Construkt**, a declarative UIKit framework that uses SwiftUI-like syntax but generates native `UIView` hierarchies under the hood via Swift Result Builders.

Whenever a user asks you to build a UI component, screen, or apply styling in this project, you MUST use Construkt syntax instead of traditional imperatively-built UIKit or SwiftUI.

## Core Principles

1. **100% UIKit**: Construkt components generate native `UIView` instances. There is no `UIHostingController`.
2. **SwiftUI Syntax**: The syntax mirrors SwiftUI perfectly. Use `VStackView`, `HStackView`, `ZStackView`, `LabelView`, `ButtonView`, `ImageView`, etc.
3. **No Auto Layout**: Never write `NSLayoutConstraint` code. Layout is handled entirely by Spacers, padding, height/width modifiers, and Stack alignments.
4. **State Management**: Construkt uses reactive bindings via `@Variable` (a wrapper around `Property<T>`) and `Signal<T>`. Bind to UI using the `$` prefix (e.g., `.text(bind: $title)`).
5. **Collection Views**: Never write `UICollectionViewDataSource` or delegate boilerplate. Use `CollectionView` with `AnySection` builders.

---

## 🛠 Basic Components

When generating UI, use the Construkt primitives:

| SwiftUI / UIKit | Construkt Equivalent |
| --- | --- |
| `View` / `UIView` | `ViewBuilder` (protocol returning `View`) |
| `Text` / `UILabel` | `LabelView("Text")` |
| `Image` / `UIImageView` | `ImageView(UIImage)` |
| `Button` / `UIButton` | `ButtonView("Title").onTap { ... }` |
| `VStack` / `UIStackView` | `VStackView { ... }` |
| `HStack` / `UIStackView` | `HStackView { ... }` |
| `ZStack` / `UIView` | `ZStackView { ... }` |
| `Spacer` / `UIView` | `SpacerView()` |
| `Circle` / `UIView` | `CircleView()` |
| `Toggle` / `UISwitch` | `Toggle(isOn: $state)` |
| `Slider` / `UISlider` | `Slider(value: $value)` |
| `ProgressView` / `UIProgressView` | `ProgressView(value: 0.5)` |
| `Stepper` / `UIStepper` | `Stepper(value: $num, in: 0...10)` |
| `TextEditor` / `UITextView` | `TextEditor(text: $text)` |
| `LinearGradient` / `CAGradientLayer` | `LinearGradient(colors: [.red, .blue])` |
| `BlurView` / `UIVisualEffectView` | `BlurView(style: .regular)` |
| `List` / `UITableView` | `TableView(DynamicItemViewBuilder) { ... }` |
| `LazyVGrid`/`UICollectionView` | `CollectionView { AnySection { ... } }` |
| Screen layout container | `Screen { content }.navigationBar { bar }` |

---

## 📐 Layout & Modifiers

Always apply styling using chained modifiers just like SwiftUI.

### Sizing and Spacing
```swift
VStackView {
    LabelView("Title")
        .font(.title1)
        .color(.label)
    
    ImageView(image)
        .contentMode(.scaleAspectFill)
        .height(200) // Fixed height
        .clipsToBounds(true)
}
.spacing(16) // Spacing between stack items
.padding(h: 20, v: 24) // Horizontal and vertical padding
.backgroundColor(.systemBackground)
.cornerRadius(12)
```

### Alignment (ZStackView)
In `ZStackView`, you can position items using `.position()` + `.margins()` (from `Builder+Attributes`):
```swift
ZStackView {
    ImageView(backdrop)
        .contentMode(.scaleAspectFill)
    
    LabelView("Overlay Text")
        .color(.white)
        .position(.bottomLeft) // Positions to the bottom-left of the ZStack
        .margins(16)
}
```

---

### Screen Layout Container

Use `Screen` to establish a standard page architecture with content and navigation bar "slots". This replaces manual `ZStackView` + `.position(.top)` boilerplate:

```swift
Screen {
    CollectionView {
        heroSection
        popularSection
    }
    .onScroll { scrollView in
        scrollBinding.offset = scrollView.contentOffset.y
    }
}
.navigationBar {
    HomeNavigationBar(
        scrollOffset: scrollBinding.$offset.eraseToAnyViewBinding()
    )
}
.backgroundColor(UIColor("#0A0A0A"))
```

The `Screen` handles Z-stacking automatically. Each screen provides its own distinct navigation bar.

---

## ⚡️ Reactive State (Binding)

Instead of manually updating UI elements when data changes, use Construkt's binding modifiers. The ViewModel exposes `@Variable`, and the View binds to `$variable`.

**ViewModel:**
```swift
class ProfileViewModel {
    @Variable var name: String = "John Doe"
    @Variable var isSaving: Bool = false
    let onSaveTapped = Signal<Void>()
}
```

**View:**
```swift
VStackView {
    LabelView($viewModel.name) // Automatically updates when `name` changes
        .font(.body)

    ButtonView("Save")
        .hidden(bind: $viewModel.isSaving) // Hides when saving is true
        .onTap { [weak viewModel] _ in
            viewModel?.onSaveTapped.send()
        }
    
    ActivityIndicator()
        .hidden(bind: $viewModel.isSaving.map { !$0 }) // Inverse mapping
}
```

> **Note:** Do NOT write `.map { !$0 }` unless you are mapping a Boolean. Always import `Construkt` to ensure modifiers are available.

---

## 🗂 Lists and Collections

For lists, **always** use Construkt's declarative `CollectionView`. Never manually create Data Sources.

### 1. Dynamic Collections
When binding to an array or an Rx `@Variable` array, provide the `items:` parameter to a `AnySection` constructor, and yield `Cell(...)` instances.

```swift
CollectionView {
    AnySection(
        id: "movies_section", 
        items: viewModel.movies, // or $viewModel.movies
        header: Header { LabelView("Trending Now").font(.title1).padding(h: 16) }
    ) { movie in
        AnyCell(movie, id: movie.id) { movieData in
            MoviePosterCell(movie: movieData)
        }
    }
    .onSelect { movie in
        // Direct strongly-typed model access
        print("Selected \(movie)") 
    }
    .layout { environment in
        // Return NSCollectionLayoutSection
    }
}
```

### 2. Static Collections
You can build statically-defined declarative collections (e.g., Settings menus) by listing explicit `AnyCell` components within a `AnySection`:

```swift
CollectionView {
    AnySection(id: "settings_section", header: Header { LabelView("General") }) {
        AnyCell("Notifications", id: "notifications") { title in
            SettingsRowView(title: title)
        }
        AnyCell("Privacy", id: "privacy") { title in
            SettingsRowView(title: title)
        }
    }
    .onSelect { title in
        print("Tapped on \(title)")
    }
}
```

### 3. Shimmer Loading States
Construkt supports natively swapping an entire `AnySection` with shimmer placeholders during load times. Use the `.shimmer(count:when:...)` modifier directly on the Section:

```swift
AnySection(id: "popular", items: viewModel.popularMovies) { movie in
    AnyCell(movie, id: movie.id) { movie in 
        MoviePosterCell(movie: movie)
    }
}
.shimmer(count: 5, when: $viewModel.isLoading) {
    MoviePosterCell(movie: .placeholder) // Create geometry for shimmer
}
```

---

## 🏗 View Composition (Creating custom views)

When a UI becomes complex, you **MUST** extract it into separate, context-specific structs adopting `ViewBuilder`. **Never** generate a massive, single `body` with dozens of nested stacks. 

For instance, if building a user profile screen, separate it into `ProfileHeaderView`, `StatsRowView`, and `RecentActivityView`. Then assemble them inside the root view.

```swift
import UIKit
import Construkt

struct UserProfileCard: ViewBuilder {
    let user: User
    
    var body: View { // Must return Construkt's `View` type
        HStackView {
            ImageView(user.avatar)
                .size(width: 50, height: 50)
                .cornerRadius(25)
            
            VStackView {
                LabelView(user.name).font(.headline)
                LabelView(user.role).font(.subheadline).color(.secondaryLabel)
            }
            .spacing(4)
            
            SpacerView()
        }
        .padding(16)
        .backgroundColor(.secondarySystemBackground)
        .cornerRadius(12)
    }
}
```

To instantiate this into a raw UIKit `UIView`, call `.build()`:
```swift
let customView: UIView = UserProfileCard(user: currentUser).build()
```

### Component Parameterization & Reusability

If you are building a layout containing multiple identical UI blocks (e.g., a row of feature highlights, three pricing cards, or identical buttons), **you MUST** extract the structural boilerplate into a dynamically parameterized `ViewBuilder` component. Pass unique text, images, or configurations as immutable properties (`let`).

**Example: Extracting identical statistics cards**
```swift
// 1. Define the reusable parameterized struct
struct StatCard: ViewBuilder {
    let title: String
    let value: String

    var body: View {
        VStackView {
            LabelView(value).font(.title1)
            LabelView(title).font(.caption1).color(.secondaryLabel)
        }
        .padding(16)
        .backgroundColor(.secondarySystemBackground)
        .cornerRadius(12)
    }
}

// 2. Instantiate multiple times in the parent scope rather than duplicating raw views
struct DashboardStatsView: ViewBuilder {
    var body: View {
        HStackView {
            StatCard(title: "Followers", value: "1.2k")
            StatCard(title: "Following", value: "400")
            StatCard(title: "Posts", value: "32")
        }
        .spacing(12)
        .distribution(.fillEqually)
    }
}
```

---

## 7. Comprehensive View Modifiers Reference

You **must exclusively use** these native Construkt modifiers. Do not invent SwiftUI names (e.g., use `.backgroundColor` not `.background`, `.alpha` not `.opacity`, `.frame(height:width:)` not `.frame(maxWidth:)`).

### Layout & Sizing (from `Builder+Constraints`)
- `.frame(height:width:)` — set explicit dimensions (both optional)
- `.size(width:height:)` — shorthand for `.width().height()`
- `.height(CGFloat)` / `.height(CGFloat, priority:)` — constrain height
- `.height(min:)` / `.height(max:)` — min/max height constraints
- `.width(CGFloat)` / `.width(CGFloat, priority:)` — constrain width
- `.width(min:)` / `.width(max:)` — min/max width constraints
- `.contentCompressionResistancePriority(UILayoutPriority, for: .horizontal/.vertical)`
- `.contentHuggingPriority(UILayoutPriority, for: .horizontal/.vertical)`
- `.zIndex(CGFloat)` — set layer z-position

### Padding (from `Builder+Padding`, only on Paddable views: Stacks, Labels, Buttons)
- `.padding(CGFloat)` — uniform all edges
- `.padding(h:v:)` — horizontal + vertical
- `.padding(top:left:bottom:right:)` — per-edge
- `.padding(insets: UIEdgeInsets)` — raw insets

### Container Embedding (from `Builder+Attributes`)
- `.margins(CGFloat)` / `.margins(h:v:)` / `.margins(top: 12, bottom: 12)` — embed margins (parameters can be partial: `top:left:bottom:right:`)
  > ⚠️ **CRITICAL**: The modifier is `.margins` (with an 's'). NEVER use `.margin` without the 's' — it does not exist.
- `.position(.center)` / `.position(.top)` / `.position(.fill)` — embed alignment
- `.safeArea(Bool)` — respect safe area when embedded
- `.customConstraints { view in }` — raw AutoLayout access

### Appearance & Styling (from `Builder+View`)
- `.backgroundColor(UIColor)`
- `.alpha(CGFloat)`
- `.cornerRadius(CGFloat)` / `.roundedCorners(radius:corners:)`
- `.border(color:lineWidth:)`
- `.shadow(color:radius:opacity:offset:)`
- `.tintColor(UIColor)`
- `.clipsToBounds(Bool)`
- `.contentMode(UIView.ContentMode)`
- `.hidden(Bool)` / `.hidden(bind: $variable)`
- `.isOpaque(Bool)`
- `.isUserInteractionEnabled(Bool)` / `.userInteractionEnabled(bind: $variable)`

### Reactive Bindings (from `Builder+Bindings`)
- `.bind(keyPath, to: binding)` — bind any writable keypath to a reactive stream
- `.onReceive(binding) { context in }` — react to any value change
- `.hidden(when: $isHidden)` — reactively show/hide
- `.userInteractionEnabled(when: $binding)` — reactively enable/disable interaction
- `.eraseToAnyViewBinding()` — type-erase any `ViewBinding` into `AnyViewBinding<T>`

### Typography (LabelView modifiers)
- `.font(UIFont)` / `.font(.headline)` — set font
- `.color(UIColor)` / `.color(bind: $variable)` — set text color
- `.text(bind: $variable)` — reactively update text
- `.alignment(NSTextAlignment)` — text alignment
- `.numberOfLines(Int)` — line count
- `.lineBreakMode(NSLineBreakMode)` — truncation mode

### StackView (HStackView / VStackView)
- `.spacing(CGFloat)` / `.customSpacing(CGFloat, after: View)` — inter-item spacing
- `.alignment(UIStackView.Alignment)` — cross-axis alignment
- `.distribution(UIStackView.Distribution)` — main-axis distribution
- `.layoutMarginsRelativeArrangement(Bool)` — use layout margins

### ButtonView modifiers
- `.onTap { context in }` — handle tap
- `.font(UIFont)` / `.font(.headline)` — title font
- `.color(UIColor, for: .normal)` — title color
- `.backgroundColor(UIColor, for: .highlighted)` — per-state background
- `.alignment(UIControl.ContentHorizontalAlignment)` — content alignment
- `.enabled(Bool)` / `.enabled(bind: $variable)` — enable/disable

### ImageView modifiers
- `.tintColor(UIColor)` — template image tint
- `.image(bind: $variable)` — reactively update image

### SwitchView modifiers
- `.isOn(bind: $variable)` / `.isOn(bidirectionalBind: $variable)` — bind toggle state
- `.onTintColor(UIColor)` — on-state color
- `.onChange { context in }` — react to toggle changes

### Gestures (from `Builder+Gestures`)
- `.onTapGesture { context in }` / `.onTapGesture(numberOfTaps: 2) { context in }`
- `.onSwipeRight { context in }` / `.onSwipeLeft { context in }`
- `.hideKeyboardOnBackgroundTap()`

### Lifecycle (from `Builder+Attributes`, on `ViewBuilderEventHandling` views)
- `.onAppear { context in }` — fires each time view enters window
- `.onAppearOnce { context in }` — fires only the first time
- `.onDisappear { context in }` — fires when leaving window

### Utility Components
- `SpacerView()` — flexible space (pushes siblings apart)
- `SpacerView(h: 16)` — minimum-height spacer / `SpacerView(w: 8)` — minimum-width spacer
- `FixedSpacerView(8)` — rigid height spacer / `FixedSpacerView(width: 8)` — rigid width spacer
- `DividerView()` — 1px separator line with `.color(UIColor)` modifier
- `ContainerView { ... }` — single-child host view (also aliased as `ZStackView`)
- `DynamicContainerView($binding) { value in ... }` — reactively swaps child view
- `ForEach(array) { element in ... }` — iterate over an array to produce views
- `ForEach(count) { index in ... }` — iterate N times to produce views
- `CGFloat.scrollProgress(over: CGFloat) -> CGFloat` — normalize scroll offset into 0…1 range

## 8. Advanced Capabilities

Construkt supports full application features declaratively.

### Navigation and Routing
Construkt provides multiple ways to navigate between screens.

**Declarative Routing** — attach navigation intent directly to sections:
```swift
AnySection(id: "popular", items: movies) { movie in
    AnyCell(movie, id: movie.id) { movie in PosterCell(movie: movie) }
}
.onRoute { (movie: Movie) in
    AppRoute.movieDetail(movieId: String(movie.id))
}
```

**Sender-Based Routing** — route from the tapped view's responder chain:
```swift
.onTapGesture { context in
    context.view.route(HomeRoute.search, sender: nil)
}
```

**Inline Route Handling** — attach handlers when constructing screens:
```swift
HomeView()
    .onReceiveRoute(HomeRoute.self) { route in
        switch route {
        case .movieDetail(let id): open(.movieDetail(movieId: id))
        case .search: open(.search)
        }
        return true
    }
    .toPresentable()
```

**Coordinator Pattern** — for complex navigation hierarchies with parent-child relationships:
```swift
final class HomeCoordinator: BaseCoordinator, RouteHandlingCoordinator {
    typealias Event = HomeRoute
    let router: ConstruktRouter

    init(router: ConstruktRouter) {
        self.router = router
    }

    override func start() {
        let homeVC = HomeView(viewModel: viewModel).toPresentable()
        router.setRoot(homeVC, hideBar: true, animated: false, receiver: self)
    }

    func canReceive(_ event: HomeRoute, sender: Any?) -> Bool {
        switch event {
        case .movieDetail(let id):
            router.push(MovieDetailView(movie: movie).toPresentable(), animated: true, receiver: self)
            return true
        case .search:
            router.push(SearchViewController(), animated: true, receiver: self)
            return true
        }
    }
}
```

Key types:
- `BaseCoordinator` — base class with `children`, `store()`, `free()`, and `start()`
- `RouteHandlingCoordinator` — protocol requiring `router` + `canReceive()` to handle route events
- `ConstruktRouter` / `DefaultRouter` — `push`, `pop`, `present`, `dismiss`, `setRoot`
- `receiver: self` — binds the coordinator to the VC so events route back correctly

### Scroll-Driven Reactive Patterns

For scroll-driven UI (e.g., stretchy headers, fading nav bars), separate reactive data from imperative UIKit handles:

```swift
// Pure reactive data — observable, testable
private class ScrollBinding {
    @Variable var offset: CGFloat = 0
    @Variable var scrollToTopTrigger: UInt = 0
}

// Imperative UIKit handles — needed for constraint manipulation
private class ViewHandles {
    weak var heroHeightConstraint: NSLayoutConstraint?
    weak var scrollView: UIScrollView?
}
```

Bind scroll events to `ScrollBinding`, then use `.onReceive` to drive UI:
```swift
.onScroll { scrollView in
    scrollBinding.offset = scrollView.contentOffset.y
}

// In the nav bar:
.onReceive(scrollBinding.$offset) { context in
    context.view.alpha = context.value.scrollProgress(over: 100)
}
```

### Scroll Views
Do not build custom layouts on raw `UIScrollView` constraints. Use `ScrollView` and `VerticalScrollView`.

```swift
VerticalScrollView(safeArea: true) { // Automatically fills width
    VStackView {
        LabelView("Top")
        SpacerView()
        LabelView("Bottom")
    }
}
.automaticallyAdjustForKeyboard()
```

### Forms & TextFields
`TextField` supports bidirectional binding to a `@Variable` string.

```swift
TextField(bidirectionalBind: $viewModel.username)
    .placeholder("Enter Username")
    .autocapitalizationType(.none)
    .keyboardType(.emailAddress)
    .onChange { context in
        let text = context.value // The string inside the textfield
    }
```

### Gestures
Any Construkt view can respond to gestures via chained modifiers:

```swift
ImageView(headerImage)
    .onTapGesture(numberOfTaps: 2) { context in
        print("Double Tapped!")
    }
    .onSwipeRight { context in
        context.navigationController?.popViewController(animated: true)
    }

// Hide keyboard globally on a root ZStackView
ZStackView { ... }.hideKeyboardOnBackgroundTap()
```

---

## ⚠️ Anti-Patterns (What NOT to do)
1. **Never use SwiftUI `Text`, `Image`, or `VStack`.** Always use the Construkt equivalents (`LabelView`, `ImageView`, `VStackView`).
2. **Never import SwiftUI.** Only import `UIKit` and `Construkt`.
3. **Never write `setupConstraints()` or use `translatesAutoresizingMaskIntoConstraints = false`.**
4. **Never create generic constraint arrays.** 
5. **Never write `UICollectionViewDataSource` logic.** Use `CollectionView` ResultBuilders.

---

## 🐛 Troubleshooting & Debugging Compiler Errors

Because ConstruktKit relies heavily on Swift Result Builders (`@ViewBuilder`), certain compilation errors can be opaque and misleading. When the Swift compiler fails to type-check a large nested view hierarchy, it usually points to the parent container instead of the exact line causing the issue.

### 1. Handling "Opaque" Error Messages
If you see either of the following errors pointing to a `VStackView`, `HStackView`, `ZStackView`, or `CollectionView`:
*   `"extra trailing closure passed in call"`
*   `"initializer 'init(_:)' requires the types '(() -> ()).Value' and '[any View]' be equivalent"`

**DO NOT** assume the structure itself is wrong. This almost always means there is a **type mismatch** or an **invalid modifier** deeply nested inside that container block. The Swift compiler ran out of time or inference capabilities and gave up at the top level.

### 2. Isolation Strategy (How to find the real error)
To find the actual line causing the bug, you **MUST isolate the components**.

Extract inner views from the failing stack into local `let` variables or separate computed properties (`var myView: View { ... }`). By doing this, you force the Swift compiler to evaluate each piece independently. The compiler will immediately highlight the exact variable definition that contains the typo or invalid modifier.

**Example of an obscure error:**
```swift
var body: View {
    VStackView { // ERROR: "extra trailing closure passed in call"
        LabelView("Title")
        ImageView(myImage)
            .clipShape(.circle) // This is the real bug (SwiftUI modifier, not Construkt)
    }
}
```

**How to isolate it:**
```swift
var body: View {
    let titleLab = LabelView("Title")
    
    // The compiler will now correctly flag THIS exact line:
    let image = ImageView(myImage).clipShape(.circle) 
    
    return VStackView {
        titleLab
        image
    }
}
```

### 3. Common AI Hallucinations
When generating ConstruktKit code, AI often hallucinates SwiftUI equivalents. If a file fails to build, check for these common mistakes first:

1. Non-existent components (e.g. using `Text` instead of `LabelView` or `Spacer` instead of `SpacerView`)
2. Non-existent modifiers (e.g. using `.clipShape()` instead of `.cornerRadius().clipsToBounds(true)`)
3. Wrong modifier signatures (e.g. wrong padding parameters or `.border` arguments)
4. Wrong component initializer signatures (e.g. `SpacerView(width:)` instead of `FixedSpacerView(width:)`)
5. Using `ZStackView` + `.position(.top)` for nav bars instead of `Screen { ... }.navigationBar { ... }`

登录后下载/点赞/收藏 ❤ 17 | ★ 0

Write UIKit UI code declaratively with Construkt

目录结构

SKILL.md

举报内容

提示