From 40b43ac3c3407ef78785711c3cbf92284f907928 Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Thu, 12 Nov 2026 21:20:10 +0800 Subject: [PATCH] docs: clarify typed example callbacks and delegation contracts --- examples/constructor-contracts.endor | 1 + examples/field-contracts.endor | 1 + examples/method-contracts.endor | 3 ++- examples/native-signatures.endor | 4 ++-- examples/property-bindings.endor | 3 ++- examples/visual-protocols.endor | 1 + 6 files changed, 9 insertions(+), 4 deletions(-) diff --git a/examples/constructor-contracts.endor b/examples/constructor-contracts.endor index 4e59e27..299bd23 100644 --- a/examples/constructor-contracts.endor +++ b/examples/constructor-contracts.endor @@ -21,6 +21,7 @@ rect = TaggedRect(180, 60, "省略 radius/color 后的字段") // kind 是原生 Event 参数,第二个字符串才是 TaggedEvent 的源字段 tag。 event = TaggedEvent("click", "事件字段") // 前两个托管对象归入原生 ObjectList 成员,末尾字符串留给子类字段,不作为第三个列表成员。 +// TaggedList.tag 是该列表实例的业务字段;它既不改变 items.count,也不会参与 rect 的容器布局。 items = TaggedList(rect, event, "列表成员之后的字段") actions = Actions(rect) button = Button("调用原对象方法") diff --git a/examples/field-contracts.endor b/examples/field-contracts.endor index e2dcbd3..303993e 100644 --- a/examples/field-contracts.endor +++ b/examples/field-contracts.endor @@ -1,5 +1,6 @@ // 字段类型契约示例:CounterText 同时有原生文本载荷和源 Number 字段。 // 绑定显示读取该字段,GUI 回调与 Console 赋值受同一契约约束。 +// 不匹配的字段写入保留该字段旧值;这不表示整次回调或同一输入中较早的其他写入都会回滚。 // 增加 value:Number;构造时先传原生 text,再传源字段值。 class CounterText: TextBlock { // value 是源字段,不是 TextBlock 的原生 text;页面把两者作为不同内容分别展示。 diff --git a/examples/method-contracts.endor b/examples/method-contracts.endor index f6d95e4..54af72c 100644 --- a/examples/method-contracts.endor +++ b/examples/method-contracts.endor @@ -14,7 +14,8 @@ class BaseRect: RectBlock { class WideRect: BaseRect { // 调用基类后复制测量数值到新的 Sized;新结果仍满足 MeasureResult 协议。 function measure(self: WideRect, mount: Object, constraints: Object): Sized { - // 宿主布局驱动仍传入 Mount/Constraints;Object 注解只放宽覆盖签名,不改变实际输入对象。 + // 宿主布局驱动仍传入 Mount/Constraints;Object 注解只放宽本覆盖的参数检查,不改变实际输入对象。 + // 若手工传入其他 Object,下一行委托 BaseRect.measure 仍检查其较窄的 Mount/Constraints 契约,不保证调用成功。 measured = BaseRect.measure(self, mount, constraints) // 拷贝的是本轮测量结果的两个数值,不复制业务矩形或 Mount;返回新结果供宿主校验。 return Sized(measured.width, measured.height) diff --git a/examples/native-signatures.endor b/examples/native-signatures.endor index 9f8c30c..3f00e9f 100644 --- a/examples/native-signatures.endor +++ b/examples/native-signatures.endor @@ -1,4 +1,4 @@ -// 原生回调也发布 Function 签名:state.set 接收一个 Event,increment 接收零参数。 +// 原生回调也发布 Function 签名:state.set 接收一个任意值,increment 接收零参数;此处事件分发将 Event 作为 set 的那个值。 // 同一事件注册机制按实际签名调用;label 绑定再把事件 kind 转成可显示的字符串。 // 保留最后一次收到的 Event 对象,初值 kind=waiting;不是只存一份格式化事件文本。 received = ui.state(Event("waiting")) @@ -11,7 +11,7 @@ label = TextBlock("waiting") subscription = label.bind("text", eventKind) // subscription 管理字段绑定,下面两个 Connection 管理输入监听,两种注册的用途不同。 withEvent = Button("传递 Event 给原生 set") -// received.set 是一参数原生方法,分发器传入实际 click Event。 +// received.set 的参数并非专门限定为 Event;本次订阅按一参数签名调用,传入实际 click Event 并覆盖 received.value。 firstConnection = withEvent.on("click", received.set) // 保存的是绑定 count 的原生方法,事件分发按它的零参签名调用,无需人为包装一个丢弃 Event 的函数。 withoutEvent = Button("调用零参数原生 increment") diff --git a/examples/property-bindings.endor b/examples/property-bindings.endor index e7ee271..ead98a2 100644 --- a/examples/property-bindings.endor +++ b/examples/property-bindings.endor @@ -6,7 +6,7 @@ class Model { width: Number color: String label: String - // 返回 Number,目标 width 属性同时做类型/尺寸验证。 + // 绑定求值调用此零参 getter 并取得 Number;结果写入 rect.width,布局读取时仍须符合有限尺寸范围。 function getWidth(self: Model): Number { return self.width } // 返回颜色文本;依赖只包含实际读取的模型属性。 function getColor(self: Model): String { return self.color } @@ -33,6 +33,7 @@ button = Button("更新宽度、颜色和文字") clickConnection = button.on("click", model.expand) root = Column(24, 16, label, rect, button) // 两个页面共享 root 及其子对象,因此只有一组属性绑定,不需要为每个 Mount 再注册一组。 +// 两页同属一个窗口,本例最终仅激活第一页;同时跨窗口显示的传播由宿主测试另外覆盖。 page = Page() page.title = "通用属性绑定" page.render(root) diff --git a/examples/visual-protocols.endor b/examples/visual-protocols.endor index 0a5de36..218ea03 100644 --- a/examples/visual-protocols.endor +++ b/examples/visual-protocols.endor @@ -3,6 +3,7 @@ // 把协议探测结果保存到普通业务字段,textOf 将其中一部分显示出来。 class VisualResults { // width/height 来自测量返回值,childX/childY 来自安排返回值,color 来自新绘制命令;都不是最终 Mount 的几何快照。 + // 只在 onMount 探测时覆盖这些值,未建立对所有后续协议调用的自动镜像或响应式绑定。 width: Number height: Number childX: Number