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.niminit / 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 模型。

平台状态实现
macOSPreviewAppKit、WKWebView、CoreGraphics、CoreText、NSMenu、NSOpenPanel/NSSavePanel
WindowsPreviewWin32、WebView2、GDI、原生菜单/IME/托盘
LinuxPreviewGTK3、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: