从表达式解析到节点层a2ui/web_core 完整版本演进与技术拆解【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2uia2ui/web_core 是 A2UI 框架中负责核心逻辑、状态管理与协议处理的框架无关层它同时是 Angular、React、Lit 等具体渲染器实现的地基。本文以仓库中 renderers/web_core/CHANGELOG.md 为主线逐版本梳理从 0.8.3 到 0.10.7 的关键演进表达式解析器的硬化、Node 节点层的引入、响应式信号的抽象、安全修复、主题系统与基础目录Basic Catalog的 Web Component 化。读完本文你将掌握 web_core 的模块划分、每个版本的破坏性变更与迁移要点并能结合源码定位对应实现。一、包定位web_core 在 A2UI 渲染体系中的角色根据 renderers/web_core/README.mda2ui/web_core包含 A2UI 框架的核心逻辑、状态管理和协议处理被刻意设计为框架无关为 Angular、React、Lit 等具体渲染器提供基础。其核心能力包括协议处理实现 A2UI 规范v0.8 与 v0_9的消息处理与校验状态管理基于preact/signals-core的响应式数据模型DataContext带依赖追踪与自动更新的高级数据绑定和函数执行逻辑Catalog 系统组件与函数的可扩展注册表支持跨渲染器复用Schema 校验内置基于 Zod 的协议消息与组件属性校验。从 package.json 可以看到当前版本为0.10.7包的导出入口分为v0_8legacy与v0_9推荐两套并额外提供./v0_9/basic_catalog与./styles/*、./types/*、./data/*等子路径。依赖包括lit、preact/signals-core、zod、zod-to-json-schema与date-fns构建与测试均由wireit编排。二、Unreleased / 0.10.7表达式解析器硬化与节点层落地最新一批变更集中在两个方向让表达式解析行为跨实现严格一致以及为渲染层提供更健壮的组件树解析能力。2.1 数字字面量从 NaN 到 A2uiExpressionError此前诸如${1.2.3}这样的无效数字字面量会被交给Number()处理最终以NaN的形式静默传入渲染层。现在的行为改为解析器一旦遇到不符合语法的数字字面量直接抛出A2uiExpressionError。在 expression_parser.ts 中可以看到承载这一行为的语法定义/** * Digits, an optional decimal point, and optional further digits. * * Every client implementation accepts a trailing point (1.) today and none * accepts a second point (1.2.3), so the grammar is written to keep that. */ const NUMBER_LITERAL /^\d\.?\d*$/; export class ExpressionParser { /** The maximum allowed recursion depth for nested expressions to prevent stack overflows. */ public static readonly MAX_DEPTH 100;parseNumberLiteral会先用扫描器吞入数字与小数点再用NUMBER_LITERAL正则校验1、1.、1.2均合法而1.2.3、.5等会被拒绝。注释中特别强调接受1.这种带尾随小数点、拒绝第二个小数点这一行为是所有客户端实现共同遵守的语法被显式写入解析器而非继承平台行为从而保证 Dart、TypeScript 等各实现接受完全相同的字面量集合。2.2 嵌套深度保护不可达守卫的修复CHANGELOG 指出深度守卫此前不可达导致深度嵌套的插值或函数调用参数会不断递归直至栈溢出而不是抛出A2uiExpressionError。修复后parse()入口即检查depth MAX_DEPTHMAX_DEPTH 100关键的是parseExpressionInternal()在两条递归路径插值内嵌插值、函数调用参数本身是表达式上都执行深度检查保证守卫真正可达。2.3 共享一致性测试套件表达式解析器现在运行位于 conformance/core/expressions.yaml 的共享一致性测试与 Dart 客户端使用同一份用例。为此新增了js-yaml作为 devDependency 来读取该 YAML测试文件为 expression_parser.conformance.test.ts。这意味着语言行为字面量、路径、函数调用、插值不再由各实现各自为政而是由一份规范化的用例集统一约束。2.4 节点层Node LayerNodeResolver 与 ComponentNode这一版本引入了 web_core 最重要的架构新增——节点层。根据 node-resolver.ts 的类注释节点层的树引擎把 surface 的扁平组件映射转成以rootNode为根的一棵活的、已解析的ComponentNode树。子引用变为ComponentNode对象模板ChildList为每个数组项生成一个节点尚未到达的组件以占位节点出现并在原地升级当父节点不再引用某节点或 resolver 被销毁时该节点及其 binder、数据订阅全部被拆除。关键设计语义包括身份是父作用域的parent-scoped同一个组件 id 挂载在两个位置会产生两个节点删除其中一个位置不会影响另一个占位状态未到达的组件呈现为 placeholder 节点PLACEHOLDER_TYPE到达后原地升级错误上报去重dispatchOnce()保证无法解析的引用与循环引用在条件持续期间每个组件、数据路径组合只通过onError上报一次条件修复后再次引入会重新上报见 node-resolver.ts晚到模型事件迟到的模型事件会与当前模型状态对账子引用检测覆盖ChildList联合类型与普通组件 id 数组两种形态。节点层相关的其它细节还包括$ref在 inline-catalog capabilities 中即使设置了 per-usage description 也会被保留新增的componentId()/childList()辅助函数可在自定义描述时保持$ref不丢失GenericBinder在组件重复下发时复用 action 闭包保证 action 型属性保持引用同一性使下游的相等性检查感知不到变化Catalog与SurfaceModel接受函数类型的泛型参数默认为FunctionImplementation调用无实现的目录函数现在抛出A2uiExpressionError。2.5 导出整理与 API 稳定性A2uiLitElement.controller由属性改为只读 getter禁止外部重新赋值a2ui/web_core/v0_9/basic_catalog新入口点集中导出通用 Web Component 基础目录实现A2uiText、A2uiButton、A2uiTextField、A2uiRow、A2uiColumn、A2uiList、A2uiImage、A2uiIcon、A2uiVideo、A2uiAudioPlayer、A2uiCard、A2uiDivider、A2uiCheckBox、A2uiSlider、A2uiDateTimeInput、A2uiChoicePicker、A2uiTabs、A2uiModal以及basicCatalog见 basic_catalog/index.ts基类A2uiLitElement从a2ui/web_core/v0_9导出同时废弃了a2ui/web_core/v0_9下的injectBasicCatalogStyles、computeColorVariant、ColorVariantLightDarkOptions、ColorVariantHoverOptions导出消费方应改从a2ui/web_core/v0_9/basic_catalog导入v0_9/index.ts 中以deprecated标注ComponentIdSchema与ChildListSchema的子引用标记移入 schema 的 metadata使.describe()等重建 schema 的方法不再丢失该标记手写的REF:描述仍被识别。2.6 测试补全新增了对全部基础目录 Web Component 实现的单元测试覆盖对应 v0_9/basic_catalog/components/ 下每个组件的.test.ts文件并移除了基础目录 barrel 文件的通配导出改为显式导出。三、0.10.x 系列安全、信号抽象与破坏性变更3.1 0.10.6消息校验加固与原型污染防护组件属性 schema 校验MessageProcessor现在会针对目录 schema 校验组件属性阻止畸形组件 action 进入状态原型污染防护DataModel增加原型污染保护与安全属性查找非破坏性安全修复防止代理可控的路径写入污染Object.prototypev0.8 公共 API 新增导出A2uiMessageSchematsconfig.json开启inlineSources让 sourcemap 携带sourcesContent便于调试。3.2 0.10.5v0.9/v0.9.1 双版本兼容消息解析同时接受v0.9与v0.9.1版本A2uiClientCapabilities支持同时声明v0.9与v0.9.1两种版本能力便于渐进迁移。3.3 0.10.4JSON Pointer 与类型导出DataModel支持 RFC 6901 规范的 JSON Pointer 转义~0、~1v0.8 的UserAction以ClientEventUserAction之名从types.ts导出对应源码 client-event.ts。3.4 0.10.3可替换的信号实现新增setSignalImplementation函数允许把底层信号库整体换掉。实现位于 reactivity/signals.ts包内定义SignalImplementations接口signal、computed、effect、batchWrite、isSignal、getValue、setValue、peekValue八个函数默认实现委托给preact/signals-coresetSignalImplementation只保存函数引用忽略实现对象的其它属性变更。这让 web_core 的状态层能够被适配到不同的响应式环境。3.5 0.10.2openUrl 安全收紧openUrl现在拒绝除 HTTP/HTTPS 之外的任何协议 schema修复了 Agent 可能通过注入javascript:等 schema 执行任意脚本的安全问题。3.6 0.10.1基础目录函数的 locale 与严格化v0.9 基础目录函数pluralize、formatNumber、formatCurrency新增 locale 支持通过 catalog 级配置生效PluralizeApi的 schema 移除.passthrough()校验更严格为 v0.8 引入createDataValueSchema工厂函数可覆盖DataValueSchema中硬编码的递归深度修复formatString按规范用 JSON 序列化对象/数组而不是使用 JS 默认的字符串强制转换避免[object Object]。3.7 0.10.0破坏性变更——Icon.path 更名为 svgPath这是 0.10.x 中唯一标注BREAKING CHANGE的变更Icon组件的path属性更名为svgPath以解决与DataBindingType的类型冲突。同版本新增computeColorVariant辅助函数为基础目录组件生成明/暗/悬停色变体的 CSS 公式供各渲染器复用实现见 styles/default.ts。四、主题与设计令牌injectBasicCatalogStyles 与 computeColorVariant虽然injectBasicCatalogStyles与computeColorVariant在新版本中被要求改从basic_catalog子路径导入但它们的职责值得单独说明因为它们是跨渲染器共享设计令牌的机制。styles/default.ts 中的默认主题 CSS 遵循几个原则只用变量定义以便穿透组件的 shadow DOM使用:where()零特异性页面样式可以无冲突地覆盖默认值跟随用户的color-scheme开发者可通过在应用根元素上添加a2ui-light或a2ui-dark类强制亮/暗主题令牌覆盖背景、表面、主色/次色含--a2ui-color-primary、--a2ui-color-secondary及其 light/dark/hover 变体、圆角、边框、字体系列、间距阶梯--a2ui-spacing-xs到--a2ui-spacing-xl、字号阶梯--a2ui-font-size-xs到--a2ui-font-size-2xl等。computeColorVariant的三个重载分别生成lightcolor-mix(in oklab, var(--color) 85%, white)darkcolor-mix(in oklab, var(--color) 85%, black)hoverlight-dark(var(--darkVar), var(--lightVar))。百分比默认 85与混色目标色均可通过ColorVariantLightDarkOptions.percentage/mixColor覆盖。injectBasicCatalogStyles负责把默认样式表注入document或指定ShadowRoot的adoptedStyleSheets且只创建一次样式表被缓存。五、0.9.1FrameworkSignal 与主题导出新增FrameworkSignal概念代表来自 Preact、Angular 等特定框架的通用信号该版本中尚未使用未来版本将贯穿 web_core并可能伴随破坏性变更导出injectDefaultA2uiTheme携带 A2UI 基础目录使用的默认 CSS 变量值即上文DEFAULT_CSS的主题令牌。六、v0.8 兼容层面向旧规范的维护性演进web_core 长期维护 v0.8legacy与 v0.9推荐双轨v0.8 的变更集中在类型安全与规范对齐0.8.8 类型安全 schema 访问ComponentApi对象改为对schema类型泛型化基础组件定义从: ComponentApi改为satisfies ComponentApi使 schema 类型可被后续推断新增InferredComponentApiSchemaType类型提取ComponentApi的 schema 类型0.8.7为 v0.8 schema 补回此前误删的catalogId调整 schema 定义使其在压缩minification后依然有效0.8.6逻辑函数and/or改为必须接收values数组参数移除已废弃的独立参数formatDate强制要求format参数并对齐新配置引入date-fns支撑表达式字符串格式化数学与比较表达式 schema 增加预处理步骤把null参数正确转换为undefined以收紧校验错误消息包含函数名与 catalog ID0.8.5新增V8ErrorConstructor接口以访问 V8 专有的captureStackTrace通过复制errors.ts解除 v0_8 对 v0_9 的依赖0.8.4微调 v0.8 的 Button 与 TextField schema 以更好贴合规范0.8.3MarkdownRenderer类型改为异步返回Promisestring。七、表达式与基础目录函数从 API 定义到执行表达式与目录函数是 web_core 最常用的对外能力值得展开源码细节。7.1 表达式语法expression_parser.ts 将含${...}占位符的字符串解析为DynamicValue[]支持字符串/数字/布尔字面量、基于路径的数据绑定、带命名参数的嵌套函数调用无插值时返回原字符串作为单一字面量\${可作为转义序列输出字面量${插值内容支持括号平衡与引号含转义内的花括号函数调用必须使用命名参数fn(argName: value)缺少:或)都会抛出A2uiExpressionError关键字true/false解析为布尔值null解析为空字符串路径 token 允许字母数字、/、.、_、-等字符。7.2 基础目录函数的 Zod API 定义每个函数都由一个namereturnType Zodschema构成定义于 basic_functions_api.ts。例如算术类函数的参数统一使用预处理把null转为undefined再z.coerce.number()export const AddApi { name: add as const, returnType: number as const, schema: z.object({ a: z.preprocess(v (v null ? undefined : v), z.coerce.number()), b: z.preprocess(v (v null ? undefined : v), z.coerce.number()), }), };比较类函数equals/not_equals等则用z.any().refine(v v ! undefined, Required)保证必填。整个函数集包括算术、比较、逻辑and/or的values数组形态、字符串含formatString、日期formatDate以及本地化函数pluralize、formatNumber、formatCurrency等它们与 18 个基础组件一起构成 catalog.ts 中的单一权威basicCatalog实例。八、构建、测试与进一步阅读web_core 使用wireit编排构建copy-spec任务会把 specification/v0_8/json、specification/v0_9/json、specification/v1_0/json 及对应 catalogs 下的 JSON 拷贝进src/**/schemas/build:tsc依赖它完成编译test使用 Node.js 原生测试运行器执行dist/**/*.test.jstest:coverage通过c8生成覆盖率。常用命令在 renderers/web_core 目录下yarn install a2ui/web_core # 安装依赖package.json 中亦给出 yarn build # 触发 wireit 编排的完整构建 yarn test # 运行测试套件 yarn test:coverage # 生成覆盖率报告 yarn lint # ESLint 检查若想深入源码可按以下路径继续表达式解析与一致性expression_parser.ts、expression_parser.conformance.test.ts、conformance/core/expressions.yaml节点层node-resolver.ts、component-node.ts、resolved-binding.ts状态管理data-model.ts、surface-model.ts、surface-group-model.ts消息处理message-processor.ts响应式抽象signals.ts主题与颜色styles/default.ts基础目录组件components/ 下每个组件的.ts与.test.ts。九、版本演进主线小结纵览 CHANGELOGweb_core 的演进可归纳为四条主线安全加固从openUrl的协议白名单0.10.2、DataModel原型污染防护0.10.6到表达式解析器对无效字面量直接抛错0.10.7持续收窄不可信输入的边界行为一致化数字字面量语法显式化、共享 conformance 套件、schema 预处理与严格化保证 TypeScript 与 Dart 等实现接受相同语言子集架构深化v0.9 从消息处理 数据模型演进到以NodeResolver为核心的节点层为渲染器提供占位升级、循环检测、错误去重等树级能力信号实现可替换0.10.3解耦了底层响应式库API 规范化Icon.path→svgPath的破坏性更名、基础目录导出收敛到v0_9/basic_catalog子路径、controller只读化让公共面更清晰可迁移。对渲染器开发者而言最重要的实操结论是新代码应统一从a2ui/web_core/v0_9与a2ui/web_core/v0_9/basic_catalog两个入口导入并留意 0.10.0 起Icon的svgPath更名以及表达式解析器对非法字面量抛错而非返回NaN的行为变化。【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 从表达式解析到节点层：@a2ui/web_core 完整版本演进与技术拆解
从表达式解析到节点层a2ui/web_core 完整版本演进与技术拆解【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2uia2ui/web_core 是 A2UI 框架中负责核心逻辑、状态管理与协议处理的框架无关层它同时是 Angular、React、Lit 等具体渲染器实现的地基。本文以仓库中 renderers/web_core/CHANGELOG.md 为主线逐版本梳理从 0.8.3 到 0.10.7 的关键演进表达式解析器的硬化、Node 节点层的引入、响应式信号的抽象、安全修复、主题系统与基础目录Basic Catalog的 Web Component 化。读完本文你将掌握 web_core 的模块划分、每个版本的破坏性变更与迁移要点并能结合源码定位对应实现。一、包定位web_core 在 A2UI 渲染体系中的角色根据 renderers/web_core/README.mda2ui/web_core包含 A2UI 框架的核心逻辑、状态管理和协议处理被刻意设计为框架无关为 Angular、React、Lit 等具体渲染器提供基础。其核心能力包括协议处理实现 A2UI 规范v0.8 与 v0_9的消息处理与校验状态管理基于preact/signals-core的响应式数据模型DataContext带依赖追踪与自动更新的高级数据绑定和函数执行逻辑Catalog 系统组件与函数的可扩展注册表支持跨渲染器复用Schema 校验内置基于 Zod 的协议消息与组件属性校验。从 package.json 可以看到当前版本为0.10.7包的导出入口分为v0_8legacy与v0_9推荐两套并额外提供./v0_9/basic_catalog与./styles/*、./types/*、./data/*等子路径。依赖包括lit、preact/signals-core、zod、zod-to-json-schema与date-fns构建与测试均由wireit编排。二、Unreleased / 0.10.7表达式解析器硬化与节点层落地最新一批变更集中在两个方向让表达式解析行为跨实现严格一致以及为渲染层提供更健壮的组件树解析能力。2.1 数字字面量从 NaN 到 A2uiExpressionError此前诸如${1.2.3}这样的无效数字字面量会被交给Number()处理最终以NaN的形式静默传入渲染层。现在的行为改为解析器一旦遇到不符合语法的数字字面量直接抛出A2uiExpressionError。在 expression_parser.ts 中可以看到承载这一行为的语法定义/** * Digits, an optional decimal point, and optional further digits. * * Every client implementation accepts a trailing point (1.) today and none * accepts a second point (1.2.3), so the grammar is written to keep that. */ const NUMBER_LITERAL /^\d\.?\d*$/; export class ExpressionParser { /** The maximum allowed recursion depth for nested expressions to prevent stack overflows. */ public static readonly MAX_DEPTH 100;parseNumberLiteral会先用扫描器吞入数字与小数点再用NUMBER_LITERAL正则校验1、1.、1.2均合法而1.2.3、.5等会被拒绝。注释中特别强调接受1.这种带尾随小数点、拒绝第二个小数点这一行为是所有客户端实现共同遵守的语法被显式写入解析器而非继承平台行为从而保证 Dart、TypeScript 等各实现接受完全相同的字面量集合。2.2 嵌套深度保护不可达守卫的修复CHANGELOG 指出深度守卫此前不可达导致深度嵌套的插值或函数调用参数会不断递归直至栈溢出而不是抛出A2uiExpressionError。修复后parse()入口即检查depth MAX_DEPTHMAX_DEPTH 100关键的是parseExpressionInternal()在两条递归路径插值内嵌插值、函数调用参数本身是表达式上都执行深度检查保证守卫真正可达。2.3 共享一致性测试套件表达式解析器现在运行位于 conformance/core/expressions.yaml 的共享一致性测试与 Dart 客户端使用同一份用例。为此新增了js-yaml作为 devDependency 来读取该 YAML测试文件为 expression_parser.conformance.test.ts。这意味着语言行为字面量、路径、函数调用、插值不再由各实现各自为政而是由一份规范化的用例集统一约束。2.4 节点层Node LayerNodeResolver 与 ComponentNode这一版本引入了 web_core 最重要的架构新增——节点层。根据 node-resolver.ts 的类注释节点层的树引擎把 surface 的扁平组件映射转成以rootNode为根的一棵活的、已解析的ComponentNode树。子引用变为ComponentNode对象模板ChildList为每个数组项生成一个节点尚未到达的组件以占位节点出现并在原地升级当父节点不再引用某节点或 resolver 被销毁时该节点及其 binder、数据订阅全部被拆除。关键设计语义包括身份是父作用域的parent-scoped同一个组件 id 挂载在两个位置会产生两个节点删除其中一个位置不会影响另一个占位状态未到达的组件呈现为 placeholder 节点PLACEHOLDER_TYPE到达后原地升级错误上报去重dispatchOnce()保证无法解析的引用与循环引用在条件持续期间每个组件、数据路径组合只通过onError上报一次条件修复后再次引入会重新上报见 node-resolver.ts晚到模型事件迟到的模型事件会与当前模型状态对账子引用检测覆盖ChildList联合类型与普通组件 id 数组两种形态。节点层相关的其它细节还包括$ref在 inline-catalog capabilities 中即使设置了 per-usage description 也会被保留新增的componentId()/childList()辅助函数可在自定义描述时保持$ref不丢失GenericBinder在组件重复下发时复用 action 闭包保证 action 型属性保持引用同一性使下游的相等性检查感知不到变化Catalog与SurfaceModel接受函数类型的泛型参数默认为FunctionImplementation调用无实现的目录函数现在抛出A2uiExpressionError。2.5 导出整理与 API 稳定性A2uiLitElement.controller由属性改为只读 getter禁止外部重新赋值a2ui/web_core/v0_9/basic_catalog新入口点集中导出通用 Web Component 基础目录实现A2uiText、A2uiButton、A2uiTextField、A2uiRow、A2uiColumn、A2uiList、A2uiImage、A2uiIcon、A2uiVideo、A2uiAudioPlayer、A2uiCard、A2uiDivider、A2uiCheckBox、A2uiSlider、A2uiDateTimeInput、A2uiChoicePicker、A2uiTabs、A2uiModal以及basicCatalog见 basic_catalog/index.ts基类A2uiLitElement从a2ui/web_core/v0_9导出同时废弃了a2ui/web_core/v0_9下的injectBasicCatalogStyles、computeColorVariant、ColorVariantLightDarkOptions、ColorVariantHoverOptions导出消费方应改从a2ui/web_core/v0_9/basic_catalog导入v0_9/index.ts 中以deprecated标注ComponentIdSchema与ChildListSchema的子引用标记移入 schema 的 metadata使.describe()等重建 schema 的方法不再丢失该标记手写的REF:描述仍被识别。2.6 测试补全新增了对全部基础目录 Web Component 实现的单元测试覆盖对应 v0_9/basic_catalog/components/ 下每个组件的.test.ts文件并移除了基础目录 barrel 文件的通配导出改为显式导出。三、0.10.x 系列安全、信号抽象与破坏性变更3.1 0.10.6消息校验加固与原型污染防护组件属性 schema 校验MessageProcessor现在会针对目录 schema 校验组件属性阻止畸形组件 action 进入状态原型污染防护DataModel增加原型污染保护与安全属性查找非破坏性安全修复防止代理可控的路径写入污染Object.prototypev0.8 公共 API 新增导出A2uiMessageSchematsconfig.json开启inlineSources让 sourcemap 携带sourcesContent便于调试。3.2 0.10.5v0.9/v0.9.1 双版本兼容消息解析同时接受v0.9与v0.9.1版本A2uiClientCapabilities支持同时声明v0.9与v0.9.1两种版本能力便于渐进迁移。3.3 0.10.4JSON Pointer 与类型导出DataModel支持 RFC 6901 规范的 JSON Pointer 转义~0、~1v0.8 的UserAction以ClientEventUserAction之名从types.ts导出对应源码 client-event.ts。3.4 0.10.3可替换的信号实现新增setSignalImplementation函数允许把底层信号库整体换掉。实现位于 reactivity/signals.ts包内定义SignalImplementations接口signal、computed、effect、batchWrite、isSignal、getValue、setValue、peekValue八个函数默认实现委托给preact/signals-coresetSignalImplementation只保存函数引用忽略实现对象的其它属性变更。这让 web_core 的状态层能够被适配到不同的响应式环境。3.5 0.10.2openUrl 安全收紧openUrl现在拒绝除 HTTP/HTTPS 之外的任何协议 schema修复了 Agent 可能通过注入javascript:等 schema 执行任意脚本的安全问题。3.6 0.10.1基础目录函数的 locale 与严格化v0.9 基础目录函数pluralize、formatNumber、formatCurrency新增 locale 支持通过 catalog 级配置生效PluralizeApi的 schema 移除.passthrough()校验更严格为 v0.8 引入createDataValueSchema工厂函数可覆盖DataValueSchema中硬编码的递归深度修复formatString按规范用 JSON 序列化对象/数组而不是使用 JS 默认的字符串强制转换避免[object Object]。3.7 0.10.0破坏性变更——Icon.path 更名为 svgPath这是 0.10.x 中唯一标注BREAKING CHANGE的变更Icon组件的path属性更名为svgPath以解决与DataBindingType的类型冲突。同版本新增computeColorVariant辅助函数为基础目录组件生成明/暗/悬停色变体的 CSS 公式供各渲染器复用实现见 styles/default.ts。四、主题与设计令牌injectBasicCatalogStyles 与 computeColorVariant虽然injectBasicCatalogStyles与computeColorVariant在新版本中被要求改从basic_catalog子路径导入但它们的职责值得单独说明因为它们是跨渲染器共享设计令牌的机制。styles/default.ts 中的默认主题 CSS 遵循几个原则只用变量定义以便穿透组件的 shadow DOM使用:where()零特异性页面样式可以无冲突地覆盖默认值跟随用户的color-scheme开发者可通过在应用根元素上添加a2ui-light或a2ui-dark类强制亮/暗主题令牌覆盖背景、表面、主色/次色含--a2ui-color-primary、--a2ui-color-secondary及其 light/dark/hover 变体、圆角、边框、字体系列、间距阶梯--a2ui-spacing-xs到--a2ui-spacing-xl、字号阶梯--a2ui-font-size-xs到--a2ui-font-size-2xl等。computeColorVariant的三个重载分别生成lightcolor-mix(in oklab, var(--color) 85%, white)darkcolor-mix(in oklab, var(--color) 85%, black)hoverlight-dark(var(--darkVar), var(--lightVar))。百分比默认 85与混色目标色均可通过ColorVariantLightDarkOptions.percentage/mixColor覆盖。injectBasicCatalogStyles负责把默认样式表注入document或指定ShadowRoot的adoptedStyleSheets且只创建一次样式表被缓存。五、0.9.1FrameworkSignal 与主题导出新增FrameworkSignal概念代表来自 Preact、Angular 等特定框架的通用信号该版本中尚未使用未来版本将贯穿 web_core并可能伴随破坏性变更导出injectDefaultA2uiTheme携带 A2UI 基础目录使用的默认 CSS 变量值即上文DEFAULT_CSS的主题令牌。六、v0.8 兼容层面向旧规范的维护性演进web_core 长期维护 v0.8legacy与 v0.9推荐双轨v0.8 的变更集中在类型安全与规范对齐0.8.8 类型安全 schema 访问ComponentApi对象改为对schema类型泛型化基础组件定义从: ComponentApi改为satisfies ComponentApi使 schema 类型可被后续推断新增InferredComponentApiSchemaType类型提取ComponentApi的 schema 类型0.8.7为 v0.8 schema 补回此前误删的catalogId调整 schema 定义使其在压缩minification后依然有效0.8.6逻辑函数and/or改为必须接收values数组参数移除已废弃的独立参数formatDate强制要求format参数并对齐新配置引入date-fns支撑表达式字符串格式化数学与比较表达式 schema 增加预处理步骤把null参数正确转换为undefined以收紧校验错误消息包含函数名与 catalog ID0.8.5新增V8ErrorConstructor接口以访问 V8 专有的captureStackTrace通过复制errors.ts解除 v0_8 对 v0_9 的依赖0.8.4微调 v0.8 的 Button 与 TextField schema 以更好贴合规范0.8.3MarkdownRenderer类型改为异步返回Promisestring。七、表达式与基础目录函数从 API 定义到执行表达式与目录函数是 web_core 最常用的对外能力值得展开源码细节。7.1 表达式语法expression_parser.ts 将含${...}占位符的字符串解析为DynamicValue[]支持字符串/数字/布尔字面量、基于路径的数据绑定、带命名参数的嵌套函数调用无插值时返回原字符串作为单一字面量\${可作为转义序列输出字面量${插值内容支持括号平衡与引号含转义内的花括号函数调用必须使用命名参数fn(argName: value)缺少:或)都会抛出A2uiExpressionError关键字true/false解析为布尔值null解析为空字符串路径 token 允许字母数字、/、.、_、-等字符。7.2 基础目录函数的 Zod API 定义每个函数都由一个namereturnType Zodschema构成定义于 basic_functions_api.ts。例如算术类函数的参数统一使用预处理把null转为undefined再z.coerce.number()export const AddApi { name: add as const, returnType: number as const, schema: z.object({ a: z.preprocess(v (v null ? undefined : v), z.coerce.number()), b: z.preprocess(v (v null ? undefined : v), z.coerce.number()), }), };比较类函数equals/not_equals等则用z.any().refine(v v ! undefined, Required)保证必填。整个函数集包括算术、比较、逻辑and/or的values数组形态、字符串含formatString、日期formatDate以及本地化函数pluralize、formatNumber、formatCurrency等它们与 18 个基础组件一起构成 catalog.ts 中的单一权威basicCatalog实例。八、构建、测试与进一步阅读web_core 使用wireit编排构建copy-spec任务会把 specification/v0_8/json、specification/v0_9/json、specification/v1_0/json 及对应 catalogs 下的 JSON 拷贝进src/**/schemas/build:tsc依赖它完成编译test使用 Node.js 原生测试运行器执行dist/**/*.test.jstest:coverage通过c8生成覆盖率。常用命令在 renderers/web_core 目录下yarn install a2ui/web_core # 安装依赖package.json 中亦给出 yarn build # 触发 wireit 编排的完整构建 yarn test # 运行测试套件 yarn test:coverage # 生成覆盖率报告 yarn lint # ESLint 检查若想深入源码可按以下路径继续表达式解析与一致性expression_parser.ts、expression_parser.conformance.test.ts、conformance/core/expressions.yaml节点层node-resolver.ts、component-node.ts、resolved-binding.ts状态管理data-model.ts、surface-model.ts、surface-group-model.ts消息处理message-processor.ts响应式抽象signals.ts主题与颜色styles/default.ts基础目录组件components/ 下每个组件的.ts与.test.ts。九、版本演进主线小结纵览 CHANGELOGweb_core 的演进可归纳为四条主线安全加固从openUrl的协议白名单0.10.2、DataModel原型污染防护0.10.6到表达式解析器对无效字面量直接抛错0.10.7持续收窄不可信输入的边界行为一致化数字字面量语法显式化、共享 conformance 套件、schema 预处理与严格化保证 TypeScript 与 Dart 等实现接受相同语言子集架构深化v0.9 从消息处理 数据模型演进到以NodeResolver为核心的节点层为渲染器提供占位升级、循环检测、错误去重等树级能力信号实现可替换0.10.3解耦了底层响应式库API 规范化Icon.path→svgPath的破坏性更名、基础目录导出收敛到v0_9/basic_catalog子路径、controller只读化让公共面更清晰可迁移。对渲染器开发者而言最重要的实操结论是新代码应统一从a2ui/web_core/v0_9与a2ui/web_core/v0_9/basic_catalog两个入口导入并留意 0.10.0 起Icon的svgPath更名以及表达式解析器对非法字面量抛错而非返回NaN的行为变化。【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考