cj-tauri 0.8.0 → 1.1.0

package/src/host.cj

@@ -1,6 +1,6 @@
-package cjTauri
-
-import std.collection.*
+package cjTauri
+
+import std.collection.*
 import stdx.encoding.json.*
 
 /**
@@ -29,6 +29,13 @@ public const CJ_CAP_TRAY: Int32 = 2
 
 public const CJ_CAP_DRAG_DROP: Int32 = 4
 
+/** 全局快捷键（与 native/bridge_core.h 的 CJ_CAP_HOTKEY 逐位对齐；Linux = 编进了 X11 支持） */
+public const CJ_CAP_HOTKEY: Int32 = 16
+
+/** 标题栏副标题（与 native/bridge_core.h 的 CJ_CAP_SUBTITLE 逐位对齐；Linux = 菜单栏同排的 label，
+    Windows 的系统菜单没有自绘区、不置位）。应用据它决定要不要自己画页面顶栏。 */
+public const CJ_CAP_SUBTITLE: Int32 = 32
+
 /**
  * 宿主能力位的**可读形态**（RFC-002 §5.3）：`CJ_CAP_*` 位域 → 具名布尔 + `toJson`。
  *
@@ -44,12 +51,16 @@ public class HostCapabilities {
     public let menu: Bool
     public let tray: Bool
     public let dragDrop: Bool
+    public let hotkey: Bool
+    public let subtitle: Bool
 
-    public init(platform: String, menu: Bool, tray: Bool, dragDrop: Bool) {
+    public init(platform: String, menu: Bool, tray: Bool, dragDrop: Bool, hotkey: Bool, subtitle: Bool) {
         this.platform = platform
         this.menu = menu
         this.tray = tray
         this.dragDrop = dragDrop
+        this.hotkey = hotkey
+        this.subtitle = subtitle
     }
 
     /** 位域 → 具名布尔（`platform` 由调用方给，见类注释） */
@@ -58,17 +69,21 @@ public class HostCapabilities {
             platform,
             (caps & CJ_CAP_MENU) != 0,
             (caps & CJ_CAP_TRAY) != 0,
-            (caps & CJ_CAP_DRAG_DROP) != 0
+            (caps & CJ_CAP_DRAG_DROP) != 0,
+            (caps & CJ_CAP_HOTKEY) != 0,
+            (caps & CJ_CAP_SUBTITLE) != 0
         )
     }
 
-    /** `system:host` 的返回形状：`{"platform":"windows","menu":true,"tray":true,"dragDrop":true}` */
+    /** `system:host` 的返回形状：`{"platform":"linux","menu":true,"tray":true,"dragDrop":true,"hotkey":true,"subtitle":true}` */
     public func toJson(): JsonValue {
         var obj = JsonObject()
         obj.put("platform", JsonString(this.platform))
         obj.put("menu", JsonBool(this.menu))
         obj.put("tray", JsonBool(this.tray))
         obj.put("dragDrop", JsonBool(this.dragDrop))
+        obj.put("hotkey", JsonBool(this.hotkey))
+        obj.put("subtitle", JsonBool(this.subtitle))
         return obj
     }
 }
@@ -145,6 +160,70 @@ public interface WebViewHost {
      */
     func setMenuItemState(id: String, enabled: Bool, checked: Bool): Unit
 
+    /**
+     * 设置**窗口顶部副标题**：一行文本画在原生菜单栏**同一行的右侧**
+     *
+     * 用途是让应用省掉自己那条页面顶栏——标题 / 保存状态 / 字数挂在原生这一行上，
+     * 界面高度直接少一层。允许运行期高频更新（每次编辑都可能改），平台自己投递到
+     * UI 线程，调用方在哪个线程调都行。
+     * 这是**运行期能力**：建窗之前调用返回 -3（不像 `setMenu` 那样记 pending），
+     * 应用要么等页面加载后再调，要么按返回值如实处理。
+     * 平台没有该能力（能力位不含 `CJ_CAP_SUBTITLE`，Windows 即如此）时如实降级：
+     * 文本不显示、桥打一行 stderr，应用据能力位自己决定画不画页面顶栏。
+     */
+    func setTitlebarSubtitle(text: String): Unit
+
+    /**
+     * 设置拖放策略（RFC-002 §5）：enabled=false 平台不注册 drop target。
+     * 必须在 `start()` / `startUrl()` 之前调用（Linux 建 view 时决定挂不挂 drag dest）；
+     * 之后调用在未就绪时只记 pending、建窗生效，已就绪平台投 UI 线程重挂。
+     * 平台没有该能力（能力位不含 `CJ_CAP_DRAG_DROP`）时宿主只记日志，不报错。
+     */
+    func setDragDropPolicy(enabled: Bool, files: Bool): Unit
+
+    /**
+     * 注册**全局快捷键**（RFC-003 第 5 期）：wire 一行一条 `<accel>:<id>`（见 `HotkeyModel.toWire`）
+     *
+     * 全局 = 焦点不在本应用窗口时也生效（X11 grab / Win32 RegisterHotKey）。
+     * 允许在 `start()` 之前调（桥记 pending，宿主线程起来后注册）；运行期再调 = 整表替换。
+     * 触发事件以 `{"kind":"hotkey","id":"…"}` 走 shell 回调（按句柄路由）→ 前端 `hotkey:press`。
+     * 平台不支持时桥打一行 stderr 如实说明，调用不报错、事件不来。
+     */
+    func setGlobalHotkeys(wire: String): Unit
+
+    /**
+     * 设置**托盘**（RFC-002 §7.C）：wire 见 `TrayModel.toWire()`，空串 = 移除托盘
+     *
+     * 允许在 `start()` 之前调（桥记 pending，宿主线程装配时创建）；运行期再调 = 整体重建。
+     * 菜单项被点以 `{"kind":"tray","id":"…"}` 走 shell 回调（按句柄路由）→ 前端 `tray:click`。
+     * 平台不支持 / 依赖没编进来时桥打一行 stderr 如实说明，调用不报错、托盘不出现。
+     */
+    func setTray(wire: String): Unit
+
+    /**
+     * 显示 / 隐藏本窗口（对标 Tauri 2 的 `window.show()` / `window.hide()`）
+     *
+     * 隐藏 = 从任务栏与屏幕上消失（Windows 走 `ShowWindow(SW_HIDE)`，Linux 走 `gtk_widget_hide`），
+     * 事件循环照常跑、页面照常活着——所以「最小化到托盘」的还原路径（托盘菜单 / 全局快捷键）才成立。
+     * 两头都能调：`start()` 之前调只记下（建窗时按它定稿，隐藏态的窗口首次出现前就是隐藏的）；
+     * 之后调用投到宿主 UI 线程执行。显示时顺带把窗口提到前台（Linux 是 `gtk_window_present`，
+     * Windows 是 `SetForegroundWindow`）。
+     * 这是**宿主基元**，两平台都实现，不占能力位（没有平台只有一半）。
+     */
+    func setWindowVisible(visible: Bool): Unit
+
+    /**
+     * 最小化到托盘（RFC-003 第 5 期余项，`WindowConfig.minimizeToTray` 的落点）
+     *
+     * enabled=true 时，用户在标题栏点「最小化」不再缩到任务栏，而是**隐藏窗口**
+     * （= `setWindowVisible(false)` 的效果）；还原走应用自己的托盘菜单 / 全局快捷键。
+     * 必须在 `start()` / `startUrl()` 之前调用（窗口过程要在建窗时就知道这条策略）。
+     * 真到最小化那一刻，平台会复核托盘是否**真的**装上了（能力位不含 `CJ_CAP_TRAY`，
+     * 或应用压根没调 `setTray`）：没装就如实降级为普通最小化并打一行 stderr——
+     * 窗口藏起来却没有任何还原入口，是比「不支持」更糟的结果。
+     */
+    func setMinimizeToTray(enabled: Bool): Unit
+
     /**
      * 本宿主的静态能力位（`CJ_CAP_*` 的按位或）：能不能做菜单 / 托盘 / 文件拖入
      *
@@ -160,15 +239,15 @@ public interface WebViewHost {
      * **多窗口下必须按宿主身份路由**：C 侧回调首参是句柄，只有本窗口的句柄才转给本实例的
      * 这个回调——这正是「回调带宿主身份」的落地方式（见 docs/RFC-菜单-托盘-拖放.md §5.5）。
      */
-    func setShellHandler(handler: (String) -> Unit): Unit
-
-    /**
-     * 装配本窗口的销毁回调（窗口关闭 / 退出收尾时恰好触发一次）
-     *
-     * 多窗口下按宿主身份路由（C 侧回调首参是句柄），所以每扇窗口装自己的——回调不带参数，
-     * 因为「是哪扇窗」在装配时就已确定（应用可经 `app.hostOf(label)` 逐窗安装）。
-     * 与 `setShellHandler` 同为**可变槽位**：在 `start()` 之后再装同样生效（路由闭包读字段，不是快照）。
-     */
+    func setShellHandler(handler: (String) -> Unit): Unit
+
+    /**
+     * 装配本窗口的销毁回调（窗口关闭 / 退出收尾时恰好触发一次）
+     *
+     * 多窗口下按宿主身份路由（C 侧回调首参是句柄），所以每扇窗口装自己的——回调不带参数，
+     * 因为「是哪扇窗」在装配时就已确定（应用可经 `app.hostOf(label)` 逐窗安装）。
+     * 与 `setShellHandler` 同为**可变槽位**：在 `start()` 之后再装同样生效（路由闭包读字段，不是快照）。
+     */
     func setDestroyHandler(handler: () -> Unit): Unit
 
     /**
@@ -180,6 +259,26 @@ public interface WebViewHost {
      */
     func showFileDialog(save: Bool, title: String, filter: String): String
 
+    /**
+     * 带默认文件名的文件对话框：除预置名字外与 `showFileDialog` 完全同语义。
+     *
+     * 预置名字的用途是**自动化取证**——探针对原生框发 IDOK 时框里得已有名字才能关，
+     * 返回值因此可预期（预置什么回什么），多窗并发的「结果各归各窗」才验得动。
+     * 平台不支持预置（如 GTK 轮未接）时行为退化为 `showFileDialog`，如实降级。
+     */
+    func showFileDialogPreset(save: Bool, title: String, filter: String, defaultName: String): String
+
+    /**
+     * 原生目录选择对话框（阻塞到用户关闭）：返回选中的目录路径，取消 / 失败返回空串。
+     *
+     * 独立成方法而不是给 `showFileDialog` 加一个开关：选目录在两端都不是「换个动作」——
+     * GTK 是另一个 chooser action，Windows 更是另一套 API（`IFileOpenDialog` +
+     * `FOS_PICKFOLDERS`，`GetOpenFileName` 没有这个能力）。桥侧两者共用同名同签名的
+     * `cj_bridge_show_dialog`，以 kind=6 区分（与文件类 / 消息类并列，见 `dlg_req`）。
+     * 与 `showFileDialog` 同规矩：必须在 start() / startUrl() 之后调用（要拿应用窗口当父窗口）。
+     */
+    func showFolderDialog(title: String): String
+
     /**
      * 原生消息对话框（阻塞到用户关闭）：返回用户是否点了「确定」。
      *
@@ -188,6 +287,24 @@ public interface WebViewHost {
      */
     func showMessageDialog(kind: String, title: String, message: String): Bool
 
+    /**
+     * 写文本进系统剪贴板（上限 8 MiB，C 侧 core 校验）
+     *
+     * 与对话框同类：宿主能力，要在 start() 之后调用（未就绪时返回 false）。
+     */
+    func clipboardWriteText(text: String): Bool
+
+    /**
+     * 读系统剪贴板文本：空 / 非文本 / 平台失败都返回 None，不区分（协议层没有可读的失败明细）
+     */
+    func clipboardReadText(): Option<String>
+
+    /**
+     * 发一条系统通知（发后即忘：提交即返回，显示成败不回传）。
+     * 本平台未实现时返回 false（`system:host` 的能力位会同口径如实上报）。
+     */
+    func notify(title: String, body: String): Bool
+
     /**
      * 原生 → JS：在 WebView 中执行脚本
      */
@@ -300,11 +417,7 @@ class HostGlobals {
     static func registerHostRoute(handle: CPointer<Unit>, onShell: (String) -> Unit,
                                   onDestroy: () -> Unit, onDialog: (String) -> Unit): Unit {
         for (r in HostGlobals.hostRoutes) {
-            var same: Int32 = 0
-            unsafe {
-                same = cj_bridge_host_eq(r.handle, handle)
-            }
-            if (same != 0) {
+            if (hostHandleEquals(r.handle, handle)) {
                 r.onShell = onShell
                 r.onDestroy = onDestroy
                 r.onDialog = onDialog
@@ -319,11 +432,7 @@ class HostGlobals {
      */
     static func hostRouteOf(handle: CPointer<Unit>): Option<HostRoute> {
         for (r in HostGlobals.hostRoutes) {
-            var same: Int32 = 0
-            unsafe {
-                same = cj_bridge_host_eq(r.handle, handle)
-            }
-            if (same != 0) {
+            if (hostHandleEquals(r.handle, handle)) {
                 return Some(r)
             }
         }
@@ -407,23 +516,85 @@ func shellOnEvent(host: CPointer<Unit>, json: CString): Unit {
  * 必须是构造参数而不是事后 setter——label 决定页面侧 `window.__CJ_TAURI_LABEL__` 与事件过滤，
  * 启动之后再改就晚了（见 docs/架构演进-多平台与多窗口.md §7.3）。
  */
-@When[os == "Linux"]
+// 判据为什么是 `env`（2026-10-19 校正）：鸿蒙目标下 `os` 仍取 `Linux`，`arch` 也只有
+// `aarch64`——桌面 aarch64 Linux 同样是 `aarch64`，拿它当判据会把「跑在 GTK 上」误判成
+// 「跑在 ArkWeb 上」，两边的宿主实现会互相打架（编译期就撞名）。官方条件编译映射表给出
+// `aarch64-linux-ohos` → `env == "ohos"`、桌面 Linux → `gnu`，这才是真正互斥的维度。
+// 于是桌面 Linux 侧写 `env != "ohos"`：**桌面 aarch64 Linux 因此重新拿回 WebKit 宿主**
+// （改判据之前它落到「只能注入宿主」的分支，是同一处误判的另一半）。
+@When[os == "Linux" && env != "ohos"]
 func createHost(label: String): WebViewHost {
     return WebKitHost(label)
 }
 
+// 鸿蒙：内置 ArkWeb 宿主（应用侧只负责建 ArkUI 组件并把 controller 交给它，见 src/host_arkweb.cj）
+@When[env == "ohos"]
+func createHost(label: String): WebViewHost {
+    return ArkWebHost(label)
+}
+
 @When[os == "Windows"]
 func createHost(label: String): WebViewHost {
     return WebView2Host(label)
 }
 
+/**
+ * 两个宿主句柄是否指向同一宿主
+ *
+ * 桌面两平台走 C 桥 `cj_bridge_host_eq`——仓颉的 `CPointer` 既没有 `==` 也没有 `!=`
+ * （实测报 `invalid binary operator '!=' on type 'CPointer<Unit>'`），也没有 `hashCode`，
+ * 比较只能交给 C 侧。鸿蒙侧没有 C 桥（`native/platforms/harmonyos/` 尚未产出 `cj_bridge_*`），
+ * `ArkWebHost` 的句柄在仓颉侧不参与路由（回调是仓颉闭包，不经 C 中转），因此恒为 false
+ * 并留一行 stderr——**不假装相等**（假装相等会把两扇窗的路由串台）。
+ */
+@When[os == "Windows"]
+func hostHandleEquals(a: CPointer<Unit>, b: CPointer<Unit>): Bool {
+    unsafe {
+        return cj_bridge_host_eq(a, b) != 0
+    }
+}
+
+@When[os == "Linux" && env != "ohos"]
+func hostHandleEquals(a: CPointer<Unit>, b: CPointer<Unit>): Bool {
+    unsafe {
+        return cj_bridge_host_eq(a, b) != 0
+    }
+}
+
+// 只在无 C 桥的平台用到，声明也放进同一门禁：桌面侧保留会变成 unused variable
+@When[env == "ohos"]
+private var HOST_ROUTE_WARNED: Bool = false
+
+@When[env == "ohos"]
+func hostHandleEquals(a: CPointer<Unit>, b: CPointer<Unit>): Bool {
+    let _ = a
+    let _ = b
+    if (!HOST_ROUTE_WARNED) {
+        HOST_ROUTE_WARNED = true
+        eprintln("[cj-tauri] host route by handle unavailable on this platform: injected host keeps its own callbacks")
+    }
+    return false
+}
+
 /**
  * 造一个「裸宿主句柄」：只分配 C 侧宿主对象（不 init / 不 start、不碰图形栈）
  *
  * 只给单元测试用（子包可见，不算对外 API）。为什么需要这层包皮：`cj_bridge_create` 是
  * `foreign func`——没有函数体、也就没有跨包符号，子包 `cjTauri.tests` 直接调会在**链接期**炸
  * （实测 `ld.lld: error: undefined symbol: cjTauri:cj_bridge_create`）；框架包内包一层就有实体符号了。
+ *
+ * 只编桌面两平台：鸿蒙没有 C 桥也就没有这个符号，而单测只在桌面跑（`cjpm test` 用桌面目标）。
  */
+@When[os == "Windows"]
+func createBareHostHandle(): CPointer<Unit> {
+    var h: CPointer<Unit> = CPointer<Unit>()
+    unsafe {
+        h = cj_bridge_create()
+    }
+    return h
+}
+
+@When[os == "Linux" && env != "ohos"]
 func createBareHostHandle(): CPointer<Unit> {
     var h: CPointer<Unit> = CPointer<Unit>()
     unsafe {