homekit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HomeKit

Control home automation accessories and commission Matter devices. HomeKit manages the home/room/accessory model, action sets, and triggers. MatterSupport handles device commissioning into your ecosystem. Targets Swift 6.3 / iOS 26+.

控制家庭自动化配件并完成Matter设备的入网配置。HomeKit负责管理家庭/房间/配件模型、动作集和触发器。MatterSupport则处理设备接入您的生态系统的流程。目标环境为Swift 6.3 / iOS 26+。

Setup

设置

HomeKit Configuration

HomeKit配置

Enable the HomeKit capability in Xcode (Signing & Capabilities)
Add
```
NSHomeKitUsageDescription
```
to Info.plist:

xml

<key>NSHomeKitUsageDescription</key>
<string>This app controls your smart home accessories.</string>

在Xcode的「Signing & Capabilities」中启用HomeKit功能
向Info.plist中添加
```
NSHomeKitUsageDescription
```
：

xml

<key>NSHomeKitUsageDescription</key>
<string>This app controls your smart home accessories.</string>

MatterSupport Configuration

MatterSupport配置

For Matter commissioning into your own ecosystem:

Enable the MatterSupport capability
Add a MatterSupport Extension target to your project
Add the
```
com.apple.developer.matter.allow-setup-payload
```
entitlement if your app provides the setup code directly

如需将Matter设备接入您的自有生态系统：

启用MatterSupport功能
为项目添加MatterSupport Extension目标
如果您的应用直接提供配置码，需添加
```
com.apple.developer.matter.allow-setup-payload
```
权限

Availability Check

可用性检查

swift

import HomeKit

let homeManager = HMHomeManager()

// HomeKit is available on iPhone, iPad, Apple TV, Apple Watch, Mac, and Vision Pro.
// Authorization is handled through the delegate:
homeManager.delegate = self

swift

import HomeKit

let homeManager = HMHomeManager()

// HomeKit 支持在iPhone、iPad、Apple TV、Apple Watch、Mac和Vision Pro上使用。
// 授权流程通过代理处理：
homeManager.delegate = self

HomeKit Data Model

HomeKit数据模型

HomeKit organizes home automation in a hierarchy:

text

HMHomeManager
  -> HMHome (one or more)
       -> HMRoom (rooms in the home)
            -> HMAccessory (devices in a room)
                 -> HMService (functions: light, thermostat, etc.)
                      -> HMCharacteristic (readable/writable values)
       -> HMZone (groups of rooms)
       -> HMActionSet (grouped actions)
       -> HMTrigger (time or event-based triggers)

HomeKit采用层级结构组织家庭自动化内容：

text

HMHomeManager
  -> HMHome（可存在一个或多个）
       -> HMRoom（家庭中的房间）
            -> HMAccessory（房间内的设备）
                 -> HMService（设备功能：灯光、温控器等）
                      -> HMCharacteristic（可读写的特征值）
       -> HMZone（房间组）
       -> HMActionSet（组合动作）
       -> HMTrigger（基于时间或事件的触发器）

Initializing the Home Manager

初始化家庭管理器

Create a single

HMHomeManager

and implement the delegate to know when data is loaded. HomeKit loads asynchronously -- do not access

homes

until the delegate fires.

swift

import HomeKit

final class HomeStore: NSObject, HMHomeManagerDelegate {
    let homeManager = HMHomeManager()

    override init() {
        super.init()
        homeManager.delegate = self
    }

    func homeManagerDidUpdateHomes(_ manager: HMHomeManager) {
        // Safe to access manager.homes now
        let homes = manager.homes
        let primaryHome = manager.primaryHome
        print("Loaded \(homes.count) homes")
    }

    func homeManager(
        _ manager: HMHomeManager,
        didUpdate status: HMHomeManagerAuthorizationStatus
    ) {
        if status.contains(.authorized) {
            print("HomeKit access granted")
        }
    }
}

创建单个

HMHomeManager

实例并实现代理，以知晓数据加载完成时机。HomeKit采用异步加载方式——需等待代理触发后再访问

homes

属性。

swift

import HomeKit

final class HomeStore: NSObject, HMHomeManagerDelegate {
    let homeManager = HMHomeManager()

    override init() {
        super.init()
        homeManager.delegate = self
    }

    func homeManagerDidUpdateHomes(_ manager: HMHomeManager) {
        // 现在可以安全访问manager.homes
        let homes = manager.homes
        let primaryHome = manager.primaryHome
        print("已加载\(homes.count)个家庭")
    }

    func homeManager(
        _ manager: HMHomeManager,
        didUpdate status: HMHomeManagerAuthorizationStatus
    ) {
        if status.contains(.authorized) {
            print("已获取HomeKit访问权限")
        }
    }
}

Accessing Rooms

访问房间

swift

guard let home = homeManager.primaryHome else { return }

let rooms = home.rooms
let kitchen = rooms.first { $0.name == "Kitchen" }

// Room for accessories not assigned to a specific room
let defaultRoom = home.roomForEntireHome()

swift

guard let home = homeManager.primaryHome else { return }

let rooms = home.rooms
let kitchen = rooms.first { $0.name == "Kitchen" }

// 未分配到特定房间的配件所在的默认房间
let defaultRoom = home.roomForEntireHome()

Managing Accessories

配件管理

Discovering and Adding Accessories

发现并添加配件

swift

// System UI for accessory discovery
home.addAndSetupAccessories { error in
    if let error {
        print("Setup failed: \(error)")
    }
}

swift

// 系统UI用于配件发现
home.addAndSetupAccessories { error in
    if let error {
        print("设置失败：\(error)")
    }
}

Listing Accessories and Services

列出配件与服务

swift

for accessory in home.accessories {
    print("\(accessory.name) in \(accessory.room?.name ?? "unassigned")")

    for service in accessory.services {
        print("  Service: \(service.serviceType)")

        for characteristic in service.characteristics {
            print("    \(characteristic.characteristicType): \(characteristic.value ?? "nil")")
        }
    }
}

swift

for accessory in home.accessories {
    print("\(accessory.name) 位于 \(accessory.room?.name ?? "未分配")")

    for service in accessory.services {
        print("  服务：\(service.serviceType)")

        for characteristic in service.characteristics {
            print("    \(characteristic.characteristicType)：\(characteristic.value ?? "nil")")
        }
    }
}

Moving an Accessory to a Room

将配件移至其他房间

swift

guard let accessory = home.accessories.first,
      let bedroom = home.rooms.first(where: { $0.name == "Bedroom" }) else { return }

home.assignAccessory(accessory, to: bedroom) { error in
    if let error {
        print("Failed to move accessory: \(error)")
    }
}

swift

guard let accessory = home.accessories.first,
      let bedroom = home.rooms.first(where: { $0.name == "Bedroom" }) else { return }

home.assignAccessory(accessory, to: bedroom) { error in
    if let error {
        print("移动配件失败：\(error)")
    }
}

Reading and Writing Characteristics

特征值的读写

Reading a Value

读取值

swift

let characteristic: HMCharacteristic = // obtained from a service

characteristic.readValue { error in
    guard error == nil else { return }
    if let value = characteristic.value as? Bool {
        print("Power state: \(value)")
    }
}

swift

let characteristic: HMCharacteristic = // 从服务中获取

characteristic.readValue { error in
    guard error == nil else { return }
    if let value = characteristic.value as? Bool {
        print("电源状态：\(value)")
    }
}

Writing a Value

写入值

swift

// Turn on a light
characteristic.writeValue(true) { error in
    if let error {
        print("Write failed: \(error)")
    }
}

swift

// 打开灯光
characteristic.writeValue(true) { error in
    if let error {
        print("写入失败：\(error)")
    }
}

Observing Changes

监听变化

Enable notifications for real-time updates:

swift

characteristic.enableNotification(true) { error in
    guard error == nil else { return }
}

// In HMAccessoryDelegate:
func accessory(
    _ accessory: HMAccessory,
    service: HMService,
    didUpdateValueFor characteristic: HMCharacteristic
) {
    print("Updated: \(characteristic.value ?? "nil")")
}

启用通知以获取实时更新：

swift

characteristic.enableNotification(true) { error in
    guard error == nil else { return }
}

// 在HMAccessoryDelegate中：
func accessory(
    _ accessory: HMAccessory,
    service: HMService,
    didUpdateValueFor characteristic: HMCharacteristic
) {
    print("已更新：\(characteristic.value ?? "nil")")
}

Action Sets and Triggers

动作集与触发器

Creating an Action Set

创建动作集

HMActionSet

groups characteristic writes that execute together:

swift

home.addActionSet(withName: "Good Night") { actionSet, error in
    guard let actionSet, error == nil else { return }

    // Turn off living room light
    let lightChar = livingRoomLight.powerCharacteristic
    let action = HMCharacteristicWriteAction(
        characteristic: lightChar,
        targetValue: false as NSCopying
    )
    actionSet.addAction(action) { error in
        guard error == nil else { return }
        print("Action added to Good Night scene")
    }
}

HMActionSet

用于将多个特征值写入操作组合执行：

swift

home.addActionSet(withName: "晚安模式") { actionSet, error in
    guard let actionSet, error == nil else { return }

    // 关闭客厅灯光
    let lightChar = livingRoomLight.powerCharacteristic
    let action = HMCharacteristicWriteAction(
        characteristic: lightChar,
        targetValue: false as NSCopying
    )
    actionSet.addAction(action) { error in
        guard error == nil else { return }
        print("动作已添加至晚安场景")
    }
}

Executing an Action Set

执行动作集

swift

home.executeActionSet(actionSet) { error in
    if let error {
        print("Execution failed: \(error)")
    }
}

swift

home.executeActionSet(actionSet) { error in
    if let error {
        print("执行失败：\(error)")
    }
}

Creating a Timer Trigger

创建定时触发器

swift

var dateComponents = DateComponents()
dateComponents.hour = 22
dateComponents.minute = 30

let trigger = HMTimerTrigger(
    name: "Nightly",
    fireDate: Calendar.current.nextDate(
        after: Date(),
        matching: dateComponents,
        matchingPolicy: .nextTime
    )!,
    timeZone: .current,
    recurrence: dateComponents,  // Repeats daily at 22:30
    recurrenceCalendar: .current
)

home.addTrigger(trigger) { error in
    guard error == nil else { return }

    // Attach the action set to the trigger
    trigger.addActionSet(goodNightActionSet) { error in
        guard error == nil else { return }

        trigger.enable(true) { error in
            print("Trigger enabled: \(error == nil)")
        }
    }
}

swift

var dateComponents = DateComponents()
dateComponents.hour = 22
dateComponents.minute = 30

let trigger = HMTimerTrigger(
    name: "夜间模式",
    fireDate: Calendar.current.nextDate(
        after: Date(),
        matching: dateComponents,
        matchingPolicy: .nextTime
    )!,
    timeZone: .current,
    recurrence: dateComponents,  // 每天22:30重复
    recurrenceCalendar: .current
)

home.addTrigger(trigger) { error in
    guard error == nil else { return }

    // 将动作集关联到触发器
    trigger.addActionSet(goodNightActionSet) { error in
        guard error == nil else { return }

        trigger.enable(true) { error in
            print("触发器已启用：\(error == nil)")
        }
    }
}

Creating an Event Trigger

创建事件触发器

swift

let motionDetected = HMCharacteristicEvent(
    characteristic: motionSensorCharacteristic,
    triggerValue: true as NSCopying
)

let eventTrigger = HMEventTrigger(
    name: "Motion Lights",
    events: [motionDetected],
    predicate: nil
)

home.addTrigger(eventTrigger) { error in
    // Add action sets as above
}

swift

let motionDetected = HMCharacteristicEvent(
    characteristic: motionSensorCharacteristic,
    triggerValue: true as NSCopying
)

let eventTrigger = HMEventTrigger(
    name: "移动感应开灯",
    events: [motionDetected],
    predicate: nil
)

home.addTrigger(eventTrigger) { error in
    // 按上述方式添加动作集
}

Matter Commissioning

Matter设备入网

Use

MatterAddDeviceRequest

to commission a Matter device into your ecosystem. This is separate from HomeKit -- it handles the pairing flow.

使用

MatterAddDeviceRequest

将Matter设备接入您的生态系统。此流程独立于HomeKit，负责处理配对流程。

Basic Commissioning

基础入网流程

swift

import MatterSupport

func addMatterDevice() async throws {
    guard MatterAddDeviceRequest.isSupported else {
        print("Matter not supported on this device")
        return
    }

    let topology = MatterAddDeviceRequest.Topology(
        ecosystemName: "My Smart Home",
        homes: [
            MatterAddDeviceRequest.Home(displayName: "Main House")
        ]
    )

    let request = MatterAddDeviceRequest(
        topology: topology,
        setupPayload: nil,
        showing: .allDevices
    )

    // Presents system UI for device pairing
    try await request.perform()
}

swift

import MatterSupport

func addMatterDevice() async throws {
    guard MatterAddDeviceRequest.isSupported else {
        print("此设备不支持Matter")
        return
    }

    let topology = MatterAddDeviceRequest.Topology(
        ecosystemName: "我的智能家居",
        homes: [
            MatterAddDeviceRequest.Home(displayName: "主住宅")
        ]
    )

    let request = MatterAddDeviceRequest(
        topology: topology,
        setupPayload: nil,
        showing: .allDevices
    )

    // 展示系统UI用于设备配对
    try await request.perform()
}

Filtering Devices

筛选设备

swift

// Only show devices from a specific vendor
let criteria = MatterAddDeviceRequest.DeviceCriteria.vendorID(0x1234)

let request = MatterAddDeviceRequest(
    topology: topology,
    setupPayload: nil,
    showing: criteria
)

swift

// 仅显示特定厂商的设备
let criteria = MatterAddDeviceRequest.DeviceCriteria.vendorID(0x1234)

let request = MatterAddDeviceRequest(
    topology: topology,
    setupPayload: nil,
    showing: criteria
)

Combining Device Criteria

组合设备筛选条件

swift

let criteria = MatterAddDeviceRequest.DeviceCriteria.all([
    .vendorID(0x1234),
    .not(.productID(0x0001))  // Exclude a specific product
])

swift

let criteria = MatterAddDeviceRequest.DeviceCriteria.all([
    .vendorID(0x1234),
    .not(.productID(0x0001))  // 排除特定产品
])

MatterAddDeviceExtensionRequestHandler

For full ecosystem support, create a MatterSupport Extension. The extension handles commissioning callbacks:

swift

import MatterSupport

final class MatterHandler: MatterAddDeviceExtensionRequestHandler {

    override func validateDeviceCredential(
        _ deviceCredential: DeviceCredential
    ) async throws {
        // Validate the device attestation certificate
        // Throw to reject the device
    }

    override func rooms(
        in home: MatterAddDeviceRequest.Home?
    ) async -> [MatterAddDeviceRequest.Room] {
        // Return rooms in the selected home
        return [
            MatterAddDeviceRequest.Room(displayName: "Living Room"),
            MatterAddDeviceRequest.Room(displayName: "Kitchen")
        ]
    }

    override func configureDevice(
        named name: String,
        in room: MatterAddDeviceRequest.Room?
    ) async {
        // Save the device configuration to your backend
        print("Configuring \(name) in \(room?.displayName ?? "no room")")
    }

    override func commissionDevice(
        in home: MatterAddDeviceRequest.Home?,
        onboardingPayload: String,
        commissioningID: UUID
    ) async throws {
        // Use the onboarding payload to commission the device
        // into your fabric using the Matter framework
    }
}

如需完整的生态系统支持，请创建MatterSupport扩展。该扩展负责处理入网回调：

swift

import MatterSupport

final class MatterHandler: MatterAddDeviceExtensionRequestHandler {

    override func validateDeviceCredential(
        _ deviceCredential: DeviceCredential
    ) async throws {
        // 验证设备认证证书
        // 抛出错误以拒绝该设备
    }

    override func rooms(
        in home: MatterAddDeviceRequest.Home?
    ) async -> [MatterAddDeviceRequest.Room] {
        // 返回所选家庭中的房间
        return [
            MatterAddDeviceRequest.Room(displayName: "客厅"),
            MatterAddDeviceRequest.Room(displayName: "厨房")
        ]
    }

    override func configureDevice(
        named name: String,
        in room: MatterAddDeviceRequest.Room?
    ) async {
        // 将设备配置保存至您的后端
        print("正在配置 \(name) 至 \(room?.displayName ?? "无房间")")
    }

    override func commissionDevice(
        in home: MatterAddDeviceRequest.Home?,
        onboardingPayload: String,
        commissioningID: UUID
    ) async throws {
        // 使用入网负载通过Matter框架将设备接入您的网络
    }
}

Common Mistakes

常见错误

DON'T: Access homes before the delegate fires

错误做法：在代理触发前访问homes属性

swift

// WRONG -- homes array is empty until delegate is called
let manager = HMHomeManager()
let homes = manager.homes  // Always empty here

// CORRECT -- wait for delegate
func homeManagerDidUpdateHomes(_ manager: HMHomeManager) {
    let homes = manager.homes  // Now populated
}

swift

// 错误——homes数组在代理触发前为空
let manager = HMHomeManager()
let homes = manager.homes  // 此处始终为空

// 正确做法——等待代理触发
func homeManagerDidUpdateHomes(_ manager: HMHomeManager) {
    let homes = manager.homes  // 此时已填充数据
}

DON'T: Confuse HomeKit setup with Matter commissioning

错误做法：混淆HomeKit设置与Matter入网流程

swift

// WRONG -- using HomeKit accessory setup for a Matter ecosystem app
home.addAndSetupAccessories { error in }

// CORRECT -- use MatterAddDeviceRequest for Matter ecosystem commissioning
let request = MatterAddDeviceRequest(
    topology: topology,
    setupPayload: nil,
    showing: .allDevices
)
try await request.perform()

swift

// 错误——为Matter生态应用使用HomeKit配件设置流程
home.addAndSetupAccessories { error in }

// 正确做法——使用MatterAddDeviceRequest处理Matter生态入网
let request = MatterAddDeviceRequest(
    topology: topology,
    setupPayload: nil,
    showing: .allDevices
)
try await request.perform()

DON'T: Forget required entitlements

错误做法：遗漏必要权限

swift

// WRONG -- calling Matter APIs without the MatterSupport entitlement
// Results in runtime error

// CORRECT -- ensure these are set up:
// 1. HomeKit capability for HMHomeManager access
// 2. MatterSupport Extension target for ecosystem commissioning
// 3. com.apple.developer.matter.allow-setup-payload if providing setup codes

swift

// 错误——未添加MatterSupport权限就调用Matter API
// 会导致运行时错误

// 正确做法——确保已完成以下设置：
// 1. 启用HomeKit功能以访问HMHomeManager
// 2. 添加MatterSupport Extension目标以支持生态入网
// 3. 若直接提供配置码，需添加com.apple.developer.matter.allow-setup-payload权限

DON'T: Create multiple HMHomeManager instances

错误做法：创建多个HMHomeManager实例

swift

// WRONG -- each instance loads the full database independently
class ScreenA { let manager = HMHomeManager() }
class ScreenB { let manager = HMHomeManager() }

// CORRECT -- single shared instance
@Observable
final class HomeStore {
    static let shared = HomeStore()
    let homeManager = HMHomeManager()
}

swift

// 错误——每个实例会独立加载完整数据库
class ScreenA { let manager = HMHomeManager() }
class ScreenB { let manager = HMHomeManager() }

// 正确做法——使用单个共享实例
@Observable
final class HomeStore {
    static let shared = HomeStore()
    let homeManager = HMHomeManager()
}

DON'T: Write characteristics without checking metadata

错误做法：未检查元数据就写入特征值

swift

// WRONG -- writing a value outside the valid range
characteristic.writeValue(500) { _ in }

// CORRECT -- check metadata first
if let metadata = characteristic.metadata,
   let maxValue = metadata.maximumValue?.intValue {
    let safeValue = min(brightness, maxValue)
    characteristic.writeValue(safeValue) { _ in }
}

swift

// 错误——写入超出有效范围的值
characteristic.writeValue(500) { _ in }

// 正确做法——先检查元数据
if let metadata = characteristic.metadata,
   let maxValue = metadata.maximumValue?.intValue {
    let safeValue = min(brightness, maxValue)
    characteristic.writeValue(safeValue) { _ in }
}

Review Checklist

审核检查清单

HomeKit capability enabled in Xcode
```
NSHomeKitUsageDescription
```
present in Info.plist
Single
```
HMHomeManager
```
instance shared across the app

HMHomeManagerDelegate

implemented; homes not accessed before

homeManagerDidUpdateHomes

```
HMHomeDelegate
```
set on homes to receive accessory and room changes
```
HMAccessoryDelegate
```
set on accessories to receive characteristic updates
Characteristic metadata checked before writing values
Error handling in all completion handlers
MatterSupport capability and extension target added for Matter commissioning
```
MatterAddDeviceRequest.isSupported
```
checked before performing requests

Matter extension handler implements

commissionDevice(in:onboardingPayload:commissioningID:)

Action sets tested with the HomeKit Accessory Simulator before shipping
Triggers enabled after creation (
```
trigger.enable(true)
```
)

已在Xcode中启用HomeKit功能
Info.plist中已添加
```
NSHomeKitUsageDescription
```
应用中使用单个共享的
```
HMHomeManager
```
实例

已实现

HMHomeManagerDelegate

；未在

homeManagerDidUpdateHomes

触发前访问homes属性

已为家庭设置
```
HMHomeDelegate
```
以接收配件和房间变更通知
已为配件设置
```
HMAccessoryDelegate
```
以接收特征值更新
写入特征值前已检查元数据
所有完成回调中均添加了错误处理
已添加MatterSupport功能和扩展目标以支持Matter入网
执行请求前已检查
```
MatterAddDeviceRequest.isSupported
```

Matter扩展处理器已实现

commissionDevice(in:onboardingPayload:commissioningID:)

方法

上线前已使用HomeKit配件模拟器测试动作集
创建触发器后已启用（
```
trigger.enable(true)
```
）

References

参考资料

Extended patterns (Matter extension, delegate wiring, SwiftUI): references/matter-commissioning.md
HomeKit framework
HMHomeManager
HMHome
HMAccessory
HMRoom
HMActionSet
HMTrigger
MatterSupport framework
MatterAddDeviceRequest
MatterAddDeviceExtensionRequestHandler
Enabling HomeKit in your app
Adding Matter support to your ecosystem

扩展模式（Matter扩展、代理连接、SwiftUI）：references/matter-commissioning.md
HomeKit框架
HMHomeManager
HMHome
HMAccessory
HMRoom
HMActionSet
HMTrigger
MatterSupport框架
MatterAddDeviceRequest
MatterAddDeviceExtensionRequestHandler
在应用中启用HomeKit
为您的生态系统添加Matter支持

homekit

Original

Translation

HomeKit

HomeKit

Contents

目录

Setup

设置

HomeKit Configuration

HomeKit配置

MatterSupport Configuration

MatterSupport配置

Availability Check

可用性检查

HomeKit Data Model

HomeKit数据模型

Initializing the Home Manager

初始化家庭管理器

Accessing Rooms

访问房间

Managing Accessories

配件管理

Discovering and Adding Accessories

发现并添加配件

Listing Accessories and Services

列出配件与服务

Moving an Accessory to a Room

将配件移至其他房间

Reading and Writing Characteristics

特征值的读写

Reading a Value

读取值

Writing a Value

写入值

Observing Changes

监听变化

Action Sets and Triggers

动作集与触发器

Creating an Action Set

创建动作集

Executing an Action Set

执行动作集

Creating a Timer Trigger

创建定时触发器

Creating an Event Trigger

创建事件触发器

Matter Commissioning

Matter设备入网

Basic Commissioning

基础入网流程

Filtering Devices

筛选设备

Combining Device Criteria

组合设备筛选条件

MatterAddDeviceExtensionRequestHandler

MatterAddDeviceExtensionRequestHandler

Common Mistakes

常见错误

DON'T: Access homes before the delegate fires

错误做法：在代理触发前访问homes属性

DON'T: Confuse HomeKit setup with Matter commissioning

错误做法：混淆HomeKit设置与Matter入网流程

DON'T: Forget required entitlements

错误做法：遗漏必要权限

DON'T: Create multiple HMHomeManager instances

错误做法：创建多个HMHomeManager实例

DON'T: Write characteristics without checking metadata

错误做法：未检查元数据就写入特征值

Review Checklist

审核检查清单

References

参考资料