irihitech Ursa.Avalonia Controls / Ursa.Avalonia 控件
Use this skill when working with Ursa.Avalonia controls in XAML or C#. Each
control has a dedicated reference page under reference/ with property tables,
Ursa-specific styling, theme resources, and bilingual usage guidance.
在 XAML 或 C# 中使用 Ursa.Avalonia 控件时加载此 Skill。每个控件在 reference/
下都有专属参考页面，包含属性表格、Ursa 专属样式、主题资源和双语使用指南。
How to Use / 如何使用
When the user asks about a specific control, load the corresponding reference:
当用户询问某个特定控件时，加载对应的参考文件：
reference/<control-name>.md
When the user asks about Ursa.Avalonia-specific themes or control-specific
resources, load the corresponding control reference — the Styling & Templating
section documents every special theme and resource key defined by Ursa.Avalonia.
当用户询问 Ursa.Avalonia 特殊主题或控件专属资源时，加载对应的控件参考文件。
Each reference contains / 每个参考页面包含：
- When to Use / 何时使用 — criteria to decide whether this control is appropriate. / 判断是否应使用该控件的条件。
- Basic Usage / 基本使用 — minimal XAML + C# snippet. / 最简 XAML + C# 示例。
- Common Scenarios / 常用场景 — 2-4 realistic patterns with code. / 2-4 个真实场景及代码。
- Property Reference / 属性参考 — key properties and events in a table. / 表格形式的属性和事件。
- Styling & Templating / 样式与模板 — Ursa.Avalonia themes, pseudo-classes, template parts. / Ursa.Avalonia 主题、伪类、模板部件。
- FAQ / 常见问题 — common pitfalls and cross-control comparisons. / 常见陷阱和跨控件对比。
How to Get Started / 如何开始
Installation / 安装
- Ursa
Add nuget package:
dotnet add package Irihi.Ursa
- Ursa.Themes.Semi
To make Ursa controls show up in your application, you need to reference to a theme package designed for Ursa. Ursa.Themes.Semi is a theme package for Ursa inspired by Semi Design. You can add it to your project by following steps.
Add nuget package:
dotnet add package Semi.Avalonia
dotnet add package Irihi.Ursa.Themes.Semi
Include Styles in application:
<Application...
xmlns:semi="https://irihi.tech/semi"
....>
<Application.Styles>
<semi:SemiTheme Locale="zh-CN" />
<semi:UrsaSemiTheme Locale="zh-CN"/>
</Application.Styles>
You can now use Ursa controls in your Avalonia Application.
<Window
...
xmlns:u="https://irihi.tech/ursa"
...>
<StackPanel Margin="20">
<u:TagInput />
</StackPanel>
</Window>
Controls Index / 控件索引
Display & Feedback / 显示与反馈
| Control | File | Description |
|---|---|---|
| Avatar | avatar | User avatar with initials, image, or custom content. / 用户头像。 |
| Badge | badge | Notification badge with count, dot, overflow support. / 通知徽标。 |
| Banner | banner | Inline notification banner with icon and close. / 内联通知横幅。 |
| DualBadge | dualbadge | Double-layered badge with icon, header, and content. / 双层徽标。 |
| Loading | loading | Loading indicator and loading container. / 加载指示器和加载容器。 |
| Marquee | marquee | Scrolling text/content ticker. / 滚动文字/内容跑马灯。 |
| NumberDisplayer | numberdisplayer | Animated number display with typed variants. / 动画数字显示器。 |
| Notification | notification | Toast-style notification with position control. / Toast 样式通知。 |
| QRCode | qrcode | Vector QR code renderer. / 矢量二维码渲染器。 |
| Rating | rating | Star-based rating control. / 星级评分控件。 |
| Skeleton | skeleton | Loading skeleton placeholder. / 加载骨架占位符。 |
| TagInput | tag-input | Multi-value tag/chip input. / 多值标签/碎片输入。 |
| Timeline | timeline | Vertical timeline with nodes and content. / 垂直时间线。 |
| Toast | toast | Ephemeral toast notification. / 短暂 Toast 通知。 |
Date & Time / 日期与时间
| Control | File | Description |
|---|---|---|
| DatePicker | date-picker | Single date selection with calendar dropdown. / 单日期选择。 |
| DateOnlyPicker | date-only-picker | DateOnly (.NET 6+) single date picker. / DateOnly 单日期选择。 |
| DateOffsetPicker | date-offset-picker | DateTimeOffset date picker with UTC offset. / 带 UTC 偏移的日期选择。 |
| DateRangePicker | date-range-picker | Start/end date range with dual calendars. / 起止日期范围选择。 |
| DateOnlyRangePicker | date-only-range-picker | DateOnly range picker. / DateOnly 范围选择。 |
| DateOffsetRangePicker | date-offset-range-picker | DateTimeOffset range picker. / 带偏移的日期范围选择。 |
| TimePicker | time-picker | Single time selection with panel. / 单时间选择。 |
| TimeOnlyPicker | time-only-picker | TimeOnly (.NET 6+) single time picker. / TimeOnly 单时间选择。 |
| TimeRangePicker | time-range-picker | Start/end time range with dual panels. / 起止时间范围选择。 |
| TimeOnlyRangePicker | time-only-range-picker | TimeOnly range picker. / TimeOnly 范围选择。 |
| DateTimePicker | datetimepicker | Combined date + time single picker. / 日期+时间组合选择。 |
| Clock | clock | Analog or digital clock display. / 模拟或数字时钟显示。 |
| TimeBox | timebox | Editable time box with drag support. / 可编辑时间输入框。 |
Navigation & Menus / 导航与菜单
| Control | File | Description |
|---|---|---|
| Anchor | anchor | Anchor navigation with scroll-to-target. / 锚点导航。 |
| Breadcrumb | breadcrumb | Breadcrumb navigation trail. / 面包屑导航。 |
| NavMenu | navmenu | Side navigation menu with selection. / 侧边导航菜单。 |
| Pagination | pagination | Page navigation with page numbers. / 分页导航。 |
| ScrollTo | scrollto | Scroll-to-direction buttons. / 滚动到方向按钮。 |
Overlays & Dialogs / 浮层与对话框
ℹ
OverlayDialog,MessageBox, andDraweropen through anOverlayDialogHost.UrsaWindowincludes one by default. See OverlayDialogHost for multi-host setups and HostId rules.ℹ
OverlayDialog、MessageBox、Drawer通过OverlayDialogHost打开。UrsaWindow默认包含一个。 多宿主配置和 HostId 规则参见 OverlayDialogHost。
| Control | File | Description |
|---|---|---|
| Dialog | dialog | Modal dialog with standard/custom variants. / 模态对话框。 |
| Drawer | drawer | Slide-out drawer panel. / 滑出抽屉面板。 |
| MessageBox | messagebox | Simple message dialog with buttons. / 简单消息对话框。 |
| PopConfirm | popconfirm | Popover confirmation before action. / 气泡确认框。 |
| OverlayDialogHost | overlay-dialog-host | Canvas host for Dialog/Drawer/OverlayMessageBox overlays. / Dialog/Drawer/OverlayMessageBox 浮层宿主。 |
Input / 输入控件
| Control | File | Description |
|---|---|---|
| AutoCompleteBox | autocompletebox | Single-value auto-complete text input. / 单值自动完成输入。 |
| MultiAutoCompleteBox | multi-auto-complete-box | Multi-value chip auto-complete with async population. / 多选芯片自动完成。 |
| TreeComboBox | tree-combo-box | Hierarchical tree single-select dropdown. / 树形单选下拉。 |
| MultiComboBox | multi-combo-box | Multi-select dropdown with chip display. / 多选芯片下拉。 |
| ControlClassesInput | controlclassesinput | Visual style-class chip editor. / 样式类标签编辑器。 |
| EnumSelector | enumselector | Enum value dropdown selector. / 枚举值下拉选择。 |
| IPv4Box | ipv4box | IPv4 address segmented input. / IPv4 地址分段输入。 |
| KeyGestureInput | keygestureinput | Keyboard gesture capture input. / 键盘手势捕获输入。 |
| NumPad | numpad | On-screen numeric keypad. / 屏幕数字键盘。 |
| NumericUpDown | numericupdown | Numeric spinner with 11 typed variants. / 数值微调控件。 |
| PathPicker | pathpicker | File/folder path picker with browse. / 文件/文件夹路径选择。 |
| PinCode | pincode | Fixed-length PIN/password input. / 固定长度密码输入。 |
| RangeSlider | rangeslider | Dual-thumb range slider. / 双滑块范围选择。 |
| SelectionList | selection-list | Selectable item list. / 可选择项目列表。 |
| ThemeSelector | themeselector | Theme toggle button with auto-detection. / 主题切换按钮。 |
Layout & Containers / 布局与容器
| Control | File | Description |
|---|---|---|
| AspectRatioLayout | aspectratiolayout | Aspect-ratio-constrained layout. / 宽高比约束布局。 |
| ButtonGroup | button-group | Grouped button container. / 按钮组容器。 |
| ColumnWrapPanel | column-wrap-panel | Column-based wrapping panel. / 基于列的换行面板。 |
| DefaultDialogLayout | default-dialog-layout | Default dialog content layout. / 默认对话框内容布局。 |
| Descriptions | descriptions | Key-value description list. / 键值描述列表。 |
| DisableContainer | disablecontainer | Disable overlay container. / 禁用覆盖容器。 |
| Divider | divider | Horizontal/vertical divider line. / 水平/垂直分割线。 |
| ElasticWrapPanel | elastic-wrap-panel | Elastic-fill wrapping panel. / 弹性填充换行面板。 |
| Form | form | Form layout with labels and validation. / 带标签和验证的表单布局。 |
| GroupBox | groupbox | Bordered group container with header. / 带标题边框分组容器。 |
| ImageViewer | imageviewer | Zoomable/pannable image viewer. / 可缩放/平移图片查看器。 |
| ProportionalCanvas | proportional-canvas | Proportional coordinate canvas. / 比例坐标画布。 |
| Resizers | resizers | Window/dialog resize thumbs. / 窗口/对话框调整大小手柄。 |
| ThemeVariantMapper | themevariantmapper | Parent-theme-to-child-theme mapper. / 父→子主题映射器。 |
| VirtualizingUniformGrid | virtualizing-uniform-grid | Virtualized uniform grid panel. / 虚拟化均匀网格面板。 |
| WrapPanelWithTrailingItem | wrap-panel-with-trailing-item | Wrap panel with a trailing overflow item. / 带尾部溢出项的换行面板。 |
Toolbars & Title / 工具栏与标题
| Control | File | Description |
|---|---|---|
| IconButton | icon-button | Icon-only button with 4 theme variants. / 纯图标按钮。 |
| TitleBar | title-bar | Custom window title bar. / 自定义窗口标题栏。 |
| ToolBar | tool-bar | Toolbar with overflow support. / 带溢出支持的工具栏。 |