irihitech Semi.Avalonia Controls / Semi.Avalonia 控件
Use this skill when working with Semi.Avalonia controls in XAML or C#. Each
control has a dedicated reference page under reference/ with property tables,
Semi-specific styling, DynamicResource keys, and bilingual usage guidance.
在 XAML 或 C# 中使用 Semi.Avalonia 控件时加载此 Skill。每个控件在 reference/
下都有专属参考页面，包含属性表格、Semi 专属样式、DynamicResource 键和双语使用指南。
How to Use / 如何使用
When the user asks about a specific control (e.g., "use a Button", "style a TextBox", "add a DataGrid"), load the corresponding reference:
当用户询问某个特定控件时（如"使用 Button"、"给 TextBox 添加样式"），加载对应的参考文件：
reference/<control-name>.md
When the user asks about Semi.Avalonia-specific themes or control-specific
DynamicResource keys (e.g., "what themes does Button support", "how to
use a CardCheckBox", "what resources does Slider define"), load the
corresponding control reference — the Styling & Templating and
DynamicResource Keys sections document every special ControlTheme and
resource key defined by Semi.Avalonia.
当用户询问 Semi.Avalonia 特殊主题或控件专属 DynamicResource 键（如"Button 支持哪些主题"、"如何使用 CardCheckBox"、"Slider 定义了哪些资源"）时，加载对应的控件参考文件 —— Styling & Templating 和 DynamicResource Keys 部分记录了 Semi.Avalonia 定义的每个特殊 ControlTheme 和资源键。
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 / 样式与模板 — Semi.Avalonia themes, pseudo-classes, template parts, and special ControlThemes. / Semi.Avalonia 主题、伪类、模板部件和特殊 ControlTheme。
- DynamicResource Keys / 动态资源键 — every theme resource key used by the control. / 该控件使用的每个主题资源键。
- FAQ / 常见问题 — common pitfalls and cross-control comparisons. / 常见陷阱和跨控件对比。
How to Get Started / 如何开始
Install via NuGet:
dotnet add package Semi.Avalonia
Include Semi Design Styles in application:
<Application xmlns:semi="https://irihi.tech/semi">
<Application.Styles>
<semi:SemiTheme Locale="zh-CN" />
</Application.Styles>
</Application>
That's all.
Optional Packages / 可选包
dotnet add package Semi.Avalonia.ColorPicker
dotnet add package Semi.Avalonia.DataGrid
dotnet add package Semi.Avalonia.TreeDataGrid
dotnet add package Semi.Avalonia.Dock
dotnet add package Semi.Avalonia.Tabalonia
dotnet add package Semi.Avalonia.AvaloniaEdit
<Application.Styles>
<semi:ColorPickerSemiTheme />
<semi:DataGridSemiTheme />
<semi:TreeDataGridSemiTheme />
<semi:DockSemiTheme />
<semi:TabaloniaSemiTheme />
<semi:AvaloniaEditSemiTheme />
</Application.Styles>
ℹ Dock, Tabalonia and AvaloniaEdit are delivered via nuget for free, but not open source.
Controls Index / 控件索引
Basic Input / 基础输入
| Control | File | Description |
|---|---|---|
| Button | button | Clickable action trigger with 4 themes × 6 colors × 2 sizes. / 可点击的操作触发器。 |
| TextBox | textbox | Single/multi-line text input with validation. / 单行/多行文本输入。 |
| CheckBox | checkbox | Toggle for boolean options, supports indeterminate. / 布尔选项切换。 |
| RadioButton | radiobutton | Mutually exclusive single selection. / 互斥单选。 |
| ToggleSwitch | toggleswitch | On/off switch with immediate effect. / 即时生效的开关。 |
| Slider | slider | Range value selection with track and thumb. / 范围值选择。 |
| ComboBox | combobox | Dropdown selection with optional editing. / 下拉选择框。 |
| AutoCompleteBox | autocompletebox | Text input with suggestion dropdown. / 带建议下拉的文本输入。 |
| NumericUpDown | numeric-up-down | Numeric value spinner. / 数值微调控件。 |
Button Variants / 按钮变体
| Control | File | Description |
|---|---|---|
| RepeatButton | repeatbutton | Button that fires repeatedly while pressed. / 按住时重复触发的按钮。 |
| ToggleButton | togglebutton | Button with checked/unchecked state. / 带选中状态的按钮。 |
| DropDownButton | dropdownbutton | Button with an attached flyout. / 带浮出层的按钮。 |
| SplitButton | splitbutton | Button with primary action + dropdown part. / 主操作+下拉部分的按钮。 |
| HyperlinkButton | hyperlinkbutton | Link-styled button with URI navigation. / 链接样式的按钮。 |
| ButtonSpinner | buttonspinner | Button pair for increment/decrement. / 增减按钮对。 |
Display & Text / 显示和文本
| Control | File | Description |
|---|---|---|
| TextBlock | textblock | Read-only text with inline formatting. / 只读文本，支持内联格式。 |
| Label | label | Text label with target/access-key support. / 带目标控件关联的文本标签。 |
| SelectableTextBlock | selectable-text-block | Selectable, copyable read-only text. / 可选择可复制的只读文本。 |
| PathIcon | path-icon | Vector icon from path data. / 路径数据的矢量图标。 |
| ProgressBar | progress-bar | Linear or ring progress indicator. / 线性或环形进度指示器。 |
Lists & Selection / 列表和选择
| Control | File | Description |
|---|---|---|
| ListBox | listbox | Selectable item list with virtualization. / 可选择项列表。 |
| ItemsControl | itemscontrol | Base repeating items control. / 基础重复项控件。 |
| TreeView | treeview | Hierarchical tree with expandable nodes. / 层级树控件。 |
| TableView | table-view | Column-based data table. / 基于列的数据表格。 |
| TabControl | tabcontrol | Tabbed content switching. / 选项卡内容切换。 |
| TabStrip | tabstrip | Tab header row (pair with Carousel). / 选项卡标题行。 |
| TabItem | tabitem | Single tab within TabControl. / TabControl 中的单独选项卡。 |
Containers & Layout / 容器和布局
| Control | File | Description |
|---|---|---|
| Border | border | Single-child decorator with border/radius/shadow. / 单子元素装饰器。 |
| Expander | expander | Collapsible content with header. / 可折叠内容区域。 |
| GroupBox | groupbox | Titled border around grouped controls. / 带标题边框的分组容器。 |
| ScrollViewer | scrollviewer | Scrollable viewport for overflowing content. / 可滚动视口。 |
| SplitView | splitview | Master-detail with collapsible pane. / 主从布局，可折叠面板。 |
| GridSplitter | gridsplitter | Draggable splitter for Grid rows/columns. / Grid 行列拖动分割器。 |
| HeaderedContentControl | headeredcontentcontrol | Base class for headered controls. / 带标题控件的基类。 |
Date & Time / 日期和时间
| Control | File | Description |
|---|---|---|
| Calendar | calendar | Month-view date grid with selection. / 月份视图日期网格。 |
| CalendarDatePicker | calendar-date-picker | Date picker with calendar dropdown. / 带日历下拉的日期选择。 |
| DatePicker | date-picker | Date selection with year/month/day spinners. / 年/月/日选择器。 |
| TimePicker | time-picker | Time selection with hour/minute/second. / 时间选择器。 |
Navigation & Pages / 导航和页面
| Control | File | Description |
|---|---|---|
| Carousel | carousel | Page switcher with transition animations. / 带过渡动画的页面切换器。 |
| CarouselPage | carouselpage | Carousel page with indicator support. / 带指示器的 Carousel 页面。 |
| ContentPage | contentpage | Simple content page for navigation. / 简单导航内容页。 |
| DrawerPage | drawerpage | Page with slide-out drawer panel. / 带滑出抽屉面板的页面。 |
| NavigationPage | navigationpage | Stack-based page navigation. / 基于栈的页面导航。 |
| TabbedPage | tabbedpage | Bottom-tabbed page container. / 底部选项卡页面容器。 |
Menus & Flyouts / 菜单和浮出层
| Control | File | Description |
|---|---|---|
| ContextMenu | contextmenu | Right-click context menu. / 右键上下文菜单。 |
| Menu | menu | Horizontal/vertical menu bar. / 水平/垂直菜单栏。 |
| MenuFlyoutPresenter | menuflyoutpresenter | Flyout presenter for menu flyouts. / 菜单浮出层的呈现器。 |
| FlyoutPresenter | flyoutpresenter | Base flyout content host. / 浮出层内容宿主。 |
| Popup | popup | Floating popup content. / 浮动弹出内容。 |
| Tooltip | tooltip | Hover tooltip popup. / 悬停提示弹出框。 |
Feedback & Progress / 反馈和进度
| Control | File | Description |
|---|---|---|
| ProgressBar | progress-bar | Linear/ring progress indicator. / 线性/环形进度。 |
| RefreshContainer | refresh-container | Pull-to-refresh container. / 下拉刷新容器。 |
| PipsPager | pips-pager | Page indicator dots. / 页面指示器点。 |
| NotificationCard | notificationcard | In-app notification banner. / 应用内通知横幅。 |
| DataValidationErrors | data-validation-errors | Validation error display. / 验证错误显示。 |
Window & Infrastructure / 窗口和基础设施
| Control | File | Description |
|---|---|---|
| Window | window | Top-level application window. / 顶级应用窗口。 |
| EmbeddableControlRoot | embeddable-control-root | Root for embedded Avalonia views. / 嵌入式 Avalonia 视图的根。 |
| ManagedFileChooser | managedfilechooser | In-app file picker dialog. / 应用内文件选择对话框。 |
| ThemeVariantScope | themevariantscope | Local theme variant override. / 局部主题变体覆盖。 |
| WindowNotificationManager | windownotificationmanager | Window-level notification manager. / 窗口级通知管理器。 |
| CommandBar | commandbar | App bar with primary/secondary commands. / 主要/次要命令栏。 |
| TransitioningContentControl | transitioningcontentcontrol | Content control with transition animations. / 带过渡动画的内容控件。 |
| AdornerLayer | adorner-layer | Overlay layer for visual adorners. / 视觉装饰器覆盖层。 |