ebox/docs/user/ebox-api-reference.zh.md

Ebox 公共 API 参考

English

本文描述独立 Ebox 包当前的公共边界，并把普通 author 路径与框架集成使用的 evaluated typed API 分开。以 ebox-- 开头的名称都是私有实现。

Ebox 需要 Emacs 29.1 或更高版本、ECSS 和 TP：

(require 'ebox)

1. Author 语法

ebox-build 只接受以下 author 入口：

STRING
(text PROPERTY VALUE ... STRING)
(box PROPERTY VALUE ... CHILD ...)
(row PROPERTY VALUE ... CHILD ...)
(column PROPERTY VALUE ... CHILD ...)
(flex PROPERTY VALUE ... CHILD ...)
(grid PROPERTY VALUE ... CHILD ...)

STRING 是 (text STRING) 的简写。Text form 必须且只能有一个字符串 payload。 每种 Box form 都接受零个或多个直接嵌套的 Text/Box 子节点。form 名称选择 Normal、 Row、Column、Flex 或 Grid 子布局；author 不通过 property 传入布局选择器。

(ebox-build
 '(column :padding (1 2)
          (box :id "status" :color "#166534" "Ready")
          (row :item-gap 1
               (box "Left")
               (box "Right"))))

author source field 是 :key、:class 与 :id。:outer 可取 inline 或 block，控制 Box 如何参与父布局。

布局拥有的 property

Form 或关系	Property
row、column	:item-gap、:cross-align
flex	:flex-direction、:flex-wrap、:flex-flow、:justify-content、:align-items、:align-content、:gap、:row-gap、:column-gap
flex 的直接子 Box	:order、:flex、:flex-grow、:flex-shrink、:flex-basis、:align-self
grid	:grid-template-columns、:grid-template-rows、:grid-auto-columns、:grid-auto-rows、:grid-auto-flow、:justify-items、:justify-content、:align-items、:align-content、:gap、:row-gap、:column-gap
grid 的直接子 Box	:order、:grid-column、:grid-row、:grid-column-span、:grid-row-span、:align-self

participation property 就是普通子 Box property，不会创建另一种公共节点或 wrapper。

当前常用 property

范围	当前输入
尺寸	:box-sizing、:width、:min-width、:max-width、:height、:min-height、:max-height
边缘	:padding、:margin、:border、各 side shorthand 与 longhand
绘制	:color、:background-color、精确 alias :bgcolor、border color、:visibility
文本布局	:text-align、:wrap-mode（word、char、kp、none）
Overflow	:overflow（visible、hidden、scroll）

普通横向数字表示字符列，单元素横向 list 表示像素；纵向数字表示行数。 (viewport) 与 (viewport-height) 使用当前 render context。property 验证属于 Ebox；context/value 组合无效时会直接报错。

2. Evaluated typed construction

已经拥有 author parsing 的框架可以直接构造 canonical node：

(let ((layout (ebox-column-layout-create
               :item-gap 1 :cross-align 'stretch)))
  (ebox-box-create
   :layout layout
   :children (list (ebox-text-create :value "One")
                   (ebox-text-create :value "Two"))))

• ebox-text-create 要求 :value STRING；
• ebox-normal-layout-create 构造 Normal LayoutConfig；
• ebox-row-layout-create 与 ebox-column-layout-create 接受 :item-gap 和 :cross-align；
• ebox-flex-layout-create 构造经过验证的 Flex LayoutConfig；
• ebox-grid-layout-create 构造经过验证的 Grid LayoutConfig；
• ebox-box-create 要求一个 typed :layout 值，并接受 typed node 的 :children list。

最后两个 field 只属于 evaluated 集成契约，不是 author property，也不是另一套 DSL。

typed 模块还公开 ebox-node-kind、ebox-text-node-p、ebox-box-node-p、 ebox-node-source-handle、ebox-text-node-value、ebox-box-node-layout、 ebox-box-node-children 和 ebox-box-node-range-anchors。下面的 facade 清单重点列出 应用入口，因此不重复这些 inspection function。

3. 渲染与 retained 发布

函数	契约
ebox-render	返回带属性字符串，不发布 live buffer。
ebox-render-to-buffer	复制 built root，挂载 retained TP surface，启用 ebox-buffer-mode 并返回 buffer。
ebox-display-buffer	走 retained 路径渲染，删除其他 window 后切换到结果。
ebox-commit	原子发布重新构建的 root 或 one-shot logical candidate。
ebox-buffer-update-report	返回最近一次成功更新报告的防御性副本。
ebox-rerender-buffer-with-context	应用显式 viewport width 与可选 height，同时保留 identity。
ebox-viewport-window-width	返回 Ebox 对 window 使用的 display-safe 像素宽度。

ebox-commit 接受可选 framework publish/rollback callback。它们加入现有原子发布； 失败会恢复旧 buffer、surface、runtime state 与最近一次成功报告。

ebox-call-with-render-burst 是框架 callback 的 exception-safe allocation/GC 边界。 ebox-render-burst-begin 与 ebox-render-burst-end 提供较底层的 token 形式，必须用 unwind-protect 配对。它们本身不发布内容。

4. Identity、直接更新与 logical candidate

函数	契约
ebox-region-ids	按文档顺序返回当前底层 region id。
ebox-region-resolve	把 mounted buffer 中一个逻辑 :id 解析为不透明、surface-scoped 的 handle。
ebox-region-update	通过一次 retained transaction 应用支持的可变样式或滚动 property。
ebox-child-range	从 typed node 构造透明、可寻址的 child Range descriptor。
ebox-candidate-begin	在 one-shot candidate 中捕获当前准确 mounted generation。
ebox-candidate-replace	替换一个 candidate node address。
ebox-candidate-replace-range-ref	替换一个透明 child Range payload。
ebox-candidate-replace-root	替换 candidate 的私有 root address。
ebox-candidate-replace-host-ref	替换一个 framework-owned opaque host reference。
ebox-candidate-patch-host-paint	记录经过证明的 paint-only host patch；需要 replacement 时返回 nil。
ebox-host-ref-bounds	返回 opaque host reference 当前不含 margin 的 bounds。
ebox-host-ref-position	返回其当前第一个位置。

handle 和位置只属于一个 live publication generation；对象被删除后要重新解析。 candidate 被 commit 封存后不能复用。

5. Selector

ECSS 是唯一 selector parser 与 matcher；Ebox 只提供 logical tree relation 和 mounted index。

函数	契约
ebox-selector-parse	把 CSS-like selector 编译为 ECSS AST。
ebox-selector-match-node-p	用 selector 或 AST 匹配一个 built node。
ebox-selector-query-all	按文档顺序查询 unmounted built tree。
ebox-selector-query-buffer	查询一个 mounted runtime。
ebox-selector-update-buffer	更新所有可编辑 mounted match 并返回结构化报告。
ebox-select-all	ebox-selector-query-buffer 的 alias。
ebox-update-selector	ebox-selector-update-buffer 的 alias。

6. 滚动

ebox-buffer-mode 安装 ebox-scroll-map。map 会把行、页和滚轮意图先交给最内层 semantic scroll owner，再回退到普通 Emacs 滚动。

公共命令是 ebox-scroll-down、ebox-scroll-up、ebox-scroll-page-down、 ebox-scroll-page-up、ebox-wheel-scroll-down 与 ebox-wheel-scroll-up。 ebox-scroll-state 根据数字 region id 返回只读快照。

7. 测量、缓存与构建工具

函数	契约
ebox-string-pixel-width	测量字符串第一行的 display width。
ebox-display-signature	返回 measurement cache invalidation 使用的 display 输入。
ebox-clear-cache	清理 Ebox measurement/render cache。
ebox-byte-compile	编译 Ebox 活跃 Elisp 源码；重启 Emacs 后加载新 bytecode。
ebox-native-status	报告 native toolchain、module、ABI 与加载状态。
ebox-native-build	异步构建并安装可选 native 模块。

native 模块只是加速器，不是正确性依赖。加载包不会构建它。

8. Facade 清单

ebox-public-api 保存稳定 facade 入口。下面的分组列出其中每一个名称：

• 构造：ebox-build、ebox-text-create、ebox-normal-layout-create、 ebox-row-layout-create、ebox-column-layout-create、 ebox-flex-layout-create、ebox-grid-layout-create、ebox-box-create、 ebox-child-range；
• 渲染/发布：ebox-render、ebox-render-to-buffer、ebox-display-buffer、 ebox-commit、ebox-buffer-update-report、 ebox-rerender-buffer-with-context、ebox-viewport-window-width、 ebox-call-with-render-burst、ebox-render-burst-begin、 ebox-render-burst-end；
• Candidate/identity：ebox-candidate-begin、ebox-candidate-replace、 ebox-candidate-replace-range-ref、ebox-candidate-replace-root、 ebox-candidate-replace-host-ref、ebox-candidate-patch-host-paint、 ebox-region-ids、ebox-region-resolve、ebox-region-update、 ebox-host-ref-bounds、ebox-host-ref-position；
• Selector：ebox-selector-parse、ebox-selector-match-node-p、 ebox-selector-query-all、ebox-selector-query-buffer、 ebox-selector-update-buffer、ebox-select-all、ebox-update-selector；
• 滚动：ebox-buffer-mode、ebox-scroll-map、ebox-scroll-down、 ebox-scroll-up、ebox-scroll-page-down、ebox-scroll-page-up、 ebox-wheel-scroll-down、ebox-wheel-scroll-up、ebox-scroll-state；
• 测量/构建：ebox-string-pixel-width、ebox-display-signature、 ebox-clear-cache、ebox-byte-compile、ebox-native-status、 ebox-native-build。

9. 验证

make load EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs
make compile EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs
make docs-contract-tests EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs
make dsl-tests EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs
make check EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs