slint-pixel 0.2.2

可复用像素风 Slint 1.18 组件库:16×16 像素画板 widget + 像素标题栏(跨平台)
Documentation

slint-pixel

License: MIT Slint

基于 Rust + Slint 1.18 的像素风可复用组件库:16×16 像素画板 widget、 自绘像素标题栏,以及一套常用像素风控件;附带组件画廊与画板演示程序。

  • 主仓:自托管 walgit(本机 http://127.0.0.1:8081/gqf2008/slint-pixel.git,remote origin)

  • 镜像 / 发版:https://github.com/gqf2008/slint-pixel(remote github,由 walgit 自动单向同步,只读)

  • 许可证:MIT

  • 可复用:所有组件通过 @slint_pixel 导入到任意 Slint 项目(见下方组件清单)。

  • 一键接线:Rust 侧调用 install_painter() / install_title_bar_controls(), 画/擦、清空、导出 PNG、窗口控制全部自动接好。

  • 自绘像素标题栏:无系统边框(no-frame),可拖拽、双击最大化,右侧最小化/最大化/关闭; Slint 1.18 起可设 native-move: true 把移动交给平台(拖动超过阈值才启动、单击不移动,宿主无需 Rust 接线)。

  • 像素画布:16×16 网格,格子放大 24px 显示(棋盘格 + 网格线 + 立体像素块)。

  • PICO-8 色板:16 色,点击选色;画笔 1×1 / 2×2 / 3×3;左键画、右键擦除。

  • 导出:一键保存为网格分辨率 PNG(透明背景),存到当前工作目录。

  • 跨平台:仅依赖 slint + image(纯 Rust),无平台特定代码。

gallery

最新特性(v0.2.2)

  • Slint 1.18:依赖升到 slint / slint-build 1.18.0(上游生成代码更瘦 —— 编译更快、二进制更小), 并适配 1.18 的兼容性变更(Flickable/ScrollView 的 viewport-* 更名为 content-*)。
  • 可选原生窗口移动:PixelTitleBar { native-move: true; }(成品窗口用 PixelPainterWindow::set_native_move(true))改用 Slint 1.18 的 WindowMoveArea 把拖动交给平台—— 拖动超过阈值才启动、单击不移动,宿主无需 Rust 接线。默认关闭,既有宿主行为不变。
  • 暗色主题:设置 PixelTheme.scheme = "dark" 即可一键切换全部组件配色;画廊里有“切到暗色 / 切回浅色”按钮。
  • 对话框可拖动:PixelDialog 支持按住标题栏拖动。
  • 高级组件:图表、专业表格、虚拟滚动、校验、排期、向导、看板、甘特、地图、媒体、PDF/条码/验证码等(详见组件清单)。
  • 交互增强:PixelTransferPro 搜索、PixelKanbanPro 拖拽、PixelDataGrid 列宽拖拽。
  • UI 组件测试:compile smoke 覆盖 @slint_pixel 全部组件编译,另有标题栏拖动的契约/行为守卫 (cargo test -p slint-pixel)。

文档

组件清单

所有组件都是 in/in-out 属性 + 回调,宿主可覆盖主题色,无系统依赖、跨平台。

组件 说明
PixelPainter 16×16 像素画板 widget(画布 + 色板 + 工具栏 + 状态栏)
PixelTitleBar 可拖拽像素标题栏(拖拽/最小化/最大化/关闭回调;可选 native-move 由平台负责移动)
PixelButton 像素按压按钮(按下下沉效果)
PixelCheckBox 复选框(像素勾选 + 文字标签)
PixelSwitch 开关(滑块滑动动画)
PixelSlider 滑块(拖拽取值,min/max,changed(value) 回调)
PixelTextInput 单行文本输入(占位符 + 焦点高亮 + accepted/edited)
PixelProgressBar 进度条(0..1,可选百分比文字)
PixelBadge 徽章/标签
PixelPanel 分组面板(标题 + 内容插槽 @children)
PixelDialog 模态对话框(遮罩 + 标题 + 内容插槽 + 确定/取消)
PixelRadioButton 单选框(独立使用)
PixelRadioGroup 单选框组(互斥,options 数据驱动)
PixelComboBox 下拉选择框(PopupWindow,open 可控)
PixelMenu 下拉菜单("---" 项渲染分隔线)
PixelTableView 表格(表头 + 数据行 + 选中行回调)
PixelScrollPanel 滚动面板(基于 Slint 内置 ScrollView,滚轮/拖拽原生)
PixelCollapsible 可折叠面板(高度动画)
PixelAccordion 手风琴(titles/contents 数据驱动,互斥展开)
PixelSidebar 侧边栏(导航项 + 选中态 + 内容区 @children)
PixelText / PixelTitle 像素风文本 / 标题(统一字号)
PixelForm / PixelFormItem 表单容器 / 表单项(左标签 + 右控件插槽)
PixelTextArea 多行文本输入(换行 + 占位符)
PixelIconButton 图标按钮(通用字形图标 + 悬停高亮)
PixelTooltip 悬停提示气泡(延迟显示,包裹任意目标)
PixelBubble 富内容气泡/弹出卡片(触发图标 + 箭头 + 内容插槽)
PixelPopconfirm 操作确认气泡(触发按钮 + 确定/取消)
PixelAlert 警告/提示条(info/success/warning/error,可关闭)
PixelToast 通知(自动消失 + 手动关闭)
PixelSpinner 加载动画(像素方块循环)
PixelSkeleton 骨架屏(加载占位条,呼吸动画)
PixelTabs 标签页(数据驱动 + 激活态)
PixelBreadcrumb 面包屑(路径导航)
PixelPagination 分页(上一页/下一页 + 页码)
PixelDrawer 抽屉(右侧滑出 + 遮罩 + 内容插槽)
PixelAvatar 像素头像(方块 + 字形/首字)
PixelTag 标签(可关闭)
PixelCard 卡片(可选标题 + 内容插槽)
PixelNavbar 顶栏导航(品牌 + 菜单项 + 右侧插槽)
PixelEmpty 空状态(图标 + 标题 + 描述 + 操作插槽)
PixelDivider 分隔线(可带文字)
PixelStat 统计卡片(大数字 + 标签 + 变化)
PixelWindowResize 无边框窗口缩放热区(四边/四角,配合 install_window_resize)
PixelTheme 全局主题(bg/panel/hover/edge/shadow/text/dim/accent/danger 九色,改一处全部组件实时换肤)
Swatch 像素风色块(也可作图标按钮右上角数字角标)

扩展组件(ROUND 2)

组件 说明
PixelSegmentedControl 分段控制器(互斥选项)
PixelSteps 步骤条(数据驱动,可点击)
PixelNumberInput 数字步进输入框
PixelSelect 多选下拉
PixelSwatchGroup / PixelColorPicker 色板组 / 简单取色器
PixelContextMenu 右键/受控上下文菜单
PixelRangeSlider 双滑块范围选择
PixelTree / PixelTreeSelect 树 / 树形下拉
PixelTransfer 双栏穿梭框
PixelUpload 上传/文件选择视觉组件
PixelTimeline 时间线
PixelCarousel 轮播
PixelSplitPane 可拖拽分栏
PixelDatePicker / PixelTimePicker 日期 / 时间选择
PixelCommandPalette 命令面板
PixelKanban 看板
PixelOnboarding 分步引导
PixelImage / PixelImageViewer 像素图片 / 图片查看器
PixelTagInput 标签输入
PixelAutoComplete 自动补全
PixelCascader 级联选择
PixelDateRangePicker 日期范围选择
PixelRating 评分
PixelDescriptionList 描述列表
PixelResult 结果页
PixelAvatarGroup / PixelList / PixelVirtualList 头像组 / 列表 / 虚拟列表
PixelTreeTable / PixelDataTable 树形表格 / 数据表格
PixelSearchBox / PixelNotificationCenter 搜索框 / 通知中心
PixelSubMenu 二级菜单
PixelBackTop / PixelAffix / PixelSticky 回到顶部 / 固钉 / 吸顶
PixelRichTextEditor / PixelCodeBlock 富文本编辑器 / 代码块
PixelImageCrop / PixelQRCode / PixelWatermark / PixelCalendar 图片裁切 / 二维码 / 水印 / 日历

高级组件(ROUND 3)

组件 说明
PixelChart / PixelSparkline 柱状图 / 迷你趋势图
PixelDataGrid / PixelProTable 专业数据表格 / Pro 表格
PixelVirtualScroll 虚拟滚动列表
PixelTreePro 树(levels + expanded 受控)
PixelFormValidator 表单校验器
PixelScheduler / PixelCalendarAgenda 排期器 / 日历议程
PixelWizard / PixelMultiStepForm 向导 / 多步表单
PixelTransferPro / PixelKanbanPro 穿梭框 Pro / 看板 Pro
PixelCommandPalettePro / PixelColorPickerPro 命令面板 Pro / 取色器 Pro
PixelMention / PixelOTPInput / PixelSignature 提及 / 验证码 / 手写签名
PixelDrawerPro 抽屉 Pro
PixelOrgChart / PixelFlowChart / PixelMindMap 组织架构 / 流程图 / 思维导图
PixelGantt / PixelMap / PixelGeo 甘特图 / 地图 / 地理
PixelVideoPlayer / PixelAudioPlayer 视频 / 音频播放器
PixelPDFViewer / PixelPrintPreview PDF 预览 / 打印预览
PixelBarcode / PixelCaptcha 条码 / 图形验证码

主题:默认是 纯白(纯白底 + 近黑边框 + 纯黑文字,主色仅黑白,danger 保留红色做功能区分;PICO-8 绘画色板不变)。 一键换肤:所有组件默认色引用全局 PixelTheme(九色语义),改一处全部生效; 画廊里点 主题编辑器 可调色/切预设,点 一键生成样式 直接产出 .slint 覆盖代码。 PixelButton 支持 variant(default/primary/danger/ghost)与 size(small/medium/large),对齐 Tailwind 按钮语义。 所有组件主题色均为 in 属性,宿主可在 .slint 里整体覆盖为深色或任意配色。

提示:提示气泡请直接用 Slint 内置 Tooltip(延迟出现、自动跟随指针):

PixelButton {
    text: "悬停";
    Tooltip { text: @markdown("**提示文字**"); }
}

在盒布局中放置组件时,未显式给 width 的组件会拉伸占满剩余空间, 需要固定宽度的场景请显式指定(如 PixelButton { width: 90px; })。

运行演示

cargo run

启动后打开 组件画廊(展示全部常用控件),点画廊里的 打开像素画板 → 可打开画板窗口。窗口为无边框自绘标题栏,四边/四角可直接拖拽缩放,标题栏可拖动/最小化/最大化/关闭。

结构(workspace)

crates/
├── slint-pixel/                  # 组件库(lib)
│   ├── ui/lib.slint               # @slint_pixel 汇总入口(re-export 全部组件)
│   ├── ui/pixel_theme.slint         # 全局主题 PixelTheme(九色语义)
│   ├── ui/pixel_painter_widget.slint   # 画板 + 标题栏 + 按钮 + 色块
│   ├── ui/pixel_widgets.slint          # 基础控件:复选/开关/滑块/输入/进度/徽章/面板/对话框
│   ├── ui/pixel_complex.slint         # 进阶控件:单选/下拉/菜单/表格/滚动/手风琴/侧边栏
│   ├── ui/pixel_extra.slint           # 表单/文本/输入/图标按钮/提示/气泡/确认
│   ├── ui/pixel_tailwind.slint        # 对齐 Tailwind:警告/通知/加载/骨架/标签页/面包屑/分页/抽屉/头像/卡片/顶栏/空状态/统计
│   ├── ui/pixel_painter_window.slint   # 成品窗口 PixelPainterWindow
│   ├── ui/pixel_more.slint              # ROUND 2 扩展组件(分段/步骤/数字/选择/取色/上下文菜单)
│   ├── ui/pixel_p1.slint                # ROUND 2 扩展组件(范围/树/穿梭/上传/时间线/轮播/分栏)
│   ├── ui/pixel_p2.slint                # ROUND 2 扩展组件(日期/时间/命令/看板/引导)
│   ├── ui/pixel_p3.slint                # ROUND 2 扩展组件(图片/标签/联想/级联/评分/描述/结果)
│   ├── ui/pixel_p4.slint                # ROUND 2 扩展组件(列表/数据表格/搜索/通知/菜单/吸顶)
│   ├── ui/pixel_p5.slint                # ROUND 2 扩展组件(富文本/代码/裁切/二维码/水印/日历)
│   ├── ui/pixel_p6.slint                # ROUND 3 高级组件(图表/表格/虚拟滚动/树/校验/排期)
│   ├── ui/pixel_p7.slint                # ROUND 3 高级组件(向导/穿梭/看板/命令/提及/签名)
│   ├── ui/pixel_p8.slint                # ROUND 3 高级组件(架构/流程/甘特/地图/媒体/PDF/条码)
│   └── src/
│       ├── lib.rs                 # library_paths()、接线 trait/宏、install_painter() 等
│       └── canvas.rs              # 画布数据、放大渲染、PNG 导出(含单元测试)
└── slint-pixel-demo/             # 演示程序(bin,作为下游消费者组装窗口)
    ├── ui/gallery.slint           # 组件画廊窗口
    ├── ui/theme_editor.slint        # 主题编辑器(一键换肤 + 生成样式代码)
    ├── ui/main.slint              # 画板窗口(通过 @slint_pixel 组装)
    └── src/main.rs                # 接线:install_painter / install_title_bar_controls / 打开画板

在其它 Slint 项目里复用

1. 添加依赖

从 crates.io 引入(推荐):

[dependencies]
slint = "1.18"
slint-pixel = "0.2.2"

[build-dependencies]
slint-build = "1.18"
slint-pixel = "0.2.2"

也可以直接从 GitHub 引入:

[dependencies]
slint = "1.18"
slint-pixel = { git = "https://github.com/gqf2008/slint-pixel" }

[build-dependencies]
slint-build = "1.18"
slint-pixel = { git = "https://github.com/gqf2008/slint-pixel" }

本地开发时也可用 path 引入:

[dependencies]
slint = "1.18"
slint-pixel = { path = "path/to/slint-pixel/crates/slint-pixel" }

[build-dependencies]
slint-build = "1.18"
slint-pixel = { path = "path/to/slint-pixel/crates/slint-pixel" }

2. 在 build.rs 注册 @slint_pixel 库并编译自己的 UI

fn main() {
    println!("cargo:rerun-if-changed=ui/main.slint");
    let library_paths = slint_pixel::library_paths();
    for path in library_paths.values() {
        println!("cargo:rerun-if-changed={}", path.display());
    }
    let config = slint_build::CompilerConfiguration::new().with_library_paths(library_paths);
    slint_build::compile_with_config("ui/main.slint", config).unwrap();
}

3. 在 ui/main.slint 里导入组件并组装

import { PixelPainter, PixelTitleBar } from "@slint_pixel";

export component MainWindow inherits Window {
    no-frame: true;
    preferred-width: 720px;
    preferred-height: 560px;

    in-out property <image> canvas-image;
    in-out property <string> status-text: "就绪";

    callback paint(length, length, bool);
    callback clear-canvas();
    callback save-png();
    callback drag-start();
    callback minimize();
    callback toggle-maximize();
    callback close-window();

    VerticalLayout {
        padding: 12px;
        spacing: 10px;
        PixelTitleBar {
            title: "我的像素窗口";
            drag-start => { root.drag-start(); }
            minimize => { root.minimize(); }
            toggle-maximize => { root.toggle-maximize(); }
            close-window => { root.close-window(); }
        }
        PixelPainter {
            canvas-image <=> root.canvas-image;
            status-text <=> root.status-text;
            paint(px, py, erase) => { root.paint(px, py, erase); }
            clear-canvas => { root.clear-canvas(); }
            save-png => { root.save-png(); }
        }
    }
}

完整参考:crates/slint-pixel-demo/ui/main.slint 与 crates/slint-pixel-demo/ui/gallery.slint。

4. Rust 侧一键接线

slint::include_modules!();

// 把生成的 MainWindow 适配到组件库契约(一行宏,无需手写胶水代码)
slint_pixel::impl_painter_ui!(MainWindow);
slint_pixel::impl_title_bar_ui!(MainWindow);

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let ui = MainWindow::new()?;
    slint_pixel::install_painter(&ui);           // 画/擦、清空、导出 PNG
    slint_pixel::install_title_bar_controls(&ui); // 拖拽、最小化、最大化、关闭
    ui.run()?;
    Ok(())
}

不想写 .slint?直接用成品窗口

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let ui = slint_pixel::PixelPainterWindow::new()?;
    slint_pixel::install_painter(&ui);
    slint_pixel::install_title_bar_controls(&ui);
    ui.run()?;
    Ok(())
}

自定义主题

所有组件暴露 in 主题属性(如 PixelPainter 的 page / panel / panel-light / edge / shadow / text-color / dim / highlight / danger 与 palette;PixelSlider 的 track / fill / thumb / border / shadow 等),宿主可在 .slint 里直接覆盖。

窗口拖动的两种接法(native-move)

默认(native-move: false)沿用老契约:标题栏按下 → drag-start 回调 → 宿主调用 install_title_bar_controls()(内部是 winit drag_window())。已有宿主不用改。

宿主只写 .slint、不想接 Rust 时,可以把移动交给 Slint 1.18 的 WindowMoveArea:

PixelTitleBar {
    title: "我的像素窗口";
    native-move: true;   // 移动由平台完成(拖动超过阈值才启动、单击不移动);此时 drag-start 不再触发
    minimize => { root.minimize(); }
    toggle-maximize => { root.toggle-maximize(); }
    close-window => { root.close-window(); }
}

成品窗口同样支持 ui.set_native_move(true)(PixelPainterWindow 已直通该属性)。 开启后不要再依赖 drag-start:同一次拖动若既走平台移动又调用 drag_window(),会重复发起。

平台支持:winit 后端(Windows / macOS / X11 / Wayland)与 Qt;其它后端下该元素是空操作。

实现细节:WindowMoveArea 必须包住标题栏内容(容器形态)。同层兄弟形态下,全宽 TouchArea 的鼠标抓取会 抢先中止同层派发,表现为"配了 native-move 但窗口纹丝不动";仓库内用结构守卫 + 事件路由断言防回归 (cargo test -p slint-pixel --test title_bar_native_move)。副作用:从右侧按钮上按下并拖过阈值也会移动窗口 (上游容器语义)。

验证口径:start_window_move() 只在 Slint 内核内部 trait 上,公开 API 断言不了"平台移动是否被发起" (testing backend 的计数入口仅在 internal feature 下公开),该项在本仓由审查方用本地补丁版 backend 实测 (兄弟形态计数 0 / 容器形态拖动 40px 后计数 1)。建议升级后跑一次真机检查:cargo run 起 demo, 按住标题栏拖动看窗口是否移动,且单击标题栏不应移动窗口。

操作(画板)

操作 说明
左键拖动画布 用当前颜色/笔刷作画
右键拖动画布 擦除
点击色板 选择颜色
画笔 / 橡皮擦 切换工具
1×1 / 2×2 / 3×3 切换笔刷大小
清空 清空画布
存 PNG 导出 pixel-art-<时间戳>.png
标题栏拖拽 移动窗口
标题栏双击 最大化 / 还原
标题栏右侧按钮 最小化 / 最大化 / 关闭

说明

  • Slint 在 crates.io 上最新稳定版为 1.18(无 0.18 版本线)。
  • Linux Wayland 下合成器可能强制保留系统装饰,no-frame 效果取决于合成器。
  • 高 DPI(150%)显示器下按物理像素渲染,画布仍保持像素锐利。
  • install_painter 导出的 PNG 保存在进程当前工作目录。
  • 组件清单已对齐 Tailwind 常见 UI:按钮/表单/反馈/导航/数据展示/覆盖层均已覆盖;仍需按需扩展的:日期选择器、上传、时间线等,可在 pixel_tailwind.slint 里继续追加(组件均遵循同一黑白像素风主题约定)。