WhatsNewKit

import SwiftUI
import WhatsNewKit

struct ContentView : View {

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

} 

Caractéristiques

• Présenter facilement vos nouvelles fonctionnalités d'application?
• Mode de présentation automatique et manuel ✅
• Prise en charge de Swiftui, Uikit et Appkit? ‍?
• Fonctionne sur iOS, macOS et Visionos? ?
• Disposition réglable?

Installation

Swift Package Manager

Pour intégrer à l'aide de Swift Package Manager d'Apple, ajoutez ce qui suit en tant que dépendance à votre Package.swift :

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

Ou accédez à votre projet Xcode, puis sélectionnez Swift Packages , cliquez sur l'icône «+» et recherchez WhatsNewKit .

Exemple

Consultez l'exemple d'application pour voir WhatsNewKit en action. Ouvrez simplement l' Example/Example.xcodeproj et exécutez le schéma "Exemple".

Usage

Table des matières

• Présentation manuelle
• Présentation automatique
• Whatwewenvironment
• WhatsNewversionStore
• WhatsNew
• Mise en page
• WhatsNewViewController

Présentation manuelle

Si vous souhaitez présenter manuellement un WhatsNewView vous pouvez utiliser la sheet(whatsNew:) Modificateur.

 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
        )
    }

}

Présentation automatique

Le mode de présentation automatique vous permet de simplement déclarer vos nouvelles fonctionnalités via l'environnement Swiftui et WhatsNewkit prendra soin de présenter WhatsNewView correspondant.

Ajoutez d'abord un modificateur .whatsNewSheet() à la vue sur laquelle le WhatsNewView doit être présenté.

 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 ( )
    }

}

Le modificateur .whatsNewSheet() utilise le WhatsNewEnvironment pour récupérer un objet WhatsNew facultatif qui doit être présenté à l'utilisateur pour la version actuelle. Par conséquent, vous pouvez facilement configurer WhatsNewEnvironment via le modificateur environment .

 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 " ,
            // ...
        )
    }

} 

Whatwewenvironment

Le WhatsNewEnvironment prendra soin de déterminer l'objet WhatsNew correspondant qui devrait être présenté à l'utilisateur pour la version actuelle.

Comme on le voit dans l'exemple précédent, vous pouvez initialiser un WhatsNewEnvironment en spécifiant WhatsNewVersionStore et en fournissant un WhatsNewCollection .

// 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 " ,
            // ...
        )
    }
)

De plus, le WhatsNewEnvironment comprend un repli pour les versions Patch. Par exemple, lorsqu'un utilisateur installe la version 1.0.1 et que vous n'avez déclaré que WhatsNew pour la version 1.0.0 l'environnement se repliera automatiquement à la version 1.0.0 et présentera WhatsNewView à l'utilisateur si nécessaire.

Si vous souhaitez personnaliser davantage le comportement de WhatsNewEnvironment vous pouvez facilement le sous-classer et remplacer la fonction whatsNew() .

 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

Un WhatsNewVersionStore est un type de protocole qui est responsable de l'enregistrement et de la récupération des versions qui ont été présentées à l'utilisateur.

 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 s'accompagne de trois implémentations prédéfinies:

// 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 ( )

Si vous avez déjà une implémentation spécifique pour stocker des paramètres liés à l'utilisateur comme les données de royaume ou de base, vous pouvez facilement adopter votre implémentation existante dans le protocole WhatsNewVersionStore .

Nsubiquitouskeyvaluewhatsnewversionstore

Si vous utilisez le NSUbiquitousKeyValueWhatsNewVersionStore , veuillez vous assurer d'activer la capacité de stockage de la valeur clé iCloud dans la section "Signing & Capacities" de votre projet Xcode.

WhatsNew

Les sections suivantes expliquent comment une structure WhatsNew peut être initialisée afin de décrire les nouvelles fonctionnalités pour une version donnée de votre application.

 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

Le WhatsNew.Version spécifie la version qui a introduit certaines fonctionnalités de votre application.

// 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

Un WhatsNew.Title représente le texte de titre rendu au-dessus des fonctionnalités.

// 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

A WhatsNew.Feature décrivez une fonctionnalité spécifique de votre application et consiste généralement en une image, un titre et un sous-titre.

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

WhatsNew.primaryAction

Le WhatsNew.PrimaryAction vous permet de configurer le comportement du bouton principal qui est utilisé pour rejeter le WhatsNewView présenté

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

Remarque: HapticFeedback ne sera exécuté que sur iOS

WhatsNew.SecondaryAction

Une WhatsNew.SecondaryAction qui s'affiche au-dessus du WhatsNew.PrimaryAction peut être fournie éventuellement lors de l'initialisation d'une instance WhatsNew et vous permet de présenter une vue supplémentaire, d'effectuer une action personnalisée ou d'ouvrir une URL.

// 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
        // ...
    }
)

Remarque: HapticFeedback ne sera exécuté que sur iOS

Mise en page

WhatsNewkit vous permet d'ajuster la disposition d'un WhatsNewView présenté de différentes manières.

Le moyen le plus simple est de muter l'instance WhatsNew.Layout.default .

 WhatsNew . Layout . default . featureListSpacing = 35

Lorsque vous utilisez le style de présentation automatique, vous pouvez fournir une disposition par défaut lors de l'initialisation de WhatsNewen Environment.

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

Vous pouvez également passer un WhatsNew.Layout lorsque vous présentez automatiquement ou manuellement le WhatsNewView

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

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

WhatsNewViewController

Lorsque vous utilisez UIKit ou AppKit vous pouvez utiliser WhatsNewViewController .

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

Si vous souhaitez présenter un WhatsNewViewController uniquement si la version de l'instance WhatsNew n'a pas été présentée, vous pouvez utiliser l'initialiseur de commodité à l'échelle.

// 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 )