iPaas.Controls 1.0.7

iPaas.Controls

<img src="src/iPaas.Controls/Assets/icon.png" width="72" alt="" />

一个 Avalonia 设计系统与组件库，语义与 shadcn-svelte 一一对应： 同样的 token 名字、同样的组件命名与变体、同样的浅色/深色两套配色，只是把「网页」换成了「桌面」。

接上这一行，平台自带控件（Button、TextBox、CheckBox…）就已经是 shadcn 的外观：

<Application.Styles>
    <ipaas:Theme />
</Application.Styles>

快速开始

包发在 CyberStone 的 BaGet 源上，先让 NuGet 认识它（放在解决方案旁边，或写进用户级 NuGet.Config 一次到位）：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <clear />
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
        <add key="CyberStone" value="https://baget.cyber-stone.com/v3/index.json" />
    </packageSources>
</configuration>

dotnet add package iPaas.Controls

跟预览版用 dotnet add package iPaas.Controls --prerelease。要求 .NET 10 与 Avalonia 12.1 以上。

不想先写代码可以直接看画廊：每个 vX.Y.Z 的 Release 上都挂着 iPaasControlsDemo.exe（win-x64，自包含单文件，双击即跑，不用装 .NET），旁边是同版本的 .nupkg 与带 SourceLink 的 .snupkg。

接上开头那一行 <ipaas:Theme />（它一次带入三层内容：设计 token、浅色/深色两套语义色、以及所有控件主题， 含 Button、TextBox、CheckBox 这些平台控件），库里的控件补齐平台没有的部分，第一个界面大概长这样：

<ipaas:Card Width="360" HorizontalAlignment="Left">
    <StackPanel Spacing="24">
        <ipaas:CardHeader>
            <ipaas:CardTitle Content="Deployment" />
            <ipaas:CardDescription Content="The last one is still rolling out." />
        </ipaas:CardHeader>
        <ipaas:CardContent>
            <StackPanel Spacing="12">
                <StackPanel Spacing="6">
                    <Label Content="Environment" />
                    <TextBox PlaceholderText="production" />
                </StackPanel>
                <StackPanel Orientation="Horizontal" Spacing="8">
                    <ipaas:Badge Content="Healthy" />
                    <ipaas:Badge Variant="Outline" Content="iPaas" />
                </StackPanel>
            </StackPanel>
        </ipaas:CardContent>
        <ipaas:CardFooter>
            <StackPanel Orientation="Horizontal" Spacing="8">
                <Button Content="Deploy" />
                <Button Classes="outline" Content="Cancel" />
            </StackPanel>
        </ipaas:CardFooter>
    </StackPanel>
</ipaas:Card>

组件画廊（src/iPaas.Controls.Demo）里有同样的内容，而且是活的：目录最前面的 Install、Get started、 Styles、Theme 四页就是这份文档，每个示例都能当场看到它自己的 AXAML 源码。

样式

每个控件都按 shadcn 的写法给变体与尺寸：类名和附加属性两条路等价，前者短、后者编译期可发现。

<Button Classes="secondary" Content="Secondary" />
<Button Classes="destructive" Content="Destructive" />
<Button Classes="outline" Content="Outline" />
<Button Classes="ghost" Content="Ghost" />
<Button Classes="link" Content="Link" />


<Button Classes="sm" Content="小" />       
<Button Classes="lg" Content="大" />       
<Button Classes="icon" Content="+" />      


<Button ipaas:ButtonAssist.Variant="Outline" ipaas:ButtonAssist.Size="Sm" Content="取消" />

谁赢，三条规则覆盖全部：

内缩跟谁走

一个控件要么按密度（跟着控件高度变），要么按某一档（固定）。同一条规则在仓库里踩过好几次 （侧栏分组标题、导航触发器、输入框、表格列头），现在写进了 docs/design-system.md 第 7 节：高度走密度的 控件，内缩与字号也必须走密度；固定高度的行里，纵向内缩只会挤掉文字；而"装裱"类内缩（比如输入框组的 addon）只缩朝外那一侧。

主题

颜色是两个互相独立的旋钮，合起来只有一套语义角色：

ControlDefaults.BaseColor = ThemeBaseColor.Slate;   // 基色：22 种（Neutral…Rose）
ControlDefaults.Mode      = ThemeMode.Dark;         // 浅色 / 深色 / 跟随系统

// 也可以只给一个窗口：不动库级默认
window.RequestedThemeVariant = ThemeVariant.Dark;

• Mode 选哪本字典：浅色与深色是同一批角色的两本字典（Theming/Themes/Light.axaml、Dark.axaml）， 控件只写角色名（BackgroundBrush、PrimaryBrush…），由 variant 决定读哪本。它是 Avalonia 的 variant， 所以同一个窗口里也能局部切（ThemeVariantScope）。
• 基色重指两本字典背后的调色板：Neutral 是 shadcn 发布的原始数值，其余 21 种按「角色 → Tailwind 色阶」派生，浅色与深色一起改，所以两者正交、不会互相覆盖。
• 不受基色影响的角色：destructive、success、warning、info 与遮罩——警告永远是警告的颜色。

派生规则（Theming/ThemePalette.cs，完整表格见 docs/design-system.md 第 4 节）：

两支墨不写死档位：primary foreground 与 muted foreground 在它自己要压的那张面上按亮度挑（亮面翻成 深墨，中亮度的面挑不出 AA 就让面自己走一档），AccessibilityTests 走遍 22 个基色 × 浅深两套盯着； warning 那支琥珀的浅色档也在数据里改深了一档（2.94:1 → 4.92:1）。

另外两个旋钮动的是几何——密度与圆角，和上面两个颜色旋钮各管各的：

ControlDefaults.Size   = ControlSize.Sm;        // 密度：Xs / Sm / Md / Lg / Xl
ControlDefaults.Radius = ControlRadius.Xs;      // 圆角族：None / Xs / Sm / Md / Lg / Full

设计系统

四层，自下而上，每层只依赖下一层：

颜色以 OKLCH 撰写（shadcn 的原始格式），由 build/GenerateThemeTokens.ps1 转成 Avalonia 可读的 Color/SolidColorBrush 并生成 C# 表，所以 XAML 与运行期两条路径不会漂移。

组件

命名与属性尽量沿用 shadcn-svelte，Avalonia 已有的控件直接复用（只换外观），shadcn 有而 Avalonia 没有的 以 iPaas.Controls 下的同名控件补齐。

已实现

其余组件

以画廊为准：一个组件一页，65 页组件，外加开头四页文档。除上表之外还有：

ipaas:Led / ipaas:LcdDisplay / ipaas:Meter / ipaas:Progress 都能用 ValueBrushSelector（值 → 画刷）按值取色；Led 另有 Value / ValueBrush，关灯取同一支色的 30% 档；Blink.IsBlinking / Blink.Brush（附加属性）给 Led / LcdDisplay / Meter 一个闪烁的开关与颜色——闪不闪是页面的判断，库只管效果（相位是缝，Blink.PinnedPhase 能钉住，测试与截图都读得到）。

读数**拼不成"小数位 + 后缀"**时用 ipaas:Knob / ipaas:Meter 的 ReadoutOf（值 → 词，{value}℃ 那类模板的语法归调用方）；ipaas:TextDisplay 的对齐走 TextAlignment（居中的读数不用自己拼 TextBlock）。

三个不做的：chart 不做组件（shadcn 的 chart 是 recharts 封装，Avalonia 侧请用 LiveCharts / ScottPlot， 配色取 Chart1..5Brush）；pythonBlock 不做（脚本引擎是宿主的事，外壳件用 Select / TextBlock / Button 拼）； form 不做 schema 绑定（错误态走 Field.IsInvalid）。

更细的（每个控件为什么长这样、踩过哪些坑）在 docs/design-system.md 第 7 节的坑表里； 组件清单、还没做的事与开工流程见 docs/roadmap.md。

图标

控件自己的 chrome（勾、箭头、叉、加载圈…）用的是随包发布的几何图形：Icons.g.cs，由 build/GenerateIcons.ps1 从 docs/reference/icons 下的 Lucide SVG 生成，绘图方式是 Lucide 的描边方式。

应用侧要整套图标时用 Lucide.Avalonia（本包已依赖）：

<lucide:LucideIcon Kind="Star" Size="16" />

仓库结构

dotnet build iPaas.Controls.slnx
dotnet test src/iPaas.Controls.Tests/iPaas.Controls.Tests.csproj
dotnet run --project src/iPaas.Controls.Demo/iPaas.Controls.Demo.csproj

构建前先关掉正在运行的画廊：它会锁住 src/iPaas.Controls.Demo/bin/… 里的 iPaas.Controls.dll，于是解决方案里的依赖项目拷不进去、构建失败（测试项目引用了画廊，所以 dotnet test 也会受影响）。临时绕过：先 dotnet build src/iPaas.Controls/iPaas.Controls.csproj， 再 dotnet test src/iPaas.Controls.Tests/iPaas.Controls.Tests.csproj -p:BuildProjectReferences=false。

许可

MIT，见 LICENSE。设计语言来自 shadcn-svelte（MIT），图标来自 Lucide（ISC）， 出处与改动见 NOTICE。