看板卡片类SDK使用

修改历史

一、概述

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

二、前提条件

1. 确认完成准备工作
2. 确认完成环境搭建
3. 确认完成看板卡片类SDK集成

三、使用

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 接入建议

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

3.3.4 使用说明

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 的调用链，即可快速落地家庭首页与核心卡片能力。