@ a2ui/ web core (韩语)
这个 @a2ui/web_core 软件包为 A2UI 框架提供状态管理、协议解析和计划生成。 它具有框架不可知性,为Angular,React等渲染器包提供基础引擎.
特征
- 协议处理:在所有支持的协议版本中执行 A2UI 规格消息验证和状态处理.
- 州管理层: 使用
@preact/signals-core。 。 。 . - 数据语句: 数据绑定、范围界定和职能评价以及依赖跟踪.
- 目录系统: 支持运行时验证和计划生成的组件和函数目录.
- Schema- Driven 代码生成: 从规格JSON schemas直接取自自自动生成的Zod schemas和TypeScript组件/函数定义.
建筑
渲染是由一个 SurfaceGroupModel 及其组成 SurfaceModel 实例 DataModel 管理反应状态, DataContext 提供表达评价 MessageProcessor 验证并应用收到的协议消息.
Schema 代码生成( C)
协议信件计划,常见类型和目录定义直接由 JSON 计划生成 specification/ 目录.
运行代码生成
重新生成所有 Zod 计划和目录 API :
# Generate all protocol Zod schemas and versioned Basic Catalog APIs
yarn generate-zod-schemas
# Or run individual version generators directly
node src/v0_9/scripts/generate-catalog.mjs
node src/v1_0/scripts/generate-catalog.mjs
Catalog Schema 合同
代码生成器使用 斯克马平板电脑 保留版本 目录 和类型不可知性 Schema文件坚持以下结构:
1. 目录JSONcatalog.json(中文(简体) )
- 顶级词典数字 :
components: 将组件名称映射到 JSON schema 对象.functions:将函数名称映射到 JSON schema 对象.
- 歧视者数字 :
- 衍生自
catalog.discriminator.propertyName(违约)"component") (中文(简体) ). - 歧视者的财产和
"id"在生成的属性计划中省略,因为它们是由运行时组件信封处理的.
- 衍生自
- 继承和内涵数字 :
- 可使用组件
allOf参考通用信封(例如:ComponentCommon或者说CatalogComponentCommon) (中文(简体) ). 生成器递归解决$ref指向并合并allOf枝入平地产袋.
- 可使用组件
- 职能数字 :
- 函数指定 a
returnType(例如:."string", (中文(简体) ),"number", (中文(简体) ),"boolean", (中文(简体) ),"validationResult")在根一级,并定义其中的参数args或者说parameters对象属性.
- 函数指定 a
2. 可重复使用的类型定义(common_types.json(中文(简体) )
$defs范围数字 :- 可再利用类型计划
$defs。定义名称没有硬编码;任何定义都存在于$defs可在引用时动态解决.
- 可再利用类型计划
- 参考说明数字 :
- 当组件属性引用时
$defs/<DefName>,生成器将它映射到<DefName>Schema并附有.describe('REF:#/$defs/<DefName>|<description>')注释. - 跑步时,
generateValidationSchema检查这些标记以发出$ref未使用的指针和树摇$defs定义.
- 当组件属性引用时
- 儿童参考资料数字 :
- 单身儿童参考书目和收集儿童资料时,应注明
$defs参考指标或说明表明儿童构成关系(例如提及ComponentId, (中文(简体) ),Child,或ChildList) (中文(简体) ).
- 单身儿童参考书目和收集儿童资料时,应注明
目录序列化
A 类 Catalog 有三个序列化切入点:
Catalog.fromJson(json, protocolVersion?, catalogId?)将目录文档装入目录模型。 每个条目都是JsonComponentApi或者说JsonFunctionApi其模型是其书面的JSON Schema定义jsonSchema));其佐德schema来源于关于第一使用的定义。 目录保留文档级别字段(元数据,命名为$defs,其他顶级密钥).protocolVersion,当给出时,优先于文档宣布的版本并选择加载规则,同时toJson仍然写文档的自己protocolVersion;没有它,文档的版本适用,那么DEFAULT_PROTOCOL_VERSION。 。 。 .catalogId替换文档本身的ID.catalog.toJson()从模型组装未分解的目录文档,计算anyComponent财务报告和审定财务报表anyFunction工会。 装入目录fromJson返回其文档时未修改(减去文档中遗漏的任何条目)anyComponent.oneOf或者说anyFunction.oneOf工会,其中fromJson装入时过滤). 在代码中定义的条目, Zod 计划用spec()在目录协议版本的布局中从模型中计算出它的定义; 代码中定义的任何其他条目都来自它的Zod schema. 计算结果为每个目录一次;每次呼叫返回一份新副本.catalog.validationSchema是用于验证有效载荷的自成一体的计划:常见类型和目录本身$defs捆绑到$defs和每个$ref当地。 每个目录计算一次;每个目录读出一份新副本.
import {Catalog} from '@a2ui/web_core';
const catalog = Catalog.fromJson(document);
const unchanged = catalog.toJson(); // deep-equals document
const schema = catalog.validationSchema; // bundled JSON Schema
这个 Catalog 构造器为 a CatalogOptions 对象作为其第五个参数 themeSchema,文档级字段(instructions, (中文(简体) ), schemaUri, (中文(简体) ), schemaId, (中文(简体) ), title, (中文(简体) ), description, (中文(简体) ), declaredProtocolVersion, (中文(简体) ), declaresCatalogId, (中文(简体) ), declaresComponents, (中文(简体) ), functionsLayout, (中文(简体) ), unions, (中文(简体) ), defs, (中文(简体) ), extensionFields这 toJson 发布,并且,对于代码定义的目录, commonTypesUri, (中文(简体) ), themeLocation 财务报告和审定财务报表 defModels。 。 。 . catalog.withEntries(components, functions) 返回具有相同字段和其他条目的目录,因为目录转换器需要.
catalog.derive(options) 返回自编号下新建目录,该目录由下列条目构建: catalog 和新来的。 单位 components 财务报告和审定财务报表 functions,一个名称保留该名称的条目,一个对象添加一个条目。 新目录没有保留源代码 $id,标题,描述或指示,因为基本目录的指示,例如,在其示例中标明其编号:
const chatCatalog = basicCatalog.derive({
catalogId: 'https://example.com/catalogs/chat.json',
components: ['Text', 'Image', 'Row', 'Column', 'Button', carousel],
functions: ['openUrl'],
instructions,
});
规格说明
spec(schema, annotation) 返回 Zod 的 schema 副本, 记录目录文件在 schema 本身之外所写的内容, 而无需更改验证 : mixins (常见类型,例如: 'ComponentCommon',则 specDef() 一个组件定义的模型 allOf, (中文(简体) ), closure (单位:千美元)additionalProperties 或者说 unevaluatedProperties, (中文(简体) ), required (会议顺序) required 清单), allOf (按照schema自己的方案,例如格式规则)和 keywords (例如: format) (中文(简体) ). specDef(name, schema) 命名文档中宣布的模型 $defs。描述来自 .describe(),以及来自 REF:#/$defs/<Name> 说明标记.
import {Catalog, spec, specDef} from '@a2ui/web_core/catalog';
import {z} from 'zod';
const Common = specDef('Common', z.object({weight: z.number().optional()}));
const Badge = {
name: 'Badge',
schema: spec(
z
.object({...Common.shape, label: z.string()})
.describe('A badge.')
.strict(),
{mixins: ['ComponentCommon', Common]},
),
};
// Badge's definition composes ComponentCommon and #/$defs/Common with allOf,
// and $defs.Common is computed from the Common model.
const document = new Catalog('https://example.com/badges', '0.9', [Badge]).toJson();
内置的基本目录是用这种方式来建造的. 它们的组件和功能是 Zod 模型,由已出版的目录文件生成 scripts/generate-catalog-schemas.mjs (v0.9和v1)和 src/v0_8/scripts/generate-catalog.mjs (v0.8),作为 yarn generate-zod-schemas对于每一个计划节点, 生成器预测 JSON Schema toJson 来源于它发出的Zod代码, 并用与公布的策略的区别来注释节点. toJson 每个基本目录从模型中计算其已公布的文档; 包中不保存文档副本.
发展
大楼
软件包使用 wireit 用于构建管弦乐 :
yarn build
测试
运行单元测试 :
yarn test
运行符合性测试套件 :
node tests/conformance/conformance_test.mjs
运行时间大小写 conformance/core/message_processor_scaling.yaml,它检查处理许多小信息中发出的表面需要与其大小成正比的时间。 时间取决于机器及其负荷,所以 yarn test 将这些案件排除在外:
yarn test:timing
格式化和 Linting
yarn format
yarn lint