WhatsNewKit

import SwiftUI
import WhatsNewKit

struct ContentView : View {

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

} 

คุณสมบัติ

• นำเสนอคุณสมบัติแอพใหม่ของคุณได้อย่างง่ายดายหรือไม่?
• โหมดการนำเสนออัตโนมัติและด้วยตนเอง✅
• สนับสนุน Swiftui, Uikit และ AppKit? ‍?
• ทำงานบน iOS, macOS และ Visionos? -
• เค้าโครงปรับได้?

การติดตั้ง

Swift Package Manager

หากต้องการรวมโดยใช้ Swift Package Manager ของ Apple ให้เพิ่มสิ่งต่อไปนี้เป็นการพึ่งพา Package.swift ของคุณ:

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

หรือนำทางไปยังโครงการ XCode ของคุณจากนั้นเลือก Swift Packages คลิกไอคอน“+” และค้นหา WhatsNewKit

ตัวอย่าง

ตรวจสอบแอปพลิเคชันตัวอย่างเพื่อดู WhatsNewKit ในการดำเนินการ เพียงเปิด Example/Example.xcodeproj แล้วเรียกใช้โครงการ "ตัวอย่าง"

การใช้งาน

สารบัญ

• การนำเสนอด้วยตนเอง
• การนำเสนออัตโนมัติ
• WhatsNewenVironment
• WhatsNewversionStore
• WhatsNew
• เค้าโครง
• WhatsNewViewController

การนำเสนอด้วยตนเอง

หากคุณต้องการนำเสนอ WhatsNewView ด้วยตนเองคุณสามารถใช้ประโยชน์จาก sheet(whatsNew:) ตัวดัดแปลง

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

}

การนำเสนออัตโนมัติ

โหมดการนำเสนออัตโนมัติช่วยให้คุณสามารถประกาศคุณสมบัติใหม่ของคุณผ่านสภาพแวดล้อม Swiftui และ WhatsNewKit จะดูแลเพื่อนำเสนอ WhatsNewView ที่เกี่ยวข้อง

ก่อนอื่นเพิ่ม .whatsNewSheet() modifier ลงในมุมมองที่ควรนำเสนอ WhatsNewView

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

}

ตัวปรับเปลี่ยน .whatsNewSheet() กำลังใช้ประโยชน์จาก WhatsNewEnvironment เพื่อดึงวัตถุ WhatsNew เสริมที่ควรนำเสนอต่อผู้ใช้สำหรับเวอร์ชันปัจจุบัน ดังนั้นคุณสามารถกำหนดค่า WhatsNewEnvironment ผ่านตัวดัดแปลง 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 " ,
            // ...
        )
    }

} 

WhatsNewenVironment

WhatsNewEnvironment จะดูแลเพื่อกำหนดวัตถุ WhatsNew ที่ตรงกันที่ควรนำเสนอให้กับผู้ใช้สำหรับเวอร์ชันปัจจุบัน

เท่าที่เห็นในตัวอย่างก่อนหน้านี้คุณสามารถเริ่มต้น WhatsNewEnvironment โดยการระบุ WhatsNewVersionStore และให้บริการ 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 " ,
            // ...
        )
    }
)

นอกจากนี้ WhatsNewEnvironment ยังมีทางเลือกสำหรับรุ่นแพตช์ ตัวอย่างเช่นเมื่อผู้ใช้ติดตั้งเวอร์ชัน 1.0.1 และคุณได้ประกาศ WhatsNew สำหรับเวอร์ชัน 1.0.0 สภาพแวดล้อมจะย้อนกลับไปที่เวอร์ชัน 1.0.0 โดยอัตโนมัติและนำเสนอ WhatsNewView ให้กับผู้ใช้หากจำเป็น

หากคุณต้องการปรับแต่งพฤติกรรมของ WhatsNewEnvironment เพิ่มเติมคุณสามารถ subclass ได้อย่างง่ายดายและแทนที่ฟังก์ชัน 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

A WhatsNewVersionStore เป็นประเภทโปรโตคอลที่รับผิดชอบในการบันทึกและดึงเวอร์ชันที่นำเสนอต่อผู้ใช้

 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 มาพร้อมกับการใช้งานที่กำหนดไว้ล่วงหน้าสามครั้ง:

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

หากคุณมีการใช้งานเฉพาะเพื่อจัดเก็บการตั้งค่าที่เกี่ยวข้องกับผู้ใช้เช่น Realm หรือ Core Data คุณสามารถนำการใช้งานที่มีอยู่ของคุณไปใช้กับโปรโตคอล WhatsNewVersionStore ได้อย่างง่ายดาย

nsubiquitouskeyvaluewhatsnewversionstore

หากคุณใช้ประโยชน์จาก NSUbiquitousKeyValueWhatsNewVersionStore โปรดตรวจสอบให้แน่ใจว่าสามารถเปิดใช้งานความสามารถในการจัดเก็บค่าคีย์ iCloud ในส่วน "การลงนามและความสามารถ" ของโครงการ XCode ของคุณ

WhatsNew

ส่วนต่อไปนี้อธิบายว่า struct WhatsNew สามารถเริ่มต้นได้อย่างไรเพื่ออธิบายคุณสมบัติใหม่สำหรับแอพเวอร์ชันที่กำหนด

 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

WhatsNew.Version ระบุเวอร์ชันที่ได้แนะนำคุณสมบัติบางอย่างให้กับแอปของคุณ

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

A WhatsNew.Title แสดงถึงข้อความชื่อเรื่องที่แสดงผลเหนือฟีเจอร์

// 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 อธิบายคุณสมบัติเฉพาะของแอพของคุณและโดยทั่วไปประกอบด้วยรูปภาพชื่อเรื่องและคำบรรยาย

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

whatsnew.primaryaction

WhatsNew.PrimaryAction ช่วยให้คุณกำหนดค่าพฤติกรรมของปุ่มหลักซึ่งใช้ในการยกเลิก WhatsNewView ที่นำเสนอ

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

หมายเหตุ: HapticFeedback จะถูกดำเนินการบน iOS เท่านั้น

WhatsNew.SecondaryAction

A WhatsNew.SecondaryAction ซึ่งแสดงอยู่เหนือ WhatsNew.PrimaryAction สามารถเลือกได้เมื่อเริ่มต้นอินสแตนซ์ WhatsNew และช่วยให้คุณนำเสนอมุมมองเพิ่มเติมดำเนินการที่กำหนดเองหรือเปิด 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
        // ...
    }
)

หมายเหตุ: HapticFeedback จะถูกดำเนินการบน iOS เท่านั้น

เค้าโครง

WhatsNewKit ช่วยให้คุณสามารถปรับเค้าโครงของ WhatsNewView ที่นำเสนอได้หลายวิธี

วิธีที่ง่ายที่สุดคือการกลายพันธุ์อินสแตนซ์ WhatsNew.Layout.default

 WhatsNew . Layout . default . featureListSpacing = 35

เมื่อใช้รูปแบบการนำเสนออัตโนมัติคุณสามารถจัดหาเค้าโครงเริ่มต้นเมื่อเริ่มต้นการเริ่มต้นของ WhatsNewenVironment

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

หรือคุณสามารถผ่าน WhatsNew.Layout ได้เมื่อนำเสนอ 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

เมื่อใช้ UIKit หรือ AppKit คุณสามารถใช้ประโยชน์จาก WhatsNewViewController

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

หากคุณต้องการนำเสนอ WhatsNewViewController เฉพาะในกรณีที่ไม่ได้นำเสนออินสแตนซ์ของ WhatsNew เวอร์ชันคุณสามารถใช้ประโยชน์จากการเริ่มต้นที่ล้มเหลวอย่างสะดวกสบาย

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