HowTo

Cahier 简介:一款全新的 Android GitHub 示例应用,助力大屏设备上的办公和创作

阅读用时:11 分钟
查看 Chris Assigbe 的个人资料
Chris Assigbe 开发者关系工程师

Ink API 现已推出测试版,可供您集成到应用中。这一里程碑的实现离不开开发者提供的宝贵反馈,这些反馈帮助我们不断提升了 API 的性能、稳定性和视觉质量。

Google 应用(例如 Google 文档、Pixel Studio、Google 相册、Chrome PDF、YouTube 特效工坊)以及 Android 上的独特功能(例如圈定即搜)都使用最新的 API。

为庆祝这一里程碑,我们很高兴地宣布推出 Cahier,这是一款全面的笔记应用示例,针对各种尺寸的 Android 设备(尤其是平板电脑和折叠屏手机)进行了优化。

什么是 Cahier?

Cahier(法语中的“笔记本”)是一款示例应用,旨在演示如何构建一款应用,让用户能够通过结合文本、绘图和图片来记录和整理自己的想法。

该示例可作为在大屏设备上提高用户效率和创造力的首选参考。它展示了打造此类体验的最佳实践,可帮助开发者更快地了解和采用相关的强大 API 和技术。本文将带您了解 Cahier 的核心功能、关键 API 以及架构决策,这些决策使该示例成为您自己应用的绝佳参考。

示例中演示的主要功能包括:

  • 多功能记事创建:展示如何实现灵活的内容创建系统,该系统支持在单个记事中添加多种格式的内容,包括文本、自由绘图和图片附件。
  • 创意墨迹书写工具:使用 Ink API 实现高性能、低延迟的绘图体验。该示例提供了一个实际示例,展示了如何集成各种画笔、颜色选择器、撤消/重做功能和橡皮擦工具。
  • 通过拖放实现流畅的内容集成:演示如何使用拖放功能处理传入和传出内容。这包括接受从其他应用拖放的图片,以及让用户能够将内容拖出您的应用,实现无缝分享。
  • 整理笔记:将笔记标记为收藏,以便快速访问。过滤视图,让一切井井有条。
  • 离线优先架构:采用 Room 构建离线优先架构,确保所有数据都保存在本地,并且应用在没有网络连接的情况下仍能正常运行。
  • 强大的多窗口模式和多实例支持:展示如何支持多实例,让您的应用可以在多个窗口中启动,以便用户可以并排处理不同的记事,从而提高在大屏设备上的工作效率和创造力。
  • 适用于所有屏幕的自适应界面:界面使用 ListDetailPaneScaffold 和 NavigationSuiteScaffold 无缝适应不同的屏幕尺寸和屏幕方向,在手机、平板电脑和可折叠设备上提供经过优化的用户体验。
  • 深度系统集成:提供有关如何通过响应系统级记事 intent,使您的应用成为 Android 14 及更高版本上的默认记事应用的指南,从而实现从各种系统入口点快速捕获内容。

专为大屏设备打造,助力高效工作和创意挥洒

在初始发布阶段,我们将重点宣传几项核心功能,这些功能使 Cahier 成为提高工作效率和激发创造力的重要学习资源。

自适应基础

Cahier 从一开始就设计为自适应应用。该示例利用 material3-adaptive 库(特别是 ListDetailPaneScaffold 和 NavigationSuiteScaffold)使应用布局无缝适应各种屏幕尺寸和屏幕方向。这是现代 Android 应用的关键元素,Cahier 提供了一个清晰的示例,展示了如何有效实现这一功能。

使用 Material 3 自适应库构建的 Cahier 自适应界面。gif

使用 Material 3 自适应库构建的 Cahier 自适应界面

展示关键 API 和集成

该示例重点展示了您可以在自己的应用中利用的强大效率提升 API,包括:

深入了解关键 API

我们来深入了解一下 Cahier 集成的两个基石 API,它们共同打造了一流的笔记体验。

使用 Ink API 打造自然的墨迹书写体验

触控笔输入可将大屏设备转变为数字笔记本和素描本。为了帮助您打造流畅自然的墨迹书写体验,我们在此示例中重点使用了 Ink API。Ink API 可让您轻松创建、渲染和操控精美的墨迹笔画,并提供一流的低延迟体验。

Ink API 采用模块化架构,因此您可以根据应用的特定堆栈和需求进行定制。API 模块包括:

  • 创作模块(Compose - 视图):处理实时墨迹输入,以设备可提供的最低延迟创建流畅的笔画。
    • 在 DrawingSurface 中,Cahier 使用新引入的 InProgressStrokes 可组合项来处理实时触控笔或触控输入。此模块负责捕获指针事件,并以尽可能低的延迟渲染湿墨水笔画。
  • 笔画模块:表示墨迹输入及其视觉表示。用户完成线条绘制后,onStrokesFinished 回调会向应用提供一个最终/干笔画对象。这个不可变对象代表已完成的墨迹笔画,随后在 DrawingCanvasViewModel 中进行管理。
  • 渲染模块:高效显示墨迹笔画,并支持与 Jetpack Compose 或 Android 视图结合使用。
  • 笔刷模块(Compose - 视图):提供了一种声明式方法来定义笔画的视觉样式。最近的更新(自 alpha03 版本以来)包括一个新的虚线画笔,对于套索选择等功能特别有用。DrawingCanvasViewModel 会保留 currentBrush 的状态。DrawingCanvas 中的工具箱允许用户选择不同的画笔系列(例如 StockBrushes.pressurePen() 或 StockBrushes.highlighter())并更改颜色。ViewModel 会更新 Brush 对象,然后 InProgressStrokes 可组合项会使用该对象来绘制新笔画。
  • 几何图形模块(Compose - 视图):支持对笔画进行操作和分析,以实现擦除和选择等功能。
    • 工具箱中的橡皮擦工具和 DrawingCanvasViewModel 中的功能都依赖于几何图形模块。当橡皮擦处于活动状态时,它会在用户手势的路径周围创建一个 MutableParallelogram。然后,橡皮擦会检查该形状与现有笔画的边界框之间是否存在交集,以确定要擦除哪些笔画,从而使橡皮擦感觉直观且精确。
  • Storage 模块:为墨迹数据提供高效的序列化和反序列化功能,从而显著节省磁盘和网络空间。为了保存绘图,Cahier 会将 Stroke 对象保留在其 Room 数据库中。在 Converters 中,该示例使用存储模块的 encode 函数将 StrokeInputBatch(原始点数据)序列化为 ByteArray。字节数组以及画笔属性会保存为 JSON 字符串。decode 函数用于在加载笔记时重构笔画。
orion.png

除了这些核心模块之外,最近的更新还扩展了 Ink API 的功能:

  • 用于自定义 BrushFamily 对象的新实验性 API 使开发者能够创建富有创意且独特的画笔类型,从而为铅笔和激光笔画笔等工具提供更多可能性。

Cahier 善用自定义画笔(包括下方展示的独特音乐画笔),展现了高级创作的可能性。

使用 Ink API 的自定义画笔创建的彩虹激光.gif

使用 Ink API 的自定义画笔创建的彩虹激光

notes.png

使用 Ink API 的自定义画笔创建的音乐画笔

  • 原生 Jetpack Compose 互操作性模块可简化直接在 Compose 界面中集成墨迹书写功能的过程,从而提供更符合惯例且更高效的开发体验。

Ink API 具有多项优势,使其成为效率和创意应用的理想选择,优于自定义实现:

  • 易用性:Ink API 抽象化了图形和几何图形的复杂性,让您能够专注于 Cahier 的核心功能。
  • 性能:内置低延迟支持和经过优化的渲染,可确保流畅、响应迅速的墨迹书写体验。
  • 灵活性:模块化设计让您可以自由选择所需组件,从而将 Ink API 无缝集成到 Cahier 的架构中。

Ink API 已在许多 Google 应用中采用,包括 Google 文档中的标记功能和“圈定即搜”功能,以及 Orion Notes 和 PDF Scanner 等合作伙伴应用。

“Ink API 是我们实现圈定即搜 (CtS) 功能的首选。利用其丰富的文档,我们轻松集成了 Ink API,仅用一周时间就完成了首个工作原型。Ink 的自定义笔刷纹理和动画支持使我们能够快速迭代笔画设计。”- Jordan Komoda,Google 软件工程师

通过记事角色成为默认记事应用

记事是一项核心功能,可提高用户在大屏设备上的效率。借助记事角色功能,用户可以在锁定的屏幕上或在其他应用运行时访问您的兼容应用。此功能可识别并设置系统范围内的默认记事应用,并授予其启动以捕获内容的权限。

Cahier 中的实现

实现 notes 角色涉及几个关键步骤,这些步骤均在示例中进行了演示:

  1. 清单声明:首先,应用必须声明其处理记事 intent 的能力。在 AndroidManifest.xml 中,Cahier 包含一个针对 android.intent.action.CREATE_NOTE 操作的 <intent-filter>。这会向系统表明,该应用可能是“记事”角色的候选应用。
  2. 检查角色状态:SettingsViewModel 使用 Android 的 RoleManager 来确定当前状态。SettingsViewModel 会检查设备上是否支持记事角色 (isRoleAvailable),以及 Cahier 当前是否担任该角色 (isRoleHeld)。此状态会使用 Kotlin flow 向界面公开。
  3. 请求角色:在 Settings.kt 文件中,如果角色可用但未持有,系统会向用户显示一个 Button。点击该按钮后,系统会调用 ViewModel 中的 requestNotesRole 函数。该函数会创建一个 intent,用于打开默认应用设置界面,用户可以在其中选择 Cahier。该过程使用 rememberLauncherForActivityResult API 进行管理,该 API 负责启动 intent 并接收结果。
  4. 更新界面:用户从设置界面返回后,ActivityResultLauncher 回调会触发 ViewModel 中的函数来更新角色状态,从而确保界面准确反映应用现在是否为默认应用。

如需了解如何在应用中集成记事角色,请参阅创建记事应用指南。

helloworld.png

Cahier 在联想平板电脑上作为默认记事应用在浮动窗口中启动

重大进展:联想启用“记事”角色

我们很高兴地宣布,大屏 Android 设备的办公体验迈出了重要一步:联想已在搭载 Android 15 及更高版本的平板电脑上支持记事角色!此次更新后,您可以更新记事应用,让使用兼容联想设备的用户能够将其设为默认应用,从而在锁屏状态下顺畅访问,并解锁系统级内容捕获功能。

领先 OEM 的这一承诺表明,在 Android 上提供真正集成且高效的用户体验时,笔记角色变得越来越重要。

多实例、多窗口模式和窗口化模式

在大屏幕上提高工作效率的关键在于高效管理信息和工作流。因此,Cahier 在设计上充分利用了 Android 的高级窗口功能,提供了一个可根据用户需求灵活调整的工作空间。该应用支持:

  • 多窗口模式:在分屏或自由窗口模式下与其他应用一起运行的基本功能。这对于在 Cahier 中记笔记时参考网页等任务至关重要。
  • 多实例:这是真正实现多任务处理的环节。Cahier 允许用户同时打开应用的多个独立窗口。想象一下,您可以并排比较两个不同的记事,或者在一个窗口中参考文本记事,同时在另一个窗口中进行绘图。Cahier 演示了如何管理这些单独的实例,每个实例都有自己的状态,从而将您的应用转变为功能强大的多面工具。
  • 窗口化模式:连接到外接显示屏后,Android 桌面模式会将平板电脑或可折叠设备转变为工作站。由于 Cahier 采用自适应界面构建,并支持多实例,因此该应用在此环境中表现出色。用户可以像在传统桌面设备上一样,打开、调整和定位多个 Cahier 窗口,从而实现以前在移动设备上无法实现的复杂工作流。
cahier-desktop-windowing.webp

在 Pixel Tablet 上以窗口化模式运行的 Cahier

以下是我们在 Cahier 中实现这些功能的方式:

如需启用多实例,我们首先需要向系统表明应用支持多次启动,方法是将 PROPERTY_SUPPORTS_MULTI_INSTANCE_SYSTEM_UI 属性添加到 AndroidManifest 中的 MainActivity 声明中:

<activity

    android:name="com.example.cahier.MainActivity"

    android:exported="true"

    android:label="@string/app_name"

    android:theme="@style/Theme.MyApplication"

    android:showWhenLocked="true"

    android:turnScreenOn="true"

    android:resizeableActivity="true"

    android:launchMode="singleInstancePerTask">


    <property

        android:name="android.window.PROPERTY_SUPPORTS_MULTI_INSTANCE_SYSTEM_UI"

        android:value="true"/>

    ...

</activity>

接下来,我们实现了启动应用新实例的逻辑。在 CahierHomeScreen.kt 中,当用户选择在新窗口中打开笔记时,我们会创建一个带有特定标志的新 intent,这些标志会指示系统如何处理新 activity 的启动。FLAG_ACTIVITY_NEW_TASK、FLAG_ACTIVITY_MULTIPLE_TASK 和 FLAG_ACTIVITY_LAUNCH_ADJACENT 的组合可确保在现有窗口旁边打开一个新的单独窗口,并在其中显示该笔记。

fun openNewWindow(activity: Activity?, note: Note) {

    val intent = Intent(activity, MainActivity::class.java)

    intent.putExtra(AppArgs.NOTE_TYPE_KEY, note.type)

    intent.putExtra(AppArgs.NOTE_ID_KEY, note.id)

    intent.flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_MULTIPLE_TASK or

        Intent.FLAG_ACTIVITY_LAUNCH_ADJACENT


    activity?.startActivity(intent)

}

为了支持多窗口模式,我们需要通过设置清单的 <activity> 或 <application> 元素,向系统表明应用支持调整大小。

<activity

    android:name="com.example.cahier.MainActivity"

    android:resizeableActivity="true"

    ...>

</activity>

界面本身使用 Material 3 自适应库构建,因此能够在多窗口模式场景(例如 Android 的分屏模式)中无缝自适应。

为了提升用户体验,我们添加了对拖放功能的支持。请参阅下文,了解我们在 Cahier 中是如何实现这一点的。

拖放

真正高效或富有创意的应用不会孤立运行,而是会与设备生态系统的其他部分无缝互动。拖放是这种互动方式的基石,尤其是在大屏设备上,用户经常需要跨多个应用窗口进行操作。Cahier 充分利用了这一优势,实现了直观的拖放功能,方便用户添加和分享内容。

  • 轻松导入:用户可以从其他应用(例如网络浏览器、照片库或文件管理器)中拖动图片,然后直接放到记事画布上。为此,Cahier 使用 dragAndDropTarget 修饰符来定义放置区域、检查兼容内容(例如 image/*),并处理传入的 URI。
  • 轻松分享:Cahier 中的内容与其他应用中的内容一样,可以轻松分享。用户可以长按文字记事中的图片,或长按绘图记事和图片合成的整个画布,然后将其拖动到其他应用中。

技术深入探究:从绘图画布拖动

在绘图画布上实现拖动手势会带来独特的挑战。在我们的 DrawingSurface 中,处理实时绘图输入的可组合项(Ink API 的 InProgressStrokes)和检测长按手势以启动拖动的 Box 是同级可组合项。

默认情况下,Jetpack Compose 指针输入系统经过专门设计,只有一个同级可组合项(即声明顺序中与触摸位置重叠的第一个可组合项)会收到事件。在 Cahier 的例子中,我们希望拖放输入处理逻辑有机会运行,并可能在 InProgressStrokes 可组合项使用所有未使用的输入进行绘制并使用该输入之前,使用这些输入。如果我们不按正确的顺序排列,将无法检测到长按手势来开始拖动,或者 InProgressStrokes 将无法接收输入来绘制。

为了解决此问题,我们创建了一个自定义 pointerInputWithSiblingFallthrough 修饰符,并在可组合项代码中将使用该修饰符的 Box 放在 InProgressStrokes 之前。此实用程序是标准 pointerInput 系统的轻量级封装容器,但有一个关键变化:它会替换 sharePointerInputWithSiblings() 函数以返回 true。这会告知 Compose 框架,允许指针事件传递到同级可组合项,即使这些事件已被使用。

internal fun Modifier.pointerInputWithSiblingFallthrough(

    pointerInputEventHandler: PointerInputEventHandler

) = this then PointerInputSiblingFallthroughElement(pointerInputEventHandler)


private class PointerInputSiblingFallthroughModifierNode(

    pointerInputEventHandler: PointerInputEventHandler

) : PointerInputModifierNode, DelegatingNode() {


    var pointerInputEventHandler: PointerInputEventHandler

        get() = delegateNode.pointerInputEventHandler

        set(value) {

            delegateNode.pointerInputEventHandler = value

        }


    val delegateNode = delegate(

        SuspendingPointerInputModifierNode(pointerInputEventHandler)

    )


    override fun onPointerEvent(

        pointerEvent: PointerEvent,

        pass: PointerEventPass,

        bounds: IntSize

    ) {

        delegateNode.onPointerEvent(pointerEvent, pass, bounds)

    }


    override fun onCancelPointerInput() {

        delegateNode.onCancelPointerInput()

    }


    override fun sharePointerInputWithSiblings() = true

}


private data class PointerInputSiblingFallthroughElement(

    val pointerInputEventHandler: PointerInputEventHandler

) : ModifierNodeElement<PointerInputSiblingFallthroughModifierNode>() {


    override fun create() = PointerInputSiblingFallthroughModifierNode(pointerInputEventHandler)


    override fun update(node: PointerInputSiblingFallthroughModifierNode) {

        node.pointerInputEventHandler = pointerInputEventHandler

    }


    override fun InspectorInfo.inspectableProperties() {

        name = "pointerInputWithSiblingFallthrough"

        properties["pointerInputEventHandler"] = pointerInputEventHandler

    }

}

以下是其在 DrawingSurface 中的使用方式:

Box(

    modifier = Modifier

        .fillMaxSize()

        // Our custom modifier enables this gesture to coexist with the drawing input.

        .pointerInputWithSiblingFallthrough {

            detectDragGesturesAfterLongPress(

                onDragStart = { onStartDrag() },

                onDrag = { _, _ -> /* consume drag events */ },

                onDragEnd = { /* No action needed */ }

            )

        }

) 

// The Ink API's composable for live drawing sits here as a sibling.

InProgressStrokes(...)

这样,系统就能同时正确检测到绘图笔画和长按拖动手势。拖动操作启动后,我们会使用 FileProvider 创建一个可共享的 content:// URI,并使用 view.startDragAndDrop() 将该 URI 传递给系统的拖放框架。此解决方案可确保提供强大且直观的用户体验,并展示了如何在分层界面中克服复杂的手势冲突。

采用现代架构

除了特定 API 之外,Cahier 还展示了构建高质量自适应应用的关键架构模式。

表示层:Jetpack Compose 和自适应性

该演示层完全使用 Jetpack Compose 构建。如前所述,Cahier 采用 material3-adaptive 库来实现界面自适应。状态管理遵循严格的单向数据流 (UDF) 模式,其中 ViewModel 实例用作数据容器,用于保存笔记信息和界面状态。

数据层:Repository 和 Room

对于数据层,Cahier 使用 NoteRepository 接口来抽象化所有数据操作。这种设计选择使应用能够轻松地在本地数据源 (Room) 和未来可能使用的远程后端之间切换。编辑记事等操作的数据流非常简单:

  1. Jetpack Compose 界面会触发 ViewModel 中的方法。
  2. ViewModel 会从 NoteRepository 中提取笔记,处理逻辑,并将更新后的笔记传回存储库。
  3. NoteRepository 会将更新保存到 Room 数据库。

全面的输入支持

要成为真正的效率神器,应用必须能够完美处理各种输入方式。Cahier 旨在符合大屏设备输入指南,并支持:

  • 触控笔:与 Ink API 集成、手掌误触、注册记事角色、文本字段中的触控笔输入以及沉浸模式。
  • 键盘:支持最常见的键盘快捷键和组合键(例如 Ctrl+点击、Meta+点击),并明确指示键盘焦点。
  • 鼠标和触控板:支持右键点击和悬停状态。

支持高级键盘、鼠标和触控板互动是进一步改进的重点。

立即开始使用

我们希望 Cahier 能够成为您下一个出色应用的起点。我们将其打造为一个全面的开源资源,展示了如何将自适应界面、Ink 和笔记角色等强大的 API 以及现代自适应架构结合在一起。

准备好开始了吗?

  • 探索代码:前往我们的 GitHub 代码库,探索 Cahier 代码库,了解设计原则的实际应用。
  • 自行构建:以 Cahier 为基础,构建您自己的笔记、文档标记或创意应用。
  • 贡献:我们欢迎您做出贡献!帮助我们让 Cahier 成为 Android 开发者社区更优质的资源。

查看官方开发者指南,立即开始打造新一代效率和创意应用。我们迫不及待地想看看你的作品!

作者:
继续阅读