WhatsNewKit

import SwiftUI
import WhatsNewKit

struct ContentView : View {

    var body : some View {
        NavigationView {
            // ...
        }
        . whatsNewSheet ( )
    }

} 

Merkmale

• Ihre neuen App -Funktionen einfach präsentieren?
• Automatischer und manueller Präsentationsmodus ✅
• Unterstützung für Swiftui, Uikit und Appkit? ‍?
• Läuft auf iOS, macos und Visionos? ?
• Verstellbares Layout?

Installation

Swift Package Manager

Um mit dem Swift -Paket -Manager von Apple zu integrieren, fügen Sie Ihrem Package.swift Folgendes als Abhängigkeit hinzu.

dependencies: [
    . package ( url : " https://github.com/SvenTiigi/WhatsNewKit.git " , from : " 2.0.0 " )
]

Oder navigieren Sie zu Ihrem XCode -Projekt und wählen Sie Swift Packages aus, klicken Sie auf das Symbol "+" und suchen Sie nach WhatsNewKit .

Beispiel

Schauen Sie sich die Beispielanwendung an, um WhatsNewkit in Aktion anzuzeigen. Öffnen Sie einfach das Example/Example.xcodeproj und führen Sie das "Beispiel" -Scheme aus.

Verwendung

Inhaltsverzeichnis

• Manuelle Präsentation
• Automatische Präsentation
• WhatsNewenvironment
• WhatsNewversionStore
• Was ist neu
• Layout
• WhatsNewViewController

Manuelle Präsentation

Wenn Sie eine WhatsNewView manuell präsentieren möchten, können Sie das sheet(whatsNew:) Modifikator.

 struct ContentView : View {

    @ State
    var whatsNew : WhatsNew ? = WhatsNew (
        title : " WhatsNewKit " ,
        features : [
            . init (
                image : . init (
                    systemName : " star.fill " ,
                    foregroundColor : . orange
                ) ,
                title : " Showcase your new App Features " ,
                subtitle : " Present your new app features... "
            ) ,
            // ...
        ]
    )

    var body : some View {
        NavigationView {
            // ...
        }
        . sheet (
            whatsNew : self . $whatsNew
        )
    }

}

Automatische Präsentation

Mit dem automatischen Präsentationsmodus können Sie Ihre neuen Funktionen einfach über die Swiftui -Umgebung deklarieren, und WhatsNewkit achtet darauf, die entsprechende WhatsNewView zu präsentieren.

Fügen Sie zunächst einen .whatsNewSheet() -Modifikator zu der Ansicht hinzu, in der die WhatsNewView präsentiert werden soll.

 struct ContentView : View {

    var body : some View {
        NavigationView {
            // ...
        }
        // Automatically present a WhatsNewView, if needed.
        // The WhatsNew that should be presented to the user
        // is automatically retrieved from the `WhatsNewEnvironment`
        . whatsNewSheet ( )
    }

}

Der Modifikator .whatsNewSheet() verwendet die WhatsNewEnvironment , um ein optionales WhatsNew -Objekt abzurufen, das dem Benutzer für die aktuelle Version präsentiert werden sollte. Daher können Sie die WhatsNewEnvironment einfach über den environment konfigurieren.

 extension App : SwiftUI . App {

    var body : some Scene {
        WindowGroup {
            ContentView ( )
                . environment (
                     . whatsNew ,
                    WhatsNewEnvironment (
                        // Specify in which way the presented WhatsNew Versions are stored.
                        // In default the `UserDefaultsWhatsNewVersionStore` is used.
                        versionStore : UserDefaultsWhatsNewVersionStore ( ) ,
                        // Pass a `WhatsNewCollectionProvider` or an array of WhatsNew instances
                        whatsNewCollection : self
                    )
                )
        }
    }

}

// MARK: - App+WhatsNewCollectionProvider

extension App : WhatsNewCollectionProvider {

    /// Declare your WhatsNew instances per version
    var whatsNewCollection : WhatsNewCollection {
        WhatsNew (
            version : " 1.0.0 " ,
            // ...
        )
        WhatsNew (
            version : " 1.1.0 " ,
            // ...
        )
        WhatsNew (
            version : " 1.2.0 " ,
            // ...
        )
    }

} 

WhatsNewenvironment

Die WhatsNewEnvironment achtet darauf, das passende WhatsNew -Objekt zu bestimmen, das dem Benutzer für die aktuelle Version präsentiert werden sollte.

Wie im vorherigen Beispiel zu sehen ist, können Sie eine WhatsNewEnvironment initialisieren, indem Sie den WhatsNewVersionStore angeben und eine WhatsNewCollection bereitstellen.

// Initialize WhatsNewEnvironment by passing an array of WhatsNew Instances.
// UserDefaultsWhatsNewVersionStore is used as default WhatsNewVersionStore
let whatsNewEnvironment = WhatsNewEnvironment (
    whatsNewCollection : [
        WhatsNew (
            version : " 1.0.0 " ,
            // ...
        )
    ]
)

// Initialize WhatsNewEnvironment with NSUbiquitousKeyValueWhatsNewVersionStore
// which stores the presented versions in iCloud.
// WhatsNewCollection is provided by a `WhatsNewBuilder` closure
let whatsNewEnvironment = WhatsNewEnvironment (
    versionStore : NSUbiquitousKeyValueWhatsNewVersionStore ( ) ,
    whatsNewCollection : {
        WhatsNew (
            version : " 1.0.0 " ,
            // ...
        )
    }
)

Darüber hinaus enthält die WhatsNewEnvironment einen Fallback für Patch -Versionen. Wenn ein Benutzer beispielsweise Version 1.0.1 installiert und Sie nur für Version 1.0.0 einen WhatsNew deklariert haben, fällt die Umgebung automatisch in Version 1.0.0 zurück und präsentiert den WhatsNewView bei Bedarf dem Benutzer.

Wenn Sie das Verhalten der WhatsNewEnvironment weiter anpassen möchten, können Sie es leicht unterklassen und die whatsNew() -Funktion überschreiben.

 class MyCustomWhatsNewEnvironment : WhatsNewEnvironment {

    /// Retrieve a WhatsNew that should be presented to the user, if available.
    override func whatsNew ( ) -> WhatsNew ? {
        // The current version
        let currentVersion = self . currentVersion
        // Your declared WhatsNew objects
        let whatsNewCollection = self . whatsNewCollection
        // The WhatsNewVersionStore used to determine the already presented versions
        let versionStore = self . whatsNewVersionStore
        // TODO: Determine WhatsNew that should be presented to the user...
    }

} 

WhatsNewversionStore

Ein WhatsNewVersionStore ist ein Protokolltyp, der für das Speichern und Abrufen von Versionen verantwortlich ist, die dem Benutzer präsentiert wurden.

 let whatsNewVersionStore : WhatsNewVersionStore

// Save presented versions
whatsNewVersionStore . save ( presentedVersion : " 1.0.0 " )

// Retrieve presented versions
let presentedVersions = whatsNewVersionStore . presentedVersions

// Retrieve bool value if a given version has already been presented
let hasPresented = whatsNewVersionStore . hasPresented ( " 1.0.0 " )

WhatsNewkit wird mit drei vordefinierten Implementierungen einhergeht:

// Persists presented versions in the UserDefaults
let userDefaultsWhatsNewVersionStore = UserDefaultsWhatsNewVersionStore ( )

// Persists presented versions in iCloud using the NSUbiquitousKeyValueStore
let ubiquitousKeyValueWhatsNewVersionStore = NSUbiquitousKeyValueWhatsNewVersionStore ( )

// Stores presented versions in memory. Perfect for testing purposes
let inMemoryWhatsNewVersionStore = InMemoryWhatsNewVersionStore ( )

Wenn Sie bereits über eine bestimmte Implementierung verfügen, um benutzerbezogene Einstellungen wie Realm oder Core -Daten zu speichern, können Sie Ihre vorhandene Implementierung problemlos für das WhatsNewVersionStore -Protokoll übernehmen.

NsubiquitousKeyValueWhatsNewversionStore

Wenn Sie den NSUbiquitousKeyValueWhatsNewVersionStore verwenden, können Sie die iCloud-Schlüsselwerbung in den Abschnitt "Signier- und Funktionen" Ihres XCode-Projekts in den KLEY-Wert-Speicherfähigkeiten ermöglichen.

Was ist neu

In den folgenden Abschnitten wird erläutert, wie eine WhatsNew -Struktur initialisiert werden kann, um die neuen Funktionen für eine bestimmte Version Ihrer App zu beschreiben.

 let whatsnew = WhatsNew (
    // The Version that relates to the features you want to showcase
    version : " 1.0.0 " ,
    // The title that is shown at the top
    title : " What's New " ,
    // The features you want to showcase
    features : [
        WhatsNew . Feature (
            image : . init ( systemName : " star.fill " ) ,
            title : " Title " ,
            subtitle : " Subtitle "
        )
    ] ,
    // The primary action that is used to dismiss the WhatsNewView
    primaryAction : WhatsNew . PrimaryAction (
        title : " Continue " ,
        backgroundColor : . accentColor ,
        foregroundColor : . white ,
        hapticFeedback : . notification ( . success ) ,
        onDismiss : {
            print ( " WhatsNewView has been dismissed " )
        }
    ) ,
    // The optional secondary action that is displayed above the primary action
    secondaryAction : WhatsNew . SecondaryAction (
        title : " Learn more " ,
        foregroundColor : . accentColor ,
        hapticFeedback : . selection ,
        action : . openURL (
            . init ( string : " https://github.com/SvenTiigi/WhatsNewKit " )
        )
    )
)

WhatsNew.Version

Die WhatsNew.Version gibt die Version an, die Ihre App bestimmte Funktionen vorgelegt hat.

// Initialize with major, minor, and patch
let version = WhatsNew . Version (
    major : 1 ,
    minor : 0 ,
    patch : 0
)

// Initialize by string literal
let version : WhatsNew . Version = " 1.0.0 "

// Initialize WhatsNew Version by using the current version of your bundle
let version : WhatsNew . Version = . current ( )

WhatsNew.title

Ein WhatsNew.Title repräsentiert den Titeltext, der über den Merkmalen gerendert wird.

// Initialize by string literal
let title : WhatsNew . Title = " Continue "

// Initialize with text and foreground color
let title = WhatsNew . Title (
    text : " Continue " ,
    foregroundColor : . primary
)

// On >= iOS 15 initialize with AttributedString using Markdown
let title = WhatsNew . Title (
    text : try AttributedString (
        markdown : " What's **New** "
    )
)

WhatsNew.Feature

Eine WhatsNew.Feature beschreibt eine bestimmte Funktion Ihrer App und besteht im Allgemeinen aus einem Bild, Titel und Untertitel.

 let feature = WhatsNew . Feature (
    image : . init (
        systemName : " wand.and.stars "
    ) ,
    title : " New Design " ,
    subtitle : . init (
        try AttributedString (
            markdown : " An awesome new _Design_ "
        )
    )
)

WhatsNew.PrimaryAction

Mit der WhatsNew.PrimaryAction können Sie das Verhalten der primären Taste konfigurieren, mit der die präsentierte WhatsNewView abgewiesen wird

 let primaryAction = WhatsNew . PrimaryAction (
    title : " Continue " ,
    backgroundColor : . blue ,
    foregroundColor : . white ,
    hapticFeedback : . notification ( . success ) ,
    onDismiss : {
        print ( " WhatsNewView has been dismissed " )
    }
)

Hinweis: Hapticfeedback wird nur auf iOS ausgeführt

WhatsNew.secondaryAction

Eine WhatsNew.SecondaryAction , die über der WhatsNew.PrimaryAction angezeigt wird WhatsNew

// SecondaryAction that presents a View
let secondaryActionPresentAboutView = WhatsNew . SecondaryAction (
    title : " Learn more " ,
    foregroundColor : . blue ,
    hapticFeedback : . selection ,
    action : . present {
        AboutView ( )
    }
)

// SecondaryAction that opens a URL
let secondaryActionOpenURL = WhatsNew . SecondaryAction (
    title : " Read more " ,
    foregroundColor : . blue ,
    hapticFeedback : . selection ,
    action : . open (
        url : . init ( string : " https://github.com/SvenTiigi/WhatsNewKit " )
    )
)

// SecondaryAction with custom execution
let secondaryActionCustom = WhatsNew . SecondaryAction (
    title : " Custom " ,
    action : . custom { presentationMode in
        // ...
    }
)

Hinweis: Hapticfeedback wird nur auf iOS ausgeführt

Layout

Mit WhatsNewkit können Sie das Layout einer präsentierten WhatsNewView auf verschiedene Weise anpassen.

Der einfachste Weg ist die Mutation der WhatsNew.Layout.default -Instanz.

 WhatsNew . Layout . default . featureListSpacing = 35

Wenn Sie den automatischen Präsentationsstil verwenden, können Sie bei der Initialisierung der WhatsNewen -Umgebung ein Standardlayout anbieten.

 . environment (
     . whatsNew ,
    . init (
        defaultLayout : WhatsNew . Layout (
            showsScrollViewIndicators : true ,
            featureListSpacing : 35
        ) ,
        whatsNew : self
    )
)

Alternativ können Sie einen WhatsNew.Layout übergeben, wenn Sie die WhatsNewView automatisch oder manuell präsentieren

 . whatsNewSheet (
    layout : WhatsNew . Layout (
        contentPadding : . init (
            top : 80 ,
            leading : 0 ,
            bottom : 0 ,
            trailing : 0
        )
    )
) 

 . sheet (
    whatsNew : self . $whatsNew ,
    layout : WhatsNew . Layout (
        footerActionSpacing : 20
    )
) 

WhatsNewViewController

Bei Verwendung von UIKit oder AppKit können Sie den WhatsNewViewController verwenden.

 let whatsNewViewController = WhatsNewViewController (
    whatsNew : WhatsNew (
        version : " 1.0.0 " ,
        // ...
    ) ,
    layout : WhatsNew . Layout (
        contentSpacing : 80
    )
)

Wenn Sie einen WhatsNewViewController nur dann präsentieren möchten, wenn die Version der WhatsNew -Instanz nicht präsentiert wurde, können Sie den Convenience Failable Initializer verwenden.

// Verify WhatsNewViewController is available for presentation
guard let whatsNewViewController = WhatsNewViewController (
    whatsNew : WhatsNew (
        version : " 1.0.0 " ,
        // ...
    ) ,
    versionStore : UserDefaultsWhatsNewVersionStore ( )
) else {
    // Version of WhatsNew has already been presented
    return
}

// Present WhatsNewViewController
// Version will be automatically saved in the provided
// WhatsNewVersionStore when the WhatsNewViewController gets dismissed
self . present ( whatsNewViewController , animated : true )