Documentation
Nimi 文档.
从源码运行第一个窗口,到 WebView IPC、原生 UI、三平台后端与打包。 macOS、Windows、Linux 均已进入 Preview;API 仍可能调整。
安装
Nimi 以源码 Preview 形式使用。需要 Nim 2.4+; macOS 12+ / Xcode Command Line Tools,Windows WebView2 Runtime, Linux GTK3 与可选 WebKitGTK。
git clone https://github.com/zhimoe/nimi.git
cd nimi
nim c -o:nimi src/nimi/cli.nim
./nimi doctor
./nimi version
mygo/;
本地开发可放置只读参考副本。实际构建只需要 src/、
examples/ 和 config.nims。
快速开始
用 CLI 创建并运行一个项目:
./nimi init my-app
./nimi dev my-app
# 打包 .app + DMG
./nimi build my-app
open "my-app/dist/darwin-arm64/My App.app"
nimi dev 会监听 .nim/.nims 与
nimi.json,源码变化后自动重建并重启。
nimi build 生成 Info.plist、PkgInfo、图标、可选签名和 DMG。
直接运行仓库示例
# WebView + 类型化 IPC
nim c -r --path:src examples/hello/main.nim
# 原生 UI 布局与交互
nim c -r --path:src examples/counter-native/main.nim
# Markdown 笔记应用(WebView + 原生菜单/对话框)
nim c -r --path:src examples/notes/main.nim
WebView 与类型化 IPC
Nim 侧用 bindService 显式暴露方法。宏在编译期读取 proc 签名,
生成 JSON 参数解码、结果编码和 TypeScript 客户端。
import nimi
type
Greeter = ref object
proc greet(self: Greeter, name: string): string =
"Hello, " & name & "!"
let greeter = Greeter()
bindService(greeter, greet)
页面通过注入的 bridge 调用:
const text = await window.nimi.call("Greeter.greet", "Nim");
每个窗口有独立 secret 与 token;bridge 在 document start 注入, 页面无法直接访问文件系统或系统 API,只能调用显式绑定的服务。
运行 ./nimi generate my-app 会生成
frontend/nimi.ts 和运行时客户端,便于在 TypeScript 项目中获得补全。
原生 UI
不需要 HTML 时,用 uiView 描述每帧的 Node 树。
布局、测量、绘制、命中、焦点和键盘都走同一套实现。
import std/os
import nimi
import nimi/ui
type
Counter = ref object
n: int
proc view(s: Counter, c: Context) =
column(c).fill().center().gap(16).children(c, proc() =
text(c, $s.n).fontSize(56).bold()
row(c).gap(8).children(c, proc() =
button(c, "+", (proc() = inc s.n), key = "inc")
)
)
let counter = Counter()
let content = uiView(proc(c: Context) = view(counter, c))
app.whenReady(proc() =
discard newWindow(WindowOptions(
title: "Counter",
width: 360,
height: 260,
content: content
))
)
app.run()
已实现的控件包括 Text、Button、Checkbox、Switch、Slider、Progress、
Divider 和单行 TextInput;文本换行、Tab/Enter 焦点、鼠标拖动和
Tester 无窗口测试都已可用。
项目结构
| 路径 | 作用 |
|---|---|
src/nimi/core/ | app、window、IPC、loop、events、bridge、menu、dialog、clipboard |
src/nimi/platform/ | 平台契约与 Darwin / Windows / Linux 后端 |
src/nimi/ui/ | 原生 UI 布局、控件、输入、焦点与 Tester |
src/nimi/scene/ | rect/text display list |
src/nimi/render/ | CoreGraphics / Cairo / GDI / Metal 场景渲染 |
src/nimi/text/ | CoreText / Pango / GDI 测量与换行 |
src/nimi/cli.nim | init / generate / dev / build / doctor |
docs/ | 可行性、架构、平台后端、路线图与实现记录 |
docs/backlog/ | Preview 版本范围与平台差异 |
examples/notes/ | Nimi Notes:WebView-first 完整应用 |
平台与 Preview
core 只依赖 platform/contract。macOS、Windows、Linux
Preview 后端复用同一 Backend / NativeWindow / SurfaceHandler 模型。
| 平台 | 状态 | 实现 |
|---|---|---|
| macOS | Preview | AppKit、WKWebView、CoreGraphics、CoreText、NSMenu、NSOpenPanel/NSSavePanel |
| Windows | Preview | Win32、WebView2、GDI、原生菜单/IME/托盘 |
| Linux | Preview | GTK3、WebKitGTK、Cairo/Pango、X11/MPRIS/GStreamer |
- WebView: 系统 WebView + 类型化 IPC + TS 生成 + 自定义协议。
- 原生 UI: Surface、布局、控件、IME、滚动、Tester。
- 桌面: 菜单、对话框、剪贴板、托盘、通知、快捷键、Now Playing。
- 打包: macOS .app/DMG,Windows exe/manifest,Linux .desktop/.deb。
平台差异、真实设备验收与后续计划集中在 项目 backlog ↗, 不占用首页。
示例
Nimi Notes 是当前的端到端验收:WKWebView 页面负责编辑与预览,
Nim 负责 JSON 存储、原生菜单和文件对话框,最后打包成
Nimi Notes.app 与 DMG。
NIMI_NOTES_DIR=/tmp/nimi-notes-smoke NIMI_SMOKE=crud \
nim c -r --path:src examples/notes/main.nim
# smoke crud: ok (1 -> 2)
./nimi build examples/notes
hdiutil verify examples/notes/dist/darwin-arm64/nimi-notes-0.1.0.dmg
仓库里还有:
examples/hello— WKWebView + IPC + 50 次调用冒烟。examples/counter-native— 原生布局、鼠标、方向键、Tab+Enter。examples/widgets-native— Checkbox/Switch/Slider/Progress/Divider。examples/form-native— 原生表单、菜单、文件/消息对话框。examples/shred-native/shred-metal— Verlet 纸带、纹理四边形、Metal mask/LayerEffect。
完整文档
设计与实现细节在仓库 docs/ 下持续更新;版本范围见 backlog: