---
title: "公开 API — zenit Zig UI 文档"
description: "快速判断一个能力应该从 ui 顶层还是子命名空间获取。"
url: https://zenit.z.express/zh/docs/reference/public-api
language: zh-CN
alternate_en: https://zenit.z.express/docs/reference/public-api.md
alternate_es: https://zenit.z.express/es/docs/reference/public-api.md
alternate_ja: https://zenit.z.express/ja/docs/reference/public-api.md
alternate_ko: https://zenit.z.express/ko/docs/reference/public-api.md
alternate_fr: https://zenit.z.express/fr/docs/reference/public-api.md
alternate_de: https://zenit.z.express/de/docs/reference/public-api.md
project: zenit v0.1.0-alpha (Zig 0.15.2, macOS)
source: https://github.com/version-next/zenit
---

# 公开 API 参考

快速判断一个能力应该从 ui 顶层还是子命名空间获取。

`src/ui/ui.zig` 就是完整的公开 API：应用只使用 `ui.*` 与 `ui.<group>.*`，破坏其中任何一个名字都算 API break。

`imports.zig`

```zig
const ui = @import("ui");
const zenit_app = @import("zenit_app");

// Tier 1: straight off ui
const title = try ui.text(cx, "Hello", .{});

// Tier 2: through the group
const theme = &ui.theme.dark;
const Router = ui.fx.Router;
```

## Tier 1 · `ui.X`

每个应用都会用到的顶层名字，按用途分组。前五组覆盖大多数界面文件；最后一组面向自定义绘制与框架宿主。

Runtime  
上下文、节点与生命周期`Cx · Node · Scope · Style · BoxStyle · HandlerRef`

Builders  
节点构造`box · hstack · vstack · text · textFmt · image · imageTint · svg · svgTint · icon · iconTint · spacer · clickable · grid · animateNode`

Styled  
主题安全构造与样式系统`boxStyled · hstackStyled · vstackStyled · textStyled · iconStyled · iconTintStyled · recipe · ConditionalStyle · arb · ThemeTokens · ColorScheme`

Layout  
布局值类型`Sizing · Size · Point · Padding · Margin · Border · Outline · Direction · FlexWrap · AlignItems · JustifyContent · ComputedRect · GridStyle`

Paint  
颜色与绘制效果`Color · BlendMode · CornerRadius · CornerRadii · Shadow · InsetShadow · Gradient · GradientStop · MultiGradient · GradientDirection · GlassParams · GlassSurface`

Text  
文本属性与折行产物`TextProps · TextStyle · TextWrap · TextAlign · TextLayout · LineInfo · textAlignLineOffset · TextInputClient · TextInputSelection`

Media & cursor  
图像、图标与光标`ImageProps · IconProps · SvgAsset · CursorShape · CursorRegion · CursorToken · CustomCursorDesc`

Reactive  
响应式基础（完整面在 ui.reactive）`Signal · Memo · createEffect · createMemo`

Control flow  
条件与列表（也在 ui.control\_flow）`Show · For · Match`

A11y  
无障碍属性`A11yRole · A11yProps · A11yOrientation · A11ySortDirection · A11yRect · A11yValueRange`

Components  
受控 / 非受控 prop`ControlledProp`

Advanced  
自定义绘制、布局回调与分片任务`DisplayItem · DrawContext · BulkQuad · AfterLayoutFn · AfterLayoutResult · max_after_layout_rounds · PointerDownFocus · Task · WorkKey · frame`

## Tier 2 · `ui.<group>.X`

按关注点分组。需要超出基础能力时再使用。

| 命名空间 | 能力 |
| --- | --- |
| `ui.widgets` | 完整组件库：Button、Input、Modal、Tabs、VirtualList、Calendar、Notifier、FormOf… |
| `ui.fx` | 动画（Tween、Spring、Timeline）、物理、Transition / SnapshotTransition、Router |
| `ui.events` | 完整 Event 与 EventResult，键鼠、滚轮、拖放、IME（ImePreeditEvent / ImeCommitEvent）payload |
| `ui.hooks` | useHover、useFocusRing、useHoverHighlight、useAnimatedBackground、onMount / onCleanup |
| `ui.reactive` | 完整响应式系统：Scope、Context、StoreOf、SignalOwner、eqlValue |
| `ui.control_flow` | Show / For / Match 及其选项类型 |
| `ui.focus` | FocusManager、FocusScopeConfig、tab order |
| `ui.actions` | Action、KeyBinding、CommandBinding、ActionDispatcher |
| `ui.theme` | ThemeTokens、ColorTokens 与内置 light / dark / high\_contrast |
| `ui.icons` | 所选 provider 的完整图标目录（get、all） |
| `ui.system_icons` | 与 provider 无关的语义图标角色 |
| `ui.assets` | SVG Asset 类型与 common 兼容图标 |
| `ui.interaction` | RangeHoverRegistry、drag 等交互原语 |
| `ui.select_headless` | Select 的 headless 状态机（step、commitSelection） |
| `ui.gesture` | 手势识别与仲裁（Recognizer、GestureArena） |
| `ui.hit / ui.path` | 命中测试（HitQuery、HitBehavior…）与路径几何（PathCommand、Transform2D…） |
| `ui.platform_services` | 剪贴板与文件对话框，参数为 cx.system\_sdk |
| `ui.text_shaping` | 字体解析与测量钩子（setShapeFontResolver…） |
| `ui.console` | per-Cx 日志：Console、ScopedConsole、Level、Config、Snapshot |
| `ui.devtools` | overlay（窗口内检查）、mountPanel（独立面板）、trace、source\_link |

组件的 props 与结果类型见[组件站](https://zenit.z.express/zh/components)；图标清单见 [Icon Gallery](https://zenit.z.express/zh/docs/guide/icons)。`ui.a11y` 只用于平台运行时接线，应用作者不需要它——组件的无障碍信息写在节点的 `A11yProps` 上。

## zenit\_app

`zenit_app.App` 是单窗口运行时助手，负责平台 / GPU / 字体初始化与事件循环；`zenit_app.MultiWindowApp` 管理多个独立原生窗口（上限 16 个，超出返回 `error.TooManyWindows`）。同一模块还导出 `WindowConfig`、`MultiWindowConfig`、`FontConfig` 与 `ResourcePath`。高级宿主可以使用更低层的接口，但普通应用应从这里开始。

## 边界

> WARNING
> 
> **内部 API 不承诺兼容。** 不要从 `core/`、`reactive/`、`i18n/` 等源码路径直接导入。新增顶层命名空间必须在 `ui.zig` 的白名单测试里登记；需要的新能力应先在公开命名空间设计稳定表面。