Skip to content

Commit 4deb777

Browse files
fatbobmanclaude
andcommitted
Add App Group support documentation to Chinese README
- Added limitToInstance parameter documentation in Chinese 宏参数 section - Added comprehensive App Groups和跨进程同步 section explaining: - The cross-process notification problem in App Groups - Solution using limitToInstance: false parameter - Critical importance of unique prefixes for system-wide notification filtering - Performance considerations for different limitToInstance settings - Updated code examples with Chinese comments - Maintains consistency with English README documentation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 78b895d commit 4deb777

1 file changed

Lines changed: 79 additions & 0 deletions

File tree

README_zh.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -240,13 +240,24 @@ public init(
240240
- `prefix`: `UserDefaults` 键的前缀。
241241
- `autoInit`: 是否自动生成初始化器(默认为 `true`)。
242242
- `observeFirst`: 观察优先级模式(默认为 `false`)。
243+
- `limitToInstance`: 是否限制观察特定的 UserDefaults 实例(默认为 `true`)。设置为 `false` 以支持 App Group 跨进程同步。
243244

244245
```swift
245246
@ObservableDefaults(autoInit: false, ignoreExternalChanges: true, prefix: "myApp_")
246247
class Settings {
247248
@DefaultsKey(userDefaultsKey: "fullName")
248249
var name: String = "Fatbobman"
249250
}
251+
252+
// App Group 跨进程同步
253+
@ObservableDefaults(
254+
suiteName: "group.myapp",
255+
prefix: "myapp_",
256+
limitToInstance: false
257+
)
258+
class SharedSettings {
259+
var lastUpdate: Date = Date()
260+
}
250261
```
251262

252263
#### @ObservableCloud 宏参数
@@ -593,6 +604,74 @@ class CloudSettings {
593604
- ✅ 您遇到了 Swift 6 并发编译错误
594605
- ❌ 您的项目使用默认的 `nonisolated` 设置(不需要参数)
595606

607+
### App Groups 和跨进程同步
608+
609+
当使用 App Groups 在主应用和扩展(小组件、应用扩展)之间共享 UserDefaults 时,您需要特殊配置以确保正确的跨进程通知处理。
610+
611+
#### 问题所在
612+
613+
默认情况下,`@ObservableDefaults` 仅监听来自其特定 UserDefaults 实例的 UserDefaults 变更通知。当使用 App Groups 时:
614+
615+
- 您的主应用创建:`UserDefaults(suiteName: "group.myapp")`
616+
- 您的小组件创建:`UserDefaults(suiteName: "group.myapp")`
617+
618+
即使两者访问相同的数据存储,它们是不同的对象实例。当小组件修改数据时,主应用不会自动接收到关于变更的通知。
619+
620+
#### 解决方案
621+
622+
使用 `limitToInstance: false` 参数启用跨进程通知:
623+
624+
```swift
625+
@ObservableDefaults(
626+
suiteName: "group.com.yourcompany.app",
627+
prefix: "myapp_", // 重要:使用唯一前缀
628+
limitToInstance: false // 启用跨进程通知
629+
)
630+
class SharedSettings {
631+
var lastUpdate: Date = Date()
632+
var displayCount: Int = 0
633+
}
634+
```
635+
636+
#### 关键:必须使用唯一前缀
637+
638+
`limitToInstance: false` 时,宏会监听来自整个系统的所有 UserDefaults 变更通知,而不仅仅是您特定的套件。这意味着它会接收来自:
639+
640+
- `UserDefaults.standard`
641+
- 其他 App Groups(`group.otherapp`
642+
- 您应用中的任何其他 UserDefaults 实例
643+
644+
**前缀充当过滤器**,确保您的类仅响应来自预期 suiteName 的变更:
645+
646+
```swift
647+
// App Group 套件
648+
@ObservableDefaults(
649+
suiteName: "group.myapp",
650+
prefix: "myapp_", // 仅响应以 "myapp_" 开头的键
651+
limitToInstance: false
652+
)
653+
class AppGroupSettings {
654+
var sharedData: String = "data" // 存储为 "myapp_sharedData"
655+
}
656+
657+
// 不同的 App Group 套件
658+
@ObservableDefaults(
659+
suiteName: "group.anotherapp",
660+
prefix: "anotherapp_", // 仅响应以 "anotherapp_" 开头的键
661+
limitToInstance: false
662+
)
663+
class AnotherAppSettings {
664+
var sharedData: String = "other" // 存储为 "anotherapp_sharedData"
665+
}
666+
```
667+
668+
如果没有唯一前缀,您的 `AppGroupSettings` 可能会错误地响应来自 `group.anotherapp``UserDefaults.standard` 的变更。
669+
670+
#### 性能考虑
671+
672+
- **默认(`limitToInstance: true`**:更好的性能,仅监控来自特定 UserDefaults 实例的变更。建议用于单进程应用。
673+
- **跨进程(`limitToInstance: false`**:App Groups 所必需,但会接收所有系统 UserDefaults 通知。前缀对于过滤目标套件中的相关变更至关重要。
674+
596675
### 一般说明
597676

598677
- **外部变化**: 默认情况下,两个宏都响应其各自存储系统中的外部变化。

0 commit comments

Comments
 (0)