tipkit

仓库: dpearson2699/swift-ios-skills
安装量: 277
排名: #3235

安装

npx skills add https://github.com/dpearson2699/swift-ios-skills --skill tipkit
TipKit
Add feature discovery tips, contextual hints, and onboarding coach marks to
iOS 17+ apps using Apple's TipKit framework. TipKit manages display frequency,
eligibility rules, and persistence so tips appear at the right time and
disappear once the user has learned the feature.
Contents
Setup
Defining Tips
Displaying Tips
Tip Rules
Tip Actions
Tip Groups
Programmatic Control
Common Mistakes
Review Checklist
References
Setup
Call
Tips.configure()
once in
App.init
, before any views render. This
initializes the tips datastore and begins rule evaluation. Calling it later
risks a race where tip views attempt to display before the datastore is ready.
import
SwiftUI
import
TipKit
@main
struct
MyApp
:
App
{
init
(
)
{
try
?
Tips
.
configure
(
[
.
datastoreLocation
(
.
applicationDefault
)
]
)
}
var
body
:
some
Scene
{
WindowGroup
{
ContentView
(
)
}
}
}
DatastoreLocation Options
Option
Use Case
.applicationDefault
Default location, app sandbox (most apps)
.groupContainer(identifier:)
Share tips state across app and extensions
.url(_:)
Custom file URL for full control over storage location
CloudKit Sync
Sync tip state across a user's devices so they do not see the same tip on
every device. Add the CloudKit container option alongside the datastore
location.
try
?
Tips
.
configure
(
[
.
datastoreLocation
(
.
applicationDefault
)
,
.
cloudKitContainer
(
.
named
(
"iCloud.com.example.app"
)
)
]
)
Defining Tips
Conform a struct to the
Tip
protocol. Provide a
title
at minimum.
Add
message
for supporting detail and
image
for a leading icon. Keep
titles short and action-oriented because the tip appears as a compact callout.
import
TipKit
struct
FavoriteTip
:
Tip
{
var
title
:
Text
{
Text
(
"Pin Your Favorites"
)
}
var
message
:
Text
?
{
Text
(
"Tap the heart icon to save items for quick access."
)
}
var
image
:
Image
?
{
Image
(
systemName
:
"heart"
)
}
}
Properties
:
title
(required),
message
(optional detail),
image
(optional leading icon),
actions
(optional buttons),
rules
(optional eligibility conditions),
options
(display frequency, max count).
Lifecycle
Pending (rules unsatisfied) -> Eligible (all rules pass) -> Invalidated (dismissed, actioned, or programmatically removed). Once invalidated, a tip does not reappear unless the datastore is reset. Displaying Tips Inline Tips with TipView Embed a TipView directly in your layout. It renders as a rounded card that appears and disappears with animation. Use for tips within scrollable content. let favoriteTip = FavoriteTip ( ) var body : some View { VStack { TipView ( favoriteTip ) ItemListView ( ) } } Popover Tips with .popoverTip() Attach a tip as a popover anchored to any view. The framework draws an arrow from the popover to the anchor. Use for tips pointing to a specific control. Button { toggleFavorite ( ) } label : { Image ( systemName : "heart" ) } . popoverTip ( favoriteTip ) // Control arrow direction (omit to let system choose) . popoverTip ( favoriteTip , arrowEdge : . bottom ) Custom TipViewStyle Create a custom style to control tip appearance across the app. Conform to TipViewStyle and implement makeBody(configuration:) . struct CustomTipStyle : TipViewStyle { func makeBody ( configuration : Configuration ) -> some View { HStack ( spacing : 12 ) { configuration . image ? . font ( . title2 ) . foregroundStyle ( . tint ) VStack ( alignment : . leading , spacing : 4 ) { configuration . title . font ( . headline ) configuration . message ? . font ( . subheadline ) . foregroundStyle ( . secondary ) } } . padding ( ) } } // Apply globally or per view TipView ( favoriteTip ) . tipViewStyle ( CustomTipStyle ( ) ) Tip Rules Rules control when a tip becomes eligible. All rules in the rules array must pass before the tip displays. TipKit supports two rule types: parameter-based and event-based. Parameter-Based Rules Use @Parameter to track app state. The tip becomes eligible when the parameter value satisfies the rule condition. struct FavoriteTip : Tip { @Parameter static var hasSeenList : Bool = false var title : Text { Text ( "Pin Your Favorites" ) } var rules : [ Rule ] {

Rule

( Self . $hasSeenList ) { $0 == true } } } // Set the parameter when the user reaches the list FavoriteTip . hasSeenList = true Event-Based Rules Use Tips.Event to track user actions. Donate to the event each time the action occurs. The rule fires when the donation count or timing condition is met. This is ideal for tips that should appear after the user has performed an action several times without discovering a related feature. struct ShortcutTip : Tip { static let appOpenedEvent = Tips . Event ( id : "appOpened" ) var title : Text { Text ( "Try the Quick Action" ) } var rules : [ Rule ] {

Rule

( Self . appOpenedEvent ) { $0 . donations . count

= 3 } } } // Donate each time the app opens ShortcutTip . appOpenedEvent . donate ( ) Combining Multiple Rules Place multiple rules in the array. All must pass (logical AND). struct AdvancedTip : Tip { @Parameter static var isLoggedIn : Bool = false static let featureUsedEvent = Tips . Event ( id : "featureUsed" ) var title : Text { Text ( "Unlock Advanced Mode" ) } var rules : [ Rule ] {

Rule

( Self . $isLoggedIn ) { $0 == true }

Rule

( Self . featureUsedEvent ) { $0 . donations . count

= 5 } } } Display Frequency Options Control how often tips appear using the options property. struct DailyTip : Tip { var title : Text { Text ( "Daily Reminder" ) } var options : [ TipOption ] { MaxDisplayCount ( 3 ) // Show at most 3 times total IgnoresDisplayFrequency ( true ) // Bypass global frequency limit } } Global display frequency is set at configuration time: try ? Tips . configure ( [ . displayFrequency ( . daily ) // .immediate, .hourly, .daily, .weekly, .monthly ] ) With .daily , the system shows at most one tip per day across the entire app, unless a specific tip sets IgnoresDisplayFrequency(true) . Tip Actions Add action buttons to a tip for direct interaction. Each action has an id and a label. Handle the action in the tip view's action handler. struct FeatureTip : Tip { var title : Text { Text ( "Try the New Editor" ) } var message : Text ? { Text ( "We added a powerful new editing mode." ) } var actions : [ Action ] { Action ( id : "open-editor" , title : "Open Editor" ) Action ( id : "learn-more" , title : "Learn More" ) } } Handle actions in the view: TipView ( featureTip ) { action in switch action . id { case "open-editor" : navigateToEditor ( ) featureTip . invalidate ( reason : . actionPerformed ) case "learn-more" : showHelpSheet = true default : break } } Tip Groups Use TipGroup to coordinate multiple tips within a single view. TipGroup ensures only one tip from the group displays at a time, preventing tip overload. Tips display in priority order. struct OnboardingView : View { let tipGroup = TipGroup ( . ordered ) { WelcomeTip ( ) NavigationTip ( ) ProfileTip ( ) } var body : some View { VStack { if let currentTip = tipGroup . currentTip { TipView ( currentTip ) } Button ( "Next" ) { tipGroup . currentTip ? . invalidate ( reason : . actionPerformed ) } } } } Priority Options Initializer Behavior .ordered Tips display in the order they are listed When the current tip is invalidated, the next eligible tip in the group becomes currentTip . Programmatic Control Invalidating Tips Call invalidate(reason:) when the user performs the discovered action or when the tip is no longer relevant. let tip = FavoriteTip ( ) tip . invalidate ( reason : . actionPerformed ) Reason When to Use .actionPerformed User performed the action the tip describes .displayCountExceeded Tip hit its maximum display count .tipClosed User explicitly dismissed the tip Testing Utilities TipKit provides static methods to control tip visibility during development and testing. Gate these behind

if DEBUG

or ProcessInfo checks so they never run in production builds.

if

DEBUG // Show all tips regardless of rules (useful during development) Tips . showAllTipsForTesting ( ) // Show only specific tips Tips . showTipsForTesting ( [ FavoriteTip . self , ShortcutTip . self ] ) // Hide all tips (useful for UI tests that do not involve tips) Tips . hideAllTipsForTesting ( ) // Reset the datastore (clears all tip state, invalidations, and events) try ? Tips . resetDatastore ( )

endif

Using ProcessInfo for Test Schemes if ProcessInfo . processInfo . arguments . contains ( "--show-all-tips" ) { Tips . showAllTipsForTesting ( ) } Pass --show-all-tips as a launch argument in the Xcode scheme for development builds. Common Mistakes DON'T: Call Tips.configure() anywhere except App.init Calling Tips.configure() in a view's onAppear or task modifier creates a race condition where tip views try to render before the datastore is ready, causing missing or flickering tips. // WRONG struct ContentView : View { var body : some View { Text ( "Hello" ) . task { try ? Tips . configure ( ) } // Too late, views already rendered } } // CORRECT @main struct MyApp : App { init ( ) { try ? Tips . configure ( ) } var body : some Scene { WindowGroup { ContentView ( ) } } } DON'T: Show too many tips at once Displaying multiple tips simultaneously overwhelms users and dilutes the impact of each tip. Users learn to ignore them. // WRONG: Three tips visible at the same time VStack { TipView ( tipA ) TipView ( tipB ) TipView ( tipC ) } // CORRECT: Use TipGroup to sequence them let group = TipGroup ( . ordered ) { TipA ( ) ; TipB ( ) ; TipC ( ) } if let currentTip = group . currentTip { TipView ( currentTip ) } DON'T: Forget to invalidate tips after the user performs the action If a tip says "Tap the star to favorite" and the user taps the star but the tip remains, it erodes trust in the UI. // WRONG: Tip stays visible after user acts Button ( "Favorite" ) { toggleFavorite ( ) } . popoverTip ( favoriteTip ) // CORRECT: Invalidate on action Button ( "Favorite" ) { toggleFavorite ( ) favoriteTip . invalidate ( reason : . actionPerformed ) } . popoverTip ( favoriteTip ) DON'T: Leave testing tips enabled in production Tips.showAllTipsForTesting() bypasses all rules and frequency limits. Shipping this in production means every user sees every tip immediately. // WRONG: Always active Tips . showAllTipsForTesting ( ) // CORRECT: Gated behind DEBUG

if

DEBUG Tips . showAllTipsForTesting ( )

endif

DON'T: Make tip titles too long Long titles get truncated or wrap awkwardly in the compact tip callout. Put the key action in the title and supporting context in the message. // WRONG var title : Text { Text ( "You can tap the heart button to save this item to your favorites list" ) } // CORRECT var title : Text { Text ( "Save to Favorites" ) } var message : Text ? { Text ( "Tap the heart icon to keep items for quick access." ) } DON'T: Use tips for critical information Users can dismiss tips at any time and they do not reappear. Never put essential instructions or safety information in a tip. // WRONG: Critical info in a dismissible tip struct DataLossTip : Tip { var title : Text { Text ( "Unsaved changes will be lost" ) } } // CORRECT: Use an alert or inline warning for critical information // Reserve tips for feature discovery and progressive disclosure Review Checklist Tips.configure() called in App.init , before any views render Each tip has a clear, concise title (action-oriented, under ~40 characters) Tips invalidated when the user performs the discovered action Rules set so tips appear at the right time (not immediately on first launch for all tips) TipGroup used when multiple tips exist in one view Testing utilities ( showAllTipsForTesting , resetDatastore ) gated behind

if DEBUG

CloudKit sync configured if the app supports multiple devices Display frequency set appropriately ( .daily or .weekly for most apps) Tips used for feature discovery only, not for critical information Custom TipViewStyle applied consistently if the default style does not match the app design Tip actions handled and tip invalidated in the action handler Event donations placed at the correct user action points Ensure custom Tip types are Sendable; configure Tips on @MainActor References See references/tipkit-patterns.md for complete implementation patterns including custom styles, event-based rules, tip groups, testing strategies, onboarding flows, and SwiftUI preview configuration.

← 返回排行榜