diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7a5438b..27cc0cf 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -61,8 +61,12 @@ jobs: test "$("$core" examples/language/问候项目.yx)" = $'你好，言序\n你好，开发者' desktop-examples: - name: 桌面生态示例 + name: 桌面生态示例（言序 ${{ matrix.yanxu }}） runs-on: ubuntu-24.04 + strategy: + fail-fast: false + matrix: + yanxu: ['1.1.9', '1.1.20'] steps: - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 - name: 安装原生窗口运行依赖 @@ -71,14 +75,15 @@ jobs: sudo apt-get -o Acquire::Retries=5 install -y \ libfontconfig1 libwayland-client0 libxkbcommon0 libxkbcommon-x11-0 \ libx11-6 xvfb - - name: 检出言序 1.1.9（言界已验证基线） + - name: 检出言序 ${{ matrix.yanxu }} uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 with: repository: YanXuLang/yanxu - ref: v1.1.9 + ref: v${{ matrix.yanxu }} path: target/yanxu-core - - name: 构建言序并锁定言界 + - name: 构建言序并锁定言界 1.0 run: | + grep -Fx '言界 = { 包 = "yanxu-ui", git = "https://github.com/yanxulang/yanxu-ui.git", 修订 = "v1.0.0", 版 = "^1.0" }' examples/desktop/言序.toml cargo build --manifest-path target/yanxu-core/Cargo.toml --locked --bin yanxu target/yanxu-core/target/debug/yanxu 包 更新 examples/desktop - name: 核对文档源码、格式与静态类型 diff --git a/content/docs/ecosystem/desktop/accessibility.mdx b/content/docs/ecosystem/desktop/accessibility.mdx new file mode 100644 index 0000000..099b860 --- /dev/null +++ b/content/docs/ecosystem/desktop/accessibility.mdx @@ -0,0 +1,66 @@ +--- +title: 原生无障碍 +description: 用同一棵言界控件树接入 Windows UIA、macOS NSAccessibility 与 Linux AT-SPI。 +--- + +言界 1.0 把控件树转换为言台无障碍协议 1.0 的纯言序语义树。言台再把同一模型注册到 +Windows UIA、macOS NSAccessibility 或 Linux AT-SPI；应用不接触系统对象、原始指针或 +平台条件分支。 + +## 内置控件语义 + +每个控件存活期间拥有稳定正整数编号，并公开角色、逻辑像素边界、名称、描述、状态、值、 +动作和子节点。应用应为没有充分可见文字的控件设置名称： + +```yanxu +定 姓名 为 表单.输入框（{「占位」：「姓名」}）； +姓名.可访问名称（「账户姓名」）； +姓名.必填（真）； + +定 保存 为 表单.按钮（「保存」）； +保存.可访问描述（「保存当前账户设置」）； +``` + +`显示`、`启用`、`可聚焦`、`只读`、`必填`、`无效`、焦点、选择和忙碌状态会按角色映射。 +值只允许空、逻辑值、有限数或有界文字；集合数量、加载错误和其他诊断不应塞进值字段。 + +## 焦点与动作 + +内置控件把辅助技术请求复用到已有交互路径： + +| 控件 | 主要动作 | +| --- | --- | +| 按钮、复选框、单选框、切换 | 点击、选择 | +| 下拉选择、滑块、输入框 | 设置值；按控件支持展开、折叠、增加、减少或选择 | +| 滚动、列表项 | 滚动、选择、滚动到 | +| 标签、分割面板 | 选择或调整比例 | +| 菜单、菜单项、弹出层 | 点击、展开、折叠 | + +请求携带窗口、当前树修订和节点编号。言界先同步尚未提交的语义变化，再重新查找当前控件， +核对可见、启用、可聚焦状态和参数；旧修订、离开可见范围的列表项、已关闭控件或未声明动作 +都会被拒绝，不会转成普通事件。 + +## 同步与检查 + +通常由窗口在显示、布局、重绘和状态变化时自动同步。测试和诊断可以显式读取： + +```yanxu +定 摘要 为 窗口.同步无障碍（）； +定 快照 为 窗口.无障碍快照（）； +``` + +快照包含修订、节点数、文字字节、焦点和规范化树。单窗口最多 16384 个节点、深度 64、 +总文字 4 MiB；普通列表和虚拟列表只为当前可见范围生成最多 256 个`列表项`节点。密码框 +不把值或文字运行交给系统桥，内容安全诊断也不复制语义文字树。 + +自定义控件覆写语义时应保留父实现的编号、边界和通用状态，只声明已经实现的动作，并在 +执行动作时再次校验当前状态和参数。完整角色、状态、动作组合与限制见 +[言台协议](https://github.com/yanxulang/yanxu-platform/blob/v1.0.0/docs/ACCESSIBILITY_PROTOCOL.md)和 +[言界接入指南](https://github.com/yanxulang/yanxu-ui/blob/v1.0.0/docs/ACCESSIBILITY.md)。 + +## 上线验收 + +六目标 CI 验证适配器创建、树同步、焦点／动作回传和关闭收敛，但不能替代实际辅助技术的 +播报。发布前应分别使用 Windows Narrator、macOS VoiceOver 和 Linux Orca 检查名称、焦点 +顺序、必填／无效状态、表单改值、菜单层级、列表项和窗口关闭。运行时还应确认言台能力 +查询报告`原生无障碍桥 = 真`及预期的 UIA、NSAccessibility 或 AT-SPI 后端。 diff --git a/content/docs/ecosystem/desktop/animation.mdx b/content/docs/ecosystem/desktop/animation.mdx new file mode 100644 index 0000000..55452c7 --- /dev/null +++ b/content/docs/ecosystem/desktop/animation.mdx @@ -0,0 +1,67 @@ +--- +title: 动画与帧反馈 +description: 用言台呈现反馈驱动有界动画，并通过单槽背压避免无界帧队列。 +--- + +言界 1.0 动画使用言台 1.0 的帧提交回执和`帧呈现`事件，不用固定间隔计时器猜测窗口何时 +完成绘制。每个窗口只保存一个待呈现帧；应用持续更新时，新帧有界替换旧帧，不形成无界 +渲染队列。 + +## 创建动画 + +`窗口.动画（配置，更新回调）`返回动画任务： + +| 字段 | 默认值 | 边界 | +| --- | --- | --- | +| `起值` | `0` | 有限数，起终跨度也必须有限 | +| `终值` | `1` | 有限数，起终跨度也必须有限 | +| `时长毫秒` | `140` | 1–3600000 | +| `缓动` | `线性` | `线性`、`缓入`、`缓出`、`缓入缓出` | +| `完成` | 空 | 可选回调，只在正常到达终点后调用一次 | + +```yanxu +法 更新（值） 则 + 进度.值（值）； +终 + +法 完成（） 则 + 提示.内容（「完成」）； +终 + +定 任务 为 窗口.动画（{ + 「起值」：0， + 「终值」：100， + 「时长毫秒」：600， + 「缓动」：「缓入缓出」， + 「完成」：完成 +}，更新）； +``` + +任务公开编号、状态、运行中、取消和快照。状态为运行中、完成、已取消或失败；更新／完成 +回调抛错只终止当前任务，其他动画和事件循环继续。每窗最多 1024 个活动动画，底层队列 +硬上限为 4096。窗口关闭会取消活动任务，不再访问已释放平台资源。 + +## 呈现反馈链 + +1. 注册任务时立即写入起值并请求首帧； +2. `需要重绘`生成完整帧，并取得提交帧序号； +3. 匹配的`帧呈现`携带进程内单调呈现时间； +4. 言界用该时间推进活动任务并请求下一帧； +5. 到达终值后提交静态终帧，终帧呈现后停止调度。 + +提交回执中的`被替换帧`会替换唯一待呈现身份，旧帧此后不会驱动动画。窗口隐藏、最小化 +或表面尺寸为零时反馈可以暂停；恢复后的重绘按当前单调时间追赶，不积累计时器或帧任务。 +`帧呈现`表示软件缓冲已交给原生表面，不等同于显示器垂直同步时间戳。 + +## 诊断与性能 + +窗口诊断提供待呈现身份、提交、替换、呈现、忽略、失败、最后延迟，以及动画活动数、高 +水位、完成、取消和失败总数。诊断不保存更新回调或控件内容。提交失败会恢复全量脏区， +便于调用方处理错误后重试。 + +言界 Release 在固定 Linux x86-64 环境测量动画任务生命周期、帧反馈、64 个活动任务诊断 +以及 32 控件布局／帧编码；报告使用预热、长样本、中位数和 MAD 门禁。性能预算用于发现 +持续回归，不承诺任意机器的显示延迟，也不替代六目标真实窗口测试。 + +完整契约见 +[动画、帧反馈与运行诊断](https://github.com/yanxulang/yanxu-ui/blob/v1.0.0/docs/ANIMATION_AND_DIAGNOSTICS.md)。 diff --git a/content/docs/ecosystem/desktop/api-reference.mdx b/content/docs/ecosystem/desktop/api-reference.mdx index fe0c5aa..7c6efdd 100644 --- a/content/docs/ecosystem/desktop/api-reference.mdx +++ b/content/docs/ecosystem/desktop/api-reference.mdx @@ -9,23 +9,30 @@ description: 言界常用公开入口与言台版本化原语的索引。 引「包:言界」为 界面； 引「包:言界/几何」为 几何； 引「包:言界/文本」为 文本； +引「包:言界/数据源」为 数据； 引「包:言界/配置」为 配置； 引「包:言界/错误」为 错误； ``` | 对象 | 常用方法 | | --- | --- | -| 应用 | `窗口`、`主题`、`主题配置`、`监听`、`定时器`、`加载图片`、`运行`、`退出`、`关闭` | -| 窗口 | `行`、`列`、`堆叠`、`网格`、`显示`、`隐藏`、`标题`、`大小`、`关闭时`、`快捷`、`关闭` | -| 通用控件 | `显示`、`启用`、`可聚焦`、尺寸、边距、伸展、样式、监听、捕获、可访问名称／描述、`关闭` | -| 内容控件 | `内容`、`取内容`、`点击`、`变化时`、`选择范围` | -| 容器 | 行、列、堆叠、网格、滚动、列表、标签页、分割面板、菜单、弹出层、画布、图片 | +| 应用 | `窗口`、主题、监听、资源配额、托管定时器／图片、诊断、生命周期、运行、退出、关闭 | +| 窗口 | 容器、显示、标题、大小、快捷、动画、无障碍同步、诊断、生命周期、关闭 | +| 通用控件 | 显示、启用、可聚焦、只读、必填、无效、尺寸、边距、样式、事件、语义、关闭 | +| 表单控件 | 文字、按钮、复选框、单选框、切换、下拉选择、滑块、进度条、输入框 | +| 数据与导航 | 滚动、列表、虚拟列表、标签页、分割面板、菜单、弹出层 | +| 绘制与资源 | 画布、图片、帧反馈动画、托管图片生命周期 | | 系统服务 | 剪贴板读取／写入、打开文件／多个文件、保存文件、选择目录／多个目录 | -完整、由源码快照生成的签名参考见[言界 REFERENCE](https://github.com/yanxulang/yanxu-ui/blob/v0.1.1/docs/REFERENCE.md)，叙事 API 见[言界 API](https://github.com/yanxulang/yanxu-ui/blob/v0.1.1/docs/API.md)。 +1.0 冻结 30 个声明、23 个类、7 个包级函数、125 个域和 375 个方法。完整、由源码快照 +生成的签名参考见[言界 REFERENCE](https://github.com/yanxulang/yanxu-ui/blob/v1.0.0/docs/REFERENCE.md)， +叙事 API 见[言界 API](https://github.com/yanxulang/yanxu-ui/blob/v1.0.0/docs/API.md)，稳定范围 +见[支持政策](https://github.com/yanxulang/yanxu-ui/blob/v1.0.0/SUPPORT.md)。 ## 言台原语 -普通应用只依赖言界。自定义框架、后端调试和协议工具可查阅[言台平台 API](https://github.com/yanxulang/yanxu-platform/blob/v0.1.0/docs/PLATFORM_API.md)与[生成签名](https://github.com/yanxulang/yanxu-platform/blob/v0.1.0/docs/API.md)。 +普通应用只依赖言界。自定义框架、后端调试和协议工具可查阅[言台平台 API](https://github.com/yanxulang/yanxu-platform/blob/v1.0.0/docs/PLATFORM_API.md)与[生成签名](https://github.com/yanxulang/yanxu-platform/blob/v1.0.0/docs/API.md)。 -言台公开应用、窗口、显示器、事件批次、输入法、光标、计时器、字体、文字整形／测量／命中、图片、完整帧提交、剪贴板、文件对话框、协议查询、能力查询和统一错误；不公开任何高级控件或系统句柄。 +言台公开应用、窗口、显示器、事件批次、输入法、光标、计时器、字体、文字整形／测量／命中、 +图片、完整帧与呈现反馈、无障碍语义树、资源配额、剪贴板、文件对话框、协议／能力查询和 +统一错误；不公开任何高级控件或系统句柄。 diff --git a/content/docs/ecosystem/desktop/app-loop.mdx b/content/docs/ecosystem/desktop/app-loop.mdx index eb8f7f8..61a5dad 100644 --- a/content/docs/ecosystem/desktop/app-loop.mdx +++ b/content/docs/ecosystem/desktop/app-loop.mdx @@ -3,7 +3,9 @@ title: 应用和事件循环 description: 创建应用、监听生命周期、使用计时器并安全退出事件循环。 --- -每个进程通常创建一个`应用`，由它持有窗口、字体、图片、计时器和事件队列。`运行`必须在 VM 所有者线程调用，且同一应用不能并发运行两次。 +每个进程通常创建一个`应用`，由它持有窗口、托管图片、托管计时任务、监听和事件队列。 +`运行`必须在 VM 所有者线程调用，且同一应用不能并发运行两次。生命周期只沿`就绪`、 +`运行中`、`退出请求`、`已退出`和`已关闭`前进；已经退出的应用不能再次运行。 ```yanxu 引「包:言界」为 界面； @@ -24,10 +26,22 @@ description: 创建应用、监听生命周期、使用计时器并安全退出 窗口.关闭时（关闭）； 窗口.显示（）； 应用.运行（）； +定 关闭报告 为 应用.关闭（）； ``` -`定时器（毫秒，重复，回调）`最小间隔为 10 毫秒。回调不是操作系统线程回调，而是和窗口事件一样进入有界宿主队列，再由事件泵在言序线程执行。周期动画应使用单调时间计算当前值，不要假设每次回调间隔完全相等。 +`定时器（毫秒，重复，回调）`最小间隔为 10 毫秒，并返回托管任务。任务可查询状态、触发 +次数和结构化错误，也可幂等取消／关闭；一次任务回调完成后自动归还平台配额，回调失败只 +使该任务进入失败。回调不是操作系统线程回调，而是和窗口事件一样进入有界宿主队列，再由 +事件泵在言序线程执行。 -应用级`监听（事件类型，回调）`可处理启动、激活、失活、退出请求、系统主题和显示器变化。窗口未处理的退出请求会结束循环；显式调用`退出`只请求停止，`运行`返回后再由`关闭`释放应用根资源。 +周期动画不要使用计时器猜测显示节奏。调用`窗口.动画（配置，更新回调）`后，言界以匹配的 +`帧呈现`事件和进程内单调时间推进任务；每窗只保留一个待呈现帧，被替换帧不会继续驱动动画。 -事件队列最多保留 4096 项。指针移动、窗口缩放和重绘会保留最新状态，滚轮在同一批次累积，因此繁忙时不会因每个物理事件都跨 ABI 而无限增长。 +应用级`监听（事件类型，回调）`可处理启动、激活、失活、退出请求、系统主题和显示器变化。 +窗口未处理的退出请求会结束循环；显式调用`退出`只请求停止，`运行`返回后再由`关闭`按 +计时器、窗口、图片、监听和原生应用继续最佳努力清理。关闭报告可 JSON 序列化，生产应用 +应记录其中的失败步骤；重复关闭返回同一结果，不再次释放资源。 + +事件队列最多保留 4096 项。指针移动、窗口缩放和重绘会保留最新状态，滚轮在同一批次累积， +因此繁忙时不会因每个物理事件都跨 ABI 而无限增长；离散事件满时会以稳定错误停止循环， +而不是静默丢失。应用可读取内容安全的诊断快照观察队列水位、资源、帧、配额和生命周期。 diff --git a/content/docs/ecosystem/desktop/backend-guide.mdx b/content/docs/ecosystem/desktop/backend-guide.mdx index ec68084..e6386f0 100644 --- a/content/docs/ecosystem/desktop/backend-guide.mdx +++ b/content/docs/ecosystem/desktop/backend-guide.mdx @@ -3,7 +3,7 @@ title: 贡献新的平台后端 description: 在不泄漏系统句柄或下沉高级控件的前提下扩展言台。 --- -首版 Windows、macOS、Wayland 和 X11 共享 winit／softbuffer 后端。新增集成应先扩展公共路径；只有上游确实无法表达所需平台原语时，才增加小型目标适配器。 +1.0 的 Windows、macOS、Wayland 和 X11 共享 winit／softbuffer 后端。新增集成应先扩展公共路径；只有上游确实无法表达所需平台原语时，才增加小型目标适配器。 ## 边界 @@ -22,4 +22,4 @@ description: 在不泄漏系统句柄或下沉高级控件的前提下扩展言 高频新事件必须选择明确策略：连续状态可保留最新，增量滚轮应累积，按键、按钮、IME、拖放与生命周期事件永不合并。新绘制能力优先增加带自描述长度的次版本操作码；改变既有解释才提升主版本。 -完整贡献流程和本地命令见[言台后端指南](https://github.com/yanxulang/yanxu-platform/blob/v0.1.0/docs/BACKEND_GUIDE.md)。 +完整贡献流程和本地命令见[言台 1.0 后端指南](https://github.com/yanxulang/yanxu-platform/blob/v1.0.0/docs/BACKEND_GUIDE.md)。 diff --git a/content/docs/ecosystem/desktop/capability-matrix.mdx b/content/docs/ecosystem/desktop/capability-matrix.mdx index d36a216..8a5e998 100644 --- a/content/docs/ecosystem/desktop/capability-matrix.mdx +++ b/content/docs/ecosystem/desktop/capability-matrix.mdx @@ -1,6 +1,6 @@ --- title: 平台能力表 -description: 言台 0.1.0 与言界 0.1.1 在六个正式桌面目标上的能力和验证范围。 +description: 言台 1.0 与言界 1.0 在六个正式桌面目标上的能力和生产验证范围。 --- `支持`表示同一公开接口已实现并进入六目标 CI；`桌面验证`表示自动测试可覆盖确定部分，但最终体验还依赖真实用户会话。 @@ -15,12 +15,16 @@ description: 言台 0.1.0 与言界 0.1.1 在六个正式桌面目标上的能 | 实际中文候选窗 | 桌面验证 | 桌面验证 | 桌面验证（IBus/Fcitx5） | | 文件拖放 | 支持 | 支持 | 支持 | | 文本剪贴板 | 支持，需权限 | 支持，需权限 | 支持，需权限 | +| RGBA8 图片剪贴板 | 支持，需权限 | 支持，需权限 | 支持，需权限 | | 文件／目录对话框 | 支持，需权限 | 支持，需权限 | 支持，需权限 | | 系统字体、回退与复杂整形 | 支持 | 支持 | 支持 | | PNG／JPEG 图片 | 支持 | 支持 | 支持 | | CPU 二维绘制 YXDR 1.1 | 支持 | 支持 | 支持 | -| 言界全部首版控件 | 支持 | 支持 | 支持 | -| 原生无障碍桥 | 尚未接入 | 尚未接入 | 尚未接入 | +| 言界 1.0 全部控件 | 支持 | 支持 | 支持 | +| 原生无障碍桥 | UIA | NSAccessibility | AT-SPI | +| 帧反馈与有界动画 | 支持 | 支持 | 支持 | +| 资源配额与结构化关闭 | 支持 | 支持 | 支持 | +| 版本化运行诊断 | 支持 | 支持 | 支持 | | GPU 后端 | 尚未提供 | 尚未提供 | 尚未提供 | ## 六个正式目标 @@ -34,6 +38,12 @@ x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu ``` -每个目标都会核对动态库实际架构、包清单摘要、言序 1.1.9 类型检查、ABI 集成、API 漂移和 Release 构建。真实窗口自动退出在六个执行器运行；Linux 使用 Xvfb 验证 X11 路径，Wayland 与实际输入法会话需另做桌面冒烟。该矩阵是 0.1.1 的发布证据，不代表已经兼容当前核心 1.1.20。 +言台每个目标都会核对动态库实际架构、ABI 导出、包清单摘要、最低言序 1.1.7 集成、真实 +窗口和原生无障碍桥；另外执行 109 项 Rust 测试、协议／ABI 畸形语料、4096 轮事件背压、 +2048 轮资源浸泡、性能预算和零例外依赖审计。 + +言界每个目标同时验证最低言序 1.1.9 与正式构建基线 1.1.20，覆盖 API 漂移、全部公开 +示例、11 条无窗口集成、5 条真实窗口路径、4096 轮交互和 1024 轮资源归零。Linux 使用 +Xvfb 验证 X11 路径；Wayland、实际输入法候选窗和屏幕阅读器最终播报仍需用户桌面验收。 运行时应调用言台`能力查询（）`，根据字段判断可选能力；不要只根据操作系统名称猜测。 diff --git a/content/docs/ecosystem/desktop/choosing.mdx b/content/docs/ecosystem/desktop/choosing.mdx index 30b0956..357d28c 100644 --- a/content/docs/ecosystem/desktop/choosing.mdx +++ b/content/docs/ecosystem/desktop/choosing.mdx @@ -3,34 +3,36 @@ title: 选择 GUI 路线 description: 根据项目阶段、控件需求、稳定性与定制程度选择言窗或言界。 --- -当前稳定言序 1.1.20 与言包 0.6.1 的新项目应选择言窗 1.0。言界 0.1.1 只保留言序 1.1.9 + 言包 0.5.0 的已验证预览组合；在新版本发布前，不要把它与当前工具链混装。 +言窗 1.0 和言界 1.0 都支持六个正式桌面目标。新项目使用当前言序 1.1.20 与言包 0.6.1 +即可评估两条路线；选择依据是编程模型和能力边界，不是稳定／预览之分。 ## 直接选择言窗 -以下情况优先使用稳定的[`yanxu-gui` 1.0](/ecosystem/desktop/gui/)： +以下情况优先使用[`yanxu-gui` 1.0](/ecosystem/desktop/gui/)： - 现有应用已经上线，当前控件和主题足够； - 希望依赖成熟的 egui 生态与立即模式开发方式； -- 需要言界`0.1.1`尚未提供的复杂控件； -- 不希望在首版阶段承担新 API 迭代成本。 +- 需要言界 1.0 尚未提供的表格、树、富文本或代码编辑器成品控件； +- 希望直接采用 egui 已有组件和立即模式扩展方式； - 需要由 CI 汇总并校验的 Windows、macOS、Linux 六目标原生制品。 ## 选择言界 -以下情况适合`yanxu-ui`： +以下情况适合[`yanxu-ui` 1.0](/ecosystem/desktop/quick-start/)： - 新项目希望所有高级控件行为都由言序实现； - 需要保留模式控件树、状态绑定和捕获／冒泡事件； - 需要自定义主题、布局、语义树或绘制命令； - 希望平台差异集中在独立的`yanxu-platform`边界； -- 未来计划实现设计系统、复杂表单或可组合业务组件。 +- 需要叠层菜单、复杂表单、虚拟列表、动画、原生无障碍语义或可组合业务组件； +- 需要版本化运行诊断、资源配额和结构化关闭报告。 ## 决策检查表 | 问题 | 若回答“是” | | --- | --- | | 已有言窗应用是否稳定上线？ | 保持言窗 1.x | -| 是否依赖言界首版没有的控件？ | 保持言窗或先验证自定义控件 | +| 是否依赖言界 1.0 没有的成品控件？ | 选择言窗或先验证自定义控件 | | 是否必须控制事件传播和焦点顺序？ | 选择言界 | | 是否要用言据集中描述主题？ | 选择言界 | | 是否要直接调用操作系统句柄？ | 两条上层路线都不适合；应贡献言台通用能力 | diff --git a/content/docs/ecosystem/desktop/clipboard.mdx b/content/docs/ecosystem/desktop/clipboard.mdx index 1795230..3ce18f4 100644 --- a/content/docs/ecosystem/desktop/clipboard.mdx +++ b/content/docs/ecosystem/desktop/clipboard.mdx @@ -1,6 +1,6 @@ --- title: 剪贴板 -description: 在独立权限下读取和写入系统 UTF-8 文本剪贴板。 +description: 在独立权限下使用言界文本剪贴板与言台 RGBA8 图片剪贴板。 --- 剪贴板能力与图形窗口权限分离。应用需要在`言序.toml`显式声明： @@ -19,6 +19,12 @@ description: 在独立权限下读取和写入系统 UTF-8 文本剪贴板。 定 内容 为 界面.剪贴板读取（）； ``` -读取没有文本时返回空。首版只处理 UTF-8 文本，不提供图片、自定义 MIME 或富文本剪贴板。单行和多行输入控件的复制、剪切与粘贴会调用同一服务，并尊重当前选区和只读状态。 +读取没有文本时返回空。文字读写上限为 16 MiB；单行和多行输入控件的复制、剪切与粘贴 +会调用同一服务，并尊重当前选区和只读状态。 + +言界 1.0 的包级函数只公开文字。直接构建框架或平台工具时，言台 1.0 另提供 RGBA8 图片 +读写；宽高必须为 1..16384，内容严格等于`宽 × 高 × 4`且不超过 256 MiB。调用前读取 +`能力查询（）`中的格式和上限，不把这些值当成其他后端的默认值。自定义 MIME 与富文本 +仍不在 1.0 接口内。 缺少权限时返回`PLATFORM_PERMISSION_CLIPBOARD`一类稳定错误；不会因为应用已经能创建窗口而隐式放行。测试不应覆盖用户真实剪贴板，可在隔离桌面会话或经显式确认后运行原生冒烟。 diff --git a/content/docs/ecosystem/desktop/compatibility.mdx b/content/docs/ecosystem/desktop/compatibility.mdx index 9b89704..26a8f5d 100644 --- a/content/docs/ecosystem/desktop/compatibility.mdx +++ b/content/docs/ecosystem/desktop/compatibility.mdx @@ -1,6 +1,6 @@ --- title: 版本兼容政策 -description: 言界、言台、言序、言包、言据和言窗之间的兼容基线与已知限制。 +description: 言界 1.0、言台 1.0、工具链、协议和言窗之间的稳定兼容边界。 --- ## 言窗 1.0 稳定线 @@ -15,37 +15,44 @@ description: 言界、言台、言序、言包、言据和言窗之间的兼容 言窗 Git 标签保存源码和清单模板；完整六目标包以 1.0.0 Release 归档发布。Linux GNU 制品需要 glibc 2.39，macOS 公开制品仅做临时签名。精确限制见[言窗 1.0](/ecosystem/desktop/gui/)。 -## 言界与言台 0.1 基线 +## 言界与言台 1.0 稳定线 | 组件 | 兼容范围 | 已验证版本 | | --- | --- | --- | -| 言序 | 清单声明`>=1.1.9`；当前可复现基线固定 1.1.9 | 1.1.9 | -| 言包 | 格式 2 清单与锁文件 | 0.5.0 | -| 言台 | `^0.1`，ABI v2 | 0.1.0 | -| 言界 | `^0.1` | 0.1.1 | +| 言序 | 言界源码`>=1.1.9`；正式 YXB 使用当前稳定工具链 | 1.1.9、1.1.20 | +| 言包 | 格式 2 清单、按目标生成的锁文件 | 0.6.1 | +| 言台 | `^1.0`，言序`>=1.1.7, <2.0.0`，ABI v2 | 1.0.0 | +| 言界 | `^1.0` | 1.0.0 | | 言据 | `^1.1` | 1.1.2 | | 言窗 | 独立并行路线 | 1.0.0 | -言界 0.1.1 要求言序 1.1.9，以获得 Windows VM 所有者线程栈修复和按宿主事件隔离的执行步数预算；本站 CI 固定复现该发布基线。言台本身仍兼容`>=1.1.7`，言界的锁定发布继续使用言据 1.1.2。 +言界 1.0 同时验证最低言序 1.1.9 的源码/API 兼容和言序 1.1.20 的正式构建与回放。应用 +通常使用当前稳定工具链；最低版本是兼容下限，不是新项目的推荐降级目标。言界固定消费 +言台 1.0 标签与言据 1.1.2 已审核提交，应用只直接声明言界即可。 -言界清单虽声明`>=1.1.9`，但 0.1.1 源码目前不能通过言序 1.1.20 的静态检查；同时言包 0.6.1 最低要求核心 1.1.17。因此不存在“言序 1.1.20 + 言包 0.6.1 + 言界 0.1.1”的受支持组合。当前稳定工具链使用言窗 1.0；言界等待后续版本修复并重新发布。新路线不会替换、废弃或强制迁移`yanxu-gui`。 +言台 1.0 冻结 ABI v2、平台 1.7、事件 1.3、无障碍 1.0、绘制 1.1 和 70 个稳定错误码。 +言界 1.0 冻结 30 个声明、23 个类、7 个包级函数、125 个域和 375 个方法，并用机器门禁 +证明从`v0.1.0`到`v0.9.0`的已发布 API 仍可调用。两条 GUI 路线互不替换或强制迁移。 ## 版本政策 -- `0.1.x`修订版修复实现和文档，不改变已发布协议字段含义； -- `0.x`次版本可增加方法、控件、能力、事件、绘制操作码或可选字段； -- 删除／重命名公开 API、改变单位／所有权或二进制布局，必须提升相应协议主版本并提供迁移窗口； -- 新增替代接口后，旧接口至少在同一 0.x 次版本线保留并明确标为弃用； -- 言据是首选可读格式，JSON 兼容入口在 0.1 系列不移除。 +- `1.0.x`只接受向后兼容的实现、安全、文档和生产门禁修复； +- 后续`1.x`可以增加可选控件、方法、能力、事件或协议字段，但不能让旧调用新增必需条件； +- 删除／重命名公开 API、收窄参数、扩大旧调用方必须处理的返回类型、改变单位、所有权或 + 二进制布局，必须进入新的包、协议或 ABI 主版本； +- 新增替代接口后，旧接口在整个 1.x 中继续可用并明确标为弃用； +- 言据主题与等价 JSON 入口、事件名称、布局单位和控件创建方法属于 1.x 兼容承诺。 ## 已知限制 -- 跨行选区背景使用保守矩形，文本和 IME 提交语义不受影响； -- 无障碍语义树已生成，但尚未接入三套系统的原生无障碍桥； -- 菜单和弹出层尚无子菜单、完整模态焦点陷阱与屏幕边缘翻转； -- 列表没有公开异步数据源； - 当前使用统一 CPU 二维后端，没有 GPU 后端、隔离离屏图层或任意旋转文字保证； +- 言界 1.0 没有表格、树、富文本或代码编辑器成品控件； +- 数据源不创建线程、网络请求或隐式异步调度；加载器的执行与取消由应用负责； - 系统字体会导致跨系统文字像素差异，像素金图需携带固定字体； -- 文件对话框、剪贴板和真实 IME 候选窗依赖用户桌面会话。 +- 文件对话框、剪贴板、真实 IME 候选窗和屏幕阅读器最终播报依赖用户桌面会话； +- 不支持移动端、Web、musl、32 位目标、全局快捷键、系统托盘或打印。 -升级前检查两个项目的 CHANGELOG、Release notes、协议主／次版本和目标锁文件；不要只修改包版本而保留旧原生摘要。 +升级前检查两个项目的 CHANGELOG、Release notes、协议主／次版本和目标锁文件；不要只修改 +包版本而保留旧原生摘要。言台的支持周期见其 +[兼容政策](https://github.com/yanxulang/yanxu-platform/blob/v1.0.0/docs/COMPATIBILITY.md)，言界的 +1.x 修复边界见[支持政策](https://github.com/yanxulang/yanxu-ui/blob/v1.0.0/SUPPORT.md)。 diff --git a/content/docs/ecosystem/desktop/complete-example.mdx b/content/docs/ecosystem/desktop/complete-example.mdx index d539069..40d4534 100644 --- a/content/docs/ecosystem/desktop/complete-example.mdx +++ b/content/docs/ecosystem/desktop/complete-example.mdx @@ -3,20 +3,30 @@ title: 完整示例 description: 一个包含菜单、列表、分割面板、标签页、文本和画布的可运行言界应用。 --- -以下源码与文档仓库`examples/desktop/综合控件展示.yx`完全一致，并由 CI 使用言界 0.1.1 已验证的言序`1.1.9`执行类型检查和 Release YXB 构建。当前核心用户应先阅读[版本兼容政策](/ecosystem/desktop/compatibility/)中的兼容缺口。 +以下源码与文档仓库`examples/desktop/综合控件展示.yx`完全一致。CI 使用言序 1.1.9 与 +1.1.20 两套工具链解析言界 1.0，在真实 Linux 窗口环境执行类型检查、Release YXB 构建和 +自动退出冒烟。 ```yanxu 引「包:言界」为 界面； 定 应用 为 界面.应用（「言界综合控件展示」）； -定 窗口 为 应用.窗口（{「标题」：「言界 0.1.1」，「宽」：960，「高」：700，「最小宽」：720，「最小高」：520}）； +定 窗口 为 应用.窗口（{「标题」：「言界综合控件展示」，「宽」：960，「高」：700，「最小宽」：720，「最小高」：520}）； 定 主列 为 窗口.列（{「内边距」：18，「间距」：10}）； 定 菜单行 为 主列.行（{「间距」：8}）； -菜单行.菜单（【{「标题」：「新建」}，{「标题」：「打开」}，{「标题」：「退出」}】）； +令 菜单选择次数 为 0； + +法 记录菜单选择（所事件） 则 + 置 菜单选择次数 为 （菜单选择次数 加 1）； +终 + +定 主菜单 为 菜单行.菜单（【{「标题」：「文件」，「快捷键」：「⌘N」，「子菜单」：【{「标题」：「新建」}，{「标题」：「打开」，「快捷键」：「⌘O」}】}，{「标题」：「编辑」，「子菜单」：【{「标题」：「撤销」，「快捷键」：「⌘Z」}，{「标题」：「重做」，「快捷键」：「⇧⌘Z」}】}，{「标题」：「退出」}】）； + +主菜单.监听（「选择」，记录菜单选择）； 菜单行.文字（「保留模式控件全部由言序实现」）； @@ -59,4 +69,7 @@ description: 一个包含菜单、列表、分割面板、标签页、文本和 应用.运行（）； ``` -项目清单使用[快速开始](/ecosystem/desktop/quick-start/)中的言界`v0.1.1`依赖和四项权限。先运行`yanbao 装`，再用`yanbao 查`检查；开发桌面运行应用，发布时执行`yanbao 构 --release --bundle`。 +项目清单使用[快速开始](/ecosystem/desktop/quick-start/)中的言界`v1.0.0`依赖和四项权限。 +先运行`yanbao 装`，再用`yanbao 查`检查；开发桌面运行应用，发布时执行 +`yanbao 构 --release --bundle`。窗口边缘、键盘导航、中文 IME、DPI、屏幕阅读器和关闭 +路径仍应在目标桌面会话完成上线冒烟。 diff --git a/content/docs/ecosystem/desktop/configuration.mdx b/content/docs/ecosystem/desktop/configuration.mdx index dc1adbc..13ca506 100644 --- a/content/docs/ecosystem/desktop/configuration.mdx +++ b/content/docs/ecosystem/desktop/configuration.mdx @@ -3,11 +3,12 @@ title: 项目配置与权限 description: 固定言界、言台和言据版本，并为 GUI 系统服务声明最小权限。 --- -应用只需要直接依赖言界；言界的锁文件会解析固定的言台`0.1.x`和言据`1.1.x`。正式项目应固定 Git 标签并提交`言序.lock`： +应用只需要直接依赖言界；言界 1.0 的锁会解析言台`1.0.x`和言据`1.1.x`。正式项目应固定 +Git 标签并提交每个目标独立生成的`言序.lock`： ```toml [依赖] -言界 = { 包 = "yanxu-ui", git = "https://github.com/yanxulang/yanxu-ui.git", 修订 = "v0.1.1", 版 = "^0.1" } +言界 = { 包 = "yanxu-ui", git = "https://github.com/yanxulang/yanxu-ui.git", 修订 = "v1.0.0", 版 = "^1.0" } [权限] 图形界面 = true @@ -25,6 +26,8 @@ description: 固定言界、言台和言据版本，并为 GUI 系统服务声 不使用剪贴板或对话框时，应删除相应权限。图形权限不会自动授予文件、网络、通知、托盘、外部地址或全局快捷键。宿主嵌入应用还会把包权限与宿主上限取交集。 -运行`yanbao update`后，锁文件记录 Git 修订、包内容摘要和当前目标的原生制品摘要。切换目标或平台时要在对应平台重新生成并验证锁文件，不要手工复制另一个架构的动态库。 +运行`yanbao update`后，锁文件记录 Git 修订、包内容摘要、当前目标以及言台原生制品的 ABI、 +SHA-256 和大小。切换目标或平台时要在对应平台重新生成并验证锁文件，不要手工复制另一个 +架构的动态库。言界 1.0 固定消费言台 ABI v2、平台 1.7、事件 1.3、无障碍 1.0 和绘制 1.1。 开发言界本身时可临时使用`路径 = "../yanxu-ui"`；发布应用不得保留工作区路径依赖。 diff --git a/content/docs/ecosystem/desktop/controls.mdx b/content/docs/ecosystem/desktop/controls.mdx index 2039602..f504677 100644 --- a/content/docs/ecosystem/desktop/controls.mdx +++ b/content/docs/ecosystem/desktop/controls.mdx @@ -1,6 +1,6 @@ --- title: 控件 -description: 使用言界 0.1.1 的基础、输入、导航和绘制控件。 +description: 使用言界 1.0 的表单、数据视图、导航、叠层和绘制控件。 --- 所有高级控件都由言序实现，并共享显示、启用、焦点、尺寸、边距、样式、事件和无障碍接口： @@ -9,23 +9,33 @@ description: 使用言界 0.1.1 的基础、输入、导航和绘制控件。 控件.显示（真）； 控件.启用（真）； 控件.可聚焦（真）； +控件.只读（假）； +控件.必填（假）； +控件.无效（假）； 控件.尺寸（320，44）； 控件.外边距（【4，8，4，8】）； 控件.可访问名称（「保存文档」）； ``` -| 创建方法 | 首版能力 | +| 创建方法 | 1.0 能力 | | --- | --- | | `文字（内容）` | 显示及修改文字 | | `按钮（内容）` | 悬停、按下、焦点、Enter／空格激活和点击 | +| `复选框（内容）` | 二态／混合态、检查语义和变化事件 | +| `单选框（内容，组）` | 同组互斥、方向键循环和选择语义 | +| `切换（内容）` | 鼠标、空格、回车和辅助技术激活 | +| `下拉选择（文字列）` | 有界选项、锚定弹框、键盘导航和设置值 | +| `滑块（配置）` | 横纵拖动、键盘步进、范围夹取和辅助调整 | +| `进度条（配置）` | 确定值或不定忙碌状态 | | `输入框（配置）` | Unicode 单行编辑、选择、剪贴板、撤销与 IME | -| `多行输入框（配置）` | 多行导航、选区与滚动 | -| `滚动（配置）` | 视口、偏移与滚轮 | -| `列表（文字列）` | 虚拟行绘制、选择与变化事件 | -| `标签页（标签列）` | 标签导航和`页（名称）`页面 | -| `分割面板（配置）` | 两个面板及可拖动分隔条 | -| `菜单（项目列）` | 展开、选择与弹出菜单 | -| `弹出层（配置）` | 打开／关闭覆盖层 | +| `多行输入框（配置）` | Unicode 按行选区、可见行绘制和滚动 | +| `滚动（配置）` | 范围夹取、滚轮和无障碍滚动 | +| `列表（文字列）` | 可见行绘制、逐项语义、选择和滚动到 | +| `虚拟列表（数据源，配置）` | 增量加载、缓存、失败状态和自定义行渲染 | +| `标签页（标签列）` | 标签语义、键盘导航和程序选择页 | +| `分割面板（配置）` | 拖动、键盘、程序和辅助技术共用比例路径 | +| `菜单（项目列）` | 子菜单、指针／键盘导航、模态焦点和语义动作 | +| `弹出层（配置）` | 锚定翻转、视口夹取、外部点击和 Escape 关闭 | | `画布（配置）` | 追加言台结构化绘制命令 | | `图片（资源）` | 测量并绘制已加载图片 | @@ -42,4 +52,9 @@ description: 使用言界 0.1.1 的基础、输入、导航和绘制控件。 保存.点击（保存点击）； ``` -首版没有表格、树、富文本或代码编辑器成品控件；可先由现有容器和画布组合，或向言界贡献可复用的言序控件。 +下拉选择最多 4096 项，每项最多 65536 UTF-8 字节；普通列表与虚拟列表每次最多生成 256 个 +当前可见语义项目。菜单限制单层 1024 项、总量 4096 项和 16 层深度。所有指针、键盘、 +程序和辅助技术改值路径共用同一状态校验与变化事件。 + +1.0 没有表格、树、富文本或代码编辑器成品控件；可先由现有容器、虚拟列表和画布组合， +或向言界贡献可复用的言序控件。 diff --git a/content/docs/ecosystem/desktop/data-views.mdx b/content/docs/ecosystem/desktop/data-views.mdx new file mode 100644 index 0000000..041e25f --- /dev/null +++ b/content/docs/ecosystem/desktop/data-views.mdx @@ -0,0 +1,57 @@ +--- +title: 数据源与虚拟列表 +description: 用有界增量数据源、缓存和只创建可见行的虚拟列表呈现大型集合。 +--- + +普通`列表`适合已经在内存中的文字列。数据量很大或需要按范围取得时，言界 1.0 提供独立 +`数据源`模块和`虚拟列表`；它们不创建线程、网络连接或隐式异步调度，加载器何时执行由 +应用控制。 + +## 创建增量数据源 + +```yanxu +引「包:言界/数据源」为 数据； + +法 加载项目（起点，数量） 则 + 令 结果：列 为 【】； + 逐 偏移 于 范围（0，数量）则 + 追加（结果，「项目」）； + 终 + 归 结果； +终 + +定 源 为 数据.数据源（100000，加载项目）； +定 视图 为 窗口.列（{}）.虚拟列表（源，{「首选高」：320}）； +``` + +一次范围加载最多 256 项，默认缓存最多 1024 项；`最大缓存（上限）`可在 1–4096 之间调整。 +加载器必须返回恰好请求数量的列。抛错、返回错误类型或数量不符时，状态原子进入失败，错误 +文本保存在`错误（）`，已缓存数据不会被部分覆盖。 + +## 更新与订阅 + +| 操作 | 作用 | +| --- | --- | +| `提供（起点，项目列）` | 原子写入一段已取得的数据并发送`数据更新` | +| `失效（起点，数量）` | 丢弃一段缓存并发送`数据失效` | +| `设置总数（新总数）` | 更新总数并发送`数量变化` | +| `加载（起点，数量）` | 调用加载器，校验后原子写入缓存 | +| `刷新数据（）` | 清空缓存并允许重新请求 | +| `快照（）` | 返回总数、缓存、水位、状态、错误和版本摘要 | + +`监听（事件名，回调）`返回单调递增的监听编号。解除时把同一事件名和编号传给`取消监听`； +不要比较绑定方法对象。视图切换数据源时会按编号解除旧源订阅，旧源更新不会污染新视图。 + +## 虚拟化与无障碍 + +虚拟列表只请求视口附近的范围，并公开`刷新数据`、`数据状态`、`数据错误`、`数据数量`和 +`设置行渲染器`。不可用数据显示等待状态，加载期间显示加载状态，失败时显示有界错误文字。 +选择、焦点和滚动位置不会因为邻近缓存更新而重建。 + +普通列表和虚拟列表都只为当前可见范围生成最多 256 个`列表项`语义节点。每项公开文字、 +边界、选中状态以及选择／滚动到动作；离开当前树或来自旧修订的节点编号会被拒绝。集合值 +只保存当前选中文字，数量、索引、首可见行和错误通过查询 API 读取。 + +数据项是文字时直接显示；其他类型默认使用有界占位。调用`设置行渲染器（回调）`可以按 +数据值和行索引生成显示文字。完整 API 与失败恢复见 +[言界 1.0 数据视图指南](https://github.com/yanxulang/yanxu-ui/blob/v1.0.0/docs/DATA_VIEWS.md)。 diff --git a/content/docs/ecosystem/desktop/drawing.mdx b/content/docs/ecosystem/desktop/drawing.mdx index f53201b..09bfbdc 100644 --- a/content/docs/ecosystem/desktop/drawing.mdx +++ b/content/docs/ecosystem/desktop/drawing.mdx @@ -29,4 +29,4 @@ description: 从言界渲染树生成一次提交的 YXDR 1.1 二进制完整帧 协议覆盖清空、保存／恢复、裁剪、仿射变换、图层透明度、填充／描边矩形、圆角、直线、圆、路径、阴影、文字、字形序列和图片。整帧上限 16 MiB、命令数上限 65536、状态栈上限 256；损坏或超限帧会返回`PLATFORM_DRAW_*`错误。 -首版图层透明度不是隔离离屏组，任意旋转文字也不保证矢量轮廓级一致。固定自定义字体时，六个目标共享同一 CPU 算法；否则系统字体差异仍会影响像素。 +1.0 的图层透明度不是隔离离屏组，任意旋转文字也不保证矢量轮廓级一致。固定自定义字体时，六个目标共享同一 CPU 算法；否则系统字体差异仍会影响像素。 diff --git a/content/docs/ecosystem/desktop/events.mdx b/content/docs/ecosystem/desktop/events.mdx index 581449e..5e8d599 100644 --- a/content/docs/ecosystem/desktop/events.mdx +++ b/content/docs/ecosystem/desktop/events.mdx @@ -3,7 +3,8 @@ title: 事件系统 description: 理解事件批次、命中测试、捕获、目标、冒泡与指针捕获。 --- -言台先把系统事件规范化并批量送入言界。言界在窗口控件树上命中测试，然后依次执行三个阶段： +言台先把系统事件规范化并批量送入言界。窗口级叠层栈先从最上层处理菜单／弹层命中、外部 +点击与模态阻断；普通事件再在控件树依次执行三个阶段： ```text 根 → 父容器 → 目标控件 捕获阶段 @@ -30,4 +31,10 @@ description: 理解事件批次、命中测试、捕获、目标、冒泡与指 拖动分隔条或选区时，目标控件会请求指针捕获；即使指针离开原矩形，移动和释放仍发送给该控件。释放、取消、失焦或控件关闭都会清除捕获，避免“卡住按下”状态。 -事件批次保留顺序，但会合并连续指针移动、窗口尺寸和重绘请求，并累积滚轮增量。未知可选事件由兼容层忽略；未知主协议或损坏批次会返回统一错误。 +言台发出的`无障碍焦点请求`与`无障碍动作请求`不直接修改控件。窗口先同步当前语义变化， +再核对树修订、稳定控件编号、可见／启用状态和动作参数；有效请求才进入控件已有的点击、 +设置值、选择、滚动或展开路径。过期或畸形请求不会降级成普通事件。 + +事件批次保留顺序，但会合并连续指针移动、窗口尺寸和重绘请求，并累积滚轮增量。未知可选 +事件由兼容层忽略；未知主协议或损坏批次会返回统一错误。`帧呈现`是离散反馈，携带帧序号 +和单调呈现时间，用来推进有界动画而不是表达业务计时。 diff --git a/content/docs/ecosystem/desktop/forms.mdx b/content/docs/ecosystem/desktop/forms.mdx new file mode 100644 index 0000000..40cc6d6 --- /dev/null +++ b/content/docs/ecosystem/desktop/forms.mdx @@ -0,0 +1,65 @@ +--- +title: 表单控件 +description: 使用复选框、单选框、切换、下拉选择、滑块和进度条构建有界可访问表单。 +--- + +言界 1.0 的表单控件共享保留模式控件树、事件路由、主题状态和言台无障碍协议。应用负责 +业务校验与提交；控件负责有界状态、输入交互、绘制和语义同步。 + +## 组合表单 + +```yanxu +定 姓名 为 表单.输入框（{「占位」：「姓名」，「可访问名称」：「姓名」}）； +姓名.必填（真）； + +定 接受 为 表单.复选框（「接受服务条款」）； +接受.必填（真）； + +定 地区 为 表单.下拉选择（【「中国大陆」，「中国香港」，「新加坡」，「其他」】）； +地区.可访问名称（「地区」）； + +定 音量 为 表单.滑块（{ + 「最小」：0，「最大」：100，「步长」：5，「值」：50， + 「可访问名称」：「通知音量」 +}）； + +定 完成度 为 表单.进度条（{ + 「最小」：0，「最大」：100，「值」：50， + 「可访问名称」：「表单完成度」 +}）； +``` + +## 通用状态 + +| 状态 | 行为 | +| --- | --- | +| `启用（假）` | 不进入焦点序列，拒绝指针、键盘和辅助技术动作 | +| `只读（真）` | 仍可聚焦和读取；拒绝交互改值，程序方法仍可更新 | +| `必填（真）` | 向允许的表单角色公开必填语义；业务是否满足仍由应用判断 | +| `无效（真）` | 公开无效语义并使用危险状态样式 | + +输入框切到只读会取消正在进行的 IME 组合；下拉选择会折叠弹框，滑块会释放指针捕获。 +进度条是不可聚焦、无动作的输出角色，协议不允许它声明只读、必填或无效。 + +## 交互边界 + +- 复选框支持未选、已检查和混合三态；单选框同组互斥，方向键循环并跳过不可修改项； +- 切换支持指针、空格和回车，状态变化统一触发`变化时`； +- 下拉选择最多 4096 项，每项不超过 65536 UTF-8 字节，支持首字导航、Home/End、 + Escape、锚定翻转和辅助技术设置值； +- 滑块要求有限的最小、最大、步长和值；指针、方向键、PageUp/PageDown、Home/End 和 + 辅助动作都经过同一范围夹取与步长吸附； +- 进度条可公开确定值，或用`不定（真）`公开空值和忙碌状态。 + +程序调用仍可以更新只读控件。用户或辅助技术实际改变值时才触发变化事件；拒绝输入不会 +部分改写原状态。应用在提交回调中调用`无效（真）`表达业务校验结果，不应从样式颜色反推 +数据是否有效。 + +## 验收 + +键盘验收至少覆盖 Tab／Shift+Tab、空格、回车、方向键、Home/End 和 Escape；中文表单还要 +覆盖 IME 组合、只读切换与粘贴。屏幕阅读器应能读出名称、必填／无效、检查状态、当前值、 +范围和忙碌状态，并通过与指针／键盘相同的动作路径改值。 + +完整行为和可运行示例见 +[言界 1.0 表单指南](https://github.com/yanxulang/yanxu-ui/blob/v1.0.0/docs/FORMS.md)。 diff --git a/content/docs/ecosystem/desktop/images-resources.mdx b/content/docs/ecosystem/desktop/images-resources.mdx index 6e1ef43..43054e1 100644 --- a/content/docs/ecosystem/desktop/images-resources.mdx +++ b/content/docs/ecosystem/desktop/images-resources.mdx @@ -1,9 +1,10 @@ --- title: 图片和资源 -description: 加载图片、在控件或画布中使用资源，并理解代际句柄生命周期。 +description: 使用言界 1.0 托管图片、显式所有权、应用配额和幂等关闭。 --- -应用从 PNG 或 JPEG 字节加载图片，格式和像素上限由言台验证，单边最大 16384 像素： +应用从 PNG 或 JPEG 字节加载图片，格式和像素上限由言台验证，单边最大 16384 像素。 +`加载图片`返回言界托管资源： ```yanxu 定 图片资源 为 应用.加载图片（图片字节）； @@ -11,10 +12,20 @@ description: 加载图片、在控件或画布中使用资源，并理解代际 图片控件.尺寸（320，180）； ``` -画布图片命令引用同一资源句柄，而不是把像素重复写入每个绘制帧。后端呈现时解析句柄；资源关闭后，后续帧不能继续访问它。 +托管资源公开编号、状态、可用、查询、快照和关闭；查询包含宽、高和解码后字节数。画布 +图片命令引用内部同一资源句柄，而不是把像素重复写入每个绘制帧。后端呈现时才解析句柄； +资源关闭后公开句柄置空，后续帧不会继续访问它。 -言台的应用是资源树根，窗口拥有表面和窗口级回调，字体和图片由应用持有。句柄由槽位和代际组成：释放资源后，即使槽位被新资源复用，旧句柄也会返回`PLATFORM_RESOURCE_CLOSED`，不能误操作新对象。 +图片控件默认不取得调用者传入资源的所有权。需要让控件关闭时同步释放图片，可在配置中 +设置`拥有资源`；不要同时让调用者和控件假设自己是唯一所有者。两条路径最终进入同一幂等 +关闭状态机。 -关闭是幂等的，并按子到父顺序释放。应让窗口和控件不再引用图片后再关闭图片，最后关闭应用。`调试快照`可以在测试中核对窗口、计时器、图片、字体和回调数量是否归零，但它不是持久化格式。 +言台句柄由槽位和代际组成：释放资源后，即使槽位被新资源复用，旧句柄也只会返回 +`PLATFORM_RESOURCE_CLOSED`，不能误操作新对象。加载前会检查图片数量与应用剩余图片字节 +配额，元数据或创建失败会回滚平台资源，不产生半初始化托管对象。关闭会归还当前用量， +但不会解冻应用配额。 + +应用关闭会统一清理仍活动的图片并生成结构化报告。诊断快照可核对活动图片、持有字节、 +创建／关闭量和资源归零，但不会包含像素、路径或原生句柄，也不是持久化格式。 发布应用时把图片和字体放入项目资源目录，让言包 Bundle 携带并记录摘要；不要在启动热路径依赖网络下载核心界面资源。 diff --git a/content/docs/ecosystem/desktop/index.mdx b/content/docs/ecosystem/desktop/index.mdx index da9d7ad..72a551c 100644 --- a/content/docs/ecosystem/desktop/index.mdx +++ b/content/docs/ecosystem/desktop/index.mdx @@ -1,20 +1,20 @@ --- title: 图形界面概览 -description: 在稳定言窗 1.0 与言界、言台保留模式路线之间选择原生桌面 GUI。 +description: 在稳定言窗 1.0 与言界 1.0 保留模式路线之间选择原生桌面 GUI。 --- -言序提供两条并行的原生桌面路线。**言窗 1.0**直接以 ABI v2 封装 eframe/egui 与 -winit，适合需要稳定、完整控件和六目标发布的应用；**言界 + 言台**把高级控件保留在 -言序代码中，提供保留模式控件树和更强的主题/组合能力。两条路线都创建真实窗口，不 -依赖浏览器、Electron、WebView 或 DOM。 +言序提供两条并行的稳定原生桌面路线。**言窗 1.0**直接以 ABI v2 封装 eframe/egui 与 +winit，适合立即模式开发和 egui 控件生态；**言界 1.0 + 言台 1.0**把高级控件保留在 +言序代码中，提供保留模式控件树、确定的事件传播和可组合主题。两条路线都创建真实窗口， +不依赖浏览器、Electron、WebView 或 DOM。 ![言序原生 GUI 两条路线架构图](/desktop-architecture.svg) - - + + ## 平台范围 @@ -22,15 +22,27 @@ winit，适合需要稳定、完整控件和六目标发布的应用；**言界 | 路线 | 版本 | 最低言序 | Windows | macOS | Linux GNU | | --- | ---: | ---: | --- | --- | --- | | 言窗 `yanxu-gui` | 1.0.0 | 1.1.12 | x86-64 / ARM64 | x86-64 / ARM64 | x86-64 / ARM64 | -| 言界 0.1.1 + 言台 0.1.0 | 0.1.x | 1.1.9 | x86-64 / ARM64 | x86-64 / ARM64 | x86-64 / ARM64 | +| 言界 + 言台 | 1.0.0 | 1.1.9 | x86-64 / ARM64 | x86-64 / ARM64 | x86-64 / ARM64 | -言窗 1.0 的 Linux GNU 制品最高需要 glibc 2.39；不支持 musl、WebAssembly、移动平台 -或 32 位目标。言界/言台有独立版本和兼容文档，升级一条路线不会隐式升级另一条。 +言窗 1.0 的 Linux GNU 制品最高需要 glibc 2.39；两条路线都不支持 musl、WebAssembly、 +移动平台或 32 位目标。言界 1.0 的正式 YXB 使用言序 1.1.20 构建，同时保留言序 1.1.9 +源码兼容门禁。言界、言台与言窗各自版本化，升级一条路线不会隐式升级另一条。 - - 言界 0.1.1 的发布门禁只验证言序 1.1.9；其源码目前不能通过言序 1.1.20 的静态检查，言包 0.6.1 又要求核心至少 1.1.17。当前稳定工具链的新项目应选择言窗 1.0。言界页面保留为锁定 1.1.9 + 言包 0.5.0 的预览路线，等待后续言界版本重新建立兼容线。 + + 言界 1.0 已冻结公开 API、言台 1.0 协议组合和六目标发布契约。选型应依据编程模型、控件需求和部署验证，不再需要因工具链兼容缺口回退到言窗。 +## 言界 1.0 生产指南 + + + + + + + + + + ## 两条路线的边界 言窗公开应用、窗口、布局、控件、事件、图片、画布、剪贴板和文件对话框对象，控件由 @@ -40,6 +52,6 @@ egui 后端实现。言界中的按钮、输入、列表、布局、状态与事 两条路线不能在同一个原生窗口混用控件树，也不公开操作系统句柄。可在不同应用中并存， 迁移应按独立产品或窗口渐进完成。 -稳定言窗源码与 Release 位于[yanxu-gui](https://github.com/yanxulang/yanxu-gui)。另一条 +稳定言窗源码与 Release 位于[yanxu-gui](https://github.com/yanxulang/yanxu-gui)。保留模式 路线位于[yanxu-platform](https://github.com/yanxulang/yanxu-platform)和 -[yanxu-ui](https://github.com/yanxulang/yanxu-ui)。 +[yanxu-ui](https://github.com/yanxulang/yanxu-ui)，两个仓库均从`v1.0.0`提供稳定支持。 diff --git a/content/docs/ecosystem/desktop/lifecycle-diagnostics.mdx b/content/docs/ecosystem/desktop/lifecycle-diagnostics.mdx new file mode 100644 index 0000000..8270549 --- /dev/null +++ b/content/docs/ecosystem/desktop/lifecycle-diagnostics.mdx @@ -0,0 +1,72 @@ +--- +title: 资源生命周期与诊断 +description: 配置应用配额，管理计时器和图片，并用结构化关闭报告与内容安全快照定位问题。 +--- + +言界 1.0 在创建应用时协商言台 1.0 的配额、拒绝统计、退出幂等、生命周期统计和关闭资源 +归零能力。缺少任一必需能力会在创建首个窗口前停止，不退回无界资源管理。 + +## 在首次使用前下调配额 + +配额必须在创建首个窗口、计时器、图片或首次运行前配置： + +```yanxu +定 应用 为 界面.应用（「有界应用」）； + +定 能力 为 应用.资源能力（）； +定 生效配额 为 应用.配置资源配额（{ + 「资源总数」：64， + 「窗口数」：4， + 「计时器数」：16， + 「图片数」：16， + 「字体数」：8， + 「图片字节」：67108864， + 「字体字节」：33554432， + 「帧字节」：33554432， + 「无障碍节点」：16384， + 「无障碍文字字节」：4194304 +}）； +``` + +省略字段沿用当前值。配置只能下调，未知字段、非整数、超过言台硬上限或冻结后再次配置 +都会以`PLATFORM_QUOTA_*`稳定错误拒绝。资源关闭后会归还当前用量，但不会解冻或提高上限。 +使用`应用.资源配额（）`读取当前复制值，不要修改返回典来尝试改变内部状态。 + +## 托管资源 + +`应用.定时器（毫秒，重复，回调）`返回托管任务。一次任务正常回调后自动进入完成并归还 +配额；重复任务保持运行。任务公开编号、状态、运行中、查询／快照、取消和关闭，回调错误 +只使当前任务失败，迟到事件不会重新激活已经结束的任务。 + +`应用.加载图片（字节）`返回托管图片资源。查询保留宽、高和字节数，关闭后归还图片数量 +与解码后 RGBA 字节配额，并把公开句柄置空。图片控件默认不取得调用者资源的所有权；只有 +配置`拥有资源`时，控件关闭才调用同一幂等关闭路径。 + +## 单向关闭报告 + +窗口和应用都只沿`可用 → 关闭中 → 已关闭`前进。`关闭（）`返回可 JSON 序列化的报告， +包含状态、成功步骤和全部结构化错误。某一步失败不会阻止后续清理；重复关闭返回原报告， +不再次释放资源或调用回调。 + +```yanxu +窗口.关闭（）； +定 应用关闭报告 为 应用.关闭（）； +``` + +生产应用应在`运行（）`返回后调用一次应用关闭，记录全部失败步骤。不要围绕同一个已关闭 +对象无限重试；言台根资源已经作为最后兜底尝试回收所有子资源。 + +## 内容安全诊断 + +`窗口.诊断快照（）`和`应用.诊断快照（）`返回版本化纯言序值。窗口快照包含布局／语义 +脏状态、焦点、捕获、叠层、无障碍摘要、待呈现帧、动画和生命周期；应用快照包含言台事件 +队列、资源、帧、无障碍桥、配额、窗口、计时器、图片、主题和监听摘要。 + +快照不会复制窗口标题、显示器名称、输入框内容、密码值、回调、无障碍文字树或原生句柄， +适合写入结构化日志。计数是进程内累计量，不是持久化格式；监控系统应按时间采样计算差值。 +应用关闭后诊断不会再次访问已释放句柄，而是明确报告平台不可用。 + +完整恢复策略与验收规模见 +[生命周期指南](https://github.com/yanxulang/yanxu-ui/blob/v1.0.0/docs/LIFECYCLE_AND_RECOVERY.md)。 +六目标发布门禁执行 1024 轮窗口、计时器和图片资源归零；应用仍需对自己的并发规模、图片 +负载、退出保存和目标桌面服务做上线压力测试。 diff --git a/content/docs/ecosystem/desktop/linux-support.mdx b/content/docs/ecosystem/desktop/linux-support.mdx index 6a1b1f6..64ee13c 100644 --- a/content/docs/ecosystem/desktop/linux-support.mdx +++ b/content/docs/ecosystem/desktop/linux-support.mdx @@ -3,7 +3,9 @@ title: Linux、Wayland 与 X11 description: 在 Linux x86-64 与 ARM64 的 Wayland 或 X11 桌面运行言界。 --- -首版正式支持`x86_64-unknown-linux-gnu`与`aarch64-unknown-linux-gnu`。同一言台制品保留 Wayland 与 X11 特性，winit 会依据桌面会话选择后端；应用代码和言界字节码不按显示协议分支。 +1.0 正式支持`x86_64-unknown-linux-gnu`与`aarch64-unknown-linux-gnu`。同一言台制品保留 +Wayland 与 X11 特性，winit 会依据桌面会话选择后端；应用代码和言界字节码不按显示协议 +分支，原生无障碍桥使用 AT-SPI。 运行需要可用的 Wayland 或 X11 会话，以及系统字体、剪贴板、文件对话框和输入法服务。CI 在两个架构编译全部路径，并用 Xvfb 验证 X11 真实窗口自动退出；无头 CI 没有用户输入法会话，所以不能声称验证了实际候选窗。 @@ -12,6 +14,7 @@ description: 在 Linux x86-64 与 ARM64 的 Wayland 或 X11 桌面运行言界 - Wayland 会话：确认窗口、缩放、指针、滚轮、拖放和文件对话框； - X11 会话：确认相同场景以及 X11 回退； - 使用 IBus 或 Fcitx5 的中文输入法检查预编辑、提交、取消和候选区位置； +- 使用 Orca 或目标辅助技术检查焦点、名称、表单状态、列表项与动作； - 安装合适的中文字体，或随应用携带许可字体； - 在分数缩放和多显示器下检查逻辑像素一致性； - 分别在 x86-64 与 ARM64 原生机器或执行器生成锁和 AppDir。 diff --git a/content/docs/ecosystem/desktop/macos-support.mdx b/content/docs/ecosystem/desktop/macos-support.mdx index f9caeb3..8821d88 100644 --- a/content/docs/ecosystem/desktop/macos-support.mdx +++ b/content/docs/ecosystem/desktop/macos-support.mdx @@ -3,7 +3,9 @@ title: macOS 支持 description: 在 Intel 与 Apple Silicon macOS 构建、验证和发布原生应用。 --- -首版正式支持`x86_64-apple-darwin`与`aarch64-apple-darwin`。两个目标都在对应 macOS 执行器完成原生 Release 构建、言序集成、示例构建与真实窗口冒烟。 +1.0 正式支持`x86_64-apple-darwin`与`aarch64-apple-darwin`。两个目标都在对应 macOS +执行器完成原生 Release 构建、ABI 导出、言序集成、言界全部公开示例、真实窗口与 +NSAccessibility 语义树自动退出验收。 言台通过 winit 的 AppKit 后端接收窗口、键盘、指针、触控板手势、拖放和输入法事件。`主`修饰键对应 Command。公开 API 不返回`NSWindow`、Cocoa 对象或原始指针；应用也不需要 Objective-C 分支。 @@ -12,6 +14,7 @@ description: 在 Intel 与 Apple Silicon macOS 构建、验证和发布原生应 - 分别生成 Intel 与 Apple Silicon 锁文件和`.app` Bundle； - 在系统中文输入法中检查组合、候选窗与中英文／Emoji 混排； - 检查 Retina 与外接非 Retina 显示器之间移动； +- 使用 VoiceOver 检查焦点、名称、表单状态、列表项与动作； - 确认应用名称、标识、版本、图标和资源进入 Bundle； - 如需要对外分发，在产物验证后另行执行 Apple 签名与公证流程。 diff --git a/content/docs/ecosystem/desktop/meta.json b/content/docs/ecosystem/desktop/meta.json index b5bf8db..dfcb37c 100644 --- a/content/docs/ecosystem/desktop/meta.json +++ b/content/docs/ecosystem/desktop/meta.json @@ -1,6 +1,6 @@ { "title": "桌面应用", - "description": "生态选读：用言窗或言界构建原生跨平台桌面应用。", + "description": "生态选读：在言窗 1.0 与言界 1.0 之间选择原生跨平台桌面方案。", "pages": [ "index", "routes", @@ -14,16 +14,22 @@ "ui-architecture", "---应用与控件---", "app-loop", + "lifecycle-diagnostics", "windows", "layout", "controls", + "forms", + "overlays-menus", + "data-views", "themes", "events", + "accessibility", "keyboard", "pointer", "text-ime", "fonts", "drawing", + "animation", "images-resources", "clipboard", "dialogs", diff --git a/content/docs/ecosystem/desktop/migration.mdx b/content/docs/ecosystem/desktop/migration.mdx index c9258fb..9c2540e 100644 --- a/content/docs/ecosystem/desktop/migration.mdx +++ b/content/docs/ecosystem/desktop/migration.mdx @@ -1,11 +1,30 @@ --- -title: 从言窗迁移 -description: 保持现有言窗应用可用，并按独立页面或新项目渐进采用言界。 +title: 升级与路线迁移 +description: 将言界和言台 0.x 升级到 1.0，或从言窗渐进采用保留模式路线。 --- -迁移不是升级前置条件。`yanxu-gui`已有独立的 1.0 稳定线，新增言台和言界不会替换它。 -现有言窗应用应先按[言窗 1.0](/ecosystem/desktop/gui/)升级并锁定公开 Release 制品，再决定 -是否评估另一条编程模型。 +## 从言界 0.x 升级到 1.0 + +1.0 保留从`v0.1.0`到`v0.9.0`的全部已发布源码 API。多数应用只需： + +1. 提交当前源码和各目标锁，保留可回滚点； +2. 把言界依赖改为`v1.0.0`与`^1.0`；直接使用言台的应用也改为其`v1.0.0`与`^1.0`； +3. 在每个目标系统与架构重新生成锁，不能复制另一目标的锁或手工替换动态库； +4. 只保留实际使用的图形、原生扩展、剪贴板和文件对话框权限； +5. 重建并验收窗口、IME、DPI、主题、屏幕阅读器、系统服务和关闭路径。 + +从 0.9 升级不需要源码修改。更早版本还应复核：0.4 起的帧反馈、0.5–0.6 的语义树和原生 +无障碍桥、0.7 的资源配额与单向退出，以及言界 0.7 的托管计时器／图片和结构化关闭报告。 +列表集合的无障碍值从 0.8 起只使用标量；选择和滚动动作属于当前可见的`列表项`或`标签` +节点，应用不能缓存旧树修订中的派生编号。 + +完整逐版本清单见言界的[迁移证明](https://github.com/yanxulang/yanxu-ui/blob/v1.0.0/docs/MIGRATION_0_X_TO_1_0.md) +和言台的[迁移指南](https://github.com/yanxulang/yanxu-platform/blob/v1.0.0/docs/MIGRATION_0_X_TO_1_0.md)。 + +## 从言窗评估言界 + +路线迁移不是升级前置条件。`yanxu-gui`已有独立的 1.0 稳定线，言台和言界不会替换它。 +现有言窗应用应先锁定公开 Release 制品，再决定是否评估另一种编程模型。 ## 概念映射 @@ -26,4 +45,6 @@ description: 保持现有言窗应用可用，并按独立页面或新项目渐 5. 为中文 IME、焦点顺序、快捷键、主题和 DPI 补充验收。 6. 只有当新页面满足需求时，才决定是否继续迁移其他独立窗口。 -首版不支持在同一个原生窗口中混用言窗和言界控件树。两条路线可存在于不同应用中；不要尝试把 egui 原生对象或平台句柄传入言台。 +1.0 不支持在同一个原生窗口中混用言窗和言界控件树。两条路线可存在于不同应用中；不要 +尝试把 egui 原生对象或平台句柄传入言台。若验收失败，应一起恢复旧清单和同一目标的旧锁 +再重新构建，不能只替换原生库或继续复用新版本 YXB。 diff --git a/content/docs/ecosystem/desktop/overlays-menus.mdx b/content/docs/ecosystem/desktop/overlays-menus.mdx new file mode 100644 index 0000000..e24d441 --- /dev/null +++ b/content/docs/ecosystem/desktop/overlays-menus.mdx @@ -0,0 +1,53 @@ +--- +title: 叠层与菜单 +description: 使用窗口级叠层栈构建可翻转弹层、嵌套模态焦点和完整键盘菜单。 +--- + +言界 1.0 的菜单、下拉选择和弹出层共享窗口级叠层栈。叠层只存在于当前窗口的控件树、 +事件和绘制路径中，不创建额外原生窗口；窗口关闭时会逆序清理全部叠层。 + +## 嵌套菜单 + +```yanxu +定 文件菜单 为 工具栏.菜单（【 + {「标题」：「文件」，「快捷键」：「⌘N」，「子菜单」：【 + {「标题」：「新建」}， + {「标题」：「打开」，「快捷键」：「⌘O」} + 】}， + {「标题」：「退出」，「禁用」：假} +】）； +文件菜单.监听（「选择」，处理选择）； +``` + +项目可以是文字或典。典支持`标题`、`子菜单`、`快捷键`、`禁用`、`分隔`、`动作`和 +`保持打开`。快捷键字段只负责显示；应用级快捷键仍应调用`窗口.快捷`注册，菜单不会注册 +系统全局快捷键。 + +输入在创建时完整校验：单层最多 1024 项、全部层最多 4096 项、深度最多 16，单个标题 +最多 65536 个字符。无效输入以`UI_MENU_*`错误原子拒绝，不留下部分菜单。 + +## 放置、命中和焦点 + +弹层可选择上、下、左、右方向；首选方向空间不足时自动翻转，再按窗口视口夹取。窗口缩放 +或根布局变化会重新计算位置。指针命中从最上层倒序进行，模态叠层会阻止事件落入背景树； +点击外部或按 Escape 可以关闭允许关闭的最上层。 + +嵌套模态叠层为每层建立焦点范围。Tab／Shift+Tab 只在当前范围循环，关闭后恢复到有效的 +原焦点或下一个可聚焦控件。下拉选择、菜单和通用弹出层共用这一套边界，不应在应用中维护 +第二套外部点击或焦点陷阱状态。 + +菜单键盘导航：Up／Down 在当前层循环，Home／End 跳到边界，Right 打开子菜单，Left 返回 +父层，Enter／空格激活，Escape 关闭当前层或整个根菜单。禁用和分隔项目不会进入选择序列。 + +## 选择与无障碍 + +叶项目的`选择`事件包含当前序号、层级、规范化项目和从根到叶的索引路径。项目`动作`先于 +选择事件执行；动作失败不会留下半激活层。 + +展开菜单以`菜单`、`菜单项`和`分隔符`角色生成语义子树，并声明点击、展开、折叠和聚焦 +动作。辅助技术请求仍需携带当前树修订；言界会重新验证层级、可见、启用和项目身份。窗口 +诊断只保存叠层数量、层级和边界摘要，不复制菜单文字或回调。 + +完整行为见 +[言界 1.0 叠层与菜单指南](https://github.com/yanxulang/yanxu-ui/blob/v1.0.0/docs/MENUS.md)， +可运行代码见[综合控件示例](/ecosystem/desktop/complete-example/)。 diff --git a/content/docs/ecosystem/desktop/packaging.mdx b/content/docs/ecosystem/desktop/packaging.mdx index 38f4803..a3d70ed 100644 --- a/content/docs/ecosystem/desktop/packaging.mdx +++ b/content/docs/ecosystem/desktop/packaging.mdx @@ -5,6 +5,7 @@ description: 锁定目标原生制品并生成 macOS、Windows 或 Linux 图形 ## 锁定依赖 +言界 1.0.0 固定言台`v1.0.0`和言据 1.1.2 的已审核提交。应用清单固定言界标签后， 首次构建或切换目标平台后，在应用根目录运行： ```sh @@ -12,7 +13,9 @@ yanbao 装 yanbao 查 ``` -提交生成的`言序.lock`。它记录当前目标、依赖精确提交、包内容摘要，以及所选言台动态库的 ABI、SHA-256 和大小。一个目标的锁文件不能冒充另一个架构的锁文件。 +提交生成的`言序.lock`。它记录当前目标、依赖精确提交、包内容摘要，以及所选言台动态库的 +ABI、SHA-256 和大小。一个目标的锁文件不能冒充另一个架构的锁文件；升级言界、言台或宿主 +后也必须重新生成锁和 YXB，不能只替换动态库。 ## 图形应用清单 @@ -36,8 +39,28 @@ yanbao 查 yanbao 构 --release --bundle ``` -言包会把 YXB、当前目标的锁定言台动态库、权限元数据、资源、图标、许可和摘要装入 macOS`.app`、Windows GUI 应用目录或 Linux AppDir。应用不得复制或硬编码 DLL、dylib 或 so 路径。 +言包会把 YXB、当前目标的锁定言台动态库、权限元数据、资源、图标、许可和摘要装入 macOS +`.app`、Windows GUI 应用目录或 Linux AppDir。生产 YXB 和 Bundle 使用言序 1.1.20 或更新 +的兼容稳定版构建；言序 1.1.9 是源码/API 兼容下限，不是生产降级要求。应用不得复制或硬编码 +DLL、dylib 或 so 路径，不使用的剪贴板或文件对话框权限应从清单删除。 ## 六目标发布 -每个目标都应在对应原生执行器重新生成锁、检查、测试、构建示例并运行自动退出窗口。汇总作业只有在六项全部成功后才能创建源码归档、目标锁目录和 SHA-256 文件。平台签名、公证或商店上传属于产物验收后的分发步骤。 +每个目标都应在对应原生执行器重新生成锁、检查、测试、构建应用并运行自动退出窗口。上线 +候选还应在实际桌面会话验证 IME、DPI、字体、屏幕阅读器、剪贴板、文件对话框和关闭报告。 +平台签名、公证或商店上传属于产物验收后的分发步骤。 + +## 核对上游来源 + +言界 1.0 Release 公开六目标归档、独立 SHA-256、包清单和冻结 API。其 Release 工作流不会 +重新编译，只复用同一标签提交的成功标签 CI 候选，并核对候选报告中的来源提交和归档摘要。 +应用的供应链记录至少应保存： + +- 言界与言台标签、精确提交和 Release 链接； +- 下载附件的 SHA-256，以及应用各目标锁中的包／原生制品摘要； +- 构建使用的言序、言包、系统和架构； +- 应用测试、真实桌面冒烟、签名／公证和回滚结果。 + +若需要回滚，恢复同一目标一起保存的旧清单和锁，再重新构建 Bundle；不要把旧 YXB 与新 +动态库或新锁混装。言界自身的候选来源门禁见 +[生产验收](https://github.com/yanxulang/yanxu-ui/blob/v1.0.0/docs/PRODUCTION_VALIDATION.md)。 diff --git a/content/docs/ecosystem/desktop/platform-architecture.mdx b/content/docs/ecosystem/desktop/platform-architecture.mdx index a4febb8..c52204c 100644 --- a/content/docs/ecosystem/desktop/platform-architecture.mdx +++ b/content/docs/ecosystem/desktop/platform-architecture.mdx @@ -1,34 +1,57 @@ --- title: 言台架构 -description: 言台 0.1.0 的 ABI v2、事件、文字、绘制与资源生命周期边界。 +description: 言台 1.0 的 ABI v2、四套机器协议、资源配额与原生无障碍边界。 --- -言台把三套桌面系统收敛为版本化的平台原语。公开言序包装层调用一个 ABI v2 原生模块；原生模块使用`winit 0.30`创建窗口和接收输入，使用`softbuffer`呈现 CPU 像素缓冲、`tiny-skia`栅格化二维图形、`cosmic-text`完成字体回退、整形、测量和命中。 +言台 1.0 把三套桌面系统收敛为版本化的平台原语。公开言序包装层调用一个 ABI v2 原生 +模块；原生模块使用`winit 0.30`创建窗口和接收输入，使用`softbuffer`呈现 CPU 像素缓冲、 +`tiny-skia`栅格化二维图形、`cosmic-text`完成字体回退与整形，并以 AccessKit 接通系统 +无障碍服务。 ```text 言序应用／言界 - │ 资源句柄、原生值、事件批次、YXDR 帧 + │ 资源、原生值、事件批次、语义树、YXDR 帧 ▼ 言台言序包装层 - │ ABI v2（34 项操作） + │ ABI v2（11 个函数、41 项操作、5 类资源） ▼ Rust 公共后端 ├─ winit：窗口、显示器、键盘、指针、IME、拖放 ├─ softbuffer + tiny-skia：表面与 CPU 二维绘制 ├─ cosmic-text：字体匹配、整形、测量、命中、字形 - └─ arboard / rfd：剪贴板与文件对话框 + ├─ AccessKit：UIA、NSAccessibility、AT-SPI + └─ arboard / rfd：文字与图片剪贴板、文件对话框 ``` ## 协议 - 平台 ABI 主版本为`2`；不匹配的主版本拒绝加载。 -- 事件协议为`1.1`，覆盖 36 种应用、窗口、输入、IME、拖放和系统事件。 +- 平台协议为`1.7`，固定能力查询、帧反馈、运行诊断、配额和生命周期语义。 +- 事件协议为`1.3`，覆盖 39 种应用、窗口、输入、IME、拖放、帧和无障碍事件。 +- 无障碍协议为`1.0`，固定 38 个角色、18 个状态、15 个动作和有界语义树。 - 每批事件有数量和字节上限；队列上限为 4096，高频状态在入队前合并。 - 绘制协议`YXDR 1.1`使用一个完整二进制帧，支持清空、裁剪、变换、矩形、圆角、直线、圆、路径、阴影、文字、字形、图片、图层和透明度。 - 协议解码器拒绝损坏缓冲、超限数据和未知主版本；可忽略兼容的未知次版本字段。 ## 所有权与线程 -应用是资源树根。窗口拥有表面和窗口级回调，字体和图片由应用持有；句柄包含代际，释放后的旧句柄不能访问复用槽位。关闭按子到父顺序执行且可重复调用。原生线程只能把事件投递到有界队列，所有言序回调都在 VM 所有者线程泵出。 +应用是资源树根。窗口、计时器、字体和图片都是应用的直接子资源；句柄包含代际，释放后的 +旧句柄不能访问复用槽位。应用可在创建首个子资源或首次运行前下调资源数、持有字节、帧和 +无障碍树配额，之后配额永久冻结。关闭按子到父顺序执行且可重复调用，应用生命周期只沿 +“就绪 → 运行中 → 退出请求 → 已退出 → 已关闭”前进。 -完整实现文档见[言台架构](https://github.com/yanxulang/yanxu-platform/blob/v0.1.0/docs/ARCHITECTURE.md)、[平台 API](https://github.com/yanxulang/yanxu-platform/blob/v0.1.0/docs/PLATFORM_API.md)、[事件协议](https://github.com/yanxulang/yanxu-platform/blob/v0.1.0/docs/EVENT_PROTOCOL.md)和[绘制协议](https://github.com/yanxulang/yanxu-platform/blob/v0.1.0/docs/DRAW_PROTOCOL.md)。 +原生事件循环只把事件投递到容量为 4096 的队列，所有言序回调都在 VM 所有者线程泵出。 +离散事件超限会以稳定错误停止循环；指针移动、窗口尺寸和重绘请求会合并。每个窗口只保留 +一个待呈现帧，新帧有界替换未呈现旧帧，并通过提交回执和`帧呈现`事件提供背压反馈。 + +## 生产可观测性 + +`应用.调试快照（）`提供事件队列、资源、帧、无障碍桥、配额和生命周期的当前量、高水位、 +累计量与拒绝统计，不包含窗口标题、用户文本、剪贴板内容或原生句柄。窗口语义树在首次 +显示前接入 UIA、NSAccessibility 或 AT-SPI；焦点和动作请求返回事件循环后，会重新校验 +树修订、节点身份、状态、参数和队列容量。 + +完整实现文档见[言台架构](https://github.com/yanxulang/yanxu-platform/blob/v1.0.0/docs/ARCHITECTURE.md)、 +[平台 API](https://github.com/yanxulang/yanxu-platform/blob/v1.0.0/docs/PLATFORM_API.md)、 +[1.0 协议冻结](https://github.com/yanxulang/yanxu-platform/blob/v1.0.0/docs/PROTOCOL_CONTRACT_1_0.md)和 +[资源生命周期](https://github.com/yanxulang/yanxu-platform/blob/v1.0.0/docs/RESOURCE_LIFETIME.md)。 diff --git a/content/docs/ecosystem/desktop/pointer.mdx b/content/docs/ecosystem/desktop/pointer.mdx index f8cd40e..841af6f 100644 --- a/content/docs/ecosystem/desktop/pointer.mdx +++ b/content/docs/ecosystem/desktop/pointer.mdx @@ -17,4 +17,4 @@ description: 统一处理鼠标、触摸、触控笔、滚轮、手势与指针 滚轮提供横向、纵向增量、单位和阶段。相邻滚轮事件会在一个批次内累积；指针移动只保留最新状态，离散按下／释放事件则从不丢失。滚动容器优先消费其可滚动方向，未消费部分可以继续冒泡给父滚动容器。 -手势事件可表达缩放、旋转、平移和压力，但首版言界的常用控件主要消费指针与滚轮；自定义画布可监听原始手势构建缩放或旋转交互。 +手势事件可表达缩放、旋转、平移和压力，但言界 1.0 的常用控件主要消费指针与滚轮；自定义画布可监听原始手势构建缩放或旋转交互。 diff --git a/content/docs/ecosystem/desktop/protocols.mdx b/content/docs/ecosystem/desktop/protocols.mdx index 563886d..1302f75 100644 --- a/content/docs/ecosystem/desktop/protocols.mdx +++ b/content/docs/ecosystem/desktop/protocols.mdx @@ -8,21 +8,34 @@ description: 平台、事件、绘制和配置协议的当前版本、协商与 | 协议 | 当前版本 | 数据路径 | 主版本规则 | | --- | --- | --- | --- | | 原生 ABI | 2 | 函数、资源、回调和原生值 | 必须精确匹配 | -| 平台协议 | 1.0 | 能力与平台原语 | 主版本不匹配拒绝 | -| 事件协议 | 1.1 | 一批言序典／列／基础值 | 主版本不匹配拒绝 | +| 平台协议 | 1.7 | 能力、平台原语、配额与诊断 | 主版本不匹配拒绝 | +| 事件协议 | 1.3 | 一批言序典／列／基础值 | 主版本不匹配拒绝 | +| 无障碍协议 | 1.0 | 有界语义树、焦点和动作 | 主版本不匹配拒绝 | | 绘制协议 | YXDR 1.1 | 小端版本化二进制完整帧 | 主版本不匹配拒绝 | | 主题配置 | 1 | 言据优先、JSON 兼容 | 主版本不匹配拒绝 | +1.0 机器契约还固定 50 个能力字段、39 个事件、38 个无障碍角色、18 个状态、15 个动作、 +17 个绘制操作码、5 个路径操作码，以及 ABI v2 的 11 个函数、41 项操作和 5 类资源。 + ## 次版本兼容 - 典格式可以增加可选字段，旧消费者忽略未知字段； - 事件协议可以增加名称，旧消费者忽略未知事件并继续处理批次； +- 无障碍协议可以在可忽略位置追加角色、状态或动作，既有编号和参数语义不可复用； - YXDR 可以增加操作码，旧后端按负载长度安全跳过； - 新消费者不能假设旧生产者提供较新的可选字段； - 不得复用已有字段或操作码表达另一种单位或语义。 ## 安全上限 -事件队列 4096；绘制帧 16 MiB、单命令 4 MiB、命令数 65536、状态栈 256；字体 64 MiB；图片单边 16384、解码分配 256 MiB。损坏长度、错误 UTF-8、非有限数字、非零填充和超限输入都返回稳定错误。 +事件队列容量为 4096。单个绘制帧限制 16 MiB、单命令 4 MiB、命令数 65536、状态栈 256； +单窗口无障碍树限制 16384 个节点、深度 64、文字 4 MiB。应用默认硬上限包括 4096 个 +资源、64 个窗口、2048 个计时器、256 张图片和 64 个字体，应用可以在首次使用前下调。 +剪贴板文字限制 16 MiB，RGBA8 图片单边限制 16384、总量 256 MiB。损坏长度、错误 UTF-8、 +非有限数字、非零填充和超限输入都返回稳定错误。 -规范原文见[事件协议](https://github.com/yanxulang/yanxu-platform/blob/v0.1.0/docs/EVENT_PROTOCOL.md)、[绘制协议](https://github.com/yanxulang/yanxu-platform/blob/v0.1.0/docs/DRAW_PROTOCOL.md)与[言据／JSON 决策](https://github.com/yanxulang/yanxu-platform/blob/v0.1.0/docs/ADR-004-yanju-json-compatibility.md)。 +规范原文见[1.0 协议冻结](https://github.com/yanxulang/yanxu-platform/blob/v1.0.0/docs/PROTOCOL_CONTRACT_1_0.md)、 +[事件协议](https://github.com/yanxulang/yanxu-platform/blob/v1.0.0/docs/EVENT_PROTOCOL.md)、 +[无障碍协议](https://github.com/yanxulang/yanxu-platform/blob/v1.0.0/docs/ACCESSIBILITY_PROTOCOL.md)、 +[绘制协议](https://github.com/yanxulang/yanxu-platform/blob/v1.0.0/docs/DRAW_PROTOCOL.md)与 +[言据／JSON 决策](https://github.com/yanxulang/yanxu-platform/blob/v1.0.0/docs/ADR-004-yanju-json-compatibility.md)。 diff --git a/content/docs/ecosystem/desktop/quick-start.mdx b/content/docs/ecosystem/desktop/quick-start.mdx index a0f01d9..a928677 100644 --- a/content/docs/ecosystem/desktop/quick-start.mdx +++ b/content/docs/ecosystem/desktop/quick-start.mdx @@ -1,13 +1,13 @@ --- title: 快速开始 -description: 使用言序 1.1.9、言包 0.5.0 与言界 0.1.1 复现已验证的预览组合。 +description: 使用当前稳定工具链与言界 1.0 创建并运行第一个保留模式桌面应用。 --- - - 本页复现言界 0.1.1 发布时的已验证组合：言序 1.1.9 与言包 0.5.0。言序 1.1.20 会在言界源码的可空目标变量处报告类型错误，言包 0.6.1 也不能运行在 1.1.9 上。使用当前稳定工具链时，请改走[言窗 1.0](/ecosystem/desktop/gui/)。 - +言界 1.0 同时验证最低言序 1.1.9 和当前稳定言序 1.1.20。新项目建议使用言序 1.1.20 与 +言包 0.6.1；依赖锁仍由言序 1.1.9 生成并进入六目标 Release 验收。 -先确认`yanxu --version`为`1.1.9`，`yanbao --version`为`0.5.0`。创建普通言序项目后，在`言序.toml`中加入言界： +先确认`yanxu --version`为`1.1.20`，`yanbao --version`为`0.6.1`。创建普通言序项目后， +在`言序.toml`中加入言界： ```toml [包] @@ -18,7 +18,7 @@ description: 使用言序 1.1.9、言包 0.5.0 与言界 0.1.1 复现已验证 入口 = "src/主.yx" [依赖] -言界 = { 包 = "yanxu-ui", git = "https://github.com/yanxulang/yanxu-ui.git", 修订 = "v0.1.1", 版 = "^0.1" } +言界 = { 包 = "yanxu-ui", git = "https://github.com/yanxulang/yanxu-ui.git", 修订 = "v1.0.0", 版 = "^1.0" } [权限] 图形界面 = true @@ -62,3 +62,6 @@ yanbao run ``` 第一次更新会为当前目标下载锁定的言台原生后端。运行后可在输入框测试中文 IME，再点击“问候”。若只需要显示文字，可继续阅读[创建第一个窗口](/ecosystem/desktop/first-window/)；发布独立应用见[打包与发布](/ecosystem/desktop/packaging/)。 + +生产应用应在每个目标系统上重新运行`yanbao update`并提交各自的锁；不能复制其他架构的锁。 +最低工具链只用于验证源码下限，不要求新项目降级当前工具链。 diff --git a/content/docs/ecosystem/desktop/routes.mdx b/content/docs/ecosystem/desktop/routes.mdx index 0c814d2..fc0841f 100644 --- a/content/docs/ecosystem/desktop/routes.mdx +++ b/content/docs/ecosystem/desktop/routes.mdx @@ -1,6 +1,6 @@ --- title: 言窗与言界的区别 -description: 比较现有立即模式言窗与新的言序保留模式言界路线。 +description: 比较两条稳定 1.0 桌面路线的立即模式与保留模式编程模型。 --- 两条路线解决同一个“原生桌面应用”问题，但控件归属和编程模型不同。 @@ -9,18 +9,19 @@ description: 比较现有立即模式言窗与新的言序保留模式言界路 | --- | --- | --- | | 控件实现 | egui/eframe 后端提供 | 言序代码提供 | | 模型 | 立即模式 | 保留模式控件树 | -| 成熟度 | 稳定`1.0.0`路线 | 独立的`0.1.x`路线 | +| 稳定线 | `1.0.x` | `1.0.x` | | 自定义控件 | 围绕 egui API 扩展 | 组合控件、渲染树或画布命令 | | 布局与事件 | 后端框架语义 | 言序统一的布局、捕获／目标／冒泡 | | 原生边界 | 包直接封装 egui/eframe/winit | 言界只调用言台平台原语 | -| 迁移要求 | 无 | 可按窗口或新项目渐进采用，不强制迁移 | +| 发布目标 | Windows、macOS、Linux GNU 的 x86-64／ARM64 | Windows、macOS、Linux GNU 的 x86-64／ARM64 | 言界中的按钮不是系统按钮，也不是言台按钮：它的悬停、按下、焦点、键盘激活、布局、状态和绘制都在`yanxu-ui/src`的言序代码里。言台只接收输入事件，并提交最终绘制帧。 ## 兼容承诺 -言窗 1.0 要求言序 1.1.12、格式 2 清单和 ABI v2；言界 0.1.x 有自己的兼容线。两个 GUI -包可以在不同应用中并存；不支持在同一原生窗口内混合两棵控件树。 +言窗 1.0 要求言序 1.1.12、格式 2 清单和 ABI v2。言界 1.0 最低支持言序 1.1.9，正式 +制品使用 1.1.20 构建，并固定消费言台 1.0。两个 GUI 包可以在不同应用中并存；不支持在 +同一原生窗口内混合两棵控件树。 -若已有言窗项目，应先升级到公开 1.0 制品并保持兼容线。只有当新页面需要保留状态、 -深度主题化、可组合控件、确定的事件传播或将控件逻辑留在言序层时，才评估言界。 +已有言窗项目无需迁移。新页面需要保留状态、深度主题化、可组合控件、确定的事件传播或 +希望把控件逻辑留在言序层时，选择言界；依赖 egui 现成控件或立即模式时继续选择言窗。 diff --git a/content/docs/ecosystem/desktop/themes.mdx b/content/docs/ecosystem/desktop/themes.mdx index 4e43011..07e2096 100644 --- a/content/docs/ecosystem/desktop/themes.mdx +++ b/content/docs/ecosystem/desktop/themes.mdx @@ -24,3 +24,7 @@ description: 使用内置浅深主题、控件状态样式和可继承自定义 颜色使用`【红，绿，蓝，透明度】`的 0–255 整数列；几何度量使用逻辑像素。应用级设计系统应写成[言据配置](/ecosystem/desktop/yanju-config/)，再调用`应用.主题配置（配置.规范主题（数据））`。JSON 可作为外部工具兼容输入，但不是唯一格式。 系统主题变化会成为应用事件。是否自动跟随由应用决定；切换主题后，言界标记受影响控件的绘制脏区并生成新帧。 + +运行时局部更新使用`应用.更新主题（覆盖典）`。更新会先完整解析和校验，再原子替换主题、 +清空样式缓存并返回单调修订；失败不会留下半更新状态。窗口会重新布局并重建绘制与语义 +快照，应用不需要逐个控件手工失效。 diff --git a/content/docs/ecosystem/desktop/troubleshooting.mdx b/content/docs/ecosystem/desktop/troubleshooting.mdx index 15a3808..97d8450 100644 --- a/content/docs/ecosystem/desktop/troubleshooting.mdx +++ b/content/docs/ecosystem/desktop/troubleshooting.mdx @@ -5,7 +5,9 @@ description: 定位依赖锁、权限、显示会话、ABI、绘制、资源和 ## 包无法解析或原生库不匹配 -确认言界依赖使用存在的`v0.1.1`标签、言台由锁图解析到兼容的`v0.1.0`，删除手工复制的动态库，再在目标平台运行`yanbao 装`。检查`言序.lock`中的目标、ABI、SHA-256 和大小；不要复用另一架构的锁。 +确认言界依赖使用`v1.0.0`与`^1.0`，锁图中的言台解析到`v1.0.0`。删除手工复制的动态库， +再在目标平台运行`yanbao 装`。检查`言序.lock`中的系统、架构、ABI、SHA-256、大小和精确 +提交；不要复用另一架构的锁。升级依赖后必须重新构建 YXB 与 Bundle。 ## 权限错误 @@ -31,4 +33,23 @@ description: 定位依赖锁、权限、显示会话、ABI、绘制、资源和 `PLATFORM_RESOURCE_CLOSED`表示句柄代际已失效；重新获取资源，不能缓存旧编号。`PLATFORM_WRONG_THREAD`表示从非所有者事件循环使用资源；把操作投递回应用事件泵。 -报告问题时附上系统、架构、言序／言包／言界／言台版本、协议查询、能力查询和最小可复现源码，不要附带私密路径或剪贴板内容。 +## 配额耗尽或应用不能再次运行 + +`PLATFORM_QUOTA_*`表示资源数量、图片／字体持有字节、帧或无障碍树达到应用配额。读取 +`应用.资源配额（）`和诊断快照，关闭不用的资源；只能在首个子资源或首次运行前下调配额， +冻结后不能提高或重新配置。应用退出后生命周期只会继续到已关闭，不能再次调用`运行（）`。 + +## 动画停止或出现帧替换 + +动画依赖匹配的`帧呈现`反馈。窗口隐藏、最小化或表面尺寸为零时反馈可暂停；恢复后由新的 +重绘继续。检查窗口诊断中的待呈现身份、提交、替换、忽略和失败计数。被替换帧不会再产生 +呈现事件，应用不能围绕旧帧编号持续等待。 + +## 屏幕阅读器没有读出控件 + +先确认`能力查询（）`中的`原生无障碍桥`为真，后端为 UIA、NSAccessibility 或 AT-SPI。 +自定义控件必须保留稳定正编号、逻辑边界、标量值和实际实现的动作；处理焦点／动作请求时 +核对当前树修订。无头 CI 只能证明适配器与树同步，最终播报需在启用辅助技术的桌面会话验证。 + +报告问题时附上系统、架构、言序／言包／言界／言台版本、协议查询、能力查询、内容安全的 +诊断快照、结构化关闭报告和最小可复现源码，不要附带私密路径、输入内容或剪贴板内容。 diff --git a/content/docs/ecosystem/desktop/ui-architecture.mdx b/content/docs/ecosystem/desktop/ui-architecture.mdx index ba3398c..b970b9b 100644 --- a/content/docs/ecosystem/desktop/ui-architecture.mdx +++ b/content/docs/ecosystem/desktop/ui-architecture.mdx @@ -1,22 +1,25 @@ --- title: 言界架构 -description: 言界 0.1.1 的保留模式控件树、布局、事件、文本与渲染管线。 +description: 言界 1.0 的保留模式控件树、数据视图、无障碍、动画与资源生命周期。 --- -言界除调用言台的边界模块外全部使用言序编写。一个窗口拥有一棵长期存在的控件树；属性变化标记布局或绘制脏区，下一帧只重新计算受影响的子树，再把渲染树编码为一个`YXDR`帧提交。 +言界除调用言台的边界模块外全部使用言序编写。一个窗口拥有一棵长期存在的控件树；属性 +变化标记布局、语义或绘制脏区，下一帧只重新计算受影响的子树，再把无障碍语义树和渲染 +树分别作为完整快照提交。 ```text -状态／数据绑定 +状态／数据绑定／增量数据源 ↓ -控件树与组件生命周期 +控件树／叠层栈／组件生命周期 ↓ 约束测量 → 行列／堆叠／网格／滚动布局 ↓ 命中测试 → 捕获 → 目标 → 冒泡 → 焦点／快捷键 + ├─ 稳定控件编号 → 言台无障碍语义树 ↓ 渲染树 + 脏区合并 ↓ -版本化二进制绘制帧 → 言台 +版本化二进制绘制帧 → 帧反馈 → 有界动画 ``` ## 核心子系统 @@ -25,11 +28,18 @@ description: 言界 0.1.1 的保留模式控件树、布局、事件、文本与 - **事件**：命中测试、指针捕获、捕获／目标／冒泡阶段、Tab 焦点顺序和应用快捷键。 - **文本**：Unicode 文档、光标与选区、插入删除、剪切复制粘贴、撤销重做、上下／Home／End、鼠标定位、IME 组合和多行滚动。 - **样式**：浅色、深色和自定义主题；状态样式沿控件树继承；言据优先、JSON 兼容。 -- **渲染**：保留渲染节点、脏区合并、单调时间动画值、图片资源和自定义画布命令。 -- **语义**：控件角色、名称、描述、状态和焦点关系组成可序列化无障碍语义树。 +- **叠层**：锚定、四方向自动翻转、视口夹取、逆序命中、嵌套模态焦点范围和子菜单。 +- **数据**：批次最多 256 项的增量数据源、缓存淘汰、失败状态和只创建可见行的虚拟列表。 +- **渲染与动画**：保留渲染节点、脏区合并、单槽帧背压、呈现反馈驱动动画、图片资源和画布命令。 +- **语义**：稳定控件编号、角色、状态和动作组成有界无障碍树，并接收系统焦点／动作请求。 +- **生命周期**：言台配额协商、托管计时器和图片、单向窗口／应用关闭及结构化关闭报告。 按钮等高级控件完整处理悬停、按下、键盘激活和绘制；言台没有“创建按钮”操作。言界源码也不包含 Win32、AppKit、Wayland、X11 或平台指针分支。 -0.1.1 会按样式名与悬停、按下、焦点、禁用状态位缓存主题解析结果，并缓存基础样式与控件种类样式的合并，避免每个控件在每帧重复深合并。缓存只改变渲染开销，不改变主题字段、继承或状态优先级。 +1.0 会按样式名与悬停、按下、焦点、禁用状态位缓存主题解析结果；主题更新原子清空缓存并 +使窗口重新布局。应用与窗口诊断只汇总编号、数量、状态、帧、动画和生命周期计数，不复制 +窗口标题、控件内容、密码值、回调、无障碍文字树或原生句柄。 -实现细节见[言界架构](https://github.com/yanxulang/yanxu-ui/blob/v0.1.1/docs/ARCHITECTURE.md)与[API 文档](https://github.com/yanxulang/yanxu-ui/blob/v0.1.1/docs/API.md)。 +实现细节见[言界 1.0 架构](https://github.com/yanxulang/yanxu-ui/blob/v1.0.0/docs/ARCHITECTURE.md)、 +[API 文档](https://github.com/yanxulang/yanxu-ui/blob/v1.0.0/docs/API.md)与 +[生产验收](https://github.com/yanxulang/yanxu-ui/blob/v1.0.0/docs/PRODUCTION_VALIDATION.md)。 diff --git a/content/docs/ecosystem/desktop/windows-support.mdx b/content/docs/ecosystem/desktop/windows-support.mdx index e9e8eb4..61f140c 100644 --- a/content/docs/ecosystem/desktop/windows-support.mdx +++ b/content/docs/ecosystem/desktop/windows-support.mdx @@ -3,7 +3,9 @@ title: Windows 支持 description: 在 Windows x86-64 与 ARM64 构建、测试和发布言界应用。 --- -首版正式支持`x86_64-pc-windows-msvc`与`aarch64-pc-windows-msvc`。两个目标都在对应 GitHub Actions Windows 执行器上构建言台动态库、言序工具链、言界包入口和全部公开示例，并运行自动退出的真实窗口冒烟。 +1.0 正式支持`x86_64-pc-windows-msvc`与`aarch64-pc-windows-msvc`。两个目标都在对应 +Windows 执行器构建言台动态库、核对 ABI 导出、运行言序集成、言界全部公开示例、真实 +窗口和 UIA 语义树自动退出验收。 窗口、键盘、鼠标、触摸、触控笔、显示器、拖放和 IME 由 winit 的 Windows 后端接入；CPU 表面由 softbuffer 呈现。`主`修饰键对应 Control。窗口尺寸和事件坐标使用逻辑像素，系统缩放变化会产生`DPI变化`。 @@ -14,6 +16,7 @@ description: 在 Windows x86-64 与 ARM64 构建、测试和发布言界应用 - 在系统拼音或其他目标输入法中检查组合更新、提交、取消与候选窗位置； - 检查 100%、150%、200% 缩放及跨显示器移动； - 测试文件对话框、剪贴板和包含中文／Emoji 的路径； +- 使用 Narrator 或目标屏幕阅读器检查焦点、名称、表单状态、列表项与动作； - 用 GUI Bundle 入口启动，确认不会额外打开控制台窗口。 Windows ARM64 是正式矩阵目标，不以 x86-64 模拟结果代替。系统字体集合与 x86-64 可能不同，品牌界面应携带同一许可字体。 diff --git a/content/docs/ecosystem/desktop/windows.mdx b/content/docs/ecosystem/desktop/windows.mdx index c1f02b8..70be6e3 100644 --- a/content/docs/ecosystem/desktop/windows.mdx +++ b/content/docs/ecosystem/desktop/windows.mdx @@ -25,7 +25,9 @@ description: 创建、显示、调整和关闭言界原生窗口。 窗口.显示（）； ``` -尺寸使用逻辑像素。言台还统一实现位置、最小／最大尺寸、最大化、最小化、全屏、无边框、透明、始终置顶、请求重绘、客户区尺寸、比例因子和当前显示器；言界首版公开常用窗口方法，其余能力可通过贡献通用包装逐步开放，不能在应用中绕过言台读取平台句柄。 +尺寸使用逻辑像素。言台还统一实现位置、最小／最大尺寸、最大化、最小化、全屏、无边框、 +透明、始终置顶、请求重绘、客户区尺寸、比例因子和当前显示器；言界 1.0 公开常用窗口方法， +其余能力应通过通用包装扩展，不能在应用中绕过言台读取平台句柄。 窗口关闭包含“请求”和“完成”两个阶段。用`关闭时`拦截用户关闭按钮： @@ -36,4 +38,6 @@ description: 创建、显示、调整和关闭言界原生窗口。 窗口.关闭时（关闭主窗）； ``` -`窗口.关闭（）`可由程序主动关闭资源；重复调用安全。关闭会先释放子控件和回调，再释放绘制表面和原生窗口，旧代际句柄随后失效。 +`窗口.关闭（）`可由程序主动关闭资源；重复调用安全，并返回同一份结构化关闭报告。关闭 +会按叠层、帧调度、控件树、无障碍、原生窗口和应用登记继续最佳努力清理；单个步骤失败 +不会跳过后续步骤。旧代际句柄随后失效。 diff --git a/content/docs/ecosystem/index.mdx b/content/docs/ecosystem/index.mdx index b1cf53c..07e6397 100644 --- a/content/docs/ecosystem/index.mdx +++ b/content/docs/ecosystem/index.mdx @@ -9,7 +9,7 @@ description: 了解在语言核心之外独立版本化、独立发布的官方 - + 选择生态包前先核对其 Release、最低核心版本、锁定来源、权限和测试范围。核心版本号不能 diff --git "a/examples/desktop/\347\273\274\345\220\210\346\216\247\344\273\266\345\261\225\347\244\272.yx" "b/examples/desktop/\347\273\274\345\220\210\346\216\247\344\273\266\345\261\225\347\244\272.yx" index c4ea296..4936cde 100644 --- "a/examples/desktop/\347\273\274\345\220\210\346\216\247\344\273\266\345\261\225\347\244\272.yx" +++ "b/examples/desktop/\347\273\274\345\220\210\346\216\247\344\273\266\345\261\225\347\244\272.yx" @@ -2,13 +2,21 @@ 定 应用 为 界面.应用（「言界综合控件展示」）； -定 窗口 为 应用.窗口（{「标题」：「言界 0.1.1」，「宽」：960，「高」：700，「最小宽」：720，「最小高」：520}）； +定 窗口 为 应用.窗口（{「标题」：「言界综合控件展示」，「宽」：960，「高」：700，「最小宽」：720，「最小高」：520}）； 定 主列 为 窗口.列（{「内边距」：18，「间距」：10}）； 定 菜单行 为 主列.行（{「间距」：8}）； -菜单行.菜单（【{「标题」：「新建」}，{「标题」：「打开」}，{「标题」：「退出」}】）； +令 菜单选择次数 为 0； + +法 记录菜单选择（所事件） 则 + 置 菜单选择次数 为 （菜单选择次数 加 1）； +终 + +定 主菜单 为 菜单行.菜单（【{「标题」：「文件」，「快捷键」：「⌘N」，「子菜单」：【{「标题」：「新建」}，{「标题」：「打开」，「快捷键」：「⌘O」}】}，{「标题」：「编辑」，「子菜单」：【{「标题」：「撤销」，「快捷键」：「⌘Z」}，{「标题」：「重做」，「快捷键」：「⇧⌘Z」}】}，{「标题」：「退出」}】）； + +主菜单.监听（「选择」，记录菜单选择）； 菜单行.文字（「保留模式控件全部由言序实现」）； diff --git "a/examples/desktop/\350\250\200\345\272\217.lock" "b/examples/desktop/\350\250\200\345\272\217.lock" index 51791b0..fdfc1cd 100644 --- "a/examples/desktop/\350\250\200\345\272\217.lock" +++ "b/examples/desktop/\350\250\200\345\272\217.lock" @@ -1,23 +1,23 @@ lock_version = 2 -manifest_checksum = "9287fbf4340310fae1aeef66c4eb2aafca93c0c74a6d31b13eac3bbabe5ac5a8" +manifest_checksum = "6c55aec4be9991dabc748e93b85c2b82a8c066bfd9ef5e8809a9ed317d596789" target = "aarch64-apple-darwin" generator = "1.1.9" [root_dependencies] -"言界" = "yanxu-ui@0.1.1#44f9b5e8534a-193ba75d1d46bdf0" +"言界" = "yanxu-ui@1.0.0#44f9b5e8534a-cfb7de23c2dcbb76" [root_dev_dependencies] [[package]] -id = "yanxu-platform@0.1.0#d95caa6bf952-93c96bdb2e39ad2a" +id = "yanxu-platform@1.0.0#d95caa6bf952-c0ebb9773aa5a4d9" name = "yanxu-platform" -version = "0.1.0" +version = "1.0.0" source = "git:https://github.com/yanxulang/yanxu-platform.git" -revision = "c9aac937942cf81bfdfb285f6b50afcb56a49a86" -checksum = "93c96bdb2e39ad2a8bf740dc24bb71082a232dc44885e5a9f07c05dea38b5e24" +revision = "9b6bce794a2e23fba04340f762e3d8f49a2724ff" +checksum = "c0ebb9773aa5a4d9e889213ef085d9f75f5959f7cc5b63aa7c60f4e83f5df0ad" entry = "src/主.yx" target = "aarch64-apple-darwin" -minimum_yanxu = ">=1.1.7" +minimum_yanxu = ">=1.1.7, <2.0.0" [package.dependencies] @@ -28,26 +28,28 @@ minimum_yanxu = ">=1.1.7" abi = 2 target = "aarch64-apple-darwin" path = "dist/aarch64-apple-darwin/libyanxu_platform_native.dylib" -checksum = "ad91b0a85a9f39926dc2b2127a648b29eaff2e4b3521be893f7c11ec7ffc3c9c" -size = 4670368 +checksum = "4ba2a55db0828178d67c555500844bc2e03856bef79aeddae96bf0d3bfec6fdb" +size = 6129760 [[package]] -id = "yanxu-ui@0.1.1#44f9b5e8534a-193ba75d1d46bdf0" +id = "yanxu-ui@1.0.0#44f9b5e8534a-cfb7de23c2dcbb76" name = "yanxu-ui" -version = "0.1.1" +version = "1.0.0" source = "git:https://github.com/yanxulang/yanxu-ui.git" -revision = "fb7776baa05ba4ec950696eb9a4cc1f11f290638" -checksum = "193ba75d1d46bdf0489fc5c7efd667f4f1c3dad0ee578d2461c84e2bc44494c9" +revision = "5818a5aa76790f85480c90b3ce80be73df3f11b9" +checksum = "cfb7de23c2dcbb76a4eafc265217fcb33ef19d065b36cf12c22c3902ee34eae1" entry = "src/主.yx" target = "aarch64-apple-darwin" minimum_yanxu = ">=1.1.9" [package.dependencies] -"言台" = "yanxu-platform@0.1.0#d95caa6bf952-93c96bdb2e39ad2a" +"言台" = "yanxu-platform@1.0.0#d95caa6bf952-c0ebb9773aa5a4d9" "言据" = "言据@1.1.2#9f376cc5bbdb-224c315783494338" [package.exports] "几何" = "src/核心/几何.yx" +"叠层" = "src/叠层/公共.yx" +"数据源" = "src/数据/源.yx" "文本" = "src/文本/文档.yx" "脏区" = "src/核心/脏区.yx" "配置" = "src/样式/配置.yx" diff --git "a/examples/desktop/\350\250\200\345\272\217.toml" "b/examples/desktop/\350\250\200\345\272\217.toml" index 59e5fc8..adcaeb3 100644 --- "a/examples/desktop/\350\250\200\345\272\217.toml" +++ "b/examples/desktop/\350\250\200\345\272\217.toml" @@ -1,18 +1,18 @@ [包] 格式 = 2 名称 = "言序文档图形示例" -版本 = "0.1.0" +版本 = "1.0.0" 言序 = ">=1.1.9" 入口 = "自动关闭冒烟.yx" [依赖] -言界 = { 包 = "yanxu-ui", git = "https://github.com/yanxulang/yanxu-ui.git", 修订 = "v0.1.1", 版 = "^0.1" } +言界 = { 包 = "yanxu-ui", git = "https://github.com/yanxulang/yanxu-ui.git", 修订 = "v1.0.0", 版 = "^1.0" } [应用] 类型 = "图形" 名称 = "言序文档图形示例" 标识 = "dev.yanxu.docs-gui-examples" -版本 = "0.1.0" +版本 = "1.0.0" [应用.窗口] 宽 = 960 diff --git a/scripts/check-content.mjs b/scripts/check-content.mjs index 76c0205..51d8525 100644 --- a/scripts/check-content.mjs +++ b/scripts/check-content.mjs @@ -96,7 +96,8 @@ assert.match(read('app/layout.tsx'), /metadataBase:\s*new URL\('https:\/\/docs\. const docsCi = read('.github/workflows/ci.yml'); assert.match(docsCi, /name: 入门语言示例[\s\S]*?ref: v1\.1\.20/, '语言示例 CI 未固定言序 1.1.20'); -assert.match(docsCi, /name: 桌面生态示例[\s\S]*?ref: v1\.1\.9/, '言界示例 CI 未固定已验证的言序 1.1.9'); +assert.match(docsCi, /yanxu: \['1\.1\.9', '1\.1\.20'\]/, '言界示例 CI 未覆盖最低与当前工具链'); +assert.match(docsCi, /ref: v\$\{\{ matrix\.yanxu \}\}/, '言界示例 CI 未按矩阵固定工具链标签'); assert.match(read('content/docs/language/binary-data.mdx'), /单值硬上限为 16 MiB/); assert.match(read('content/docs/reference/project-format.mdx'), /\| 字节码块 \| 2 \| 2 \|/); assert.match(read('content/docs/reference/permissions.mdx'), /15 项宿主能力/); @@ -115,16 +116,55 @@ for (const requirement of [ } const desktopManifest = read('examples/desktop/言序.toml'); assert.match(desktopManifest, /言序 = ">=1\.1\.9"/); -assert.match(desktopManifest, /修订 = "v0\.1\.1"/); +assert.match(desktopManifest, /版本 = "1\.0\.0"/); +assert.match(desktopManifest, /修订 = "v1\.0\.0"/); +assert.match(desktopManifest, /版 = "\^1\.0"/); +for (const permission of ['图形界面', '原生扩展', '剪贴板', '文件对话框']) { + assert.match(desktopManifest, new RegExp(`^${permission} = true$`, 'm'), `桌面示例缺少 ${permission} 权限`); +} const desktopLock = read('examples/desktop/言序.lock'); assert.match(desktopLock, /generator = "1\.1\.9"/); -assert.match(desktopLock, /yanxu-ui@0\.1\.1/); +assert.match(desktopLock, /target = "aarch64-apple-darwin"/); +assert.match(desktopLock, /yanxu-ui@1\.0\.0/); +assert.match(desktopLock, /yanxu-platform@1\.0\.0/); assert.match(desktopLock, /minimum_yanxu = ">=1\.1\.9"/); +assert.match(desktopLock, /\[package\.native\][\s\S]*?abi = 2/); const desktopCompatibility = read('content/docs/ecosystem/desktop/compatibility.mdx'); -for (const requirement of ['1.1.9', '1.1.20', '0.5.0', '0.6.1', '0.1.1', '1.1.2']) { +for (const requirement of [ + '1.1.9', '1.1.20', '0.6.1', '1.0.0', '1.1.2', + '平台 1.7', '事件 1.3', '无障碍 1.0', '绘制 1.1', '70 个稳定错误码', +]) { assert.ok(desktopCompatibility.includes(requirement), `桌面兼容矩阵缺少 ${requirement}`); } -assert.match(desktopCompatibility, /不存在“言序 1\.1\.20 \+ 言包 0\.6\.1 \+ 言界 0\.1\.1”/); +const desktopMeta = JSON.parse(read('content/docs/ecosystem/desktop/meta.json')); +for (const page of [ + 'accessibility', 'lifecycle-diagnostics', 'forms', 'overlays-menus', 'data-views', 'animation', +]) { + assert.ok(desktopMeta.pages.includes(page), `桌面 1.0 导航缺少 ${page}`); +} +assert.equal( + firstCodeBlock(read('content/docs/ecosystem/desktop/complete-example.mdx'), 'yanxu'), + read('examples/desktop/综合控件展示.yx'), + '言界完整示例与可运行源码不一致', +); +const desktopPages = desktopMeta.pages + .filter((page) => !page.startsWith('---')) + .map((page) => read(`content/docs/ecosystem/desktop/${page}.mdx`)) + .join('\n'); +assert.doesNotMatch(desktopPages, /yanxu-(?:ui|platform)\/blob\/v0\./, '桌面 1.0 文档仍链接 0.x 上游文档'); +assert.doesNotMatch(desktopPages, /言界 0\.1\.1|言台 0\.1\.0/, '桌面 1.0 文档仍把旧预览版写成当前版本'); +for (const requirement of [ + '30 个声明', '23 个类', '7 个包级函数', '125 个域', '375 个方法', +]) { + assert.ok(read('content/docs/ecosystem/desktop/api-reference.mdx').includes(requirement), + `言界 1.0 API 参考缺少 ${requirement}`); +} +for (const requirement of [ + '平台协议为`1.7`', '事件协议为`1.3`', '无障碍协议为`1.0`', 'YXDR 1.1', +]) { + assert.ok(read('content/docs/ecosystem/desktop/platform-architecture.mdx').includes(requirement), + `言台 1.0 架构缺少 ${requirement}`); +} const stableLibraries = [ ['yanju', '1.2.0', '1.1.6', 'content/docs/ecosystem/yanju/index.mdx', '/ecosystem/yanju/'], diff --git a/scripts/check-site.mjs b/scripts/check-site.mjs index d833348..5a896ae 100644 --- a/scripts/check-site.mjs +++ b/scripts/check-site.mjs @@ -77,7 +77,8 @@ for (const required of [ const searchIndex = fs.readFileSync(path.join(output, 'api/search')); const searchIndexBytes = searchIndex.byteLength; const compressedSearchIndexBytes = gzipSync(searchIndex, { level: 9 }).byteLength; -if (searchIndexBytes > 8_000_000) failures.push(`中文搜索索引超过 8 MB：${searchIndexBytes} B`); +// 1.0 桌面指南增加索引内容；实际传输体积继续由下方 2 MB gzip 门禁约束。 +if (searchIndexBytes > 8_250_000) failures.push(`中文搜索索引超过 8.25 MB：${searchIndexBytes} B`); if (compressedSearchIndexBytes > 2_000_000) { failures.push(`中文搜索索引 gzip 后超过 2 MB：${compressedSearchIndexBytes} B`); }