docs: clarify typed example callbacks and delegation contracts

This commit is contained in:
2026-11-12 21:20:10 +08:00
parent c3e7d01c09
commit 40b43ac3c3
6 changed files with 9 additions and 4 deletions
+1
View File
@@ -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("调用原对象方法")
+1
View File
@@ -1,5 +1,6 @@
// 字段类型契约示例:CounterText 同时有原生文本载荷和源 Number 字段。
// 绑定显示读取该字段,GUI 回调与 Console 赋值受同一契约约束。
// 不匹配的字段写入保留该字段旧值;这不表示整次回调或同一输入中较早的其他写入都会回滚。
// 增加 value:Number;构造时先传原生 text,再传源字段值。
class CounterText: TextBlock {
// value 是源字段,不是 TextBlock 的原生 text;页面把两者作为不同内容分别展示。
+2 -1
View File
@@ -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)
+2 -2
View File
@@ -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")
+2 -1
View File
@@ -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)
+1
View File
@@ -3,6 +3,7 @@
// 把协议探测结果保存到普通业务字段,textOf 将其中一部分显示出来。
class VisualResults {
// width/height 来自测量返回值,childX/childY 来自安排返回值,color 来自新绘制命令;都不是最终 Mount 的几何快照。
// 只在 onMount 探测时覆盖这些值,未建立对所有后续协议调用的自动镜像或响应式绑定。
width: Number
height: Number
childX: Number