看板卡片类SDK使用

修改历史

一、概述

本文介绍如何在完成集成后，参考宿主工程中的 MainActivity、initHome() 以及宿主回调与策略实现，接入看板卡片类SDK提供的页面、跳转、资源扩展与 Aqara Spec 数据通知能力。

二、前提条件

1. 确认完成准备工作
2. 确认完成环境搭建
3. 确认完成看板卡片类SDK集成
4. 详情查看看板卡片清单

三、使用

3.1 跳转到看板卡片页面

宿主入口页先判断当前设备形态，再完成 Home 模块初始化，最后加载家庭首页 HomeMainFragment：

class MainActivity : BaseActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // 1. 设置手机 / 平板形态
        LumiRouterManager.instance.isTablet =
            resources.configuration.orientation == Configuration.ORIENTATION_LANDSCAPE

        // 2. 初始化家庭配置能力
        initHome()

        // 3. 加载家庭首页
        startHome()
    }

    open fun startHome() {
        loadRootFragment(R.id.fl_container, HomeMainFragment())
    }
}

关键参数说明

跳转到其他页面，例如服务广场、卡片列表等，直接复用宿主中 ARouter.build(...).withString(PATH_KEY, ...).navigation() 的写法，并替换为目标页面路径。

3.2 看板跳转回调

3.2.1 回调说明

看板中的卡片点击、页面跳转、离线处理、Web 打开等能力，统一通过 IHomeConfigurationCallback 对外提供，由宿主实现具体业务逻辑。

接入方式如下：

1. 宿主实现一个回调类，例如 HomeCallBack
2. 该类实现 IHomeConfigurationCallback
3. 通过 ARouter 暴露给看板模块使用

IHomeConfigurationCallback 是看板模块对宿主暴露的统一跳转接口。看板首页中的卡片点击、页面跳转、离线处理、Web 打开、主题切换等行为，最终都会通过这个接口回调给宿主实现。

3.2.2 IHomeConfigurationCallback 接口说明

接口定义的核心特点如下：

1. 继承自 IProvider，通过 ARouter 服务发现使用
2. 多数实体参数使用 Any 透传，宿主需要按约定强转为真实类型
3. 看板模块通过统一路由层调用该接口，不直接依赖宿主业务页面

当前常用方法与参数约定如下：

补充说明：

1. 看板模块会根据卡片类型决定调用哪个接口方法
2. 例如设备卡片会走 gotoDeviceHomePage(...)，场景卡片会走 gotoSceneHomePage(...)
3. 宿主实现时，需要正确识别 Any 参数的真实类型，否则无法拿到看板透传的业务数据

3.2.3 接入要求

1. 梳理宿主现有页面，确认设备详情、家庭管理、场景、自动化和 Web 容器等页面路径及参数
2. 在 IHomeConfigurationCallback 的实现类中逐个补齐跳转逻辑，改成调用 ARouter 或宿主自有路由
3. 项目只做看板展示时，先实现设备页、场景页和 Web 页跳转，其他接口保留占位处理

3.3 IALinkCallBack 接口说明

3.3.1 接口职责

看板卡片类SDK通过 IALinkCallBack 与宿主的设备链路层对接，用于承接 Aqara Spec 相关的数据通知与控制能力。宿主需要在该接口中实现以下几类方法：

1. 推送回调方法：接收设备 trait 的实时变更通知
2. 数据读取代理方法：按设备、功能或 trait 读取当前值
3. trait write 方法：用于修改设备 trait 属性值
4. 命令下发方法：用于执行独立于 trait write 的设备命令

3.3.2 重点方法说明

3.3.3 相关实体说明

IALinkCallBack 接入时涉及以下几个核心实体：

补充说明：

1. TraitPushEntity 更偏向“设备上报结果”，适用于被动通知场景
2. Trait 使用 deviceId、path、value 表达目标设备、目标能力和当前值，适用于读、写、展示等通用链路
3. AqaraSpecConfigCmdEntity 更偏向“控制指令描述”，适用于命令下发场景

3.3.4 接入要求

1. 宿主需确保 IALinkCallBack 已完成注册，并由统一链路层正常回调
2. onTraitPush(...) 作为实时更新入口，用于处理设备上报和被动刷新
3. 数据读取代理方法复用宿主现有设备缓存、设备中心或查询接口，减少重复实现
4. trait write 方法统一收口到宿主已有写入链路，便于做权限校验、节流、日志和失败重试
5. 命令下发方法走独立的命令控制链路，实现上与 trait write 分开处理，避免接口语义混淆
6. trait 变更频率较高时，增加去重、节流或按设备维度合并刷新，减少 UI 抖动与重复渲染

3.3.5 使用说明

1. IALinkCallBack 是看板模块接入 Aqara Spec 数据通知与控制能力的核心接口
2. 推送回调、数据读取代理、trait write、命令下发由宿主统一规划，且实现上区分不同链路
3. 其中 trait write 用于属性修改，命令下发用于执行独立设备命令，两者不是同一种控制方式
4. 宿主未正确实现该接口时，会出现卡片不刷新、首屏状态不准确、控制行为异常或状态不同步等问题

3.4 看板功能开关

3.4.1 IPanelPermissionStrategy 说明

看板能力是否展示、是否允许点击、是否允许编辑等，统一通过 IPanelPermissionStrategy 控制。

该接口用于控制家庭配置页面中哪些功能可用或可见，宿主可在初始化时注入自己的策略实现。

LMHomeManager.getInstance().setPanelPermissionStrategy(object : IPanelPermissionStrategy {
    override fun supportVoice() = false
    override fun supportAddDeviceSceneAutomation() = true
    override fun supportCardClick() = false
    override fun supportEditCard() = true
    override fun supportSwitchHome() = true
    override fun supportStatistics() = true
    override fun supportThemePanel() = false
    override fun supportLAN() = true
    override fun supportCardType() = getSupportCardType()
})

3.4.2 常用策略项说明

3.4.3 使用要求

只面向看板项目内容时，优先确认以下几个开关：

1. supportCardClick()：决定首页卡片是否可进入详情或执行跳转
2. supportEditCard()：决定用户能否编辑卡片
3. supportSwitchHome()：决定是否允许跨家庭切换
4. supportCardType()：决定看板允许展示哪些卡片类型

目标是“只展示不跳转”时，将 supportCardClick() 设为 false，并保留编辑、切换家庭等开关。

3.5 资源扩展

3.5.1 本地资源扩展（可选）

覆盖默认皮肤、图片或文案时，参考 Demo 中的 resources、assets 目录放置自定义内容，并通过 ThemeStyle.getInstance().getBaseThemePack() 或 ResourcesWrapper 等扩展点进行注入。

3.5.2 远程资源（可选）

看板卡片类SDK支持通过远程配置下发卡片皮肤、文案等内容。当前版本由内部配置中心维护。对外开通请联系商务支持。

以上示例基于宿主工程中的 Demo 结构。业务接入时按业务范围裁剪，保持 onCreate -> initHome -> startHome 的调用链，完成家庭首页与核心卡片能力接入。