hz-metavrx-ui-set

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Using the Meta VR UI Set

使用 Meta VR UI Set

UISet is a Jetpack Compose component library and design system for Android apps on Meta Horizon OS. Its dark and light themes ship Meta VR typography, shapes, density, interaction states, and semantic colors complete and usable with no configuration. Everything public lives under

metavrx.uiset.compose

and its subpackages.

It ships as the Maven artifact

com.meta.metavrx.uiset:uiset-compose-compat

This skill uses progressive disclosure: this page is the map — load the one reference file that matches your task.

UISet 是面向 Meta Horizon OS 上 Android 应用的 Jetpack Compose 组件库和设计系统。其深色和浅色主题内置 Meta VR 字体排版、形状、密度、交互状态和语义颜色，完整可用，无需任何配置。所有公开 API 均位于

metavrx.uiset.compose

及其子包下。

它以 Maven artifact

com.meta.metavrx.uiset:uiset-compose-compat

的形式发布。

此 skill 使用 渐进式披露：本页是一张地图——请加载与你的任务匹配的一个参考文件。

Mental model

心智模型

kotlin

@Composable
fun AppContent(onContinue: () -> Unit) {
  UiSetTheme {                       // dark scheme, VR typography, Standard density
    Surface {
      Column {
        Text("Guardian", style = UiSetTheme.typography.headline)
        LabelButton(label = "Continue", onClick = onContinue)
      }
    }
  }
}

Below the theme it is ordinary Compose —

Row

Column

Box

from foundation, your own state, normal recomposition. The deltas from a Material 3 app are small but they are replacements, not additions:

Material 3	UISet
`androidx.compose.material3.MaterialTheme`	`metavrx.uiset.compose.theme.UiSetTheme`
`androidx.compose.material3.Text` / `.Icon`	`metavrx.uiset.compose.Text` / `.Icon`
`Button(onClick) { Text(…) }`	`LabelButton(label, onClick)`
`androidx.compose.material.icons.Icons.Filled.Add`	`metavrx.uiset.compose.theme.icons.Icons.Regular.Add`
`MaterialTheme.colorScheme.primary`	`UiSetTheme.colorScheme.accent`
`androidx.compose.material3.LocalContentColor`	`metavrx.uiset.compose.LocalContentColor`

UISet does not extend Material. The names collide, the types do not — import from

metavrx.uiset.compose.*

and do not mix the two in one screen.

kotlin

@Composable
fun AppContent(onContinue: () -> Unit) {
  UiSetTheme {                       // dark scheme, VR typography, Standard density
    Surface {
      Column {
        Text("Guardian", style = UiSetTheme.typography.headline)
        LabelButton(label = "Continue", onClick = onContinue)
      }
    }
  }
}

在主题之下，它就是普通的 Compose——使用 foundation 提供的

Row

Column

Box

、你自己的状态以及常规重组。它与 Material 3 应用之间的差异很小，但这些差异是替换项，而不是新增项：

Material 3	UISet
`androidx.compose.material3.MaterialTheme`	`metavrx.uiset.compose.theme.UiSetTheme`
`androidx.compose.material3.Text` / `.Icon`	`metavrx.uiset.compose.Text` / `.Icon`
`Button(onClick) { Text(…) }`	`LabelButton(label, onClick)`
`androidx.compose.material.icons.Icons.Filled.Add`	`metavrx.uiset.compose.theme.icons.Icons.Regular.Add`
`MaterialTheme.colorScheme.primary`	`UiSetTheme.colorScheme.accent`
`androidx.compose.material3.LocalContentColor`	`metavrx.uiset.compose.LocalContentColor`

UISet 并未扩展 Material。名称会冲突，但类型并不相同——请从

metavrx.uiset.compose.*

导入，并且不要在同一个屏幕中混用两者。

Rules that bite

容易踩坑的规则

Import from UISet, not Material.
```
Text
```
,
```
Icon
```
,
```
Surface
```
,
```
Checkbox
```
,
```
RadioButton
```
,
```
Switch
```
,
```
Slider
```
,
```
Icons
```
,
```
LocalContentColor
```
all exist in both. Mixed imports compile and then render unthemed.
Icons are
@Composable
properties.
```
Icons.Regular.Add
```
resolves a vector resource, so reading it is a composable call — it cannot be evaluated in a
```
val
```
, an enum argument, or a
```
remember { }
```
block. Component
```
icon
```
/
```
leadingIcon
```
parameters take
```
@Composable () -> Unit
```
for exactly that reason.

Item lists must be
PersistentList
.

Dropdown

IconDropdown

, and

ChoiceListDialog

take

PersistentList<…>

from kotlinx-collections-immutable; build with

persistentListOf(…)

inside

remember

Dialogs are modal and caller-controlled. Emit them under
```
if (showDialog) { … }
```
and always pass
```
onDismissRequest
```
.
Every interactive target is at least 48dp in both dimensions, whatever the density preset or a custom
```
Dimensions.minimumInteractiveSize
```
says. Visible artwork can be smaller than its target; lay out with the target in mind.
Icon-only controls require a
contentDescription
— it is a required parameter on
```
IconButton
```
, not an optional one.
Components read the theme through composition locals. Anything outside a
```
UiSetTheme
```
gets the built-in defaults and your customization never reaches it.

请从 UISet 而非 Material 导入。
```
Text
```
、
```
Icon
```
、
```
Surface
```
、
```
Checkbox
```
、
```
RadioButton
```
、
```
Switch
```
、
```
Slider
```
、
```
Icons
```
和
```
LocalContentColor
```
在两者中都存在。混合导入虽然能够编译，但渲染时不会应用主题。
图标是
@Composable
属性。
```
Icons.Regular.Add
```
会解析为矢量资源，因此读取它本身就是一次 composable 调用——不能在
```
val
```
、枚举参数或
```
remember { }
```
块中求值。组件的
```
icon
```
/
```
leadingIcon
```
参数正是出于这一原因采用
```
@Composable () -> Unit
```
。
条目列表必须是
PersistentList
。
```
Dropdown
```
、
```
IconDropdown
```
和
```
ChoiceListDialog
```
接收来自 kotlinx-collections-immutable 的
```
PersistentList<…>
```
；应在
```
remember
```
中使用
```
persistentListOf(…)
```
构建。
对话框是模态且由调用方控制的。 将它们放在
```
if (showDialog) { … }
```
下渲染，并且始终传入
```
onDismissRequest
```
。
无论密度预设或自定义
Dimensions.minimumInteractiveSize
的值如何，每个交互目标的两个维度都至少为 48dp。可见图形可以小于其目标区域；布局时应以目标尺寸为准。
仅含图标的控件必须提供
contentDescription
。它是
```
IconButton
```
的必填参数，而不是可选参数。
组件通过 composition locals 读取主题。 位于
```
UiSetTheme
```
之外的任何内容都会使用内置默认值，你的自定义设置也无法生效。

Read what you need

按需阅读

references/components.md — which component to reach for, what the
```
ButtonStyle
```
emphasis levels mean, and the behaviour that is not visible in a signature. Start here for "which component, and what will it do that I don't expect".
references/theming.md —
```
UiSetTheme
```
, the semantic
```
ColorScheme
```
roles, typography, shapes, density, and interaction indications, plus the customization ladder from a one-value copy to a full replacement. Read when colors or metrics need to change.
references/icons.md —
```
Icons.Regular
```
, the composable-getter constraint, the icon-slot pattern, and how to find an icon.
references/integration.md — adding UISet to an Android app with Gradle and the Horizon OS manifest shape. Read when wiring the dependency, not the API.
references/migration.md — moving off the Spatial SDK UI Set (
```
com.meta.spatial:meta-spatial-sdk-uiset
```
): the coordinate and package changes, the
```
Spatial*
```
rename table, and the behavioral differences. Read when the existing code says
```
SpatialTheme
```
.

For exact signatures and KDoc, hover the symbol in your IDE — every public type is documented. Outside the IDE,

metavr docs api-search "<Component>"

reaches the same reference.

references/components.md——该使用哪个组件、
```
ButtonStyle
```
的强调级别意味着什么，以及签名中看不出来的行为。如果你想知道“应该选择哪个组件，以及它会有哪些预期之外的行为”，请从这里开始。
references/theming.md——
```
UiSetTheme
```
、语义
```
ColorScheme
```
角色、字体排版、形状、密度和交互指示，以及从复制单个值到完全替换的定制路径。需要更改颜色或度量值时阅读。
references/icons.md——
```
Icons.Regular
```
、composable getter 约束、图标插槽模式，以及如何查找图标。
references/integration.md——使用 Gradle 将 UISet 添加到 Android 应用，以及 Horizon OS manifest 结构。在接入依赖项时阅读，无需关注 API。
references/migration.md——从 Spatial SDK UI Set（
```
com.meta.spatial:meta-spatial-sdk-uiset
```
）迁出：坐标和包变更、
```
Spatial*
```
重命名对照表以及行为差异。当现有代码中出现
```
SpatialTheme
```
时阅读。

如需查看精确签名和 KDoc，可在 IDE 中将鼠标悬停在符号上——每个公开类型都有文档。在 IDE 之外，命令

metavr docs api-search "<Component>"

可访问同一份参考资料。