Voltra 让 React Native 开发者用 JSX 编写 Android 主屏 Widget（小组件），底层由 Jetpack Compose Glance 原生渲染，无需手写 Kotlin。本文带你完整走一遍：声明 Widget、Glance 渲染映射、主屏选择器预览图配置，以及用一行 API 把小组件置顶（Pin）到主屏的实战流程。

为什么用 Voltra 做 Android 小组件

传统方式开发 Android Home Screen Widget，需要自己写RemoteViews或 Glance 的 Kotlin 代码，与 React Native 主应用割裂。Voltra 的做法是：

• 写一份 JSX：使用VoltraAndroid命名空间下的组件（Box、Column、Row、Text、Image、Scaffold等）；
• 原生渲染：组件被编译成载荷（payload），在设备端由Jetpack Compose Glance直接渲染，性能与系统 Widget 一致；
• 插件自动化：Expo 插件在 prebuild 时自动生成appwidget-providerXML、注册 Widget、处理尺寸与预览图，见 setup.mdx。

核心渲染链路实现在 packages/android/src/renderer/renderer.ts，JSX 经过@use-voltra/core的渲染器转换为 Glance 可消费的节点树。

一键安装：接入只需两个包

在 React Native 应用中安装 Android 平台包：

npm install @use-voltra/android @use-voltra/android-client

• @use-voltra/android：导出VoltraAndroid、AndroidDynamicColors等 JSX 原语；
• @use-voltra/android-client：导出updateAndroidWidget、requestPinAndroidWidget、VoltraWidgetPreview等运行时 API。

然后在app.json中声明 Expo 插件和你的第一个 Widget：

{ "expo": { "plugins": [ ["@use-voltra/android-client", { "widgets": [{ "id": "my_widget", "displayName": "My First Widget", "targetCellWidth": 2, "targetCellHeight": 2 }] }] ] } }

执行npx expo prebuild --platform android后，插件会自动生成原生配置，Widget 随即出现在系统小组件选择器中。示例项目的完整声明（含多语言名称、resizeMode、previewImage等字段）可参考 example/app.json。

Glance 渲染：JSX 到 Compose 原语的映射

Android 侧使用VoltraAndroid组件，它们一一映射到 Glance 原语，详见官方文档 developing-widgets.md：

一个典型的天气小组件只需要十几行 JSX：

import { VoltraAndroid } from '@use-voltra/android' const WeatherWidget = ({ temperature, condition }) => ( <VoltraAndroid.Box style={{ padding: 16, borderRadius: 12, width: '100%', height: '100%' }}> <VoltraAndroid.Column> <VoltraAndroid.Text style={{ fontSize: 24, fontWeight: 'bold' }}>{temperature}°C</VoltraAndroid.Text> <VoltraAndroid.Text style={{ color: '#666' }}>{condition}</VoltraAndroid.Text> </VoltraAndroid.Column> </VoltraAndroid.Box> )

布局约束要注意：与 React Native 不同，Glance 布局更严格——width/height只能使用固定 dp 数值、"100%"或"auto"；对齐用verticalAlignment/horizontalAlignment属性；样式通过style属性映射为 GlanceModifier。

预览图配置：让选择器里第一眼就专业

用户在主屏小组件选择器（Widget Picker）里看到的画面，由三种机制按优先级自动降级：previewLayout（Android 12+）→previewImage（全版本）→ 系统占位布局。完整说明见 widget-sizing-and-previews.md。

方式一：静态预览图previewImage（最简单）

{ "id": "weather", "previewImage": "./assets/widgets/weather-preview.png" }

只配置previewImage时，Voltra 会自动生成一个带正确缩放行为的布局来展示这张图。示例项目就是这样为voltra小组件配置的。

方式二：矢量预览布局previewLayout（Android 12+，推荐）

提供一个 XML 布局文件，按小组件目标尺寸渲染，缩放时始终清晰，官方示例在 todos-preview.xml：

{ "id": "todos", "previewLayout": "./assets/widgets/todos-preview.xml" }

最佳实践：两个都配上，Android 12+ 用布局、旧版本回退到图片。

尺寸速查表：选对格子数

Android 12+ 按网格单元（cell）放置，Voltra 同时输出targetCellWidth/Height与minWidth/minHeight（dp）以兼容 Android 11 及更早版本。常见规格：

还可通过resizeMode+minResizeWidth/Height、maxResizeWidth/Height控制用户可拖拽缩放的边界（maxResize*仅 Android 12+ 生效）。

应用内预览：VoltraWidgetPreview 所见即所得

开发阶段不必每次都把 Widget 拖到真机主屏——VoltraWidgetPreview组件能在你的应用内按标准尺寸渲染小组件，且底层就是真实的原生 Glance 渲染器，布局、样式与主屏完全一致：

import { VoltraWidgetPreview } from '@use-voltra/android-client' <VoltraWidgetPreview family="mediumWide" style={{ backgroundColor: '#f0f0f0', borderRadius: 16 }}> <VoltraAndroid.Column style={{ padding: 16 }}> <VoltraAndroid.Text style={{ fontSize: 20, fontWeight: 'bold' }}>My Awesome Widget</VoltraAndroid.Text> </VoltraAndroid.Column> </VoltraWidgetPreview>

支持的 family：small、mediumSquare、mediumWide、mediumTall、large、extraLarge（见 testing-and-previews.md）。需要自定义尺寸时可用更底层的VoltraView组件。

小组件置顶流程：requestPinAndroidWidget 一步直达主屏

用户不必手动长按桌面找小组件——你的 App 可以主动发起置顶请求，系统弹出确认框，用户点一下即可把 Widget 放到主屏。API 为requestPinAndroidWidget（Android 8.0 / API 26+），实现位于 packages/android-client/src/widgets/api.ts：

import { requestPinAndroidWidget } from '@use-voltra/android-client' const success = await requestPinAndroidWidget('voltra', { previewWidth: 250, // 可选：确认弹窗中预览图的宽/高（dp） previewHeight: 150, })

返回值是Promise<boolean>：true表示置顶请求已发出（注意还需用户在系统弹窗中确认）；false表示设备不支持（低于 Android 8.0）。previewWidth/previewHeight可省略，系统会使用 Widget 的默认尺寸。

完整的可交互演示（选择 Widget、自定义预览尺寸、带/不带预览两种置顶方式）见 AndroidWidgetPinScreen.tsx。

首屏状态与内容更新：完整的上线闭环

初始状态：给 Widget 配置initialStatePath，指定一个预渲染文件（在 prebuild 时运行于 Node.js），用户在应用首次更新前看到的就不是空白，而是有意义的"加载中"界面。注意该文件必须从@use-voltra/android导入 JSX，不能引用 client 包，详见 widget-pre-rendering.md。

内容更新：应用内调用updateAndroidWidget，传入新数据即刷新所有已放置的实例：

import { updateAndroidWidget } from '@use-voltra/android-client' await updateAndroidWidget('weather_widget', <WeatherWidget temperature={22} condition="Sunny" />)

⚠️ 注意：updateAndroidWidget仅用于载荷驱动（payload-driven）Widget；基于entry的 Dynamic Widget 应使用updateAndroidDynamicWidget，两者混用会抛出VOLTRA_WIDGET_KIND_MISMATCH。

总结：Voltra Android Widget 开发清单

按这套流程走下来，从安装到小组件出现在真机主屏，全程不写一行 Kotlin。更多主题（动态颜色、图表、服务器驱动更新、图片预加载）可继续阅读 skills/voltra/references/android-widgets.md 与 website/docs/v2/android 目录下的官方文档。