ursa-avalonia-controls

name	ursa-avalonia-controls
description	Ursa.Avalonia control references with usage patterns, styling conventions, and theme resources. Load individual control references from `reference/<control-name>.md` when generating or reviewing code involving specific Ursa.Avalonia controls.
license	MIT

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 / 安装

1. Ursa

Add nuget package:

dotnet add package Irihi.Ursa

2. 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, and Drawer open through an OverlayDialogHost. UrsaWindow includes 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. / 带溢出支持的工具栏。