最后更新:2026-08-11;适用版本:0.6.0-dev;兼容基线:0.5.0
这份文档是 JellyFrame 面向应用开发者的实际能力契约。开发者在使用某个 HTML 标签、CSS 属性、DOM/JS API、事件或渲染能力前,应能通过这里判断:它现在能不能工作、 会如何降级、是否只是被解析保存、是否会被懒处理或直接跳过。
JellyFrame 不是通用浏览器。它是一个为可穿戴/嵌入式 UI 准备的小型 HTML/CSS/DOM/script runtime,目标是保留“像写小网页一样写应用”的开发模型,同时裁剪 网络、完整浏览器加载、GPU、复杂字体、完整 CSS layout 等高成本能力。
App 作者写进 HTML、CSS 和 JavaScript 的内容应当是明确记录的 Web 平台子集。
JellyFrame 自有配置应放在 jellyframe.app.json、CLI/tool 参数、frame script、
package report 或宿主/移植接口里,而不是伪装成页面私有语法。页面内资源和数据请求应使用
/assets/icon.bmp、/data/weather.json 或相对 URL 这样的 package-local 标准路径;
私有 URL scheme 不属于 app 语法契约。
- 可用:已经实现,属于当前建议使用范围。
- 子集:能用,但只应依赖这里写明的子集。
- 已保存:会被解析或保存在内部结构里,但视觉/行为未完整执行。
- 懒处理:整体跳过或简化,不应破坏后续解析和渲染。
- 延后:刻意不支持;不要依赖。
- 壳层限定:只存在于桌面例程或 Win32 验证壳,不属于平台无关核心。
本能力矩阵是面向 app 作者的可读契约,负责解释 JellyFrame 重要子集和降级行为。 如果要在使用某个标签、DOM API 或浏览器行为前查支持性,请使用 HTML Living Standard 全量支持表:
全量表故意保持完整、便于搜索;能力矩阵保持更短,只解释 app 作者最可能依赖的行为细节。
全量表里的状态含义:
supported:可按 JellyFrame 文档化子集使用。partial:只有子集、降级或普通元素保留;详细行为看本能力矩阵。host_dependent:依赖 manifest capability、target profile、宿主服务、codec、文本后端或预算。unsupported:不要在 JellyFrame app 中依赖。out_of_scope:规范说明文字、旧浏览器兼容机制,或 app runtime 明确排除的浏览器级能力。
前几批后续工作已经把低成本尾项推进到支持子集:details / summary disclosure、
title / lang / dir 反射、document.title、document.dir、readOnly、
maxLength、range min / max / step 反射,以及 JellyFrame 实际派发事件的
on* handler property。navigation/history、browsing context、Workers、Worklets、完整媒体、
Shadow DOM、Custom Elements 生命周期、Microdata export 和 XML/XHTML 语法仍是明确非目标;
除非未来产品 profile 把它们做成宿主持有 capability,否则不进入页面可依赖能力。
在使用 CSS 属性、函数、选择器、值或 at-rule 前,请搜索 CSSWG 全量支持表。它和 HTML
全量表使用同一组状态;尤其注意 partial:CSS 值细节只能在已文档化的所属属性或值位置中使用。
- 面向人阅读:csswg_support_table_zh.md
- 面向工具消费:csswg_support_table.csv
适合:
- 天气、时钟、计时器、计算器、设置页。
- 卡片式小仪表盘、本地配置界面、表单型设备 UI。
- 想用 HTML/CSS/JS 编写嵌入式应用,而不是用 canvas 手绘全部 UI 的项目。
- 使用
jellyframe_pseudo_browser验证平台无关管线,使用jellyframe_desktop_shell验证交互式 app 行为。
暂不适合:
- 任意现代网站。
- 假设完整 DOM、selector API、浏览器 loader、网络、存储、模块、canvas 或 Web Components 的前端框架。
- 像素级兼容浏览器渲染。
- 依赖完整 flex/grid、container query、图片解码、字体加载、复杂文字 shaping 的大页面。
| 能力 | 状态 | 行为 |
|---|---|---|
| 平台无关核心 | 可用 | 核心不做文件、网络、窗口、硬件 I/O。 |
| 伪浏览器 | 壳层限定 | 运行完整管线并写出 BMP/PPM。默认使用极小内置字体;未注入平台文本绘制时中文会显示为 fallback glyph。 |
| Win32 browser 壳 | 壳层限定 | 打开桌面窗口,使用 GDI 文本测量/绘制,转发鼠标/滚轮/键盘输入,支持截图输出和可选 scripting 构建。 |
| 嵌入式后端边界 | 移植层持有子集 | 平台无关引擎已经暴露 framebuffer 转换、dirty rect、scroll-blit 计划、frame sink 边界、input-controller hook、文本 callback 和 host-service pump。真实 display flush、触摸/按键驱动、panel DMA、睡眠唤醒,以及 storage/network/audio/sensor 设备仍由 port 持有。 |
| 外链 CSS 加载 | 壳/宿主子集 | 宿主可通过核心 callback helper 加载本地 <link rel="stylesheet">;仍不支持远程加载。单个 document 只接受宿主配置的 stylesheet 数量和 CSS 聚合字节预算(max_document_stylesheets 与 max_resource_bytes);超限的后续完整 stylesheet 会以 css-document-resource-limit 跳过,绝不会截断后交给 parser。 |
| Classic script 收集 | 宿主子集 | 启用 scripting 时,classic inline 和 package-local external script 按文档顺序收集。单个 document 只接受宿主配置的 script 数量和 source 聚合字节预算(max_document_scripts 与 max_resource_bytes);超限的后续完整 script 会以 script-document-resource-limit 跳过,绝不会截断。模块加载和远程 script 仍不支持。 |
| 网络 | 宿主可选 XHR V0 | 核心仍无 HTTP、WebSocket 或远程资源加载,不允许远程 HTML/CSS/script/image 进入页面 loader。NetworkFetchMock 已提供 fixture/handle/completion 契约;只有 network.fetch 与 host profile 同时准入且 host 完成绑定时,JerryScriptRuntime 才在 scripting 构建中暴露 async XMLHttpRequest GET 子集。网络 request/completion 失败会归类为稳定 diagnostics,例如 capability-denied、invalid-url、resource-not-found、offline、response-budget-exceeded、response-handle-budget-exceeded、request-timeout 和 request-cancelled。真实网络由宿主 service/worker 完成,JS callback 只在 UI/main task pump completion 后执行。 |
| 存储 | 宿主可选 localStorage V0 | 无 cookie、IndexedDB 或核心文件系统 API。AppPrivateKvStorageMock 已提供 app id 隔离的异步 KV 契约和预算检查;只有 storage.kv 与 host profile 同时准入且 host 绑定非阻塞 AppLocalStorageShadow 时,JerryScriptRuntime 才暴露极小 localStorage 子集,否则不暴露。存储失败会归类为稳定 diagnostics,例如 capability-denied、invalid-key、value-budget、quota-exceeded、not-found、handle-budget-exceeded、operation-timeout 和 operation-cancelled。AppStorageLifecyclePolicy 和 apply_app_storage_lifecycle(...) 定义宿主在 suspend、exit、crash、uninstall、update 和 memory pressure 时如何 flush、drop、delete 或 retain pending/persistent app storage,并输出 storage-flush-ok、storage-flush-failed、storage-drop-pending、storage-delete-data 和 storage-retain-data 等稳定 system-shell diagnostics。 |
| App 分发 | 壳/宿主 contract V0 | CLI 可生成 .jfapp,并安装到桌面 registry mock。bundle 携带 package validation 生成的规范化 manifest summary;registry 安装和原生 Win32 bundle loader 都会在解释 app policy 前拒绝字段缺失/类型错误、未规范化 entry path 或 capability 投影漂移的 summary。Registry entry 现在带有产品语义字段,例如 status、enabled、updatedAtUtc、可选 rollback 和可选 failure 记录。status 仅限 installed、disabled 和 failed;rollback-ready 由 rollback 元数据派生,见 tools/schemas/jellyframe.installed_apps.registry.schema.json。更新 app 时会保留上一版 bundle 作为回滚目标;安装更低 versionCode 默认会被拒绝,必须显式 --allow-downgrade。jellyframe_cli.py install --candidate 与 Win32 壳 --install-candidate PATH 接受宿主下载并验证后的本地 candidate JSON;提交前会检查声明的 SHA-256、trusted 签名状态和用户批准。tools/app_registry.py state 会输出面向 launcher 的派生 state report。tools/app_registry.py rollback 和 Win32 壳 --rollback-app ID 可验收常规回滚路径。enable / disable 会保留 bundle 与数据,只控制是否可启动;启用 failed app 会清除 failure 记录。示例 Win32 壳在清数据或删除 app 前要求独立的宿主持有确认。删除 app 会删除当前 bundle 和 rollback bundle;是否保留 app 私有数据由显式参数决定。这仍是桌面/system-shell contract,不是完整 app store、签名权威、支付流程或 JavaScript 包管理 API。真实产品仍需负责下载、签名校验、用户授权、固件安全 staging 和持久 registry 存储。 |
| 授权文件访问 | 宿主 broker 设计 V0 | 普通 app 没有通用文件系统访问能力,不能影响 runtime 文件、系统组件或其他 app 数据。系统组件、文件管理器或用户批准的 app 应声明 file.read、file.write 或 file.manage,并通过宿主持有的 file broker。核心已提供 AuthorizedFilePolicy、AuthorizedFileRequest 和校验 helper,用于 capability gate、用户授权、规范化逻辑路径、字节预算,以及 user-approval-required、capability-denied、invalid-path、traversal-rejected、byte-budget-exceeded 等稳定错误。Win32 壳提供 --authorized-file-smoke DIR,用于验收未授权写入、路径穿越拒绝、staged commit/rollback 和 manage 操作 gate。真实产品 I/O 与授权 UX 仍由宿主实现;目前不暴露 JavaScript 文件 API。App 仍不能获得裸 filesystem、flash partition 或 block-device handle。 |
| 视频帧预览 | 宿主可选实验合同 | media.video.frame 是面向产品私有 preview surface 的有界 host-owned 最新帧合同。V0 runtime 接受 MJPEG,以及仅在显式启用时的 H.264 baseline;每个 source 同时只有一个 in-flight request,分配有界 RGB565 frame handle,替换帧无法分配时保留旧帧,替换成功后丢弃旧帧。它不提供 HTML <video>、HTMLMediaElement、track、JavaScript media API、core 内 codec,也不会影响未声明该能力的 app。target 通过 package/check diagnostics 报告 hostServices.videoFrame。 |
| Canvas 2D | 可选 V0.4 capability | graphics.canvas2d 用于声明有界 <canvas> / CanvasRenderingContext2D 使用。render core 提供 Canvas2DRegistry,包含按需 RGBA backing store、单 surface/总像素预算、path 点数/状态栈预算、gradient/stop 预算和 image display-list 集成;JerryScript 构建在宿主绑定 registry 后暴露 canvas.getContext("2d")、fillStyle、strokeStyle、lineWidth、globalAlpha、font、save、restore、clearRect、fillRect、strokeRect、beginPath、moveTo、lineTo、arc、closePath、fill、抗锯齿 stroke、measureText、fillText、createLinearGradient、createRadialGradient、CanvasGradient.addColorStop、translate、resetTransform、quadraticCurveTo 和 bezierCurveTo。linear gradient 会用于矩形、path 和 stroke 的逐像素采样;Canvas 文本因为复用 DOM 文本相同的宿主 text-command backend,会退化为在文本起点采样出的单色。Canvas 文本在宿主提供时复用与 DOM 文本相同的 text backend,否则退回极小内置 bitmap 路径。像素只在 getContext("2d") 后分配;不用 Canvas 的 app 不承担绘制成本。target preset 仍需用 hostServices.canvas2d 显式开启;不支持的 target 会输出 package/check warning。canvas-to-canvas drawImage() 支持标准 3/5/9 参数形式、裁切后的最近邻缩放和现有 globalAlpha;它要求 source canvas 已分配 surface,且不会新建 surface。createRadialGradient() 只接受同心圆上的双 stop;translate(x, y) 会把有限偏移按像素取整,作用于绘制/path/text/image 目标坐标,在创建 gradient 时捕获当前平移,并由 save()/restore() 保存;resetTransform() 只清除这一有界平移。quadraticCurveTo() 会把一段二次曲线 tessellate 为最多 24 个保留 path 点,bezierCurveTo() 会把一段三次曲线 tessellate 为最多 32 个;两者超过现有点数预算时均拒绝。<img>、ImageBitmap 与视频 source、self-copy、imageData、焦点/非同心或多 stop radial gradient、scale、rotate、通用矩阵、pattern fill 和 source-over 以外的合成模式仍延后。 |
| 系统状态事件 | 宿主可选 V0 queue | AppSystemEventQueue 允许宿主 producer 为当前 app instance 注入有界的时间/时区/网络/电量/屏幕/低功耗状态快照。producer push、UI frame pump、discard 与查询都受同步保护;producer 只读取 host 的原子 instance-id snapshot,不借用 lifecycle 或 DOM 状态。旧实例事件会在帧边界丢弃;try_push_current(...) 可诊断 empty-instance / queue-full。JerryScript V0 已将宿主时间映射到标准 Date.now(),并映射 navigator.onLine、window 的 online/offline 事件子集、document.hidden、document.visibilityState 和 visibilitychange。TimeChanged 只刷新宿主时钟,不派发 Web 事件。 |
| 宿主数据快照 | 宿主可选 V0 | AppHostDataSnapshot 定义固定大小、无分配的宿主摘要形状,覆盖 battery、weather、activity、location 和 sensor summary。AppHostDataAccessPolicy 默认清掉所有字段。仅当 host 显式绑定快照,且 manifest 声明 system.battery、system.weather 或 system.activity 时,navigator.jellyframe.getSnapshot() 才同步返回已批准的 battery/weather/activity 值;不可用字段为 null。调用不会创建 service request、订阅、轮询循环、callback queue 或 native handle。该私有命名空间刻意不模拟 Battery Status、Geolocation 或 sensor 浏览器 API。 |
| 宿主计算任务 | 宿主可选合同 V0 | compute.jobs 可声明有界的具名宿主工作。AppComputeJobRequest 只携带 operation name、有界字节输入和 timeout;宿主在 UI owner 之外执行,并通过既有 request/completion/handle 边界返回 result handle。AppComputeJobPolicy 限制 input bytes、result bytes 和每 app jobs;app teardown 时结果会被清理。这刻意不是 Worker、MessagePort、任意 callback code 或 JS API。 |
| 传感器/定位 | 宿主可选语义服务 V0 | App 可在 manifest 声明 sensor.accelerometer、sensor.gyroscope、sensor.heart-rate、sensor.ambient-light 或 location.position。只有 host/profile 同时允许时,平台无关 AppSensorSampleMock / AppLocationSnapshotMock 语义服务才启用。结果通过有界 request/completion 和 host handle 回 UI task;App 不会得到 GPIO/I2C/SPI/BLE/GPS 等裸硬件句柄。宿主绑定 location service 后,JerryScriptRuntime 暴露 navigator.geolocation.getCurrentPosition(success, error) 子集;sensor JS API 仍延后。失败会归类为 capability-denied、sample-unavailable、record-budget-exceeded、handle-budget-exceeded、request-timeout 等 diagnostics。真实硬件采样频率、后台策略和授权提示由宿主决定。 |
| App frame policy | 可用 V0 | AppFramePolicy 将 foreground/suspended、screen-on 和 low-power 状态转换为 input/timer/rAF/present 预算策略。低功耗可保持输入和 timer、停止动画;息屏或 suspended 会暂停前台输入、timer、rAF 和 present,并在 resume 时建议首帧 repaint。 |
| App teardown/recovery | 可用 V0 | AppRuntimeHost::terminate_current(reason) 会取消当前 app request、丢弃 completion、释放 host handle,并清理 app font resource;稳定 reason 包括 user-kill、script-watchdog、budget-exceeded、load-failure 和 system-policy。script-service request 会把内部 runtime client token 贯穿到 request、completion 和返回 handle;clear_app_services() 只释放该 runtime 自己的资源,并会回收其迟到 completion,不会误触同一 app instance 中其他 consumer 的资源。Win32 system shell 会在 watchdog 或 budget 耗尽终止已安装 app 后,将它标记为 failed 再返回 launcher;用户可重新启用、回滚或移除。--system-survival-smoke N 用于验收坏 app 多轮 budget recovery、stale completion 过滤和 launcher 事件投递。 |
| 功能 | 状态 | 行为 |
|---|---|---|
| UTF-8 输入 | 可用 | 解析按字节/字符串处理。最终文字显示质量取决于文本后端。 |
| 开始/结束标签 | 可用 | 常用标签会生成 DOM 元素。 |
| 属性 | 可用 | 支持常见引号形式和未加引号形式。HTML 路径会规范化属性名。 |
| 文本节点 | 可用 | DOM 文本保留作者空白。Render tree 会跳过非保留上下文中的纯格式化空白文本,避免缩进换行污染 block/grid/flex layout;Layout/rendering 会折叠普通显示文本;pre、script、style、textarea 和 title 保留文本。 |
| 注释 | 可用 | tokenizer 可处理,视觉树忽略。 |
| Doctype | 可用/懒处理 | 接受但不进入 quirks mode。 |
| 字符引用 | 子集 | 常见 named references 和十进制/十六进制 numeric references 会解码,并包含常见 Windows-1252 legacy numeric remap;未知情况按字面或 fallback 处理。 |
script/style raw text |
子集 | 足够支持样式/脚本收集。 |
textarea/title RCDATA-like |
子集 | 在有界简化内容扫描中解码字符引用;不提供完整浏览器 RCDATA 状态兼容。 |
自动合成 html/body |
可用 | 缺失外层结构会被修复。 |
| void elements | 可用 | 常见 void 标签不要求闭合。 |
| 隐式闭合 | 子集 | 容忍常见段落/列表/table-ish 情况;不追求完整 HTML tree builder 兼容。 |
| 错误恢复 | 子集 | 有明确资源上限。tokenizer 在构造 DOM 前限制每 tag 的属性数量,以及 tag 名、属性名和属性值字节数;超限内容会被继续消费但不会继续扩容,并报告稳定 diagnostic。tree builder 继续报告 node/depth/attribute 预算压力;畸形输入不应导致死循环或崩溃。 |
| Quirks mode | 延后 | 完全抛弃。JellyFrame 只面向现代作者写法。 |
template |
懒处理 | 默认样式隐藏;template 内容语义未实现。 |
| 自定义元素 | 子集 | 未知标签可成为普通元素并被样式化;无生命周期回调。 |
details / summary |
子集 | 闭合的 details 只渲染第一个 summary;打开的 details 会渲染 summary 和内容。点击 summary 或在其获得焦点时激活,会切换 open 属性并派发 toggle 事件;click.preventDefault() 可阻止默认切换。name 分组行为、ToggleEvent 类和浏览器默认 disclosure marker 样式未实现。 |
| 功能/API | 状态 | 行为 |
|---|---|---|
Node tree |
可用 | Element/Text 两类节点,带 parent/children 所有权。 |
tag_name、text、attributes |
可用 | C++ 内部模型直接保存。 |
append_child |
可用 | 挂载/移动子节点,并标记 tree/layout dirty。 |
detach_child / remove_child |
可用 | 移除子节点所有权,并标记 tree/layout dirty。 |
set_attribute / remove_attribute |
可用 | 更新属性,必要时重置表单状态,并标记 attributes/style/layout dirty。 |
set_text / set_text_content |
可用 | 内容变化时标记 text/layout dirty;同值设置不会制造脏标记。 |
text_content() |
可用 | 拼接后代文本。 |
attribute() |
可用 | 缺失属性返回空字符串。 |
has_class() |
可用 | 按空白分隔 class token。 |
| Dirty flags | 可用 | dirty 位向祖先传播,因此根节点 dirty 检查为 O(1);清理时跳过干净子树。 |
| DOM Range/Selection | 延后 | 暂无 Range、Selection。 |
| MutationObserver | 延后 | 使用宿主 dirty flags 观察变化。 |
| Shadow DOM | 延后 | 无 shadow root、slot、part、scoped tree。 |
完整浏览器 document |
延后 | 只有 scripting 绑定里的小型子集。 |
| 功能 | 状态 | 行为 |
|---|---|---|
| 注释 | 可用 | 解析时移除。 |
| 普通规则 | 可用 | selector { declarations }。 |
| selector list | 可用 | 顶层逗号拆分。 |
| declaration 顺序 | 可用 | 保留重复属性,用于 fallback。 |
!important |
可用 | 参与 cascade。 |
| 函数/字符串/括号组件 | 可用 | 平衡跳过,避免坏值破坏后续规则。 |
| 错误恢复 | 可用 | 在 declaration/rule 边界恢复。 |
@layer |
懒处理 | block 被展开;不建模 layer ordering。 |
@media |
子集 | 空、all、screen block 会解析。由 screen/all 加 min-width、max-width、min-height、max-height 组成的查询会按 parser viewport 求值,条件值支持 px 和无单位 px-like 数字。不支持或复杂的 media query 会整体跳过。 |
@supports |
子集 | 保守求值 declaration feature query。支持 (property: value)、not、同质 and/or 链和括号;selector() 以及未知或不安全特性会求值为 false 并跳过 block。 |
@container |
延后/懒处理 | 整个 block 跳过。不要把必需 UI 放在里面。 |
@font-face |
懒处理 | 平衡跳过;不实现 CSS 字体加载规则。App 字体必须在 manifest fonts[] 中声明;当宿主使用 app-font 文本后端时,.jffont 条目可通过下方文档化的 font-family 子集参与 runtime 选择。 |
| 字体覆盖检查 | 默认工具预检 | package、check、preview 和源码包 install 默认运行 jellyframe_font_resource_check,并以 --font-subset auto 在 report 旁写出 *.used_chars.txt,同时在 JSON report 中写入 fontSubset 计划。--font-coverage 在嵌入前报告缺失 codepoints,--font-source-bdf + --font-output 可在预检中调用现有 BDF 转 .jffont 生成器;生成结果仍需由 app 作者显式声明到 manifest fonts[]。--no-font-check 或 --font-subset off 可显式跳过。Package report 还会输出 fontDiagnostics,合并源码 codepoints、目标字体 profile 估算和 manifest .jffont glyph table,在安装前报告 app 可见缺字。 |
| 字体 profile 与预算估算 | 默认工具预检 | 默认按 16x16 估算 bitmap font pack bytes;--font-budget WxH 可调整,并根据扫描到的码点建议 tiny、tiny-plus-symbols、app-subset-cn、cn-standard 或 global-product。manifest fonts[].license、sizes 或 weights 缺失会产生发布前诊断;budgets.maxAppFonts、maxAppFontBytes、maxAppFontGlyphs 会限制可安装 .jffont 数量、总字节和 glyph 数。 |
| Bitmap font pack 生成 | 工具/runtime/fallback 链可用 | jellyframe_font_pack_gen 把 BDF bitmap 字体裁剪成嵌入式构建可用的 C++ BitmapFont header,也可输出 .jffont V0/V1 二进制补充包。V0 是紧凑 1bpp;V1 通过 `--coverage-bits 2 |
@keyframes |
子集 | 解析命名 @keyframes block,并保存 from/to 或 0%/100% declaration。中间百分比会诊断并忽略。执行范围受下方 animation 属性子集限制。 |
| 未知 at-rule | 懒处理 | 跳过 statement 或平衡 block。 |
| CSS custom properties | 子集 | 支持直接 var(--token) 和 var(--token, fallback),来源包括继承的 :root、祖先、当前元素和 inline custom property declarations。无法解析的 var() 不会覆盖之前的受支持 fallback。完整依赖图、区分大小写的 custom property 名称和完整 invalid-at-computed-value-time 语义尚未实现。 |
| CSS nesting | 显式单层子集 | 一个 qualified rule 内可包含一层嵌套 qualified rule,但每个嵌套 selector 都必须含 &,例如 .card { &:hover { ... } & .label { ... } }。父声明和嵌套规则保留 source order;逗号展开最多 16 个 selector。隐式 nesting、超过一层、nested at-rule 和不含 & 的 selector 会被跳过并输出 css-nesting-skipped。 |
| Cascade origins | 子集 | author + inline + 小型内置默认样式;无 user/animation origin。 |
| Rule indexing | 可用 | 按最右侧 id/class/tag/universal 建桶。 |
| Selector | 状态 | 行为 |
|---|---|---|
| Type selector | 可用 | button、section。 |
| Class selector | 可用 | .card。 |
| ID selector | 可用 | #search。 |
| 简单 compound | 可用 | button.primary.large。 |
| Descendant combinator | 可用 | .panel button。 |
| Child combinator | 可用 | main > section。 |
| 简单 attribute selector | 子集 | 支持存在性和简单等值类匹配。 |
:root |
可用 | 支持。 |
| 动态 pseudo-class | 子集 | :hover、:active、:focus、:focus-within、:checked 和 :disabled 会参与 selector matching。输入状态变化会标记 style/layout dirty;checked/disabled 来自表单控件和属性状态。 |
:is() / :where() |
子集 | :is() 匹配 selector-list 参数,并贡献参数中的最高 specificity。:where() 匹配同一子集,但 specificity 为 0。 |
:has() |
延后/懒处理 | 含 :has() 的规则会跳过;关系型 selector matching 刻意延后。 |
| Pseudo-elements | 子集 | ::before 支持极小的 generated-content 路径,可用于文本/counter 列表标记和短 generated text。::after 支持同一文本/counter 绘制子集,适合单位、角标和状态点。完整 generated-content layout、marker styling 和 selection styling 延后。 |
| Sibling combinators | 子集 | Adjacent + 和 general ~ sibling selectors 会匹配前序元素兄弟。元素之间的文本节点不会阻断 adjacent matching。 |
| Shadow selectors | 延后 | ::part、::slotted 跳过。 |
只应把下表支持的值用于必需 UI。不支持的值不会覆盖之前已经支持的 fallback。
| 属性 | 状态 | 支持值/降级 |
|---|---|---|
display |
子集 | block、inline、inline-block、flex、inline-flex、grid、inline-grid、none。inline flex/grid 映射为同一简化布局模式。 |
color |
子集 | 基础命名色、hex、rgb()、rgba()、数值角度/百分比饱和度和明度/可选 alpha 的 hsl() / hsla(),以及双色 color-mix(in srgb, <color> [<percentage>], <color> [<percentage>])。可用它实现半透明描边和带色层次,无需额外 DOM。oklch() 等不覆盖 fallback。 |
background-color |
子集 | 与 color 相同的颜色解析;刻意不接受渐变,因为 CSS 语义中渐变属于背景图像。 |
background |
子集 | 支持纯色;双色 linear-gradient(),方向可为 to top/bottom/left/right、对角关键字,或设计工具常输出的 0deg 至 315deg、每 45 度一档;双色进度 conic-gradient(<color> 0% N%, <color> N% 100%);以及两色圆形 radial-gradient([circle] [at center|<x%> <y%>,] <color> [0%], <color> [100%])。支持最多两层,按标准从底到顶绘制,可组合底层渐变与透明径向高光。可选顶层以 RGBA4444 压缩保存,避免每个节点常驻大对象。Conic gradient 面向表盘环;可定位 radial gradient 面向水凝胶高光和内凹层次。其他角度、复杂 stop、焦点、椭圆、repeating 与超过两层的背景会诊断并忽略,不会覆盖之前 fallback。超出 conic/radial 子集会分别输出 style-conic-gradient-unsupported / style-radial-gradient-unsupported,过大的绘制区域会输出 layer-conic-gradient-area-budget / layer-radial-gradient-area-budget。 |
background-image |
子集 | 接受与 background 相同的一层/两层 gradient 子集,但不接受纯色。也支持一个包内绝对路径 url("/assets/image.bmp"):它复用宿主拥有的图片 surface cache,background-color 保留为 fallback。单张包内图片可使用 background-size: cover、contain 或 100% 100%,简单 background-position 子集以及 background-repeat: no-repeat;选择的 fit、position 与采样模式复用既有 image display command,不会给未声明背景图片的页面增加字段、decoder、cache 或绘制工作。远程/data URL、相对路径、query/fragment/traversal、多 URL 层、平铺和任意尺寸表达式仍不支持。package report 会以 backgroundImageDiagnostics 指出非法或缺失的本地资源。 |
margin |
可用 | 1-4 个长度值,支持水平 auto。 |
margin-top/right/bottom/left |
可用 | 物理 longhand。margin-left/right:auto 可用于当前水平居中路径。 |
padding |
可用 | 1-4 个长度值。 |
padding-top/right/bottom/left |
可用 | 物理 longhand。 |
| 逻辑 box edge | LTR 子集 | 在 horizontal LTR writing mode 下,margin-inline / margin-block、padding-inline / padding-block、border-inline-width / border-block-width 及其 -start / -end longhand 会展开到同一组物理 cascade slot。逻辑 border color/style shorthand、writing mode 和 RTL 映射暂不实现。 |
border |
子集 | 支持 none,从简单 shorthand 中提取 width 和 color;style 关键词只作为可忽略文本。 |
border-top/right/bottom/left |
子集 | 支持单边 shorthand 的 width/color 子集,例如 border-right: 1px solid #ddd。当前内部只有单个 border_color,因此单边 shorthand 的 color 会成为全局 border color;单边宽度按对应边生效。 |
border-width |
可用 | 1-4 个长度值。 |
border-top/right/bottom/left-width |
可用 | 物理边框宽度 longhand。 |
border-color |
子集 | 单色应用到所有边。 |
border-radius |
子集 | 支持 1-4 个非负长度值,按标准物理角顺序解释;也支持 50% 这类单值百分比。圆角填充和边框使用局部 coverage 抗锯齿。单值 radius 保持紧凑快路径;不同角才进入有界四角栅格路径。椭圆 slash 语法和逐角百分比延后。 |
outline / outline-width / outline-color / outline-offset |
子集 | 作为不参与布局的外扩 stroke 绘制。支持简单 width/color shorthand 与受支持 length offset;正 offset 会形成清晰的 focus 间隙,负 offset 会与 border box 重叠。outline style keyword、auto/invert color 和浏览器 focus-ring policy 继续延后。 |
width / height |
可用 | 支持单位的长度值和百分比值。百分比相对 containing content box 解析;根节点/全屏 app wrapper 会使用真实 viewport 宽高。 |
min-width / min-height |
可用 | 长度值和百分比值。 |
max-width / max-height |
可用 | 长度值或百分比值;block layout 使用。 |
aspect-ratio |
可用 | 正数或 w / h,包括 auto w / h。用于 intrinsic box height。 |
font-size |
可用 | 长度值。 |
font-weight |
子集 | normal、bold、bolder、lighter 和数字权重。软件 fallback 近似加粗;最终字重由平台 text painter 决定。 |
line-height |
可用 | 无单位倍率或长度。 |
text-align |
可用 | left、right、start、end、center。 |
text-indent |
可用 | 长度值。 |
letter-spacing |
有界子集 | 支持 normal,或在当前字号解析后处于 -0.5em 到 2em 的受支持长度。声明字距时,测量与绘制使用同一 UTF-8 scalar advance,且属性可继承。该路径会为每个 scalar 生成一条文本命令,应用于短标签和数字显示,不应用于长段落。复杂文字 shaping、保留 kerning 与浏览器的边界语义仍由平台文本后端决定。 |
text-transform |
ASCII 子集 | none、uppercase、lowercase 和 capitalize。转换会在文本测量和绘制前统一执行。V0 只转换 ASCII 字母;locale-sensitive Unicode 大小写映射延后。 |
text-decoration / text-decoration-line |
子集 | none、underline、line-through 会绘制便宜的实线装饰。颜色/粗细/style 变体和 wavy/double 延后。 |
text-shadow |
子集 | 一条 <offset-x> <offset-y> [blur-radius] [color] shadow 会绘制为偏移文本。作者指定颜色会被保留;未写颜色时使用 currentColor。blur 只用于解析兼容,不做真实模糊;多重阴影暂不栅格化。 |
box-sizing |
可用 | content-box、border-box。 |
visibility |
有界子集 | 可继承的 visible 和 hidden 保留正常 layout 流。hidden 不绘制该元素自身,也不会成为命中目标;显式声明 visible 的后代可以绘制并接收输入。隐藏子树不会产生额外分配、cache 或 idle-frame 工作。collapse、accessibility tree 行为和浏览器 focus-navigation 语义继续延后。 |
overflow / overflow-y |
子集 | overflow 接受 visible、hidden、clip、auto、scroll。标准 overflow-y 只接受 auto 和 scroll,是显式纵向滚动的推荐写法;其他轴专属值会被拒绝,不会悄悄裁切两个轴。V0 原生滚动容器支持固定尺寸的垂直 auto/scroll 区域,由宿主提供 scroll offset,并参与裁切绘制和命中测试。VerticalScrollGesture 是零分配的宿主 helper,统一 tap/drag 阈值、开始拖动后取消控件激活以及有界惯性;宿主不驱动它时不会产生工作。Win32 壳会把 wheel/arrow/drag 默认动作先交给最近的可滚容器,不能滚时才回退页面滚动;ESP32-S3 retained-scroll demo 对队列触控使用相同规则。宿主在 dirty 面积预算内只重绘容器视口。保守的 strip-blit 快路径只用于安全的矩形、不透明、无覆盖容器;圆角、半透明、重叠容器会回退到 dirty repaint。overflow-x 和横向滚动仍延后。 |
white-space / text-wrap |
有界子集 | white-space: normal / nowrap 与现代等价别名 text-wrap: wrap / nowrap 共用同一 cascade slot 和布局路径。nowrap 会继承到文本 layout,阻止便宜换行。balance、pretty、text-wrap-mode 和 text-wrap-style 仍不支持。 |
overflow-wrap |
有界子集 | 支持 normal 和可继承的 anywhere。anywhere 只在合法 UTF-8 scalar 边界断行,且使用与绘制相同的 scalar 测量路径。不实现 hyphenation、字素/词典分词、break-word、balance/pretty 换行或复杂文字断行。额外 scalar 工作和 display command 只在声明该属性时产生。 |
text-overflow |
有界视觉子集 | 接受 clip 和 ellipsis。ellipsis 与继承的 white-space: nowrap 组合时,超宽文本会在 layer-tree 构建中按 UTF-8 标量安全截短,并绘制所有小型 bitmap font 都可显示的 ASCII ... 标记。该路径使用当前 host/app font 测量,且仅在作者声明且实际超宽时运行。多行省略、区域相关的 U+2026 选择行为和 browser line-clamp 语义继续延后。 |
opacity |
子集 | 0..1;软件合成中创建 composited layer。 |
position |
子集 | relative 只做视觉偏移,不改变普通流占位。absolute/fixed box 会脱离普通流,并用简单 inset 定位。sticky 目前只作为 layer hint 保存。 |
top / right / bottom / left |
子集 | 支持长度和 auto。Absolute/fixed box 使用父内容框或近似 viewport 原点。百分比、shrink-to-fit、完整 containing-block 规则和 sticky 滚动行为不支持。 |
| 逻辑 sizing/inset | LTR 子集 | inline-size / block-size、它们的 min- / max- 形式、inset、inset-inline / inset-block 及 start/end longhand 映射到现有 LTR 物理 width/height/inset 子集。writing mode 和 RTL 映射延后。 |
z-index |
子集 | 整数或 auto;目前是 layer-local ordering。 |
transform |
子集 | translate()/translateX()/translateY()、scale()/scaleX()/scaleY() 和 rotate()/rotateZ() 会解析为 composited layer,并由软件合成器绘制。角度支持 deg、turn、rad 和 grad。transform-origin 支持常用关键字和百分比。skew()、matrix()、perspective 和 3D transform 不支持,会诊断并忽略。 |
justify-content |
子集 | start、flex-start、normal、end、flex-end、center、space-around、space-between、space-evenly,作用于简化 row/column flex 的主轴。 |
align-items |
子集 | stretch、normal、start、flex-start、center、end、flex-end,作用于简化 row/column flex 的交叉轴。 |
align-self |
子集 | auto、stretch、normal、start、flex-start、center、end、flex-end 可为单个简化 row/column flex item 覆盖父容器交叉轴对齐。 |
align-content |
子集 | start、flex-start、normal、end、flex-end、center、space-around、space-between、space-evenly 仅在 row 换行且 flex 容器有额外固定/min-height 时分配行组。stretch 与 column 换行不支持。 |
place-content |
子集 | 一/两个值的 shorthand,会展开到文档化的 align-content / justify-content 子集。place-items 和 place-self 继续延后,因为缺少的 grid 对齐语义不能静默丢弃。 |
flex-direction |
子集 | 支持 row 和 column。row-reverse、column-reverse 会被拒绝,不做近似实现。 |
order |
子集 | 直接 flex child 可使用有符号整数 order。只有存在非零 order 时,layout 与同 stack 绘制顺序才构造一次稳定临时排序视图;默认全零的 flex 容器继续走无分配 source-order 路径。它不是供浏览器 API 使用的完整 order-modified document model。 |
flex |
子集 | Shorthand 支持常见 none、auto、<grow>、<grow> <basis> 和 <grow> <shrink> <basis> 形式,用于简化 row 和不换行 column flex layout。完整 Flexbox 语法不支持。 |
flex-grow / flex-shrink / flex-basis |
子集 | 非负数字 grow/shrink 因子和受支持长度/auto basis 会参与简化 row 和不换行 column sizing pass;column 中 basis 是高度基准。 |
flex-wrap |
子集 | wrap/wrap-reverse 启用简单 row 换行。column flex 有意保持不换行。换行后只做固定/basis 探测,不执行完整逐行 Flexbox 算法。 |
gap |
可用 | 1-2 个长度值,用于 grid 和简化 flex。 |
row-gap / column-gap |
可用 | 长度值。 |
grid-template-columns |
子集 | 从 repeat(auto-fit, minmax(<length>, 1fr))、minmax(<length>, 1fr)、单个长度或 1fr 中提取最小轨道。 |
grid-template-rows |
有界子集 | 支持 2 到 4 条固定长度或 1fr 行轨道。grid 有确定高度时,剩余空间会平均分给 1fr 行;没有确定高度时由内容提供最小高度。named line/area、带权 fr、repeat()、content-sized track、subgrid 与 masonry 延后。 |
| 简单固定 grid 列 | 子集 | 支持 grid-template-columns: <length> 1fr、repeat(N, 1fr)、repeat(N, minmax(0, 1fr)) 及相近的 2-4 列 length/fr 模板,适合描述列表、设置表单和紧凑键盘。 |
grid-auto-rows |
子集 | 长度或 minmax(<length>, auto) 最小行高。 |
grid-column / grid-row |
有界子集 | 支持正整数 start、span N、start / end、start / span N;span 有上限。显式 placement 覆盖已文档化的模板轨道,隐式 tracked row 最多 128 行。超出该行/span 上限的项会以 grid-placement-budget 放到 grid 之后的非重叠 block flow,而不是钳回最后一行。没有负 line、named line、auto grammar、grid-*-start/end longhand、dense packing 或浏览器 overlap resolution。 |
list-style / list-style-type |
子集 | none、disc-like 和 decimal-like 值。li 会绘制轻量原生列表标记。 |
content on ::before / ::after |
子集 | 支持纯文本和 counter(name) "suffix",用于轻量列表计数、单位和角标。Generated content 被绘制在元素盒内,并计入 display command 预算,不是真实 DOM 节点。完整 generated-content layout 延后。 |
box-shadow |
子集 | none 可清空阴影。一条外部 <offset-x> <offset-y> [blur-radius] [spread-radius] [color] shadow 会生成有界、圆角、二次衰减的软阴影命令。作者写入的 hex/rgb/rgba/color-mix() RGB 与 alpha 会被保留;未写颜色时使用 currentColor。blur 上限为 24 px,超过会输出 layer-box-shadow-blur-clamped。Inset、负 spread、多 shadow 和 blend mode 仍延后。只有声明 shadow 的元素才产生绘制工作;面积过大仍输出 layer-box-shadow-area-budget。 |
object-fit / object-position |
子集 | object-fit 支持 fill、contain、cover、none、scale-down。object-position 支持关键词和百分比的一/二值子集,例如 center、right top、25% 80%;复杂四值和长度偏移延后。 |
image-rendering |
子集 | 支持标准关键词 auto、pixelated、crisp-edges。auto 允许宿主 image painter 使用双线性/平滑采样;pixelated 和 crisp-edges 保持 nearest-neighbor,适合像素图标。 |
font-family |
runtime 子集 | 解析逗号分隔 family list。首个自定义 family 会规范化为小型 runtime hash;system-ui、sans-serif 等 generic family 会映射到宿主/系统 fallback。使用 app-font 后端时,manifest .jffont 的 family 若匹配该 hash,会优先于普通系统优先 fallback 链;layout 测量和 paint 使用同一选择结果。不实现完整浏览器 cascade、@font-face、style/stretch/features 和多字号匹配。Package diagnostics 仍会报告 generic family、manifest 匹配和未匹配首选 family。Win32 默认使用 GDI;传 --use-app-fonts 才验收包内 .jffont 选择。 |
requestAnimationFrame |
脚本子集 | JerryScript 构建中可用。宿主按每帧预算和时间戳泵动 callback。后台/低功耗 profile 可把 animation callback/FPS 预算设为 0。Win32 验证壳通过 --animation-fps、--animation-callbacks 和 frame-script 命令暴露这些预算,便于确定性低功耗验收。 |
CSS transition |
子集 | 支持 transition 和 transition-* 的有界列表,当前可动画属性为 opacity、transform: translate()/scale()/rotate()、background-color 和 color。timing 支持命名 linear/ease*,以及有界 cubic-bezier(x1, y1, x2, y2),其中 x1/x2 为 0..1,y1/y2 为 -2..2。Win32 调试壳会在交互状态变化时推进 timeline,并用 animation dirty-region helper 只重绘前后运动/绘制区域;layout 属性动画不做逐帧重排。 |
@keyframes / animation-* |
子集 | 支持有界 animation、animation-name、animation-duration、animation-delay、animation-timing-function、animation-iteration-count、animation-direction 和 animation-fill-mode。timing 支持命名曲线与同一有界 cubic-bezier() 子集。执行的 keyframes 仅限 from/to,属性限于 opacity、transform: translate()/scale()/rotate()、background-color 和 color;width、margin、grid/flex 等 layout 属性会诊断并忽略,不做逐帧 reflow。支持 normal/alternate、正整数或 infinite iteration,以及 none/forwards/backwards/both fill mode。只有显式声明 fill mode 才会保留首尾 override。不支持 play-state 和多个百分比关键帧插值。 |
| filter/backdrop-filter | 延后 | 不绘制。 |
当前长度单位包括 px、无单位 px-like 数字、rem、em 和简化 vh/vw。
width、height、min-width、min-height、max-width 和 max-height 会保留百分比值,
并在 layout 阶段相对 containing box 或根 viewport 解析。其他百分比长度仍使用保守 parser fallback。
min()、max()、clamp() 和简单
calc(A +/- B) 会在参数能归约为受支持长度时解析。这是保守 fallback,不是完整 CSS value algebra。
| 功能 | 状态 | 行为 |
|---|---|---|
| Block layout | 可用 | 垂直盒模型,支持 margin、padding、border、max-width、水平 auto margin。 |
| Inline text flow | 子集 | 文本和 inline 控件横向流动,并按可用宽度换行。 |
| Inline 背景/边框 | 子集 | 尽量收缩到文本/内容范围。 |
inline-block |
子集 | 表示为 inline-like render object,并具备可用盒行为。 |
| Flex | 子集 | 简化 row 支持基础 grow/shrink/basis sizing、justify、align、gap 和可选 wrapping;不换行 column 使用相同的主轴/交叉轴 sizing controls。direct flex child 支持有符号整数 order。无完整 Flexbox 算法、反向方向、baseline alignment 或 min-content sizing。 |
| Grid cards/forms | 子集 | 响应式 auto-fit/minmax 卡片 grid、gap、最小 auto rows、span、repeat(N, 1fr)、repeat(N, minmax(0, 1fr))、固定/fr grid-template-rows 与正整数 grid-column/grid-row start/end/span placement。无 named lines/areas、subgrid、dense packing。 |
| Aspect ratio | 可用 | 没有显式高度/内容高度时提供 intrinsic height。 |
| Positioned boxes | 子集 | 有界支持 relative、absolute 和 fixed 定位,适合 app overlay、角标和固定面板。Out-of-flow box 不占 block/flex/grid/inline placement 空间。 |
| Replaced elements | 子集 | 常见控件/媒体作为 leaf boxes,有 fallback 尺寸;真实 image/video layout 延后。 |
| 文本测量 | 子集 | core 暴露 TextMeasureProvider;fallback 很小但按 UTF-8 码点估算。Win32 壳使用 GDI 测量。HostTextAdapter 可包装 LVGL/vendor 测量 callback。 |
| Bidi/text shaping | 延后 | 生产级非拉丁文本需要平台 text backend 或后续 shaping 策略。 |
| Fragmentation/multicolumn | 延后 | 未实现。 |
| 元素/功能 | 状态 | 行为 |
|---|---|---|
button |
可用 / submit 子集 | 轻量原生风格绘制,默认近似按内容收缩,支持 click。form 内默认按钮或 type=submit 按钮会在 click 默认动作未被阻止时先执行有界校验,再派发可取消 submit。 |
input type=text 和默认 input |
可用 | 有 value 状态,宿主可输入 UTF-8 文本,支持 Backspace。 |
input type=search/tel/url/email/number |
子集 | 这些 ASCII 大小写不敏感的 type 会保留规范化 IDL type token,并走有界 text-entry 路径。没有浏览器键盘提示、URL/email/number 解析或对应 constraint validation。 |
readonly / maxlength |
子集 | 文本输入类控件会在用户输入路径遵守 readonly 和 maxlength。脚本写 value 仍是程序性状态修改;V0 校验会报告程序写入后超过 maxlength 的值。 |
input list / datalist |
子集 | 不显示原生 popup。获得焦点的文本输入框可用 Tab/Enter 接受第一个匹配的 datalist option。 |
textarea |
子集 | value-like 状态和基础绘制;完整多行编辑有限。 |
input type=checkbox |
可用 | checked 状态、点击激活、input/change 事件。 |
input type=radio |
子集 | checked 状态和绘制;同 name 互斥组仍有限。 |
input type=range |
可用 | track/thumb 绘制,拖动更新 value,并使用 min、max 和 step。 |
select / option / optgroup |
forms.advanced popup 子集 |
基础 profile 绘制当前选中项,并在激活时循环选项。启用 forms.advanced 后,单选 select 的点击或焦点激活会打开核心渲染的选项浮层;指针选择会提交 value 并派发 input/change,Up/Down 仍可跨 optgroup 在 option 间移动。浮层受 viewport 限制,无法显示全部选项时会告警;尚无 popup 滚动、multiple、原生 picker 或浏览器 top-layer/分组菜单行为。 |
progress / meter |
可用 | 根据属性绘制 value bar。 |
| 日期/颜色/文件控件 | 延后 | 暂用 text/select/range fallback。 |
| 表单验证 / form submission | 子集 | form 和控件级 checkValidity() / reportValidity() 及 submit 激活会检查 required、text/textarea minlength/maxlength、required checkbox/radio group 和 required select value。参与校验的控件提供新建的 validity 快照(valueMissing、tooShort、tooLong、customError、valid)、willValidate、validationMessage 和 setCustomValidity(message)。无效控件会收到不冒泡 invalid,但不绘制浏览器 popup。form.requestSubmit([submitter]) 会在校验成功并收集数据后派发可取消、带 submitter 的 SubmitEvent 形状 submit。form.reset() 及未取消的 button/input type=reset 激活会派发可取消、可冒泡的 reset;未取消时从作者 attribute/text 懒恢复控件状态,不保留 snapshot。browser navigation、action/method POST、multipart/file upload、pattern/type/date/range/step 校验、form.submit() 和其余 ValidityState 标志仍未实现。 |
dialog |
有界 modal 子集 | scripting 构建提供 open、returnValue、showModal() 和 close([returnValue])。每个 document 同时最多一个 showModal() dialog。宿主可为 Escape/back 调用 request_modal_cancel(),它先派发可取消 cancel,再派发 close。Win32 会在 rebuild 后重新安装 modal input gate,把 focus/hit test 限制在 dialog 内,并在关闭后恢复之前的 focus。不提供 show()、requestClose()、嵌套 modal、light dismiss、浏览器 top layer、backdrop 或完整 inert algorithm。 |
| IME | 壳层相关 | 核心接收 UTF-8 文本;平台壳负责输入法集成。 |
| 功能 | 状态 | 行为 |
|---|---|---|
EventTarget |
可用 | 按类型紧凑存储 listener。 |
| 捕获/目标/冒泡 | 可用 | 类 DOM 事件流。 |
preventDefault |
可用 | event object 记录取消状态。 |
stopPropagation / stopImmediatePropagation |
可用 | 已实现。 |
MouseEvent |
可用 | clientX、clientY、button、buttons、modifier 字段。 |
WheelEvent |
可用 | deltaX、deltaY、deltaMode、modifier 字段。 |
| Hit testing | 可用 | 基于 layer/layout geometry,考虑裁剪和 z-order hint。 |
| Pointer move/down/up | 子集 | 平台无关 input controller 派发 mouse-like events,并提供 pointerdown/pointerup aliases。滚动拖动是宿主默认行为,不是 HTML Drag and Drop;setPointerCapture()、pointercancel、touch-action、多指输入和完整 Pointer Events 字段仍延后。 |
| Click synthesis | 可用 | 同一目标 down/up 合成 click。 |
| Hash anchor click | 壳层限定 | Win32 壳会把 <a href="#id"> 处理为 viewport scroll。核心只派发 click 事件。 |
Focus tracking / tabindex |
子集 | InputController 保存 focused node、驱动 :focus / :focus-within,在真实焦点切换时派发不冒泡 focus/blur,并在创建时选择第一个可聚焦的 [autofocus] node。native control/link 及带非负 tabindex 的普通 element 会按 tree order 加入焦点导航;tabindex=-1 会跳过。正 tabindex 排序、脚本 focus()/blur()、focus-visible heuristic 和浏览器 focus scope 延后。 |
| Modal input gate | 宿主安装子集 | InputController::set_modal_root() 把 hit test、focus traversal 和 activation 限制到一个可见 dialog subtree。它不保存全局 inert 状态;只有宿主安装 root 时才工作。 |
| Touch events | 子集 | touchstart/touchend 以 mouse-like event 暴露,用于按下反馈;完整 multi-touch object 延后。 |
| Keyboard events | 延后 | 核心只处理控件所需的简单 key action;DOM keyboard event object 不完整。 |
JavaScript 只在 JELLYFRAME_BUILD_SCRIPTING=ON 且通过 JERRYSCRIPT_ROOT 配置本地
JerryScript 源码树时可用。
| API | 状态 | 行为 |
|---|---|---|
| Classic document scripts | 子集 | scripting 构建中,伪浏览器/Win32 壳会执行 inline classic <script>,并通过宿主 callback 加载本地外部 <script src>。 |
window / document |
子集 | 暴露下列方法。window、window.window、self 和 document.defaultView 指向同一个 JellyFrame window 对象;window.document 指向绑定的包内文档,window.navigator 指向嵌入式 Navigator 子集。包内文档暴露 origin === "null"、isSecureContext === false、crossOriginIsolated === false;不建模浏览器 URL/origin/security-policy 机制。 |
document.head / document.body |
可用 | 返回第一个 head / body element wrapper 或 null。V0 中只读,不暗示资源加载或 live document collection。 |
document.title / document.dir / document.readyState / document.defaultView / document.hasFocus() |
可用 | document.title 读取/写入第一个 title 元素文本。document.dir 反射 html 元素上的文档方向属性;简化文档中会 fallback 到 body/document。document.readyState 在 JellyFrame 绑定包内文档后始终为 complete;不模拟浏览器加载过程中的中间状态。document.defaultView 返回绑定的 JellyFrame window。document.hasFocus() 跟随嵌入式生命周期;宿主将文档标记为 hidden 时返回 false。 |
| Document collections | 子集 | document.images、embeds、plugins、links、forms、scripts 和 getElementsByName() 返回静态数组快照。它们不是 live HTMLCollection,不提供 named lookup 或浏览器 collection 方法。links 包含带 href 的 a/area 元素;plugins 与 embeds 返回同一类 embed 快照。 |
document.getElementById |
可用 | 返回 wrapper 或 null。 |
document.createElement |
可用 | 创建由 runtime 持有、等待挂载的 detached element;同时受 HostBudgets::max_detached_dom_nodes 与聚合 DOM 节点/深度/属性/字符串账本限制。 |
document.createTextNode |
可用 | 创建 detached text node,适用同一 detached root 与聚合 DOM 预算。 |
appendChild / append / prepend / removeChild |
子集 | appendChild 移动一个节点并返回它。append(...items) / prepend(...items) 接受现有 runtime-owned 节点和会转换为文本节点的标量值,保留参数顺序、防止环并标记 dirty;文本新增与深度变化会先预检,超预算的多参数调用不会留下部分修改。不接受 DocumentFragment;replaceChildren() 因多 wrapper 生命周期和 detached budget 需要独立事务设计,继续延后。removeChild 返回的节点会继续由 runtime 持有,保持可用。 |
setAttribute / getAttribute / removeAttribute / hasAttribute / toggleAttribute |
可用 / 子集 | 绑定层会 lowercase 属性名。新增/替换值会在 mutation 前检查聚合 DOM 字符串预算和每 element 属性上限。toggleAttribute(name[, force]) 采用普通 boolean attribute 风格的添加/移除并返回是否存在;空名称抛出 TypeError,而非浏览器 InvalidCharacterError。 |
Node.remove() |
可用 | 通过与 removeChild 相同的 runtime-owned detached-node budget 移除已连接 node;已 detached/root node 为 no-op。 |
textContent / innerText |
可用 / 子集 | textContent getter/setter;同值设置不会触发 dirty。替换会先预检节点和保留字符串预算,拒绝时保持旧 subtree。已有唯一 text child 时会原地更新;替换混合子节点仍是结构变化。innerText 在 element wrapper 上作为轻量 textContent 别名暴露;不执行浏览器 layout-aware rendered-text 算法。 |
id |
可用 | 反射到 id attribute,并走现有 style/layout dirty 路径。 |
className |
可用 | 反射到 class attribute,并走现有 style/layout dirty 路径。 |
title / lang / dir |
可用 | element wrapper 上的字符串属性反射。lang 和 dir 反射不等于完整语言特定 shaping 或 bidi layout。 |
| 元素专用反射属性 | 子集 | 对纯内容属性形式的常见低成本 IDL 反射提供支持:meta.name/content/httpEquiv/media、data.value、time.dateTime、img.alt、label.htmlFor、anchor 的 text/download/ping/rel,以及以字符串形式反射但不做浏览器 policy 规范化的 anchor referrerPolicy。label.control 会在访问时解析 for=id 或第一个可标记后代。导航、资源加载、图片解码、ping 发送、Shadow DOM/custom-element label 关联和完整 URL 工具仍不实现。 |
classList |
子集 | 极小 DOMTokenList-like helper,支持 contains(token)、add(...tokens)、remove(...tokens)、toggle(token[, force]) 与 replace(oldToken, newToken)。含空白 token 会被忽略而不是抛异常;无效的 replace() 返回 false。它反射到 class 并走正常 dirty 路径;迭代和完整 DOMTokenList 异常语义延后。 |
children / parentElement |
子集 | element children 快照数组,以及 parent wrapper/null。 |
matches / closest |
子集 | 简单 tag、.class、#id、[attr] 和 [attr=value] selector;不支持 combinator。 |
dataset |
有界子集 | 已存在的 data-* 属性以 camelCase property 读取。可写的 DOMStringMap 子集支持 dataset[key] = value 与 delete dataset[key],只接受 ASCII identifier-like camelCase key,并反射到普通 attribute dirty 路径;key 最长 48 bytes、value 最长 256 bytes、每个 element 最多 64 个 data-* attribute。不提供迭代、任意 key 或完整 DOMStringMap/prototype 语义。 |
getBoundingClientRect() |
frame snapshot 子集 | element 请求测量后,返回上一个完成的宿主 layout frame 的新数值对象 {x,y,width,height,top,right,bottom,left}。快照相对 client;Win32 壳会应用根页面 scroll,而 nested scroll 与 transform 后的几何仍延后。它绝不保存 LayoutBox*、不强制同步 layout,也不是 live DOMRect。runtime 最多保留 32 个已请求 element 的快照;首次或不可用快照返回零矩形。 |
element.style |
子集 | 可写 inline style object,支持常见安全 CSS 属性:display、color、background*、textAlign、textTransform、fontSize、fontWeight、lineHeight、尺寸/min/max 尺寸、boxSizing、margin/padding shorthand 与各边、opacity、transform、borderRadius、inset/position、visibility、whiteSpace、textOverflow、overflow、overflowY 和 zIndex。style.getPropertyValue(name)、style.setProperty(name, value) 和 style.removeProperty(name) 接受同一安全 CSS 属性子集,以及 --progress 这类 CSS custom property。 |
hidden / disabled / open / autofocus / tabIndex properties |
子集 | hidden、disabled、open、autofocus 为 Boolean reflection,tabIndex 为整数 reflection。hidden 提供默认的 display:none 行为,正常 author CSS 可以覆盖;当它使节点在重建后的 layer tree 中消失时,命中测试以及恢复的 hover/active/focus 状态会一并清除。CSS visibility:hidden 保留 layout,但走同一恢复交互状态清理。disabled 表单控件不会激活或接收文本输入;open 反射 details disclosure 和非 modal dialog 的可见状态。host 创建 InputController 时会消费 autofocus,tabIndex 只影响有界 hardware focus order。HTMLElement.focus() / blur() 继续延后:在 port 能跨 layer-tree rebuild 提供生命周期安全 adapter 前,焦点归属始终由 host 持有。 |
HTMLElement.click() |
子集 | 派发坐标为 0 的合成 mouse-like click。对 JellyFrame 控件会复用现有有界 activation 路径:checkbox/radio 状态变化会派发 input/change;forms.advanced 中单选 select 的 click 只会开关选项浮层,不提交 value;未被取消的 summary.click() 会切换父 details,未取消的 form submit button 会进入有界提交路径。不实现 browser navigation。 |
addEventListener / removeEventListener |
可用 | JS callback 桥接到核心事件派发。 |
on* event handler properties |
子集 | 只为 JellyFrame 实际派发的事件支持函数型 handler property:onclick、oninput、onchange、ontoggle、oncancel、onclose、mouse/wheel handlers、onfocus/onblur、document.onvisibilitychange、window.ononline/window.onoffline/window.onhashchange/window.onpopstate,以及可穿戴按下反馈别名 onpointerdown/onpointerup/ontouchstart/ontouchend。设置为 null 或非函数会清除 handler。它们复用普通 listener 预算和 runtime 清理路径。不实现完整 GlobalEventHandlers、HTML inline event handler attribute 或浏览器级 handler 编译语义。 |
| Event object | 子集 | type、target、currentTarget、phase、取消/停止传播 API、鼠标/滚轮字段。form submit event 还会暴露 submitter wrapper。 |
表单属性 / FormData |
子集 | 相关控件上的常用 IDL 属性:value、defaultValue、input defaultChecked、type、name、placeholder、required、checked、selectedIndex、readOnly、maxLength、minLength、min、max、step、willValidate、validationMessage、validity,textarea 的 rows/cols/wrap/textLength,select 的 size,option 的 label/defaultSelected/value/text/index,optgroup 的 label,以及 progress/meter 数值 value/min/max、meter 的 low/high/optimum 和 progress 的 position。控件提供 checkValidity()、reportValidity() 和 setCustomValidity(message);form wrapper 额外提供 requestSubmit() 和可取消 reset()。new FormData(form) 以及 append/set/delete/get/getAll/has/forEach 覆盖字符串 form entry。每个 FormData 在核心收集和 JS mutation 时都受 runtime entry/总 name+value 字节预算约束,默认是 32 entries / 4096 bytes,超限抛出 RangeError 且不保留部分收集结果。forEach 按 entry 顺序传入 (value, name, formData),在有界 entry 快照上运行;回调中新加的 entry 留待下一次调用。ValidityState 快照刻意只包含已实现的标志;labels collections、selection API、picker UI、file entry、iterator 方法和浏览器表单导航延后。 |
| Timer | 可用 | 宿主泵动 setTimeout、clearTimeout、setInterval、clearInterval;callback budget 由宿主控制。 |
| 脚本执行 watchdog | 宿主/runtime 可选 | 当链接的 JerryScript 使用 JERRY_VM_HALT=ON 构建时,JerryScriptRuntimeOptions::max_execution_check_count 与 HostBudgets::max_script_execution_checks 可中断失控 eval 和 callback,并给出 script execution budget exceeded。若 JerryScript 缺少该特性,JellyFrame 会报告 watchdog 不可用,不伪造抢占。Win32 验证壳可用 --require-script-watchdog 和有界 check 参数强制验收这条 recovery 路径。 |
btoa / atob |
部分支持 | 绑定 document 的 runtime 会在 window 和 global 暴露 Base64 helper。btoa 接受 HTML binary string,并拒绝超过 255 的 code point;atob 忽略 ASCII whitespace、容忍缺省 padding,并拒绝非法输入。错误目前使用 JellyFrame TypeError,不是 DOMException InvalidCharacterError。 |
| Promise/microtask | 延后 | 不要依赖浏览器 task 语义。 |
| App 内路由片段 / history | 子集 | window.location.hash / 全局 location.hash 为当前运行 app 保存一个 route fragment。fragment 改变时会在 window 派发不可取消的 hashchange;history.length、back()、forward()、go(delta)、pushState(state, title, url) 和 replaceState(state, title, url) 最多保留 max_route_history_entries 个 fragment entry。history 的 URL 参数只能为空或 #fragment;state/title 可传入但不保留,遍历时会先派发 popstate,fragment 变化再派发 hashchange。window.onhashchange / window.onpopstate 与普通 listener 共用预算。新 document 绑定时 fragment 和 history 重置。URL 加载、Location.assign/replace/reload、history.state、go(0) reload、浏览器导航、browsing context 与跨 app 路由均不存在。 |
| Modules/import | 打包期子集 | 一个外部 type="module" 入口可 import 一个有界、无环的 package-local .js 图。打包器会改写入口 HTML 并生成一个 classic bundle;原 module 不会留在最终 resources 中。支持 named/default/namespace import、named/default export 和副作用 import。inline module script、多个 module entry、循环、re-export、export *、远程/非 JS path、modulepreload 与动态 import() 仍延后。 |
querySelector / querySelectorAll |
子集 | 支持 document/element 上的简单 selector:tag、.class、#id、[attr]、[attr=value] 及同一 compound 内组合,例如 button.primary。返回静态 wrapper/数组快照,不是 live NodeList。不支持 descendant/child/sibling combinator、逗号、伪类、:has() 或完整 CSS selector API;复杂字面量会在 package report 中输出 script-api-subset。 |
innerHTML |
延后 | 使用 DOM creation APIs。 |
| XHR/fetch/storage | 部分支持 | scripting 构建已支持异步 XMLHttpRequest GET V0;绑定非阻塞 AppLocalStorageShadow 时支持极小 localStorage 子集;fetch() 等 Promise/microtask 有界后再考虑。 |
| 管线 diagnostics | 已开始 | HTML tokenizer/parser、CSS parser、style resolver、render tree、layout、layer tree、script collection、package/resource loader 和 software renderer 会通过可选 sink 向桌面工具报告预算截断、跳过、忽略、加载失败和降级。jellyframe_pseudo_browser --diagnostics-json 会输出结构化报告,jellyframe_cli.py check/preview/package 会把它合并到 pipelineDiagnostics。开发期视觉诊断还会报告横向溢出 visual-horizontal-overflow、垂直绘制溢出 visual-vertical-paint-overflow、页面需要滚动 visual-scroll-needed、内部滚动容器内容被裁切 visual-scroll-container 和 display command 密度过高 visual-display-command-density。常见布局诊断会尽量暴露面向 app 作者的解析字段,包括文本片段、紧凑节点标签、类似选择器的 DOM path、文本测量/可用宽度、滚动容器高度/溢出、paint bounds、viewport 和越界像素。横向和纵向溢出在可安全归因时会带上可能的 layout-box node/path 与 box overflow metrics。Package report 还包含 htmlApiDiagnostics,用静态 HTML 扫描提示浏览器专属标签、form submission 及响应式图片、表格、ruby、template、media、富文本等高风险 partial markup;还包含 scriptApiDiagnostics,扫描 manifest 不匹配以及 fetch()、Promise、复杂 querySelector、innerHTML、getBoundingClientRect()、pointer capture、动态 import()、WebSocket、EventSource、浏览器/消息 channel、Worker、session storage/cookie、浏览器 navigation 和 Selection/Range 等延后或子集 API。CLI 写出的 report 还会派生 developerAdvice[],作为 package warnings、管线 diagnostics、responsive profiles 和字体 diagnostics 面向 app 作者的解释/修复建议层;已知 crosswork 诊断会指向 package-local、Canvas、app route、host service 或 system component 等真实替代方案。结构化的文本/滚动/绘制溢出诊断会转成直接指出可能元素/文本和像素越界量的建议。针对 target 的建议带 targetViewport 与结构化 targetGate decision/reasons;字体建议在可用时带缺失 codepoint sample、target profile 和未匹配 CSS family。未知或无法分类的异常会保留 diagnostic code、stage/source 和触发 detail,让 app 作者至少能定位字段或片段。 |
| 性能预检报告 | 工具限定 | CLI 写出的 report 会从 package resources、responsive profiles 和伪浏览器管线统计派生 performanceSummary 和可选 performanceAdvice[]。summary 会报告 ok/watch/high-risk 等级、对象数量、layer/display-command 数量、framebuffer bytes、估算 pipeline heap、资源预算占比、full-frame present 规模、可用时的桌面工具侧阶段耗时,以及用于快速定位慢 UI 主因的 bottlenecks[] 短列表。这是预检归因,不是设备 FPS;--runtime-log 可合并 Win32 frame-script/capture 计数,--port-telemetry 可合并真实 port 的 frame ms、DMA wait、flush-done 和 internal-RAM 峰值,分别写入 runtimeMetrics / portTelemetry 和 measured performance summary 字段。 |
| Responsive profile report | 工具限定 | jellyframe_cli.py check/preview/package/install 可显式传 --targets a,b 或 --all-targets,对同一 package 按多个 target preset 跑 render-core pseudo browser,并在 report 写入 responsiveProfiles[]。它报告 viewport、shape、content height、横向溢出、是否需要滚动和 diagnostics 计数。manifest targets[id].gate 可声明发布前 accept/warn/reject 门槛,例如最小 viewport、是否允许滚动、是否允许横向溢出和 warning/error 上限;reject 会让 CLI 失败。普通单 target 路径不输出该字段,也不多跑额外视口。它是发布前适配检查,不是完整浏览器级 responsive/layout engine。 |
| 字体资源检查 | 工具限定 | jellyframe_font_resource_check 暂时保留用于确定性的字体工作:输出非 ASCII 使用字符、估算 bitmap font 预算,并验证嵌入式字体覆盖。 |
| 功能 | 状态 | 行为 |
|---|---|---|
| Display list | 可用 | 矩形、边框、渐变、文本和 image-surface-handle 命令,包含近似文本字重。Canvas 输出通过同一条有界 image command 路径集成。 |
| CPU framebuffer | 可用 | 软件 rasterizer/compositor 可输出 BMP/PPM。带预算的 compositor 会在分配前拒绝过大的主 framebuffer。 |
| 嵌入式 framebuffer adapter | 可用 | embedded_framebuffer 可把 HostFrameBufferView 转换到调用方持有的 RGBA8888/BGRA8888、RGB565/BGR565、RGB332、Gray8 或 1-bit 单色 buffer,并通过 callback flush dirty rects。EmbeddedPackedRgb565Sink 还可把每个 dirty rect 直接转换为紧凑、宿主原生的 RGB565/BGR565 word buffer,供同步面板路径使用;它是可选的 presentation contract,不是性能保证,每个 port 都必须与线性 framebuffer 路径进行 A/B 实测。RGB565/BGR565 target 可选择开启 4x4 ordered dithering;可选 EmbeddedFrameBufferPresentStats 会报告 converted pixels、packed bytes、clipped/empty rects 和 flush count,供开发板 bring-up 对齐真实 panel 指标。 |
| Source-over alpha | 可用 | straight-alpha 合成。 |
| Opacity layer | 子集 | opacity/composited layer 使用离屏合成。嵌入式宿主可限制 offscreen pixels;超限 layer 会降级为逐命令直接透明绘制,避免分配过大的临时 buffer。相同上限也覆盖裁剪 text/image 的临时 surface:text 会跳过,image 以带裁剪的占位色和 paint-transient-surface-budget 降级。 |
| 圆角填充 | 子集 | 背景/阴影支持 rounded rectangle fill clipping;圆角 fill/stroke/gradient 边缘使用局部 coverage 抗锯齿,普通不透明直角矩形仍走快速填充路径。 |
| 边框绘制 | 可用 | 边框拆成 fill rectangles。 |
| Render Core flex-grid profile | 构建期可选 family | css.flex-grid 将简化 flex/grid 的 parser、computed-style 字段、layout pass 和 flex order 绘制排序作为一条垂直 family 门控。关闭时 flex/grid 声明及命中的 @supports 条件都会被拒绝,布局回退到 block/inline,也不要求 minimal profile 注册 flex/grid 专属测试或示例。Canvas/modern-paint/flex-grid/advanced-forms 的 profile 组合使用确定且不重复的名称;是否在受限固件启用仍须由移植侧提供链接、flash/RAM 和启动成本数据。 |
| Render Core modern-paint profile | 构建期可选 family | css.modern-paint 将有界渐变和阴影栅格路径作为一条垂直 feature family 裁剪。生成的 profile 必须与桌面链接 map 一致;关闭时不会链接 modern_paint.cpp,渐变使用首色/纯色 fallback,阴影不生成专属 command。App 不能加载 native feature module。 |
| Render Core advanced-forms profile | 构建期可选 family | forms.advanced 裁剪本地 constraint validation、custom validity、有界 FormData、SubmitEvent、requestSubmit() 及可取消的 form reset/default action。关闭时基础控件仍可输入,但激活不再 submit/reset,脚本层也不暴露 FormData、validity、checkValidity()、requestSubmit() 与 reset()。公开 C++ API 仍由安全 no-op stub 保持可链接;App 不能在运行时启用此 family。 |
| Linear gradient | 子集/按 profile 裁剪 | 包含 css.modern-paint 时支持两色水平、垂直和有界对角命令;不透明方角可穿戴路径有独立 fast path。jellyframe_render_core_microbench 报告 p50/p95 栅格耗时,但不把桌面数据冒充设备 FPS。 |
| Conic gradient | 子集/按 profile 裁剪 | 包含 css.modern-paint 时支持从 12 点开始的两段顺时针进度命令,只在使用时栅格化;普通矩形和线性渐变保持原快路径。Stop 必须连续覆盖 0%..100%;越界会诊断,不静默夹取。 |
| Radial gradient | 子集/按 profile 裁剪 | 包含 css.modern-paint 时支持两色中心圆形径向渐变,用于小面积高光、胶感卡片和表盘光斑;不支持焦点偏移、椭圆、多 stop、repeating 或多层背景。大面积使用会输出 layer-radial-gradient-area-budget。 |
| 文本 | 子集 | 核心 fallback 是极小 ASCII bitmap 绘制,并为 UTF-8 非 ASCII 码点显示占位 glyph。Win32 壳注入 GDI,可验证 UTF-8/中文。 |
| 中文文本 | 壳层相关 | 用 Win32 壳或未来平台 text backend。伪浏览器 fallback 会显示占位 glyph。 |
| 图片 | 宿主可选/包内 BMP V0 + codec adapter 形状 | 已有平台无关 ImageDecodeMock、AppImageSurfaceCache、Surface handle 生命周期和尺寸/decoded bytes/pending 预算检查。render core 支持 ImageHandleResolver + image display command + ImagePainter;页面应使用 package-local 标准路径,例如 <img src="/assets/icon.bmp"> 或相对 URL。Win32 壳可从 .jfapp/源码包加载无压缩 24/32-bit BMP 作为包内图片 V0;它的私有 debug fixture 只属于壳层验收,不是 app 语法。AppImageCodecAdapter 已定义 PNG/JPEG/WebP/厂商 codec 的产品级解码器边界,app_image_codec_result_within_policy(...) 会在 decoded surface 变成 handle 前做预算校验。AppImageSurfaceCache 可按 ready surface 数量和 decoded bytes 回收未被当前 display list 引用的 LRU surface;旧 app completion 会被拒绝,stale ready entry 可在 eviction 时丢弃并报告;图片命令携带 object-fit、简单 object-position 和 image-rendering 子集;auto 路径使用双线性缩放,pixelated/crisp-edges 保留硬边采样。Package report 包含 imageDiagnostics,会分类 package 图片 codec、读取轻量 BMP/PNG metadata,并与 target hostServices.imageDecode / imageCodecs 声明进行对比。图片 request 拒绝和 completion 失败会归类为稳定原因,例如 capability-denied、resource-not-found、decode-budget-exceeded 和 surface-budget-exceeded;diagnostic_detail_for_url(...) 会暴露稳定的 src/state/reason/submit 以及可选 host/job/handle/byte 字段,供桌面工具和移植日志使用。真实 PNG/JPEG/WebP decoder 和复杂 position 语法仍属于 port/未来工作。 |
| 静态 SVG 图标构建 | 打包期子集 | package_app.py --rasterize-svg 会把 HTML/CSS 静态引用的图标 SVG 编译为生成的 32-bit BMP 路径,并在打包前改写引用。源 SVG 不会进入包,也不会链接运行时 SVG parser。输入只接受 svg/g、除 arc 外的 path 命令、基础图形、纯色 fill/stroke、unitless/px 尺寸和 viewBox;脚本、外部资源、transform、文本、filter、渐变和 JS 动态引用会以源路径给出可修复失败。package report 的 staticSvgRasterization 记录源/产物路径、尺寸和图形数量。 |
| 音频播放 | 宿主可选/runtime mock | 核心不处理 PCM/I2S/codec。app_runtime 已有 AudioCommandMock,覆盖 open/play/pause/stop/close/setVolume、AudioStream handle 生命周期、ended/error completion 和 stream 预算检查。音频 request 拒绝和 completion 失败会归类为稳定原因,例如 capability-denied、invalid-source、source-not-found、invalid-handle、stream-budget-exceeded、command-timeout 和 command-cancelled;app_audio_failure_detail(...) 会暴露稳定的 source/reason/submit/host/error 字段。JerryScript 构建暴露宿主可选、接近标准形状的极小 Audio V0:new Audio(src)、src、volume、play()、no-op pause()、onended/onerror,以及面向 ended/error 的 addEventListener/removeEventListener。Win32 壳会把它绑定到包内/本地音频资源,并按调试播放估算派发 ended;同时仍提供 --audio-smoke 验证本地文件或 /audio/tone.wav 这样的包内路径。manifest 可声明 media.audio.playback,但真实 MCU MP3/I2S 播放仍归宿主/移植层。 |
| 后台服务 | manifest 意图/runtime policy | jellyframe.app.json 的 backgroundServices 可声明网络、音频、传感器或定位是否希望在 suspended、screen-off 或传感器/定位 low-power 状态继续活动,但它本身不授予权限。AppBackgroundServicePolicy 会结合 host profile/system state 生成 AppServiceActivityPolicy:前台 app 正常运行,未批准的后台工作暂停,音频可被暂停,传感器可被节流,定位快照可被延后,且不污染 render core。 |
| Target service support | 工具限定 | Target preset 可用 hostServices.networkFetch、storageKv、audioPlayback、imageDecode、imageCodecs、语义传感器和定位字段描述目标可选服务。serviceIntent.targetSupport 会按 supported/unsupported/unknown 报告 app 请求的服务支持状态,imageDiagnostics 会报告 package-local 图片资源的 codec 目标支持状态。当 app 请求明确 unsupported 的服务时,package/check 输出 service-target-unsupported warning。它是开发期兼容性提示,不是权限授权。 |
| Host service workers | 平台无关 pump | pump_app_host_service_worker(...) 提供极薄的真实宿主服务 worker 边界:一次只处理一个 HostServiceJobKind,completion 保留 request 身份,UI completion queue 已满时不弹出 request。若 request 已归 worker 后队列才满,其 completion 会留在已有的有界 in-flight slot,直到 UI frame 可投递,因此不会静默丢失。HostHandleTable 操作受同步保护,且只提供 copy-out 查询;worker 不得保留表内指针。DOM/JS/layout/framebuffer 始终只归 UI task。它不创建线程,也不执行 I/O。 |
| 轻量视频/MJPEG/H.264 | 实验/宿主可选合同 | media.video.frame 为 MJPEG 以及显式启用的 H.264 baseline 提供有界最新帧路径。每个 source 只有一个 request;替换帧无法分配时保留旧帧,替换成功后丢弃过期帧。<video> 仍不支持;ESP32-S3 H.264 复测仍属实验,不进入默认 profile。 |
| SVG | 包期图标子集;运行时延后 | 没有 SVG renderer 或 SVG DOM。package --rasterize-svg 可在输入符合文档化受限词汇时,把一个静态 package-local 图标源转换为普通生成 BMP;非法或动态 SVG 会以源路径给出可修复失败。自定义图表可使用 DOM/CSS 盒子、图片或可选 Canvas 2D V0.4。 |
| 真实 shadow blur | 延后 | box-shadow blur 只近似。 |
| Filter/blend modes | 延后 | 仅 normal source-over。 |
| GPU compositing | 延后 | 当前 CPU-only;layer model 为未来硬件后端留接口。 |
| 机制 | 状态 | 行为 |
|---|---|---|
| Dirty propagation | 可用 | mutation 会把 dirty bits OR 到当前节点和祖先。 |
| Dirty check | 可用 | 因为祖先保存聚合 dirty bits,根节点检查为 O(1)。 |
| Dirty clear | 可用 | 清理时跳过干净分支。 |
| 宿主合并重绘 | 子集 | Win32 壳会在 input/script callback 后只对 dirty DOM 重绘。Win32 壳的 viewport scroll 会复用已有完整内容 framebuffer,并在可行时通过移动行和只复制新露出行来更新可见 blit buffer。port 可选择调用 coalesce_dirty_rects_into(...),以有界的额外绘制面积换取更少的通用 present 调用;成本策略由 port 自己提供,未使用的 app 不会为此付费。 |
| 增量 style/layout | 子集 | paint-only 表单控件状态变化可在 Win32 验证壳中复用 render/layout,只重建 layer/display commands。受保护的 same-box 单行文本路径也可在更新后文本测量结果仍匹配旧 layout box 时复用 render/layout。受保护的 style/class 路径会在 render tree 形状不变、所有影响 layout 的 style 字段不变时复用 layout;color、background、opacity、transform 等 paint/compositor 变化可以走这条路径。transform 变化会复用 animation invalidation helper,因此旧 bounds 和新 bounds 都会重绘。换行文本、影响 layout 的 style、未知结构变化和树结构变化仍重建 render/layout。 |
| Dirty rectangle repaint | 子集 | dirty_region 会通过对比旧/新 layout box,或对 paint-only 变化复用同一份 layout,为直接文本、属性、表单控件绘制变化计算有界重绘区域。瞬态的核心绘制弹层(例如 forms.advanced 的 select 弹层)是树结构变化全屏回退的明确例外:宿主必须同时传入旧、新 LayerNode tree,核心会把旧、新 LayerReasonTransientOverlay bounds 与控件本体 bounds 合并,因此打开和关闭都无需全屏重绘。真正的树结构变化仍保守重绘 viewport。若估算 dirty area 过大,宿主也可以选择全帧重绘,避免局部 flush 反而更贵。软件 compositor 会在 clip replay 前丢掉重复或被完全包含的 dirty rectangles,避免同一区域被反复清屏/重绘。 |
| Animation invalidation | 子集 | animation_invalidation 可根据上一帧/当前帧的 animation style overrides,在当前 layout tree 上生成局部 dirty rectangles,覆盖 opacity/color paint-only 动画和 translate/scale/rotate transform 前后位置。目标已拥有 layer 的 opacity-only 帧可复用该 layer 的 display list;其余动画更新仍保守重建 layer tree。 |
| Display invalidation 诊断 | 可用 | analyze_display_invalidation(...) 会报告 dirty rectangles 对 layer 和 display command 的覆盖情况。Frame planning 已能让 paint-only 和 stable-layout 变更复用现有 frame/layout 状态;完整 retained display-list diffing 仍延后。 |
| Frame dirty 诊断 | 可用 | Win32 脚本化 capture 会报告本轮 dirty flag 分布(tree、attributes、text、style、layout、paint、overlay、render_or_layout)、text_stable、style_stable、overlay_dirty 等 frame-update 原因,以及最终 layer_tree layers=N display_commands=N 计数。开发者可据此判断页面帧耗时主要来自 layout 型 DOM 变化、便宜的 paint-only 更新、瞬态弹层,还是 display-command-heavy 页面。 |
| Per-app budget snapshot | 可用 | AppBudgetSnapshot 报告当前 app instance、role/state、host service 队列、host handle/bytes、app fonts、system events、localStorage shadow 计数、frame-loop callback 上限、active animations,以及宿主提供时的 script timer/listener/detached-node 计数。Win32 frame capture 会打印这个摘要;MCU port 可采样同一个只含计数的结构用于串口 diagnostics 或恢复决策。 |
| Budget recovery | 可用 V0 | app_budget_recovery_for_snapshot(...) 会把耗尽的 runtime budget 分类为 none、warn 或 terminate-app。队列、handle、font、system-event 和 script object 耗尽会升级为 budget-exceeded app recovery;frame callback 与 active-animation 上限只警告,因为 frame policy 可以节流。Win32 system-shell 模式会输出 budget_recovery_teardown reason=budget-exceeded 并回到 launcher,用于验收坏 app 不拖垮系统。 |
| Host frame sink | 子集 | present_frame 可以通过 HostFrameSink 暴露 FrameBuffer,并携带可选 dirty rects。成功 present 是 frame buffer 可复用边界:异步 panel/DMA 宿主必须等待、复制到 driver-owned 内存,或阻止下一帧 render 直到 flush 完成。embedded_framebuffer 已提供可移植像素转换;真实显示 I/O 仍由宿主负责。 |
| Host device capabilities | 草案 | HostDeviceCapabilities 记录开发板 port 的显示、输入、内存、budget 和服务 flags。当前核心把它作为契约/策略输入文档;更深的自动适配仍延后。 |
| Device Runtime / JFDP | 参考实现 | DeviceInstallTransaction、DeviceCapabilitySnapshot 和 JFDP/1 framing 已提供平台无关的有界安装事务、capability handshake 数据、稳定结果码与消息完整性校验;CLI 的 device --transport reference 只操作桌面 registry reference endpoint,明确不代表真实板卡已可连接。真实 discovery、flash/storage、display/touch、logs 和 telemetry 必须由官方 port image 实现。 |
| Host budgets | 子集 | HostBudgets 已接入 HTML/CSS parsing、render/layout/layer tree 上限、display-list 上限、dirty rect 数量、frame-loop input/timer/animation 上限、JerryScript timer/rAF/listener 限制、detached DOM node 限制和软件 compositor 的主/offscreen pixel 上限。Render/layout/layer tree 已有 arena-backed 构建路径;完整 mutable DOM arena 仍是后续工作。 |
| Frame scratch | 可用 | FrameScratch 复用 dirty-region bounds、dirty rectangles 和 animation overrides;AppFrameScratch 复用 host completion batch/accepted list。常规帧清空复用,息屏、切 app 或内存压力时显式 release()。真实 DMA/panel buffer 仍由 port 管理。 |
实际含义:脚本中多次 DOM mutation 应尽量放在同一次事件或 timer callback 内。宿主会观察到一次 dirty 并重绘一次。paint-only 表单控件变化在 Win32 验证壳中可以避免 render/layout 重建;其他变化仍会走简化管线 pass,但 framebuffer 阶段已经能对非结构性变化做有界 dirty rectangle 局部重绘。
- 交互节点优先使用稳定
id。 - 使用简单 selector 和 class-based styling。
- 仪表盘/卡片 UI 使用已支持的 grid-card 子集。
- 使用
button、input、select、textarea、progress、meter,不要手写 canvas 控件。 - 对现代 CSS 值写 fallback,例如:
color: #334155; color: oklch(...);。 - 不要把必需 UI 放进
@container、不支持或复杂的@supports、不支持/复杂 media query 或:has()等不支持 selector 函数里。 - 脚本保持同步、小型;数据由宿主提供。
- 中文/UTF-8 可读性验收使用 Win32 壳,因为它同时通过文本后端 API 注入测量和绘制。
- 页面保持小而有界;parser limit 是设计目标,不是 bug。
- CSS parser:
max_rules4096,max_declarations_per_rule256,max_nesting_depth8,默认 media viewport 为 360x240。 - 默认 host budgets 会限制 DOM nodes、render objects、layout boxes、layers、 display commands、dirty rects、timers、listeners 和 framebuffer pixels。
- 诊断/示例工具会限制输入文件,通常为 512 KiB 或 1 MiB,取决于工具。
- Grid 自动列数内部有界,以保证嵌入式内存可预测。
- 当前 JerryScript 构建假设同一进程内只有一个 active runtime。
适合新增:
- 嵌入式应用作者常用。
- 可用整数或有界算法计算。
- 能一致降级。
- 不要求网络、GPU、字体加载或大型浏览器服务。
应延后:
- 会引入 style/layout 反馈循环,例如
@container。 - 需要大型外部子系统,例如完整 image decode、font shaping、无界 canvas。
- 依赖完整浏览器 task/loading 模型。
- 会造成“半现代半老旧”的不一致视觉结果。