【免费下载链接】voltraVoltra lets React Native developers build native iOS Live Activities, Dynamic Island layouts, and widgets as React components without writing Swift. It supports hot reload, push updates, and includes a config plugin that wires everything automatically.项目地址https://gitcode.com/gh_mirrors/vol/voltra点击查看免费下载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.tsJSX 经过use-voltra/core的渲染器转换为 Glance 可消费的节点树。一键安装接入只需两个包在 React Native 应用中安装 Android 平台包npm install use-voltra/android use-voltra/android-clientuse-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.mdVoltraAndroid 组件Glance 对应用途Column/Row垂直 / 水平布局排列内容Box堆叠布局层叠元素Text文本显示展示文字Image图片显示展示图像Scaffold顶层容器根节点一个典型的天气小组件只需要十几行 JSXimport { 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里看到的画面由三种机制按优先级自动降级previewLayoutAndroid 12→previewImage全版本→ 系统占位布局。完整说明见 widget-sizing-and-previews.md。方式一静态预览图previewImage最简单{ id: weather, previewImage: ./assets/widgets/weather-preview.png }只配置previewImage时Voltra 会自动生成一个带正确缩放行为的布局来展示这张图。示例项目就是这样为voltra小组件配置的。方式二矢量预览布局previewLayoutAndroid 12推荐提供一个 XML 布局文件按小组件目标尺寸渲染缩放时始终清晰官方示例在 todos-preview.xml{ id: todos, previewLayout: ./assets/widgets/todos-preview.xml }最佳实践两个都配上Android 12 用布局、旧版本回退到图片。尺寸速查表选对格子数Android 12 按网格单元cell放置Voltra 同时输出targetCellWidth/Height与minWidth/minHeightdp以兼容 Android 11 及更早版本。常见规格规格格子数默认 DP典型用途Small2×1130 × 51快速一瞥信息Medium2×2130 × 117主力尺寸Large4×2276 × 117富内容Extra Large4×4276 × 249复杂布局还可通过resizeModeminResizeWidth/Height、maxResizeWidth/Height控制用户可拖拽缩放的边界maxResize*仅 Android 12 生效。应用内预览VoltraWidgetPreview 所见即所得开发阶段不必每次都把 Widget 拖到真机主屏——VoltraWidgetPreview组件能在你的应用内按标准尺寸渲染小组件且底层就是真实的原生 Glance 渲染器布局、样式与主屏完全一致import { VoltraWidgetPreview } from use-voltra/android-client VoltraWidgetPreview familymediumWide 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支持的 familysmall、mediumSquare、mediumWide、mediumTall、large、extraLarge见 testing-and-previews.md。需要自定义尺寸时可用更底层的VoltraView组件。小组件置顶流程requestPinAndroidWidget 一步直达主屏用户不必手动长按桌面找小组件——你的 App 可以主动发起置顶请求系统弹出确认框用户点一下即可把 Widget 放到主屏。API 为requestPinAndroidWidgetAndroid 8.0 / API 26实现位于 packages/android-client/src/widgets/api.tsimport { requestPinAndroidWidget } from use-voltra/android-client const success await requestPinAndroidWidget(voltra, { previewWidth: 250, // 可选确认弹窗中预览图的宽/高dp previewHeight: 150, })返回值是Promisebooleantrue表示置顶请求已发出注意还需用户在系统弹窗中确认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} conditionSunny /)⚠️ 注意updateAndroidWidget仅用于载荷驱动payload-drivenWidget基于entry的 Dynamic Widget 应使用updateAndroidDynamicWidget两者混用会抛出VOLTRA_WIDGET_KIND_MISMATCH。总结Voltra Android Widget 开发清单步骤关键 API / 字段说明1. 安装use-voltra/androiduse-voltra/android-client两个包即可2. 声明app.json→widgets[]插件自动生成原生配置3. 渲染VoltraAndroid.*映射 Jetpack Compose Glance 原语4. 预览previewImage/previewLayout/VoltraWidgetPreview选择器 应用内双保险5. 首屏initialStatePath避免首见空白6. 更新updateAndroidWidget应用内一键刷新7. 置顶requestPinAndroidWidget主动请求钉到主屏按这套流程走下来从安装到小组件出现在真机主屏全程不写一行 Kotlin。更多主题动态颜色、图表、服务器驱动更新、图片预加载可继续阅读 skills/voltra/references/android-widgets.md 与 website/docs/v2/android 目录下的官方文档。赞分享【免费下载链接】voltraVoltra lets React Native developers build native iOS Live Activities, Dynamic Island layouts, and widgets as React components without writing Swift. It supports hot reload, push updates, and includes a config plugin that wires everything automatically.项目地址https://gitcode.com/gh_mirrors/vol/voltra点击查看免费下载相关推荐10分钟掌握OmniParserAI视觉界面操控的完整入门指南10分钟掌握OmniParserAI视觉界面操控的完整入门指南 想要让AI真正理解并操作图形界面吗OmniParser作为革命性的纯视觉GUI自动化工具让人工智能AI Agent计算机视觉GUI 自动化MooTool next-compose 随手记 Markdown 预览与附件切片基于 commonmark AST 的 Compose 渲染与本地附件工程实录MooTool next compose 随手记 Markdown 预览与附件切片基于 commonmark AST 的 Compose 渲染与本地附件工程实开发工具桌面应用MCP 服务Apache Ratis异步通信机制详解提升分布式系统性能的关键Apache Ratis异步通信机制详解提升分布式系统性能的关键 Apache Ratis作为一款高性能分布式事务协调框架其异步通信机制是实现高吞吐量和低延上一篇浏览器里预览 DWG 图纸Open File Viewer 从 LibreDWG WASM 到 WebGL 渲染的完整路径下一篇Shardeum稳定币机制详解算法稳定币设计与实现的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/26 1:49:17 · 阅读 1.2k 用 Voltra 开发 Android Widget：Jetpack Compose Glance 渲染、预览图与小组件置顶流程实战
【免费下载链接】voltraVoltra lets React Native developers build native iOS Live Activities, Dynamic Island layouts, and widgets as React components without writing Swift. It supports hot reload, push updates, and includes a config plugin that wires everything automatically.项目地址https://gitcode.com/gh_mirrors/vol/voltra点击查看免费下载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.tsJSX 经过use-voltra/core的渲染器转换为 Glance 可消费的节点树。一键安装接入只需两个包在 React Native 应用中安装 Android 平台包npm install use-voltra/android use-voltra/android-clientuse-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.mdVoltraAndroid 组件Glance 对应用途Column/Row垂直 / 水平布局排列内容Box堆叠布局层叠元素Text文本显示展示文字Image图片显示展示图像Scaffold顶层容器根节点一个典型的天气小组件只需要十几行 JSXimport { 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里看到的画面由三种机制按优先级自动降级previewLayoutAndroid 12→previewImage全版本→ 系统占位布局。完整说明见 widget-sizing-and-previews.md。方式一静态预览图previewImage最简单{ id: weather, previewImage: ./assets/widgets/weather-preview.png }只配置previewImage时Voltra 会自动生成一个带正确缩放行为的布局来展示这张图。示例项目就是这样为voltra小组件配置的。方式二矢量预览布局previewLayoutAndroid 12推荐提供一个 XML 布局文件按小组件目标尺寸渲染缩放时始终清晰官方示例在 todos-preview.xml{ id: todos, previewLayout: ./assets/widgets/todos-preview.xml }最佳实践两个都配上Android 12 用布局、旧版本回退到图片。尺寸速查表选对格子数Android 12 按网格单元cell放置Voltra 同时输出targetCellWidth/Height与minWidth/minHeightdp以兼容 Android 11 及更早版本。常见规格规格格子数默认 DP典型用途Small2×1130 × 51快速一瞥信息Medium2×2130 × 117主力尺寸Large4×2276 × 117富内容Extra Large4×4276 × 249复杂布局还可通过resizeModeminResizeWidth/Height、maxResizeWidth/Height控制用户可拖拽缩放的边界maxResize*仅 Android 12 生效。应用内预览VoltraWidgetPreview 所见即所得开发阶段不必每次都把 Widget 拖到真机主屏——VoltraWidgetPreview组件能在你的应用内按标准尺寸渲染小组件且底层就是真实的原生 Glance 渲染器布局、样式与主屏完全一致import { VoltraWidgetPreview } from use-voltra/android-client VoltraWidgetPreview familymediumWide 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支持的 familysmall、mediumSquare、mediumWide、mediumTall、large、extraLarge见 testing-and-previews.md。需要自定义尺寸时可用更底层的VoltraView组件。小组件置顶流程requestPinAndroidWidget 一步直达主屏用户不必手动长按桌面找小组件——你的 App 可以主动发起置顶请求系统弹出确认框用户点一下即可把 Widget 放到主屏。API 为requestPinAndroidWidgetAndroid 8.0 / API 26实现位于 packages/android-client/src/widgets/api.tsimport { requestPinAndroidWidget } from use-voltra/android-client const success await requestPinAndroidWidget(voltra, { previewWidth: 250, // 可选确认弹窗中预览图的宽/高dp previewHeight: 150, })返回值是Promisebooleantrue表示置顶请求已发出注意还需用户在系统弹窗中确认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} conditionSunny /)⚠️ 注意updateAndroidWidget仅用于载荷驱动payload-drivenWidget基于entry的 Dynamic Widget 应使用updateAndroidDynamicWidget两者混用会抛出VOLTRA_WIDGET_KIND_MISMATCH。总结Voltra Android Widget 开发清单步骤关键 API / 字段说明1. 安装use-voltra/androiduse-voltra/android-client两个包即可2. 声明app.json→widgets[]插件自动生成原生配置3. 渲染VoltraAndroid.*映射 Jetpack Compose Glance 原语4. 预览previewImage/previewLayout/VoltraWidgetPreview选择器 应用内双保险5. 首屏initialStatePath避免首见空白6. 更新updateAndroidWidget应用内一键刷新7. 置顶requestPinAndroidWidget主动请求钉到主屏按这套流程走下来从安装到小组件出现在真机主屏全程不写一行 Kotlin。更多主题动态颜色、图表、服务器驱动更新、图片预加载可继续阅读 skills/voltra/references/android-widgets.md 与 website/docs/v2/android 目录下的官方文档。赞分享【免费下载链接】voltraVoltra lets React Native developers build native iOS Live Activities, Dynamic Island layouts, and widgets as React components without writing Swift. It supports hot reload, push updates, and includes a config plugin that wires everything automatically.项目地址https://gitcode.com/gh_mirrors/vol/voltra点击查看免费下载相关推荐10分钟掌握OmniParserAI视觉界面操控的完整入门指南10分钟掌握OmniParserAI视觉界面操控的完整入门指南 想要让AI真正理解并操作图形界面吗OmniParser作为革命性的纯视觉GUI自动化工具让人工智能AI Agent计算机视觉GUI 自动化MooTool next-compose 随手记 Markdown 预览与附件切片基于 commonmark AST 的 Compose 渲染与本地附件工程实录MooTool next compose 随手记 Markdown 预览与附件切片基于 commonmark AST 的 Compose 渲染与本地附件工程实开发工具桌面应用MCP 服务Apache Ratis异步通信机制详解提升分布式系统性能的关键Apache Ratis异步通信机制详解提升分布式系统性能的关键 Apache Ratis作为一款高性能分布式事务协调框架其异步通信机制是实现高吞吐量和低延上一篇浏览器里预览 DWG 图纸Open File Viewer 从 LibreDWG WASM 到 WebGL 渲染的完整路径下一篇Shardeum稳定币机制详解算法稳定币设计与实现的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考