言麦YANMAI

YANMAI DOCUMENTATION

用言序，写出真正的
麦金塔应用。

言序是一门以中文表达程序结构的面向对象语言。言麦是它的原生 macOS GUI 框架：言序对象负责业务与界面语义，SwiftUI 负责渲染，AppKit 负责窗口和系统集成。

不是 WebView每个控件都由 SwiftUI 原生渲染。
不是静态描述器事件回到言序，状态增量更新界面。
不是 Swift 包装语法应用逻辑仍由言序对象组织。

01 · 开始

环境与安装

言麦面向 macOS 13 及以上系统，当前原生制品支持 Apple Silicon。项目需要言序 1.1.14 或更新版本，并显式允许原生扩展。

macOS 13+Apple Silicon言序 1.1.14+SwiftUI 原生宿主

安装依赖

yanbao add yanmai

允许原生扩展

[权限]
原生扩展 = true
为什么需要权限？

言麦会加载经过校验的本机动态库，以建立言序虚拟机与 SwiftUI 宿主之间的持久回调。权限必须由顶层应用声明，依赖包不能替应用自行扩大能力。

02 · 第一个应用

从对象开始，而不是从 JSON 开始

应用代码只接触视图、动作、状态、窗口和应用对象。JSON 是运行时内部的传输格式，不应成为业务模型。

引「包:yanmai」为 言麦；

定 开始动作 为 言麦.动作（「app.start」）；
定 内容 为 言麦.垂直（【
    言麦.标题（「你好，言麦」），
    言麦.文本（「这是一扇真正的原生窗口。」），
    言麦.按钮（「开始创造」，开始动作）
】）.设间距（16）.内边距（28）；

定 程序 为 言麦.应用（「我的应用」）
    .添窗口（言麦.窗口（「我的应用」，内容））
    .当事件（法（事件）则
        若 事件.名称 等于 开始动作.名称 则
            言 「点击已经回到言序」；
        终
    终）；

言麦.运行（程序）；

包名和动作名使用简短的 ASCII 标识，是工具链与稳定协议的一部分；变量、类型、方法和业务结构仍使用言序的中文表达。

03 · 核心模型

面向对象的职责边界

言麦不是一袋工厂函数。它把 GUI 拆成职责明确、可以组合并拥有自身行为的领域对象。

应
应用拥有场景、状态、菜单与事件处理器。
景
场景窗口、设置、菜单栏项目和文档场景。
视
视图描述语义、子视图、修饰和绑定。
态
状态拥有值、类型、修订号与绑定身份。
作
动作为用户意图提供稳定名称。
行
运行会话管理回调、补丁、请求与生命周期。

默认的 言麦 入口是稳定门面。大型项目也可以分别导入应用、视图、状态、动作和运行时模块；类型身份不会因为入口不同而被复制。

04 · 视图

原生视图与布局

视图对象描述意图，宿主把它映射为 SwiftUI。组合方式遵循言序对象模型，而不是把 Swift 语法搬进中文源码。

类别可用能力适用场景
内容文本、标题、标签、系统图片、链接说明、状态、品牌与跳转
输入文本、安全输入、多行文本、开关、选择器、滑块、步进器、日期、颜色表单与偏好设置
布局水平、垂直、滚动、分组、分栏、标签页、导航栈从轻量面板到三栏桌面应用
集合列表、表格、树形大纲、搜索项目、文档与数据浏览
呈现工作表、浮出、警告、文件面板临时任务与系统工作流

组合示例

定 详情 为 言麦.垂直（【
    言麦.标题（「构建设置」），
    构建表单，
    言麦.分隔线（），
    最近输出
】）.设间距（12）.内边距（16）；

定 根视图 为 言麦.分栏（项目列表，任务列表，详情）；

05 · 状态与事件

完整闭环，而非单向截图

一次点击会通过持久 ABI v2 回调进入言序；输入控件会先回写 Binding，再发出类型化事件。言序更新状态后，运行时只提交带修订号的增量补丁。

用户操作→原生回写→言序事件→业务对象→增量补丁
定 次数 为 言麦.数值状态（「counter.value」，0）；
定 增加 为 言麦.动作（「counter.increment」）；

定 程序 为 言麦.应用（「计数器」）
    .添状态（次数）
    .当事件（法（事件）则
        若 事件.名称 等于 增加.名称 则
            次数.增加（1）；
        终
    终）；
修订号的作用

每份快照和补丁都有 revision。宿主只接受连续更新，避免过期异步结果覆盖较新的界面状态。

06 · 应用与场景

一款应用，不止一个窗口

应用对象统一管理普通窗口、设置场景、文档场景、菜单栏项目、原生菜单与激活策略。窗口可以配置尺寸、最小尺寸、恢复标识、默认命令和工具栏。

窗口多窗口、聚焦、关闭、恢复、工具栏与快捷命令。
设置标准设置窗口，沿用同一套视图和绑定。
文档打开、保存、导入、导出与内容/路径绑定。
菜单原生菜单、编辑命令、快捷键和启用状态。

08 · 系统能力

让应用参与 macOS

言麦的请求对象把系统副作用与视图描述分开。业务对象发起请求，宿主执行 AppKit 或系统服务，并把结构化结果作为事件返回。

打开与保存面板文件导入与导出钥匙串读写重复定时器打开设置窗口控制应用激活退出应用

文件面板、钥匙串和计时器都不会要求应用项目编写 Swift；同时，它们不会被伪装成视图属性，便于测试和审计。

09 · 架构

漂亮在表面，稳定在边界

言
言序领域对象应用 · 场景 · 视图 · 状态 · 动作 · 请求
快照 / 补丁 / 请求
↔
稳定协议与 ABI v2持久回调 · 类型化载荷 · 修订控制
原生渲染与系统事件
◆
SwiftUI + AppKit 宿主窗口 · 菜单 · 文档 · 菜单栏 · 系统服务

兼容代码只存在于协议入口。言序领域对象不需要知道历史 schema，也不直接管理线程、窗口句柄或 SwiftUI 生命周期。

10 · 兼容

演进能力，不随意破坏应用

言麦继续接受既有公共 API、动作载荷以及 dev.yanxu.mac-ui.v1/v2 协议。协议名是稳定线格式，不是面向用户的品牌名称。

  • 默认入口保留既有工厂函数。
  • 领域模块提供更清楚的 OOP 结构，但不复制类型身份。
  • 旧快照、事件名和 ABI v2 消息语义继续有效。
  • 新能力优先通过可选字段、对象方法和新请求扩展。

11 · 工程质量

验证、测试与发布

仓库同时验证言序源码、虚拟机行为、Swift 原生宿主、原生包锁和网站。新增控件至少需要 schema、模型、渲染、事件或绑定路径及回归测试共同覆盖。

yanxu 字节 tests/工具链.yx
yanxu 字节 tests/言麦入口.yx
swift test --package-path native
发布制品

原生动态库按平台记录大小和 SHA-256，言包锁文件固定解析结果。runner 只用于维护、冒烟测试和截图，不参与普通应用运行。

12 · 继续阅读

参考入口

API 参考完整对象、方法与参数签名 →架构说明协议、运行时与线程边界 →成熟应用模式大型项目组织方式 →能力路线SwiftUI 覆盖与后续方向 →言序语言语法、对象系统与工具链 →真实示例展示台、工作台、发布器与菜单栏 →
已复制