docs: define interpreted runtime and typed resource presentation
This commit is contained in:
@@ -11,8 +11,9 @@ Endorphin 应用由相互引用的声明组成：
|
||||
| 声明 | 描述的内容 | 典型用途 |
|
||||
| --- | --- | --- |
|
||||
| 类 | 数据结构与字段类型 | 前后端共同理解商品数据 |
|
||||
| 函数 | 输入、计算和输出 | 计算价格、组合业务步骤 |
|
||||
| 场景 | 界面与渲染树 | 展示文本和排列界面元素 |
|
||||
| 函数 | 输入、计算和输出 | 计算价格、组合业务步骤、返回界面值 |
|
||||
|
||||
客户端可以查看获准访问的资源，并按资源或函数结果的类型呈现内容。界面使用普通函数返回可渲染值表达，具体访问行为见[资源访问与呈现](11-resource-access-and-presentation.md)。
|
||||
|
||||
Agent 是后续扩展的应用领域；其声明与行为语法尚未定义，见[应用领域](../appendices/application-domains.md)。
|
||||
|
||||
@@ -50,8 +51,10 @@ discountedPrice(100, 10) → 90
|
||||
|
||||
Endorphin 将程序处理划分为两个阶段：
|
||||
|
||||
- **Preflight**：理解声明与引用，检查名称、类型和程序结构，准备执行。
|
||||
- **inflight**：使用实际输入执行逻辑，交付结果，并产生界面或其他业务效果。
|
||||
- **Preflight**：理解声明与引用，检查名称、类型和程序结构，建立关联索引，准备执行。
|
||||
- **inflight**：使用实际输入解释执行逻辑，交付结果，并产生界面或其他业务效果。
|
||||
|
||||
平台承担代码的解释执行；程序处理不要求开发者先完成独立构建，也不要求字节码转译。完整阶段职责见[Preflight 与 inflight](05-preflight-and-inflight.md)。
|
||||
|
||||
阶段与前端、后端是不同概念。前端界面与后端逻辑都可以经过 Preflight，并在 inflight 中产生效果。namespace 的路径名称不决定阶段或执行位置。
|
||||
|
||||
|
||||
@@ -42,7 +42,7 @@ alice:shop.ui
|
||||
|
||||
用户身份通过代码之外的 key 与索引成员关系关联。读取、编辑和处理代码时，系统使用该归属上下文。
|
||||
|
||||
场景名、变量名、注释、字符串和存储对象名均不定义归属用户。两段内容相同的代码分别关联不同用户时，其归属上下文仍然不同。
|
||||
函数名、变量名、注释、字符串和存储对象名均不定义归属用户。两段内容相同的代码分别关联不同用户时，其归属上下文仍然不同。
|
||||
|
||||
正文中的 `use alice:shop.pricing` 表示引用目标，不表示当前代码属于 alice。例如，`bob:shop.checkout` 可以引用 alice 的逻辑，其自身归属仍是 bob。
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
|
||||
```text
|
||||
零个或多个 use 声明
|
||||
一个或多个 class、function 或 export scene 声明
|
||||
一个或多个 class 或 function 声明
|
||||
```
|
||||
|
||||
声明之间不使用逗号或分号。正文不含自身 namespace 声明，其归属来自外部 key 与索引。
|
||||
@@ -42,9 +42,9 @@ function listedPrice(product: Product): Int {
|
||||
}
|
||||
```
|
||||
|
||||
同一视图可以同时包含类和函数，也可以包含场景。类与函数不需要依附 UI 场景；只有业务逻辑的 namespace 无需声明 render。
|
||||
同一视图可以同时包含类和函数。界面逻辑通过普通函数及其结果表达，与业务逻辑共用声明和表达式规则。
|
||||
|
||||
类、函数和场景的内部结构分别在[类型与类](07-types-and-classes.md)、[函数与调用](09-functions-and-calls.md)和[场景与渲染树](11-scenes-and-render-trees.md)中定义。
|
||||
类与函数的内部结构分别在[类型与类](07-types-and-classes.md)和[函数与调用](09-functions-and-calls.md)中定义。查看资源和呈现界面结果见[资源访问与呈现](11-resource-access-and-presentation.md)。
|
||||
|
||||
## 4.4 名称引用
|
||||
|
||||
@@ -56,10 +56,10 @@ function listedPrice(product: Product): Int {
|
||||
|
||||
本书区分三类示例：
|
||||
|
||||
- 声明示例：展示可以出现在代码视图中的类、函数或场景。
|
||||
- 声明示例：展示可以出现在代码视图中的类或函数。
|
||||
- 函数体片段：展示 let、return 或局部表达式。
|
||||
- 渲染节点片段：展示 render 内的组件树。
|
||||
- 结构与访问示意：展示界面组成或资源访问行为，不表示源码。
|
||||
|
||||
局部片段用于查询语法，不自动成为程序顶层入口。入口选择、空视图与多个场景的选择规则仍列于[规范状态](../appendices/specification-status.md#声明与类型)。
|
||||
局部片段用于查询语法，不自动成为程序顶层入口。入口选择、空视图与定位形式仍列于[规范状态](../appendices/specification-status.md#声明与类型)。
|
||||
|
||||
[上一章：namespace](03-namespaces.md) · [下一章：Preflight 与 inflight](05-preflight-and-inflight.md) · [目录](../README.md)
|
||||
|
||||
@@ -1,17 +1,19 @@
|
||||
# 5. Preflight 与 inflight
|
||||
|
||||
Endorphin 将构建阶段称为 **Preflight**，将运行阶段称为 **inflight**。这两个名称表示程序处理职责，不是源码关键字。
|
||||
Endorphin 将执行准备与检查阶段称为 **Preflight**，将运行阶段称为 **inflight**。这两个名称表示程序处理职责，不是源码关键字。
|
||||
|
||||
代码由平台解释执行，不要求开发者先执行独立构建步骤，也不要求将源码转换成字节码或另一种语言。Preflight 的检查与索引准备不等同于生成编译产物。
|
||||
|
||||
## 5.1 Preflight
|
||||
|
||||
Preflight 读取代码视图及其归属上下文，理解声明和引用，为程序执行做好准备。
|
||||
Preflight 读取代码视图及其归属上下文，理解声明和引用，并建立关联索引，为程序执行做好准备。索引用于查找相关声明与依赖，减少实际调用时重复的解析和查找工作。
|
||||
|
||||
其语言职责包括：
|
||||
|
||||
- 按词法和语法规则理解类、函数、场景与表达式。
|
||||
- 按词法和语法规则理解类、函数与表达式。
|
||||
- 解析 use 指向的 namespace 及允许使用的声明。
|
||||
- 检查名称、字段、参数与返回类型。
|
||||
- 检查场景结构及组件用法。
|
||||
- 依据已定义的规则检查结果类型与组件用法。
|
||||
- 识别逻辑调用与结果使用之间的依赖。
|
||||
- 报告可以静态确定的错误。
|
||||
|
||||
@@ -27,7 +29,7 @@ inflight 使用实际输入执行程序，产生程序可以观察到的结果
|
||||
- 取得调用所请求的数据。
|
||||
- 向后续表达式提供成功结果。
|
||||
- 保持代码定义的数据依赖与业务效果。
|
||||
- 根据场景和程序结果产生 UI。
|
||||
- 解释执行实际调用，并根据资源或结果类型产生界面等呈现效果。
|
||||
- 表达执行中出现的失败或其他结果状态。
|
||||
|
||||
通信、缓存和执行组织方式可以由系统安排，但必须保持语言定义的值、类型、依赖和效果。
|
||||
@@ -40,9 +42,9 @@ inflight 使用实际输入执行程序，产生程序可以观察到的结果
|
||||
| function 声明 | 检查参数、函数体与返回类型 | 调用发生时执行逻辑 |
|
||||
| use 声明 | 理解依赖并解析可用声明 | 在调用中使用相应逻辑 |
|
||||
| 调用表达式 | 检查目标与输入类型 | 使用实际输入并取得结果 |
|
||||
| 场景声明 | 检查渲染树与组件约束 | 呈现内容和排列关系 |
|
||||
| 界面结果 | 依据已定义的类型与组件规则检查用法 | 取得可渲染值后呈现内容和排列关系 |
|
||||
|
||||
实际业务调用属于 inflight。Preflight 的准备与检查不改变调用发生时应有的语义；若引入构建阶段求值，需要另外定义相应规则。
|
||||
实际业务调用属于 inflight。Preflight 的准备与检查不执行业务调用，也不改变调用发生时应有的语义。代码加载和检查的时机可以由平台安排；对无法提前确定的依赖和结果，执行时仍须遵守相应规则。
|
||||
|
||||
## 5.4 诊断与执行失败
|
||||
|
||||
|
||||
@@ -28,8 +28,6 @@ namespace 路径段使用标识符。用户名属于系统身份规则，不直
|
||||
| `function` | 声明函数 |
|
||||
| `let` | 绑定局部结果 |
|
||||
| `return` | 返回函数结果 |
|
||||
| `export`、`scene` | 声明导出的 UI 场景 |
|
||||
| `render` | 定义场景的渲染树 |
|
||||
|
||||
这些关键字在相应产生式的位置出现。完整保留字集合见[规范状态](../appendices/specification-status.md#词法与表达式)。
|
||||
|
||||
@@ -82,15 +80,15 @@ namespace 路径段使用标识符。用户名属于系统身份规则，不直
|
||||
|
||||
| 字符 | 用途 |
|
||||
| --- | --- |
|
||||
| `{`、`}` | 声明体、函数体和子节点块 |
|
||||
| `{`、`}` | 声明体与函数体 |
|
||||
| `(`、`)` | 参数、调用和表达式分组 |
|
||||
| `:` | key 分隔、类型标注和命名参数 |
|
||||
| `:` | key 分隔与类型标注 |
|
||||
| `,` | 分隔参数 |
|
||||
| `.` | namespace 层级、成员访问和符号前缀 |
|
||||
| `=` | let 绑定 |
|
||||
| `+`、`-`、`*`、`/` | 算术运算 |
|
||||
|
||||
冒号的含义由语法位置确定：`alice:shop.data` 中分隔用户与路径，`price: Int` 中标注类型，`gap: 12` 中指定参数名。
|
||||
冒号的含义由语法位置确定：`alice:shop.data` 中分隔用户与路径，`price: Int` 中标注类型。组件参数的源码传入方式尚未定义，见[规范状态](../appendices/specification-status.md#ui)。
|
||||
|
||||
## 6.7 空白与注释
|
||||
|
||||
|
||||
@@ -17,7 +17,7 @@ name: String
|
||||
| --- | --- |
|
||||
| `Int` | 整数 |
|
||||
| `String` | 字符串 |
|
||||
| 用户声明的类名 | 具有该类字段结构的数据 |
|
||||
| 用户声明的类名 | 属于该声明类型并满足字段约束的数据 |
|
||||
|
||||
数值范围、其他基础类型、可选类型和转换规则尚未构成完整类型体系，范围见[规范状态](../appendices/specification-status.md#声明与类型)。
|
||||
|
||||
@@ -38,7 +38,7 @@ class Product {
|
||||
|
||||
## 7.3 类型与值
|
||||
|
||||
`Product` 表示数据的类型；符合 Product 结构的某个值，才包含本次业务数据。
|
||||
`Product` 表示一个声明的类型；具有 Product 类型并满足其字段约束的值，才包含本次业务数据。仅有相同字段不自动使其他类型的值成为 Product。
|
||||
|
||||
类声明本身不取得某件商品，也不指定数据库、表或连接。通过类型取得数据的用法在[数据读取](10-data-access.md)中说明；构造、方法与默认值属于独立的类型规则。
|
||||
|
||||
@@ -57,8 +57,34 @@ let price = product.price
|
||||
|
||||
## 7.5 类型检查与共享
|
||||
|
||||
Preflight 理解类和字段声明，检查字段访问、函数参数与返回值的类型关系。inflight 中取得和使用的数据必须遵守对应结构。
|
||||
Preflight 理解类和字段声明，检查字段访问、函数参数与返回值的类型关系。inflight 中取得和使用的数据必须符合对应类型及字段约束。
|
||||
|
||||
跨 namespace 引用类时，引用的是定义该结构的声明，不改变调用方代码的归属。声明是否可访问取决于可见性和权限规则，见[程序结构与导入](04-program-structure.md)。
|
||||
|
||||
## 7.6 类型身份与兼容
|
||||
|
||||
Endorphin 不采用仅依据成员结构判断兼容的结构类型规则。用户声明的类型按其声明身份区分；字段或方法相同，不自动建立类型兼容或能力实现关系。
|
||||
|
||||
类型声明通过所属 namespace 与声明定位。引用同一个声明不创建新类型；不同声明不能仅凭名称或成员相同被认定为同一类型。
|
||||
|
||||
代码归属：`alice:shop.data`。沿用本章 Product 声明，并增加以下类声明：
|
||||
|
||||
```endorphin
|
||||
class ListedProduct {
|
||||
name: String
|
||||
price: Int
|
||||
}
|
||||
```
|
||||
|
||||
Product 与 ListedProduct 都有 name 和 price，但它们是不同的类型。本例没有建立继承、转换或其他兼容关系，因此 ListedProduct 值不能自动作为 Product 参数使用。
|
||||
|
||||
```text
|
||||
Product 值 → 接收 Product 的参数：类型符合要求
|
||||
ListedProduct 值 → 接收 Product 的参数：不能仅凭字段相同通过检查
|
||||
```
|
||||
|
||||
构造某个声明类型的值时仍须检查字段及其类型；这类检查不等于允许不同类型按结构互换。类型推断也不要求结构兼容，具体推断规则仍待定义。
|
||||
|
||||
继承、接口或协议关系、显式能力实现及类型转换的规则另行定义，见[规范状态](../appendices/specification-status.md#声明与类型)。本节不增加相应关键字或写法。
|
||||
|
||||
[上一章：词法结构](06-lexical-structure.md) · [下一章：表达式与绑定](08-expressions-and-bindings.md) · [目录](../README.md)
|
||||
|
||||
@@ -87,4 +87,12 @@ inflight 使用实际参数执行函数，并把成功结果交给调用表达
|
||||
|
||||
函数不默认被视为纯计算。对带业务修改效果的调用，系统不能为了执行组织而任意重复或并行执行；相关顺序、失败和取消语义见[规范状态](../appendices/specification-status.md#调用与数据)。
|
||||
|
||||
## 9.7 函数查看与结果呈现
|
||||
|
||||
客户端可以将函数本身作为资源查看，也可以在输入满足要求后调用函数。查看定义不会取得函数返回值；调用成功后，结果才可按类型呈现或供后续计算使用。
|
||||
|
||||
界面逻辑使用同样的 function、表达式与 return 规则。可渲染结果的正式类型和构造形式尚未定义；本章普通函数示例不因此获得专用 UI 语法。
|
||||
|
||||
参数未就绪、调用等待和结果呈现的主要规则见[资源访问与呈现](11-resource-access-and-presentation.md)。源码中缺少必填参数的调用与客户端查看函数定义属于不同情况。
|
||||
|
||||
[上一章：表达式与绑定](08-expressions-and-bindings.md) · [下一章：数据读取](10-data-access.md) · [目录](../README.md)
|
||||
|
||||
@@ -59,8 +59,8 @@ Preflight 理解结构、引用和成员调用的类型关系，inflight 取得
|
||||
|
||||
本节 get 提案按一次读取说明。持续跟随数据变化与一次读取具有不同的可观察行为；是否使用不同表达式或结果类型仍未定义。
|
||||
|
||||
UI 可以使用成功取得的字段展示内容，但加载、缺失、失败与后续更新需要对应的界面语义。正文不将未定义的数据绑定或读取调用直接混入 render 示例。
|
||||
UI 可以直接使用成功取得的类型化字段展示内容，跨端通信由平台承担，不要求应用自行解析响应或恢复对象类型。加载、缺失、失败与后续更新仍需要对应的可观察状态；具体访问和呈现关系见[资源访问与呈现](11-resource-access-and-presentation.md)。
|
||||
|
||||
数据读取的协议、缓存和后端绑定不影响上述源码目标，也不在本章选择。
|
||||
|
||||
[上一章：函数与调用](09-functions-and-calls.md) · [下一章：场景与渲染树](11-scenes-and-render-trees.md) · [目录](../README.md)
|
||||
[上一章：函数与调用](09-functions-and-calls.md) · [下一章：资源访问与呈现](11-resource-access-and-presentation.md) · [目录](../README.md)
|
||||
|
||||
@@ -0,0 +1,105 @@
|
||||
# 11. 资源访问与呈现
|
||||
|
||||
客户端是 Endorphin 资源的查看与运行环境。它可以访问获准查看的 namespace、函数、类和结果值，并根据当前资源的类型及访问状态选择呈现方式。
|
||||
|
||||
界面由普通函数返回的可渲染值表达，不使用独立的 scene 声明或 render 块。本章定义资源定位、函数查看、调用与结果呈现之间的关系；顶级类型及其契约仍待定义，见[规范状态](../appendices/specification-status.md#资源访问与呈现)。
|
||||
|
||||
## 11.1 资源定位与访问
|
||||
|
||||
namespace key 定位代码归属及检索范围，函数名或类名选择其中的声明。定位声明、查看定义与发起调用是不同的访问行为。
|
||||
|
||||
```text
|
||||
namespace：alice:shop.pricing
|
||||
声明：discountedPrice
|
||||
|
||||
namespace：alice:shop.data
|
||||
声明：Product
|
||||
```
|
||||
|
||||
该示意没有定义 URL、请求协议或新的源码限定名语法。具体名称查找遵守[程序结构与导入](04-program-structure.md)的可见性规则。
|
||||
|
||||
| 访问对象 | 当前资源的含义 | 呈现或使用方式 |
|
||||
| --- | --- | --- |
|
||||
| namespace | 获准访问的逻辑代码集合 | 查看代码视图及其成员 |
|
||||
| 函数定义 | 参数、返回类型与函数体 | 查看定义，或准备相应调用 |
|
||||
| 类定义 | 类型及其结构 | 查看类型定义，不自动取得业务对象 |
|
||||
| 函数调用结果 | 本次执行产生的值 | 按结果类型呈现，或供后续程序使用 |
|
||||
|
||||
查看 namespace 不表示执行其中全部函数，也不保证包含全部下级 namespace。查看定义的权限与调用权限分别适用；代码定位本身不授予权限。
|
||||
|
||||
## 11.2 函数本身与返回值
|
||||
|
||||
函数本身具有可调用的类型，调用完成后取得的值具有结果类型。二者不能混同；尚未调用时，返回类型描述结果约束，不表示结果已经存在。
|
||||
|
||||
以下示例使用[函数与调用](09-functions-and-calls.md)中的声明，假定 discountedPrice 可查看且可调用：
|
||||
|
||||
```text
|
||||
查看 alice:shop.pricing 中的 discountedPrice
|
||||
→ 取得函数定义
|
||||
|
||||
提供 price = 100、discount = 10 并调用
|
||||
→ 取得结果 90
|
||||
```
|
||||
|
||||
前一种访问查看函数本身，后一种访问处理整数结果。函数没有因为参数未填写而改变类型。
|
||||
|
||||
## 11.3 参数就绪与调用状态
|
||||
|
||||
客户端访问函数时，如果必要输入尚未提供，应保留对函数本身的查看，可以展示函数签名及获准查看的源码。输入满足调用要求后，可以发起调用，并根据实际返回值选择呈现方式。
|
||||
|
||||
此处未填写的输入指调用前尚未绑定的必填参数，不指函数体中的局部变量。默认参数、可省略参数和平台提供参数的具体规则尚未定义。
|
||||
|
||||
这一访问行为不改变普通调用表达式的参数检查：业务源码中缺少必填参数的调用仍应得到诊断，不能静默转换成源码查看。
|
||||
|
||||
| 状态 | 客户端当前处理的内容 |
|
||||
| --- | --- |
|
||||
| 必填参数尚未就绪 | 函数本身，不执行尚不满足输入要求的调用 |
|
||||
| 调用已开始，结果未就绪 | 本次调用的等待状态，或已经可用的部分界面 |
|
||||
| 调用成功 | 符合声明的结果值，按其类型处理 |
|
||||
| 调用失败 | 本次执行失败，不伪造成功结果 |
|
||||
|
||||
等待后端结果不等于缺少调用参数，不能因此退回为函数源码展示。具体参数填写界面和状态呈现形式仍待定义。
|
||||
|
||||
## 11.4 普通函数与界面结果
|
||||
|
||||
函数使用普通参数、表达式、调用与 return 表达界面逻辑。客户端取得可渲染类型的结果后渲染界面；其他结果依据相应类型的呈现约定处理。界面构造表达式与可渲染类型的正式名称尚未定义，本章不引入占位类型或专用 UI 文法。
|
||||
|
||||
下面是访问行为示意，不是源码。假定 `bob:shop.ui` 中存在可访问的 productPage，接收一个商品编号，并返回可渲染值：
|
||||
|
||||
```text
|
||||
打开 productPage，尚未提供商品编号
|
||||
→ 查看函数定义
|
||||
|
||||
提供商品编号 p1001 并调用 productPage
|
||||
→ 取得该商品的界面值
|
||||
→ 客户端渲染界面
|
||||
```
|
||||
|
||||
函数内部产生的界面值也可以交给其他函数组合或使用。这里的自动呈现针对客户端当前打开的资源或调用结果，不要求每个中间结果都显示到屏幕上。
|
||||
|
||||
返回类型约束结果的用途，不单独决定函数的执行位置。普通业务函数、界面函数和类型声明共用 namespace 的组织方式。
|
||||
|
||||
## 11.5 跨端调用与持续更新
|
||||
|
||||
前端通过函数调用请求结果，通过 hook 关联持续更新。hook 表示触发或订阅关系，可用于界面、后端逻辑及其他数据同步用途；其源码形式与生命周期边界尚未定义。
|
||||
|
||||
系统依据调用依赖与 hook 关系组织相关执行，包括需要在后端解释执行的逻辑，并将结果交给前端使用。前后端的通信由平台承担；应用代码直接使用符合声明类型的值，不要求自行解析传输响应或恢复业务对象类型。
|
||||
|
||||
```text
|
||||
客户端执行界面逻辑
|
||||
→ 调用数据函数或建立 hook 关联
|
||||
→ 系统组织后端执行并交付结果
|
||||
→ 客户端使用结果或后续更新，调整界面
|
||||
```
|
||||
|
||||
一次调用与持续结果的区别见[数据读取](10-data-access.md#105-一次读取与持续结果)。自动更新的范围、业务修改的重复执行规则及取消行为仍待定义；依赖关系不自动授权系统重复执行所有相关函数。
|
||||
|
||||
## 11.6 按类型呈现的边界
|
||||
|
||||
按资源类型选择处理方式是客户端的呈现方向。顶级类型的名称、集合、继承或协议关系，以及不同类型对应的展示契约，统一保留在[规范状态](../appendices/specification-status.md#资源访问与呈现)中。
|
||||
|
||||
平台不能仅凭对象字段或方法的结构认定其属于可渲染类型或实现了展示能力。类型身份与兼容规则见[类型与类](07-types-and-classes.md#76-类型身份与兼容)；具体展示能力关系仍待定义。
|
||||
|
||||
本章不规定普通对象必须继承界面类型，也不指定数据查看器、媒体播放器或代码查看器的实现。官方 UI 组件的现有效果提案见[UI 组件](12-ui-components.md)。
|
||||
|
||||
[上一章：数据读取](10-data-access.md) · [下一章：UI 组件](12-ui-components.md) · [目录](../README.md)
|
||||
@@ -1,101 +0,0 @@
|
||||
# 11. 场景与渲染树
|
||||
|
||||
场景声明描述一个 UI 视图。render 块包含该视图的渲染树，树中的节点表示组件、参数和子节点。
|
||||
|
||||
## 11.1 场景声明
|
||||
|
||||
代码归属：`bob:shop.ui`。
|
||||
|
||||
```endorphin
|
||||
export scene Main {
|
||||
render {
|
||||
Column(gap: 12, padding: 24) {
|
||||
Text("Shop", role: .title)
|
||||
Row(gap: 8) {
|
||||
Text("Price")
|
||||
Spacer(size: 4)
|
||||
Text("90")
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Main 是场景名。Column 是根节点，包含一个标题和一个横向排列的 Row。
|
||||
|
||||
本章使用[UI 组件](12-ui-components.md)中的官方组件。官方库的 key 和引用形式未定义，示例仅省略这一依赖部分，不表示官方组件属于任何示例用户库或必然免导入可用。
|
||||
|
||||
## 11.2 render 与单根结构
|
||||
|
||||
本文场景文法要求一个场景包含一个 render 块，render 中恰好包含一个根节点。
|
||||
|
||||
多个同级节点放入同一个布局根节点。下面是 render 内的有效节点片段：
|
||||
|
||||
```endorphin
|
||||
Column {
|
||||
Text("First")
|
||||
Text("Second")
|
||||
}
|
||||
```
|
||||
|
||||
两个 Text 是 Column 的子节点，不是两个 render 根节点。单根规则仅约束 render 内部，不限制 namespace 只能有一个声明。
|
||||
|
||||
## 11.3 节点形式
|
||||
|
||||
节点包含组件名、可选参数列表和可选子节点块：
|
||||
|
||||
```text
|
||||
组件名
|
||||
组件名(参数列表)
|
||||
组件名(参数列表) { 子节点 }
|
||||
```
|
||||
|
||||
组件名是标识符。省略参数列表与空参数列表都表示没有显式参数；默认值由组件约定决定。
|
||||
|
||||
渲染节点片段：
|
||||
|
||||
```endorphin
|
||||
Column {}
|
||||
Spacer(size: 16)
|
||||
Text("Product")
|
||||
```
|
||||
|
||||
这三行分别展示空容器、带命名参数的节点和带位置参数的节点，不是一个具有三个根的完整 render 块。
|
||||
|
||||
## 11.4 参数
|
||||
|
||||
位置参数按参数位置表达输入，命名参数用 `参数名: 表达式`：
|
||||
|
||||
```endorphin
|
||||
Text("Product", role: .title)
|
||||
```
|
||||
|
||||
字符串为第一个位置参数，role 为命名参数。参数按逗号分隔，不使用尾随逗号。命名参数与位置参数可以在节点形式中共存，具体绑定与重复传参规则见[规范状态](../appendices/specification-status.md#ui)。
|
||||
|
||||
参数引用通用表达式文法，但 render 中允许哪些调用、状态读取和修改效果，需要另外规定；文法可以表达一种形式不等于该形式在所有渲染上下文中合法。
|
||||
|
||||
## 11.5 子节点与嵌套
|
||||
|
||||
子节点由花括号包围，相邻节点不使用逗号或分号。布局组件可以递归嵌套：
|
||||
|
||||
```endorphin
|
||||
Column(gap: 12) {
|
||||
Text("Shop", role: .title)
|
||||
Row(gap: 8) {
|
||||
Text("Left")
|
||||
Text("Right")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Column 从上到下排列标题与 Row，Row 从左到右排列两段文本。结构文法允许子节点块，组件语义决定具体组件是否接受子节点；Text 和 Spacer 的用法不接受子节点。
|
||||
|
||||
## 11.6 检查与展示
|
||||
|
||||
Preflight 检查场景结构、单根约束、组件名称、参数和子节点是否合法。不合法节点或参数应得到诊断，而不是静默替换为别的组件或默认参数。
|
||||
|
||||
inflight 展示声明的内容与排列关系。渲染树不指定绘制协议、字体引擎或某个布局计算必须发生在哪一阶段。
|
||||
|
||||
数据绑定、事件、加载状态和界面更新的具体语法见[规范状态](../appendices/specification-status.md#ui)。
|
||||
|
||||
[上一章：数据读取](10-data-access.md) · [下一章：UI 组件](12-ui-components.md) · [目录](../README.md)
|
||||
+18
-20
@@ -1,18 +1,17 @@
|
||||
# 12. UI 组件
|
||||
|
||||
本章是官方基础组件的用法参考，定义本文 UI 草案中的参数、默认值和展示效果。示例是 `bob:shop.ui` 场景 render 内的节点片段。
|
||||
本章保留官方基础组件的参数、默认值和展示效果提案。组件用于组成普通函数返回的界面值，资源与结果的呈现方式见[资源访问与呈现](11-resource-access-and-presentation.md)。
|
||||
|
||||
官方库的 key 和引用形式尚未定义，来源约定见[场景与渲染树](11-scenes-and-render-trees.md)。用户库提供的组件则以其实际声明为准。
|
||||
官方库的 key、引用形式、组件构造表达式和界面类型尚未定义。本章示例是 `bob:shop.ui` 的界面结构示意，不是源码，也不表示官方组件属于该用户库或必然免导入可用。用户库提供的组件以其实际声明为准。
|
||||
|
||||
## 12.1 Column
|
||||
|
||||
Column 从上到下排列子节点。
|
||||
|
||||
```endorphin
|
||||
Column(gap: 12, padding: 24) {
|
||||
Text("First")
|
||||
Text("Second")
|
||||
}
|
||||
```text
|
||||
Column：gap 为 12，padding 为 24
|
||||
Text：内容为 First
|
||||
Text：内容为 Second
|
||||
```
|
||||
|
||||
| 参数 | 值类型 | 默认值 | 含义 |
|
||||
@@ -28,11 +27,10 @@ Column(gap: 12, padding: 24) {
|
||||
|
||||
Row 从左到右排列子节点。
|
||||
|
||||
```endorphin
|
||||
Row(gap: 8, padding: 4) {
|
||||
Text("Left")
|
||||
Text("Right")
|
||||
}
|
||||
```text
|
||||
Row：gap 为 8，padding 为 4
|
||||
Text：内容为 Left
|
||||
Text：内容为 Right
|
||||
```
|
||||
|
||||
| 参数 | 值类型 | 默认值 | 含义 |
|
||||
@@ -48,8 +46,8 @@ Row(gap: 8, padding: 4) {
|
||||
|
||||
Spacer 占据布局空间，不显示可见内容。
|
||||
|
||||
```endorphin
|
||||
Spacer(size: 16)
|
||||
```text
|
||||
Spacer：size 为 16
|
||||
```
|
||||
|
||||
| 参数 | 值类型 | 默认值 | 含义 |
|
||||
@@ -64,14 +62,14 @@ Spacer(size: 16)
|
||||
|
||||
Text 显示字符串内容。
|
||||
|
||||
```endorphin
|
||||
Text("Product")
|
||||
Text("Shop", role: .title)
|
||||
```text
|
||||
Text：内容为 Product
|
||||
Text：内容为 Shop，role 为 .title
|
||||
```
|
||||
|
||||
| 参数 | 值类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| 第一个位置参数 | 字符串 | `""` | 显示的文本 |
|
||||
| 文本内容 | 字符串 | `""` | 显示的文本；正式参数名与传入方式待定 |
|
||||
| `role` | 符号值 | 普通文本角色 | `.title` 表示标题视觉角色 |
|
||||
|
||||
**子节点：** 不接受。
|
||||
@@ -82,8 +80,8 @@ Text("Shop", role: .title)
|
||||
|
||||
数字布局参数表达逻辑尺寸，本文不将其等同于设备像素。单位、数值范围、负数、显式尺寸、溢出、主题与文字测量规则列于[规范状态](../appendices/specification-status.md#ui)。
|
||||
|
||||
Preflight 检查组件名称、参数数量与类型、子节点约束；inflight 保持组件规定的内容和排列效果。未知参数、错误类型或不支持的子节点不能通过静默忽略获得有效语义。
|
||||
组件声明与构造规则确定后，Preflight 据此检查名称、输入类型和子节点约束；inflight 保持组件规定的内容和排列效果。未知参数、错误类型或不支持的子节点不能通过静默忽略获得有效语义。
|
||||
|
||||
本章组件参数与默认值属于 UI 提案，确定程度与其他语言主题一起记录在规范状态附录。
|
||||
|
||||
[上一章：场景与渲染树](11-scenes-and-render-trees.md) · [附录：形式文法](../appendices/formal-grammar.md) · [目录](../README.md)
|
||||
[上一章：资源访问与呈现](11-resource-access-and-presentation.md) · [附录：形式文法](../appendices/formal-grammar.md) · [目录](../README.md)
|
||||
|
||||
Reference in New Issue
Block a user