如何基于SwiftData模型创建带树形子项的List组件

云上老周

2026-7-4

错误原因

你遇到的「Unknown related type error」是因为SwiftData对模型关联关系有严格要求：自关联的集合属性不能直接用普通数组声明，必须通过@Relationship注解明确关联规则，否则模型宏无法识别关联的类型。

解决方案

1. 修正模型定义，添加自关联注解

修改LibraryItem模型，通过双向自关联满足SwiftData的要求：

@Model final class LibraryItem: Identifiable {
    @Attribute(.unique) let id: UUID
    var name: String
    
    // 父项反向关联
    var parentItem: LibraryItem?
    // 子项集合，通过inverse指定与父项的关联关系
    @Relationship(inverse: \LibraryItem.parentItem) var subMenuItems: [LibraryItem] = []
    
    init(id: UUID = UUID(), name: String) {
        self.id = id
        self.name = name
    }
}

新增parentItem作为反向关联，让SwiftData明确子项与父项的归属关系
用@Relationship(inverse: \LibraryItem.parentItem)标记subMenuItems，解决模型宏的类型识别错误

2. 调整树形结构构建逻辑

递归构建文件系统层级时，为每个子项设置parentItem，确保关联关系正确：

// 示例递归构建函数
func buildLibraryItem(from url: URL) -> LibraryItem {
    let item = LibraryItem(name: url.lastPathComponent)
    do {
        let contents = try FileManager.default.contentsOfDirectory(at: url, includingPropertiesForKeys: nil)
        for contentUrl in contents where contentUrl.hasDirectoryPath {
            let subItem = buildLibraryItem(from: contentUrl)
            subItem.parentItem = item // 绑定父项
            item.subMenuItems.append(subItem)
        }
    } catch {
        // 处理目录读取错误
    }
    return item
}

3. 保持List代码不变（或微调可选性）

现在subMenuItems是非可选的空数组，List的树形展示逻辑可直接沿用：

List(
    libraryItems,
    children: \.subMenuItems,
    selection: Binding(
        get: { selectedLibraryItemId },
        set: { ids, _ in selectionHandler(ids) }
    )
) { item in
    Text(item.name)
}

SwiftData会对关联的子项集合做懒加载，只有展开树形节点时才加载对应子项，避免了计算属性一次性初始化所有子项的性能问题。

4. 模型容器初始化无需修改

原有的ModelContainer初始化代码可直接使用，模型结构调整后仍属于同一个Schema：

init() {
    let schema = Schema([LibraryItem.self])
    let config = ModelConfiguration(schema: schema, groupContainer: .identifier("antonincharvat.com.appName"))
    
    do {
        let container = try ModelContainer(for: schema, configurations: config)
        self.libraryItemsModelContainer = container
    } catch {
        fatalError("Couldn't create ModelContainer")
    }
}

额外注意事项

若为已有数据的项目，修改模型后需处理SwiftData的数据迁移，确保现有数据正确映射到新的关联结构
双向自关联能保证数据一致性：删除父项时子项的parentItem会自动置空；删除子项时父项的subMenuItems会同步移除该子项

内容的提问来源于stack exchange，提问作者Antonin Charvat