StoreKitHelper/README.zh.md

<div markdown="1">
  <sup>使用 <a href="https://wangchujiang.com/#/app" target="_blank">我的应用</a> 也是一种 <a href="https://wangchujiang.com/#/sponsor" target="_blank">支持</a> 我的方式：</sup>
  <br>
  <a target="_blank" href="https://apps.apple.com/app/6758053530" title="Scap: Screenshot & Markup Edit for macOS"><img alt="Scap: Screenshot & Markup Edit" height="52" width="52" src="https://wangchujiang.com/appicon/scap.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6757317079" title="Screen Test for macOS"><img alt="Screen Test" height="52" width="52" src="https://wangchujiang.com/appicon/screen-test.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/Deskmark/6755948110" title="Deskmark for macOS"><img alt="Deskmark" height="52" width="52" src="https://wangchujiang.com/appicon/deskmark.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/Keyzer/6500434773" title="Keyzer for macOS"><img alt="Keyzer" height="52" width="52" src="https://wangchujiang.com/appicon/keyzer.png"></a>
  <a target="_blank" href="https://github.com/jaywcjlove/vidwall-hub" title="Vidwall Hub for macOS"><img alt="Vidwall Hub" height="52" width="52" src="https://wangchujiang.com/appicon/vidwall-hub.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/VidCrop/6752624705" title="VidCrop for macOS"><img alt="VidCrop" height="52" width="52" src="https://wangchujiang.com/appicon/vidcrop.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/Vidwall/6747587746" title="Vidwall for macOS"><img alt="Vidwall" height="52" width="52" src="https://wangchujiang.com/appicon/vidwall.png"></a>
  <a target="_blank" href="https://wangchujiang.com/mousio-hint/" title="Mousio Hint for macOS"><img alt="Mousio Hint" height="52" width="52" src="https://wangchujiang.com/appicon/mousio-hint.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6746747327" title="Mousio for macOS"><img alt="Mousio" height="52" width="52" src="https://wangchujiang.com/appicon/mousio.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6745227444" title="Musicer for macOS"><img alt="Musicer" height="52" width="52" src="https://wangchujiang.com/appicon/musicer.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6743841447" title="Audioer for macOS"><img alt="Audioer" height="52" width="52" src="https://wangchujiang.com/appicon/audioer.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6744690194" title="FileSentinel for macOS"><img alt="FileSentinel" height="52" width="52" src="https://wangchujiang.com/appicon/file-sentinel.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6743495172" title="FocusCursor for macOS"><img alt="FocusCursor" height="52" width="52" src="https://wangchujiang.com/appicon/focus-cursor.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6742680573" title="Videoer for macOS"><img alt="Videoer" height="52" width="52" src="https://wangchujiang.com/appicon/videoer.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6740425504" title="KeyClicker for macOS"><img alt="KeyClicker" height="52" width="52" src="https://wangchujiang.com/appicon/key-clicker.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6739052447" title="DayBar for macOS"><img alt="DayBar" height="52" width="52" src="https://wangchujiang.com/appicon/daybar.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6739444407" title="Iconed for macOS"><img alt="Iconed" height="52" width="52" src="https://wangchujiang.com/appicon/iconed.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6737160756" title="Menuist for macOS"><img alt="Menuist" height="52" width="52" src="https://wangchujiang.com/appicon/rightmenu-master.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6723903021" title="Paste Quick for macOS"><img alt="Quick RSS" height="52" width="52" src="https://wangchujiang.com/appicon/paste-quick.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6670696072?platform=mac" title="Quick RSS for macOS/iOS"><img alt="Quick RSS" height="52" width="52" src="https://wangchujiang.com/appicon/quick-rss.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6670167443" title="Web Serve for macOS"><img alt="Web Serve" height="52" width="52" src="https://wangchujiang.com/appicon/web-serve.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6503953628?platform=mac" title="Copybook Generator for macOS/iOS"><img alt="Copybook Generator" height="52" width="52" src="https://wangchujiang.com/appicon/copybook-generator.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6471227008?platform=mac" title="DevTutor for macOS/iOS"><img alt="DevTutor for SwiftUI" height="52" width="52" src="https://wangchujiang.com/appicon/devtutor.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6479819388?platform=mac" title="RegexMate for macOS/iOS"><img alt="RegexMate" height="52" width="52" src="https://wangchujiang.com/appicon/regex-mate.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6479194014?platform=mac" title="Time Passage for macOS/iOS"><img alt="Time Passage" height="52" width="52" src="https://wangchujiang.com/appicon/time-passage.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6478772538" title="IconizeFolder for macOS"><img alt="Iconize Folder" height="52" width="52" src="https://wangchujiang.com/appicon/iconize-folder.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6478511402?platform=mac" title="Textsound Saver for macOS/iOS"><img alt="Textsound Saver" height="52" width="52" src="https://wangchujiang.com/appicon/textsound-saver.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6476924627" title="Create Custom Symbols for macOS"><img alt="Create Custom Symbols" height="52" width="52" src="https://wangchujiang.com/appicon/create-custom-symbols.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6476452351" title="DevHub for macOS"><img alt="DevHub" height="52" width="52" src="https://wangchujiang.com/appicon/devhub.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6476400184" title="Resume Revise for macOS"><img alt="Resume Revise" height="52" width="52" src="https://wangchujiang.com/appicon/resume-revise.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6472593276" title="Palette Genius for macOS"><img alt="Palette Genius" height="52" width="52" src="https://wangchujiang.com/appicon/palette-genius.png"></a>
  <a target="_blank" href="https://apps.apple.com/app/6470879005" title="Symbol Scribe for macOS"><img alt="Symbol Scribe" height="52" width="52" src="https://wangchujiang.com/appicon/symbol-scribe.png"></a>
</div>
<hr>

StoreKit Helper
===

[English](./README.md)

专为 SwiftUI 设计的轻量级 StoreKit2 包装器，让应用内购买的实现更加简单。

![StoreKit Helper](https://github.com/user-attachments/assets/d0d27552-9d2d-4a09-8d8d-b96b3b3648a9)

## 文档

请参阅 [DevTutor](https://github.com/jaywcjlove/devtutor) 中详细的 `StoreKitHelper` [文档](https://github.com/jaywcjlove/devtutor)，其中包括多个快速入门示例、自定义支付界面示例和 API 参考，提供全面的示例和指导。

## 功能特性

- 🚀 **SwiftUI 原生**: 专为 SwiftUI 设计，支持 `@ObservableObject` 和 `@EnvironmentObject`
- 💡 **简洁 API**: 干净直观的应用内购买管理接口
- 🔄 **自动更新**: 实时交易监控和状态更新
- ✅ **类型安全**: 基于协议的产品定义，提供编译时安全性
- 🧪 **可测试**: 完全可测试的架构，测试用例覆盖 [ExampleTests.swift](https://github.com/jaywcjlove/StoreKitHelper/blob/main/Example/ExampleTests/ExampleTests.swift)/[StoreKitHelperTests.swift](https://github.com/jaywcjlove/StoreKitHelper/blob/main/Tests/StoreKitHelperTests/StoreKitHelperTests.swift)

## 使用方法

在 SwiftUI 应用程序的入口点创建并注入一个 `StoreContext` 实例，它负责加载产品列表和跟踪购买状态。

```swift
import StoreKitHelper

enum AppProduct: String, InAppProduct {
    case lifetime = "focuscursor.lifetime"
    case monthly = "focuscursor.monthly"
    var id: String { rawValue }
}

@main struct DevTutorApp: App {
    @StateObject var store = StoreContext(products: AppProduct.allCases)
    var body: some Scene {
        WindowGroup {
            ContentView().environmentObject(store)
        }
    }
}
```

`StoreContext` 现在提供三态购买状态。应用启动时，`purchaseStatus` 会先处于 `.loading`，直到 `Transaction.currentEntitlements` 首次同步完成。在这段时间里，`hasPurchased` 和 `hasNotPurchased` 都会返回 `false`，从而避免启动阶段被误判成“未购买”。

```swift
switch store.purchaseStatus {
case .loading:
    // 正在同步购买状态
case .purchased:
    // ✅ 用户存在有效购买
case .notPurchased:
    // 🧾 用户当前没有有效购买
}
```

推荐写法：

```swift
@EnvironmentObject var store: StoreContext

var body: some View {
    switch store.purchaseStatus {
    case .loading:
        ProgressView("正在检查购买状态...")
    case .purchased:
        // ✅ 用户已购买 - 显示完整功能
    case .notPurchased:
        // 🧾 用户未购买 - 显示受限内容或提示购买
    }
}
```

默认购买调用方式保持不变：

```swift
await store.purchase(product)
```

如果需要传递 StoreKit 的购买选项，现在也可以直接透传：

```swift
await store.purchase(product, options: [
    .appAccountToken(appAccountToken)
])
```

兼容旧写法：

```swift
@EnvironmentObject var store: StoreContext

var body: some View {
    if store.hasResolvedPurchaseStatus == false {
        ProgressView("正在检查购买状态...")
    } else if store.hasNotPurchased == true {
        // 🧾 用户未购买 - 显示受限内容或提示购买
    } else if store.hasPurchased == true {
        // ✅ 用户已购买 - 显示完整功能
    }
}
```

## StoreKitHelperView

使用 `StoreKitHelperView` 直接显示应用内购买弹窗视图，并通过链式 API 配置各种参数。

```swift
struct PurchaseContent: View {
    @EnvironmentObject var store: StoreContext
    var body: some View {
        let locale: Locale = Locale(identifier: Locale.preferredLanguages.first ?? "en")
        StoreKitHelperView()
            .environment(\.locale, .init(identifier: locale.identifier))
            .environment(\.pricingContent, { AnyView(PricingContent()) })
            .environment(\.popupDismissHandle, {
                // 弹窗被关闭时触发（例如用户点击关闭按钮）
                store.isShowingPurchasePopup = false
            })
            .environment(\.termsOfServiceHandle, {
                // 点击【服务条款】按钮时触发的操作
            })
            .environment(\.privacyPolicyHandle, {
                // 点击【隐私政策】按钮时触发的操作
            })
            .frame(maxWidth: 300)
            .frame(minWidth: 260)
    }
}
```

点击打开付费产品列表界面。

```swift
struct ContentView: View {
    @EnvironmentObject var store: StoreContext
    var body: some View {
        if store.hasNotPurchased == true, store.isLoading == false {
            PurchasePopupButton()
                .sheet(isPresented: $store.isShowingPurchasePopup) {
                    PurchaseContent()
                }
        }
    }
}
```

## StoreKitHelperSelectionView

跟 `StoreKitHelperView` 差不多，选择购买项进行支付。

```swift
struct PurchaseContent: View {
    @EnvironmentObject var store: StoreContext
    var body: some View {
        let locale: Locale = Locale(identifier: Locale.preferredLanguages.first ?? "en")
        StoreKitHelperSelectionView()
            .environment(\.locale, .init(identifier: locale.identifier))
            .environment(\.pricingContent, { AnyView(PricingContent()) })
            .environment(\.popupDismissHandle, {
                // 弹窗被关闭时触发（例如用户点击关闭按钮）
                store.isShowingPurchasePopup = false
            })
            .environment(\.termsOfServiceHandle, {
                // 点击【服务条款】按钮时触发的操作
            })
            .environment(\.privacyPolicyHandle, {
                // 点击【隐私政策】按钮时触发的操作
            })
            .frame(maxWidth: 300)
            .frame(minWidth: 260)
    }
}
```

## API 参考

### InAppProduct 协议

```swift
protocol InAppProduct: CaseIterable {
    var id: String { get }
}
```

### PurchaseStatus

```swift
enum PurchaseStatus {
    case loading
    case purchased
    case notPurchased
}
```

### StoreContext 属性

- `products: [Product]` - 从 App Store 获取的可用产品列表
- `purchasedProductIDs: Set<String>` - 已购买产品标识符的集合
- `purchaseStatus: PurchaseStatus` - 当前购买状态：`.loading`、`.purchased`、`.notPurchased`
- `hasResolvedPurchaseStatus: Bool` - 首次购买状态同步是否已完成
- `hasNotPurchased: Bool` - 在购买状态完成解析后，用户是否未购买任何产品
- `hasPurchased: Bool` - 在购买状态完成解析后，用户是否已购买任何产品
- `isLoading: Bool` - 产品是否正在加载中
- `errorMessage: String?` - 当前错误信息（如有）

### StoreContext 方法

- `purchase(_ product: Product, options: Set<Product.PurchaseOption> = [])` - 购买指定产品，并可选透传 StoreKit 购买参数
- `restorePurchases()` - 恢复之前的购买
- `isPurchased(_ productID: ProductID) -> Bool` - 根据 ID 检查产品是否已购买
- `isPurchased(_ product: InAppProduct) -> Bool` - 检查产品是否已购买
- `product(for productID: ProductID) -> Product?` - 根据 ID 获取产品
- `product(for product: InAppProduct) -> Product?` - 根据 InAppProduct 获取产品

## 许可证

基于 MIT 许可证授权。