#SpreadsheetEditor

SpreadsheetEditor 是受控工作簿组件，提供工作表、公式、原生表格、图表、条件格式、数据透视表 与打印布局模型。

#属性

#内容结构

#稀疏工作表与虚拟编辑

row 和 column 表示工作表的逻辑尺寸。data 可以是稀疏 JavaScript 矩阵，其 length 达到逻辑尺寸，但只有已填充的行与单元格索引是数组自身属性。工作表也可以使用 Fortune Sheet 的稀疏 celldata 投影。不要使用 Array.from、遍历完整区域的嵌套循环， 或会把数组空位展开的 JSON 序列化把它转换成密集矩阵。

编辑器只渲染和搜索已经物化的单元格，同时保留完整滚动范围。滚动到任意位置，包括工作表 最大行或最大列，都不会触发 onChange。在虚拟空白行输入时，只会物化该行和被编辑的 单元格，不会分配已有数据与新坐标之间的所有行。公式依赖扫描、选区统计、条件格式与宿主 投影也遵循同一稀疏约定。

支持的 XLSX 上限为 1,048,576 行、16,384 列（XFD）。导入会保留工作表逻辑尺寸， 但不会分配每个空白单元格；导出只写入逻辑尺寸与已填充单元格，因此最大尺寸的稀疏工作表 也可以完成 XLSX 往返，而不会变成密集矩阵。

#百万单元格量化结果

在文档记录的 Apple M2 Pro、16 GB、headless Chrome 149 参考环境中，100,000 行 × 10 列 XLSX 夹具中位 0.480 秒进入可交互状态，连续滚动为 120.1 FPS，p95 帧间隔 12.9 ms，滚动期间没有 Long Task；保留约 38.41 MiB 和 903 个 DOM 节点， Ctrl+End 到 J100000 为 77.3 ms。连续两次受控编辑墙钟延迟为 52.5 ms 和 45.9 ms。可在本地生产预览上运行 bun run performance:large-spreadsheets 与 bun run performance:large-spreadsheet-edits 复现当前夹具；完整方法和范围见 性能证据。

该夹具是矩形百万已填充单元格工作簿，不是语义 ListObject 性能测试。它量化导入、可见 Canvas 绘制、导航与受控单元格发布。结构化引用使用独立的有界计算内核路径，但本夹具不 发布其计算延迟，也不量化计算列自动填充、汇总行重算、转换为区域或 table part 导出，更不 代表可以无界地格式化全选区域。文字方向最多处理 10,000 个单元格；一次 显隐操作在创建任何原生索引数组前，最多接受 10,000 行或 1,000 列。

#原生 Table 与 ListObject

“插入 → 表格”和网格内的 Cmd/Ctrl+T 会打开同一创建弹窗。单个单元格会扩展到有限的 当前区域，显式多行选区保持精确范围。快捷键只属于工作表网格，不会拦截宿主输入框、公式栏、 单元格编辑、弹出菜单或模态弹窗。创建时会捕获区域和“表包含标题”选项，生成工作簿内唯一的 TableN 名称，并把空白、无效或重复标题规范成唯一列名。

sheet.tables 保存真正的语义记录，而不是用单元格颜色模拟表格。每条记录包含稳定 ID、 OOXML 数字 ID（如有）、名称、从零开始且包含端点的区域、有序列定义、支持的筛选条件、 标题/汇总行标记、内置样式以及首列、末列、行条纹和列条纹选项。一次创建最多覆盖 100,000 个单元格；空区域、越界、合并、保护、数据透视表、与其他表格或工作表级 AutoFilter 重叠的请求会在修改前失败。

选中表格后会自动进入上下文“表格设计”功能区。用户可以修改名称，并从 60 个原生 OOXML 样式中选择浅色 1–21、中等 1–28 或深色 1–11；样式库在桌面和紧凑宽度下都支持二维方向键、 Home 与 End 导航，并在选择后精确把焦点还给触发按钮。首列、末列、行条纹和列条纹修改的是 表格语义标记。每次创建或设计操作只发布一次受控值，并生成一条撤销记录。

普通表格样式只在 Fortune 的可见单元格 Canvas 回调中解析和绘制。标题、正文、条纹、文字 强调和边框的成本随视口变化，不会把颜色写入所有受控单元格；条件格式仍拥有更高的显示 优先级。“转换为区域”是例外，它会先把用户确认的外观物化为原生填充、文字强调和边框， 再删除 ListObject。若矩阵展开可能超过一百万个槽位，转换自动改用稀疏 celldata，不会分配 无关行列；检测到公式、名称、验证、条件格式或图表中的结构化引用时会失败关闭。

现有行列插入和删除命令会同步调整表格区域、列身份、筛选列偏移与规范标题，并阻止删除必需 的标题行、汇总行或最后一条正文。合并与工作表级 AutoFilter 也会拒绝与表格相交，避免两个 结构模型同时拥有同一区域。

如果某一列正文已经包含一致的当前行公式，表格模型会把它记录为计算列规则。在表格正文内 插入一行或多行时，新单元格会自动填入该规则，稀疏 celldata 工作表也遵循同一条路径。 自动填充只触碰空单元格，并保留展示样式，不会覆盖已有值或公式。手工写入的不同当前行 公式会作为例外保留；如果同一列出现多个冲突公式，系统会删除自动规则并停止猜测，直到 重新写入一致公式。表格外插入的行不会触发填充。

#原生汇总行创作

创建表格时可以直接启用汇总行。对于已有表格，选中任意表格单元格后打开“表格设计 → 汇总行”，同一弹窗可以启用或关闭汇总行，并为每一列选择以下状态：

原生函数集合为 sum、average、count、countNums、max、min、stdDev、 stdDevP、var 和 varP。它们映射到 SUBTOTAL 的 101–111 编号，因此表格筛选隐藏的行 不会参与结果。Rust core、WebAssembly 内核、持久 Worker 会话与 JavaScript fallback 均支持 2–255 个参数的 SUBTOTAL。自定义公式最多 8,192 个字符，并拒绝控制字符、外部 引用以及动态或可执行的危险函数；标签会去除首尾空白，最多 255 个 Unicode 码点。

启用汇总行只会把 ListObject 向下扩展一行。如果目标行已有内容、位于合并或保护区域、超出 工作表或 XLSX 边界、属于其他表格或 AutoFilter，或者结果超过 100,000 个表格单元格， 操作会在修改前失败。关闭时只清除自动生成的汇总内容。行列结构操作会一起移动汇总行和 元数据；重命名表格只改写仍匹配自动生成 SUBTOTAL 形式的公式，保留自定义或直接编辑的 公式。用户直接修改汇总单元格后，列元数据会同步变为标签、自定义公式或不汇总，避免陈旧状态。

稠密 data 与稀疏 celldata 使用同一条不可变路径。表格样式会覆盖汇总行，但不会给 视口外单元格批量写颜色。Yjs 校验并同步列级字段；XLSX 导入导出精确往返 totalsRowCount、totalsRowFunction、totalsRowLabel 与 totalsRowFormula，不会把 ListObject 扁平化。

XLSX 导入导出保留原生 table part、工作表关系、content type、名称/显示名称、区域、列、 标题/汇总标记、60 个内置样式、支持的值、自定义、Top 与动态筛选条件，以及 <calculatedColumnFormula> 规则。受控模型中的计算公式带前导 =；写入 table XML 时去掉 该字符，重新导入后恢复。危险、外部、格式错误或超长规则会被忽略，不会写入 XML。切片器、 外部/查询表格和高级集成仍是明确边界，不能据此宣称完整 Excel 或传统 Office 表格对齐。

Rstest 覆盖模型、结构协调、命令、弹窗、功能区、Canvas、协作与 XLSX；Playwright 覆盖 桌面和紧凑视觉流程。tests/e2e/spreadsheet-table.acl 与 tests/e2e/spreadsheet-table-totals.acl 只作为本地发布门，使用 A3S Test 1.0.0、standalone agent-browser 0.26.0、Web 协议 15 和已有 Playwright Chromium。GitHub Actions 与 Pages 不安装也不调用 A3S Test。

#结构化引用计算

浏览器计算内核现在可以解析常见且有界的原生表格公式。它支持表格 name 或 displayName、可选的工作表限定，以及连续列区域：

=SUM(Sales[Revenue])
=SUM(Sales[[Units]:[Unit price]])
=COUNTA(Sales[#Headers])
=SUM(Sales[#Data])
=SUM(Sales[#Totals])
=[@Units]*[@[Unit price]]

#All、#Headers、#Data、#Totals 和 #This Row 会根据表格显式的标题行与汇总行 标记解析。表内 [@Column] 公式必须位于正文行；计算列可以逐个单元格写入相同的当前行 公式，也可以从正文中一致的公式自动推断。像 =SUM(Sales!Sales[Revenue]) 这样的限定 形式会校验表格所属工作表，不会静默解析其他工作表中同名的表格。

Rust/WASM 与 JavaScript fallback 共用同一解析器、表格目录、依赖边和投影语义。增量会话 保留目录，只重算脏依赖；表格结构变化则使用经过校验的替换快照。公式结果以无历史投影 更新应用，不会额外生成撤销步骤，也不会把缓存值当成用户输入。

一次计算请求最多接受 1,024 张表；单个结构化区域最多物化 100,000 个单元格。整行或整列 展开、三维引用、外部工作簿、反向或不连续列区域、不存在的表/列/行以及超出预算的范围都会 以单元格级诊断明确失败。公开 Playground 的 新建 → 结构化引用 模板打开 Sales ListObject，包含 Revenue 计算列、汇总行、标题/数据/全部区域示例，以及使用限定引用的 第二张工作表。这是真实可编辑工作簿，不是只供文档展示的夹具。

Rust、浏览器内核、会话、XLSX 与 Playground 聚焦测试覆盖解析器一致性、依赖失效、过期结果 拒绝和稀疏预算。上方百万单元格性能表仍是矩形工作簿基线；在发布表格专项延迟或内存目标 前，还需要独立的大型 ListObject 基准。

#多关键字自定义排序

“数据 → 排序和筛选 → 自定义排序”会在弹窗打开时捕获一个规范化的连续选区和工作表身份。 列/行、排序依据、次序与外观选择使用共享 OfficeSelect 组合框（含 data-selected-value / 选项 data-value 供自动化）。传统 Office 兼容的“选项”弹窗可在“按列排序”与“按行排序”之间切换：前者以列为关键字并移动完整行， 后者以行为关键字并移动完整列。同一弹窗还可选择简体中文“拼音排序”或“笔画排序”，并可启用 区分大小写；默认使用拼音且不区分大小写。按列排序会推断可能的标题行、允许用户覆盖，并从活动列开始； 按行排序从活动行开始，并因所有选定列都会移动而禁用标题保留。用户最多可以添加、删除和调整 64 个互不重复的关键字优先级。值关键字可升序或降序排列：有限数字使用数值顺序；文字使用 所选本地排序规则，含数字的文字保持字符顺序（K1、K100、K11、K2）。区分大小写的 升序会让同一字母的小写形式先于大写形式。相等记录保留原有次序，空白在两个方向下都置于末尾。

每个关键字也可以选择七个中英文月份/星期内置序列之一，或按每行一个项目、英文逗号或中文 逗号输入用户序列。一个序列可包含 2–256 个互不重复的项目；单项最多 128 个 Unicode 码点， 总计最多 4,096 个。匹配时会去除首尾空白，并统一大小写与全半角形式。已列出的值按创作顺序 优先排列，未列出的值随后使用自然升序；相同序位继续由后续关键字稳定区分，空白仍置于末尾。 如需反向次序，应反向创作序列本身。

七个内置序列不可变。“自定义序列”会打开可用键盘操作的偏好管理器：内置序列保持只读，用户可 创建、编辑、删除和调整最多 32 个用户序列的顺序。全部修改在点击“确定”前暂存，“取消”会丢弃 整份草稿；重复序列和超预算输入会在本地拒绝。编辑正在被排序关键字使用的序列会同步替换该关键字 捕获的内容，删除它则明确让关键字回到值升序。未发生变化时点击“确定”不会写入存储，关闭弹窗后 焦点会精确归还调用按钮。

用户序列在当前编辑器实例挂载期间可复用。如需让内容与偏好顺序跨工作簿切换、整页刷新与编辑器 重挂载继续可用，应传入明确的类型化 sortCustomListStore 属性。编辑器不会把这些偏好写入受控 工作簿。每个已接受的排序请求都会携带规范化后的序列，因此执行过程不依赖可变弹窗状态。

包内提供一个可选的浏览器存储实现。请在浏览器侧模块中只创建一次，确保 React 重渲染期间 对象身份稳定：

import { LocalStorageSpreadsheetSortCustomListStore } from '@a3s-lab/office/core';
import { SpreadsheetEditor } from '@a3s-lab/office/react';

const sortCustomListStore = new LocalStorageSpreadsheetSortCustomListStore(
  window.localStorage,
);

<SpreadsheetEditor
  content={content}
  onChange={setContent}
  sortCustomListStore={sortCustomListStore}
/>;

SpreadsheetSortCustomListStore 提供同步的 load() 与 save(lists) 方法，宿主也可以用类型化 对象接入其他本地设置后端。Vue 通过同名 sortCustomListStore prop 接收该对象；Web Component 宿主应把它赋给元素的 sortCustomListStore JavaScript 属性，而不是 HTML attribute。内置实现 把带版本的载荷保存到 a3s-office.spreadsheet-sort-custom-lists.v1，读取时会校验、去重并忽略损坏或不支持的数据。 如果写入失败，完整的已修改偏好集合仍会保留在当前会话中，编辑器同时提示失败。

同一个“排序依据”控件也可以选择有效单元格颜色、有效字体颜色或条件格式图标。一个视觉目标 在移动行时可置于顶端或底端，在移动列时可置于左侧或右侧；继续添加条件即可表达下一种颜色或 图标的优先级。外观条件保持稳定，后续值、自定义序列或外观关键字会继续区分命中与未命中的 并列记录，而不会破坏来源顺序。

可选目标来自每个选定关键字字段的有界快照。计算后的条件格式优先于直接外观；直接纯色填充、 无填充、明确字体颜色与自动字体颜色保留不同身份。原生渐变与图案填充仍会完整保留，但不会伪装 成单一颜色排序目标。命令会在一次原生区域批处理前重新构建并校验有效外观快照，因此不会信任 过期弹窗状态。

部分列、窄矩形或单单元格选区会先复用 AutoFilter 的同一套稠密/稀疏“当前区域”模型。当相邻 数据令当前区域更大时，自定义排序与快速升序/降序命令都会打开可访问的传统 Office 风格“排序提醒”。 默认选择“扩展选定区域”；只有当前矩形可独立安全排序时，才允许“以当前选定区域排序”。单个 单元格不能独立排序，保护或结构所有权冲突只会禁用受影响的候选区域。自动标题识别只接受真实 且非公式的文本值，因此带格式数字与公式结果不会再被误判为标题。

排序会移动完整行或列，包括原生格式、批注和其他单元格自有元数据。公式会沿记录移动的轴平移 相对引用，绝对引用保持不变；任何引用若会超出工作表，整个请求会在修改前失败。一次成功请求 在未启用筛选时只执行一次原生区域写入；筛选活动的所属区域排序则只发布一次受控工作簿替换， 避免单元格顺序与行可见性分离。两条路径都只创建一条撤销记录。取消或应用任一弹窗后，焦点会 精确归还原功能区按钮，随后可以继续用键盘操作网格。

当选区位于唯一一张语义 ListObject 或工作表 AutoFilter 内时，“排序提醒”只允许使用该结构的 完整可排序区域。表格区域固定标题并排除已启用的汇总行；AutoFilter 区域固定筛选标题。两者都会 锁定“按列排序”方向和结构标题选项。请求会携带所有者类型、适用时的表格 ID 及标题状态；命令在 修改前重新推导所有者，并要求精确区域与指纹保持一致，因此表格被替换、汇总行状态改变或筛选区域 移动时都会在修改单元格前失败。

所属区域完成整行排序后，类型化工作表和表格条件会针对已排序的稠密或稀疏单元格重新求值。只暴露 不透明 caljs 状态的 Fortune 原生值/颜色筛选，则按稳定来源行置换迁移自己的隐藏行所有权。 独立手工隐藏的行继续隐藏，实时网格在同一个受控历史步骤中接收排序单元格与协调后的可见性。 Fortune 区域读取器遗漏的隐藏原生行会从有界受控快照恢复。

矩形选区最多包含 1,000,000 个单元格。按列排序扣除可选标题后至少需要两行数据；按行排序 至少需要两列，只接受区域内的行关键字，并且不能保留标题列。只读行列、锁定单元格、合并区域、 数据透视表输出、不完整矩阵、重复或越界关键字及超预算请求都会失败关闭。 与语义 ListObject 或工作表 AutoFilter 相交、但无法解析为该结构精确可排序所属区域的选区仍会 失败关闭。与坐标归属的超链接映射、导入公式源/区域元数据或原生边框记录相交时也会因同一原因 失败。筛选协调另有 1,000,000 次“单元格 × 条件”访问上限；侧车数据迁移和大型排序的 Worker/WASM 执行仍是明确的后续工作。

排序提醒会同时冻结原选区、两个候选矩形、活动行列、工作表与排序意图。扩展区域只有在受控实时 选区仍等于原选区时才能获得应用授权；宿主重挂载或选区变化都会在修改前使请求失效。

聚焦模型、弹窗、命令、功能区和公式平移 Rstest 覆盖有界合同。Playwright 验证真实弹窗和 移动后的公式；tests/e2e/spreadsheet-custom-sort.acl 使用锁定版本的本地 A3S Test 门禁， 验证双关键字流程、单步撤销、可访问性以及空控制台和页面错误诊断。GitHub Actions 与 Pages 不安装也不调用 A3S Test。tests/e2e/spreadsheet-sort-range.acl 还会验证精确/扩展两条提醒 路径、焦点恢复、公式安全的整行移动与撤销； tests/e2e/spreadsheet-custom-list-sort.acl 则覆盖非法输入、原子化偏好编辑、删除与调整顺序、 整页刷新后的已保存序列复用、自定义序列下的公式安全整行移动与撤销；配套的桌面/紧凑 Playwright 路径还验证响应式管理器、只读内置序列、精确焦点归还和空浏览器诊断； tests/e2e/spreadsheet-appearance-sort.acl 会同时应用单元格颜色、字体颜色与 条件格式图标条件，并验证移动后的公式、单步撤销、焦点、可访问性及空浏览器诊断； tests/e2e/spreadsheet-row-sort.acl 会通过“排序选项”切换方向，以两个行关键字移动完整列，并验证 横向公式平移、单步撤销、焦点、可访问性与空诊断。 tests/e2e/spreadsheet-text-sort.acl 会选择笔画和区分大小写的文字比较，验证小写并列次序、移动后 公式，以及受控重挂载后的即时键盘焦点、撤销、可访问性与空诊断。 tests/e2e/spreadsheet-owned-range-sort.acl 会验证表格所属区域提醒、锁定的标题与方向、公式平移、 焦点和单步撤销；配套桌面/紧凑 Playwright 还会操作真实原生 AutoFilter 值选择，并证明隐藏行 所有权会跟随排序记录及撤销结果。

#工作表 AutoFilter 条件

启用“数据 → 排序和筛选 → 筛选”或按 Cmd/Ctrl+Shift+L，再打开活动表头并选择“按条件过滤”。 A3S 自有的“自定义自动筛选”弹窗支持等于、不等于、包含、不包含、开头是、开头不是、结尾是、 结尾不是、大于、大于或等于、小于、小于或等于、介于、不介于、空白与非空白。数字条件只接受 有限数值边界，倒序区间会在命令执行前被拒绝。

对于常用自定义比较，“添加第二个条件”只增加一个条件，并用“并且”或“或者”连接两项。受控模型 使用固定的双元素非递归条件元组；区间、空白选择、前几项/后几项和动态条件不会形成嵌套条件树。

“通配符匹配”和“通配符不匹配”会保留一条明确的原生 OOXML 表达式，而不会改变现 有字面量等于条件的语义。 * 匹配零个或多个规范化 Unicode 字符，? 匹配一个字符，~ 用于转义 *、? 或 ~。 表达式共用 32,767 字符的筛选操作数上限，并可位于固定 AND/OR 条件对的任一位置。

数值列的筛选菜单还会显示“前 10 项”。弹窗支持前/后 1–500 项与前/后 1–100%，只接受整数， 并保留所选边界上的全部并列值。百分比项目数向上取整；文本、布尔值、空白和非有限值不进入排名域。

同一弹窗会为数值列提供“高于平均值”和“低于平均值”。每次应用只计算一次算术平均值，并使用 严格比较，因此等于平均值的单元格不会被两项中的任何一项保留。类型化日期列会提供今天、昨天、 明天，上/本/下周，上/本/下月，上/本/下季度，去/今/明年，年初至今，第 1–4 季度以及第 1–12 月。动态条件不需要操作数，也不能与第二个条件组合。

日期求值接受已导入的 Date 值，以及原生单元格类型为 ct.t='d' 的有限数值序列；普通未格式化 数字不会被静默当作日期。工作簿的 dateSystem 为完整动态日期家族选择 1900 或 1904 epoch。 1900 路径会拒绝 Excel 虚构的序列 60，1904 序列 0 则映射为 1904-01-01。相对条件使用用户本地 日历日期、周日作为一周起点、包含起点且不包含终点；“年初至今”包含当前本地日期。时钟是纯模型 的明确输入，便于确定性测试；编辑器命令则提供当前本地时间。

每个活动列独立拥有自己隐藏的行，因此不同列条件会形成可见行交集；清除一列时只释放该列的 所有权。通过工作表行显隐单独隐藏的行会在替换条件、清除条件或关闭 AutoFilter 后继续隐藏， 包括手工隐藏与筛选隐藏重叠的情况。稠密 data 与稀疏 celldata 工作表使用同一求值器， 不会物化无关单元格。

应用和清除条件都通过类型化 spreadsheetAutoFilter 命令扩展进入编辑器。命令会在一次受控 工作簿更新和一条撤销记录之前，重新校验可编辑状态、活动工作表、精确实时筛选区域和绝对目标列。 宿主重挂载或过期菜单目标会失败关闭。弹窗会让冻结的实时选区跨过受控重挂载，并把焦点还给 原筛选表头。

原生工作表 <autoFilter> / <filterColumn> 条件与原生表格复用同一封闭筛选联合类型，并可通过 XLSX 导入导出往返。受支持的已导入值条件和常用自定义条件会在浏览器重新计算，并根据当前单元格 推断其筛选所有行；OOXML 无法恢复与这类推断筛选行完全重叠的已导入手工隐藏。已导入的前几项/ 后几项及百分比条件会根据有限数值重新计算，并作为原生 <top10> 元素写回。已导入动态条件会根据 当前数值或类型化日期单元格重新计算，并作为原生 <dynamicFilter> 元素写回。通用双元素 原生 <customFilters and="1|0"> 会保留 AND/OR 关系，包括否定前缀和后缀操作。任意正向与否定 通配符表达式会保留其原生 <customFilter> 值；规范的首尾星号形式仍会归一化为 包含、开头是或结尾是条件。所属区域自定义排序现在会在整行移动后重新计算这些类型化条件，并按 稳定排序置换迁移不透明原生值/颜色筛选的隐藏行。源级 1900/1904 日期系统保留现已精确支持； 大型聚合/排名的 Worker/WASM 卸载仍是明确边界。

聚焦模型、命令、弹窗、Hook、导入、XLSX 和多时区 Rstest 覆盖该有界合同。桌面与紧凑 Playwright 会操作真实供应商表头菜单、自有弹窗、动态平均值创作、选区保留、应用和撤销；仅本地运行的 tests/e2e/spreadsheet-ribbon-alignment.acl A3S Test 门禁还会检查可访问性以及空控制台和页面错误 诊断。GitHub Actions 与 Pages 不安装也不调用 A3S Test。

#XLSX 1904 日期系统保留

SpreadsheetContent.dateSystem 是工作簿 epoch 的唯一事实源。字段省略或取 '1900' 表示标准 Excel 系统；导入 1904 工作簿时会从 workbookPr date1904 明确保留 '1904'。XLSX 导入保持 日期格式单元格的精确数值序列，不再经 JavaScript Date 转换，因此 1904 序列 0 和历史日历日期 不会随宿主时区漂移。导出会写回工作簿标记，并将日期类型的标量与公式缓存值保持为原生数值。

同一个 epoch 驱动动态 AutoFilter 日期识别与求值、列画像、编辑或所属区域排序后的筛选重算， 以及 Ctrl+; 当前日期输入。受控编辑器重挂载会保留该字段；Yjs/Yrs 协作将其验证为封闭的 1900 | 1904 选择，并与计算设置独立合并。真实 XLSX 包回归覆盖导入、筛选、导出与重开； tests/e2e/spreadsheet-1904-date-system.acl 还验证导入 epoch、序列 0 可见性、隐藏行所有权、 活动筛选 UI、受控重开、可访问性及空浏览器诊断。

#数据验证

“数据 → 数据工具 → 数据验证”会在弹窗打开时捕获活动工作表、焦点单元格与全部实时选区。 取消或 Escape 不发布修改；应用与全部清除分别只发布一次受控工作簿值、创建一条撤销记录， 并在受控重挂载后保留全部选区、把焦点还给原功能区按钮或网格节点。

#依赖下拉列表

序列来源也可以是本地、有限的 =INDIRECT(...) 公式。公式只允许由带双引号的文本、 单个单元格引用和 & 拼接组成；例如 =INDIRECT($F2) 会把 F2 中的 North 或 'Lists'!B1:B3 当作当前行的列表来源，=INDIRECT("'"&$F2&"'!$B$2:$B$8") 则可以把驱动值拼进带工作表名称的区域引用。每个受验证单元格都会从所在选定区域的左上角 重新平移相对引用，因此同一条紧凑规则可以安全覆盖多行。

驱动单元格为空时，网格显示为空列表；驱动值无法解析、引用隐藏或不存在的工作表、整行/整列、 外部工作簿、未缓存的公式，或二维区域时会安全失败，不会把公式文本误当成选项。公式最多 255 个 Unicode 字符，解析出的来源最多读取 1,024 个单元格，并且只能是当前工作簿内的一行或一列。 受控 SpreadsheetContent 仍保存原始公式和 namedRanges，挂载 Fortune 时才生成有限的运行时选项， 因此驱动值变化会刷新下拉列表而不会破坏撤销、协作或文件语义。

公开 Playground 的 新建 → 数据验证 模板包含 Region → Regional owner 示例： North 和 South 是 Lists 工作表上的工作簿名称。导出 XLSX 时写入原生 list 验证公式， 重新打开后仍保留 =INDIRECT($F2)；该路径完全在浏览器本地运行，不需要第三方服务。

#自定义公式

选择“自定义公式”即可在同一个数据验证弹窗中编写本地 Excel 公式。 开头的 = 可省略，保存规则时会统一规范。编辑时，待提交的值会临时替换目标 单元格再进行求值，因此 =AND(A1<>"",A1<=100) 可以检查用户即将写入的内容。 相对引用以每个选定区域的左上角为锚点，并针对每个受验证单元格独立平移。

求值在浏览器同步完成且有明确上限：只读取工作簿中的本地缓存单元格值，支持内置 公式解析器暴露的常用函数，每次决策最多读取 1,024 个被引用单元格。整行/整列引用、 外部或网络引用、不存在的工作表，以及没有缓存结果的公式单元格都会失败关闭并显示诊断。 结果为布尔 TRUE、非零数字或文本 TRUE 时通过，其余结果拒绝。粘贴和对象级批量写入 仍使用各自的前置校验路径，避免未来批量策略无意继承单元格语义。

#输入信息与错误警告设置

同一弹窗维护完整的常用验证元数据，不另设只服务于文件导出的隐藏路径：

标题最多 32 个 Unicode 码点，输入信息最多 255 个，错误消息最多 225 个。关闭输入信息或 错误警告不会删除未显示的标题与正文，再次启用时仍可继续编辑。旧 A3S 内容缺少这些字段时， 会规范为忽略空值、显示下拉箭头与停止样式。

挂载后的网格会直接解析紧凑规则，不展开空白单元格。它会执行 allowBlank、按 showDropdownArrow 隐藏箭头、显示自定义输入标题与信息，并在无效输入时使用自定义错误 标题与消息。

#与 Office 一致的错误警告分支

直接单元格编辑和公式栏编辑会在值进入受控工作簿前先执行 errorStyle：

每个弹窗都会显示自定义标题和消息，并在可用时显示当前输入。关闭任一分支后，系统会恢复同一个单元格、公式栏/网格焦点与选区， 不会让 Fortune 默认的 Enter 导航把用户带到下一行。用户确认保留 Warning 或 Information 值后，系统只通过类型化、一次性的验证绕过 写入；因此 Undo、Yjs/Yrs 协作和宿主受控持久化仍保持原有边界。粘贴和对象级批量写入继续使用各自的前置校验路径，待后续补齐逐编辑确认 交互。

一次操作可以覆盖多个互不重叠的选区，总计最多 10,000 个单元格。非法或越界区域、二维 序列来源、非法或倒序边界、保护或合并单元格、数据透视表输出和只读视图都会在修改前失败。 日期在浏览器内规范为 ISO，导出时写为原生 DATE(...) 公式；导入会识别工作簿的 1900 或 1904 日期系统。在公开 Playground 首页选择 新建 → 数据验证，即可打开包含序列、日期、 优先级、依赖下拉、自定义公式，以及停止、警告、信息三种文件语义的模板；它不是隐藏的 E2E 查询夹具。

聚焦模型、XLSX、命令、弹窗、历史、功能区与桌面/紧凑 Playwright 回归覆盖该流程。 tests/e2e/spreadsheet-data-validation.acl 只在本地通过 A3S Test 运行；GitHub Actions 与 Pages 不安装也不调用 A3S Test。

#公式条件格式

开始 → 条件格式现在包含可编辑的自定义公式规则。条件格式管理器把应用范围、 公式、文字/填充颜色和“匹配后停止后续规则”优先级保存在同一个受控草稿中。导入的公式规则 也会在相同编辑器中打开，不再只是无法修改的工具栏记录。

公式只针对工作簿内的本地缓存值同步求值。应用范围左上角是相对锚点，例如把 =AND($D4="阻塞",$C4<1) 应用到 A4:H9 后会按行平移；绝对行列保持固定。有限区域和 Limits!$A$2 这样的带工作表引用都留在当前工作簿内。文字颜色和填充颜色可以单独或同时启用， 规则按列表顺序匹配；启用“匹配后停止后续规则”后，后面的规则不会覆盖已经匹配的单元格。

浏览器求值器同步运行并在不确定时安全失败：公式源最多 255 个 Unicode 字符，每次判断最多读取 1,024 个单元格。整行/整列引用、外部链接、不存在的工作表和没有缓存结果的公式单元格不会改写 显示，并提供明确的本地诊断。有限范围即使是空白单元格也会参与扫描；超大范围只使用已经物化的 单元格，避免打开工作簿时分配无界矩阵。整个流程不需要网络或第三方服务。

原生 XLSX 的 expression 条件记录、差异样式、sqref 和优先级会在导入、编辑、导出和重新打开 之间保留。打开 Playground 的 新建 → 公式条件格式 可以查看 Status 与 Limits 工作表中的 阻塞规则和跨表完成率阈值示例。

聚焦模型、解析器、Canvas、面板和原生 XLSX 测试覆盖相对/绝对引用、跨表值、空白单元格、优先级、 边界和重新打开保真度。确定性的 tests/e2e/spreadsheet-conditional-format.acl 与 visual-tests/spreadsheet-conditional-format.functional.spec.ts 覆盖桌面、紧凑布局、键盘、 可访问性和干净的浏览器诊断。

#紧凑的数据验证、保护与条件格式

大范围数据验证保存在 sheet.dataValidationRanges 中，区域使用从零开始、包含端点的 紧凑坐标：

const sheet = {
  row: 1_048_576,
  column: 16_384,
  dataValidationRanges: [
    {
      ranges: [
        { row: [0, 1_048_575], column: [0, 16_383] },
      ],
      item: {
        type: 'dropdown',
        type2: '',
        rangeTxt: 'A1:XFD1048576',
        value1: 'Ready,Blocked',
        value2: '',
        validity: '',
        remote: false,
        allowBlank: true,
        showDropdownArrow: true,
        prohibitInput: true,
        errorStyle: 'stop',
        errorTitle: 'Invalid state',
        errorMessage: 'Choose Ready or Blocked.',
        hintShow: true,
        hintTitle: 'Workflow state',
        hintValue: 'Choose a workflow state.',
      },
    },
  ],
};

较小且经过编辑的区域也可能出现在 Fortune Sheet 的直接 dataVerification 映射中。 精确匹配某个单元格的直接规则优先于覆盖该单元格的紧凑区域。通过编辑器创建或删除验证 规则时，会更新紧凑区域，并避免展开超过 10,000 个单元格。

工作表保护仍保存在 config.authority。大范围锁定或解锁区域存入 cellProtectionRanges，无密码可编辑区域则紧凑地保存在 allowRangeList；只有已经物化的 单元格才会写入直接保护标记。条件格式继续使用 luckysheet_conditionformat_save[].cellrange 紧凑区域；比较、色阶、数据条和图标规则只计算 已填充单元格，有界公式规则会在本地上限内连空白单元格一起扫描，超大范围再退回已物化单元格。 导入与导出会把这些区域保留为原生 XLSX sqref、工作表保护和条件格式记录。

#传统 Office 常用数字格式

开始选项卡的数字组提供常规、数字、人民币货币、会计专用、百分比、短日期、时间、 科学计数、分数和文本格式，并支持七组标准 Cmd/Ctrl+Shift 快捷键。预设只修改 Fortune 原生的 cell.ct.fa 与 cell.ct.t，不会改写值、公式、批注、链接或合并区域。

增加和减少小数位会逐个读取所选单元格自身的格式。混合选择中的货币、百分比、数字、 会计和科学计数格式会保留各自的格式类别，相同结果会压缩为矩形原生调用，并在一次批处理 和一次撤销记录中提交。日期、时间、分数、文本和无法识别的自定义格式保持原样。命令最多 处理 10,000 个单元格，避免对最大尺寸工作表的空白区域进行意外密集化。

#静态当前日期与时间

开始选项卡的数字组提供“日期和时间”菜单，并支持两组 传统 Office/Excel 输入快捷键：

两项操作写入静态值，不会创建易变的 TODAY() 或 NOW() 公式。日期采用用户本地的年、 月、日；时间在写入前丢弃秒和毫秒。因此重新计算工作簿不会改变结果。

即使当前选区覆盖多个单元格，命令也只写入活动单元格，并保留原选区。一次原生 batchCallApis 先通过 setCellValuesByRange 写入标量，再只更新原生 ct 数字格式；旧公式 会经 Fortune 的值写入路径清除，其他样式保持不变，一次撤销即可同时还原值和格式。

只读视图、非活动工作表、锁定或受保护单元格、合并单元格、数据透视表输出，以及超出 1,048,576 行或 16,384 列的坐标都会在修改前被拒绝。两组快捷键只使用 Control，并且只在 活动工作表网格中生效；宿主输入框、公式栏、活动单元格文字编辑、模态控件、输入法组合事件 和重复 keydown 保留原生行为。当前日期输入使用受控工作簿的 dateSystem；仅时间的小数值在 两个系统中保持一致。

聚焦命令与功能区测试、确定性的 Playground 夹具，以及桌面/紧凑 Playwright 回归共同覆盖 动态本地时钟结果、格式状态、焦点和单步历史。仅本地运行的 tests/e2e/spreadsheet-date-time.acl 使用 A3S Test 1.0.0，并通过修订证据验证操作，不会把 真实用户当前的日期或时间硬编码到长期测试中。GitHub Actions 与 Pages 不安装也不调用 A3S Test。

#从上方复制公式或值

活动工作表网格支持两组聚焦快捷键：

即使当前选区覆盖更多单元格，两项命令也只修改活动单元格。一次 batchCallApis 只提交一个原生 setCellValuesByRange 调用，因此宿主只收到一次受控更新， 一次撤销即可还原原单元格。目标自己的字体、强调、填充、框线、对齐、数字格式、批注和其他 无关状态全部保留，不会复制源格式。修改成功后会同步公式栏；即使已经脱离挂载的公式栏更新 失败，也不会反转已经提交的工作簿修改。

目标位于第一行、超出 XLSX 行列边界、属于非活动或只读工作表、落入受保护或合并区域、 位于数据透视表输出时，命令会在修改前失败。公式复制还会拒绝非法或外部公式，以及数组、 动态数组、数据表和溢出元数据；仅复制值的命令仍可复制安全的源缓存标量。宿主输入框、公式栏、 活动单元格文字编辑、弹出菜单、模态控件、输入法组合事件和重复 keydown 保留原生行为。

聚焦规划器、命令运行时、命令目录、键盘和焦点测试，以及专用 Playground 夹具和桌面/紧凑 Playwright 回归共同验证公式原样复制、仅值复制、目标样式保留、修订次数和单步撤销。仅本地 运行的 tests/e2e/spreadsheet-copy-from-above.acl 使用 A3S Test 1.0.0 捕获可访问性证据与 空控制台/页面错误诊断。GitHub Actions 与 Pages 不安装也不调用 A3S Test。

#原生 XLSX 单元格富文本

Spreadsheet 会保留 XLSX 共享字符串与内联字符串中的原生富文本。导入时，有序 OOXML 文字 片段会进入 Fortune 既有的 ct.s 表示，并保持 ct.t='inlineStr'；导出时再写回原生内联 字符串。文字片段首尾包含空白时会准确生成 xml:space="preserve"。

“设置单元格格式”仍是整单元格命令。在单元格编辑器或公式栏中选中非空文字后，开始功能区的 字体、字号、颜色、粗体、斜体、下划线与删除线只作用于选中文字。普通字符串会在首次局部格式 操作成功时转换为原生内联字符串片段；已有片段会按选择边界拆分并合并相邻同样式片段，不会压平 未修改内容。直接使用功能区后，只要编辑器仍然活动，就会恢复原来的文字选择。整单元格与局部 格式都只产生一次受控工作簿更新，由宿主历史记录与协作层继续管理。修改数字格式会保留内联字符 串类型。未修改的语义颜色会按原生调色板引用导出；用户修改片段颜色后则回退为显式 RGB，不会 错误复用过期主题或索引身份。

通过公式栏或 F2 单元格编辑器提交的直接文字插入与删除也会进入同一个有边界的源片段协调 模型。公式栏返回普通字符串时，会从上一份原生片段重建；F2 返回值丢失源样式或颜色元数据时， 也会按受控源片段重建。插入文字继承被替换片段或紧邻的前一个片段，未受影响片段继续保留边界、 字体属性，以及主题、索引、自动或色调身份。每次提交只发布一次受控修订和一条撤销记录。文字 变化必须由精确单元格操作坐标认证；没有操作且文字未变化的回调只能恢复上一份受控片段；行、 列或工作表结构操作绝不会根据旧坐标推断富文本。

带格式富文本粘贴到公式栏或 F2 选择范围时，现在会保留上表中的常用字体片段属性。原生粘贴 修改编辑器之前，控制器会记录一次性意图，其中包含精确工作表对象、单元格坐标、受控源文字、 UTF-16 选择范围、剪贴板普通文字和净化后的片段。随后必须由经过认证的单元格操作提交完全符合 预测的替换结果。未受影响的前缀与后缀始终来自受控单元格，因此浏览器标记不能压平主题、索引、 自动或色调身份；粘贴颜色使用显式 RGB。普通或空文本单元格也只有通过这项证明后才会转换为原生 内联字符串。剪贴板解析器接受语义强调标签与常见内联字体 CSS，解析后立即丢弃 HTML 树，并忽略 脚本、样式、元数据及其他非内容元素。

解析会在物化前执行边界检查。单元格最多 32,767 个字符和 512 个文字片段；一次导入最多物化 10,000 个富文本单元格与 100,000 个片段；非法或超限候选不会进入富文本模型。局部格式还会拒绝 折叠选择、拆开 UTF-16 代理对的边界、公式单元格，以及会超过单元格片段上限的结果。带格式粘贴 还把剪贴板 HTML 限制为 256,000 个字符，并要求每次提交只有一段精确选择替换。普通、文字不匹配、 非法或超限的剪贴板标记不能授权片段；浏览器仍会按继承样式或普通文字完成文本粘贴。同次提交中的 多处不连续编辑与非字体类片段对象仍不属于公开 Spreadsheet 能力。

聚焦导入、导出、重开与格式测试覆盖共享/内联字符串、语义颜色、精确空白、不可变更新和数字 格式保留。桌面与紧凑 Playwright 使用受控 Playground 夹具验证真实浏览器 HTML 剪贴板粘贴； 夹具标题栏也提供确定性的格式复制/粘贴示例，便于本地检查。 tests/e2e/spreadsheet-rich-text.acl 的四个场景仅通过本地 A3S Test 1.0.0 门禁运行，并捕获 可访问性、空控制台与页面错误证据；GitHub Actions 与 Pages 不安装也不调用 A3S Test。

#设置单元格格式与字体快捷键

开始选项卡的数字组与 Cmd/Ctrl+1 打开同一套“设置单元格格式”对话框。工作表网格还支持 两组直接进入字体页的传统 Office 快捷键：

三个入口共用同一条类型化命令、同一份选区快照和同一套数字、对齐、字体、边框、填充与保护 修改模型，不会创建第二套字体状态。字体与字号下拉框从命令目录取得 aria-keyshortcuts；非法页签或焦点路由会在创建对话框前失败。宿主输入框、公式栏、活动单元格 文字编辑、输入法组合、重复按键和已有模态控件保留原生键盘行为，Escape 会把焦点精确归还 原工作表网格节点。

字体预览会准确保留所选文字颜色，只根据相对亮度在深色与浅色中性画布之间切换，因此白色或 其他浅色字体不会消失在固定浅色背景上。字体、字号、颜色、粗体、斜体、删除线，以及单、双、 单会计用和双会计用下划线仍写入既有 Fortune 原生字段；一次“应用”只产生一次受控更新和一条 撤销记录。

聚焦 Rstest、桌面与紧凑 Playwright，以及仅本地运行的 tests/e2e/spreadsheet-font-dialog-shortcuts.acl A3S Test 1.0.0 回归共同验证路由、初始焦点、 预览对比度、退出后的网格焦点、可访问性和空浏览器诊断。GitHub Actions 与 Pages 不安装也不 调用 A3S Test。

#字号步进与框线快捷键

开始选项卡的字体组提供可见的“增大字号”和“减小字号”按钮，并在工作表网格获得焦点时 支持以下 传统 Office 常用快捷键：

字号使用统一的 9、10、11、12、14、16、18、20、22、24、28、36、48、72 点阶梯。 混合选择会从每个单元格自身的字号分别步进，不会统一继承焦点单元格；未设置格式的空白 单元格从 10 点开始。相同结果会压缩为 Fortune 原生矩形，并通过一次 batchCallApis 批处理提交，因此一次手势只产生一次受控更新和一条撤销记录。每次最多处理 10,000 个 单元格。

外侧框线快捷键使用现有不可变框线模型写入黑色细实线轮廓，清除框线快捷键删除选区框线。 框线菜单同时显示快捷键提示，并通过 aria-keyshortcuts 暴露相同元数据。宿主输入框、 公式栏、单元格文字编辑、明确忽略编辑器快捷键的弹层和模态控件继续保留原生键盘行为。 Rstest 与桌面/紧凑 Playwright 是浏览器门禁；确定性的 tests/e2e/spreadsheet-font-size-border-shortcuts.acl 仅在本地通过 A3S Test 1.0.0 运行，GitHub Actions 与 Pages 不安装也不调用 A3S Test。

#单元格框线

开始选项卡的字体组提供上、下、左、右、无、全部、外侧、内部、水平、垂直、斜下和斜上 框线。斜下与斜上是两个独立命令；同时启用会得到交叉框线，“设置单元格格式”的框线页会 显示相同的两个按下状态。框线弹层会保留下一次主按钮操作所用的目标、精确颜色和十种原生 线型。成功操作只发布一次受控 onChange、生成一条撤销记录，并把焦点还给工作表网格。

非对角框线继续使用紧凑的原生区域记录。A3S 在一个规范的逐单元格记录中保存 OOXML diagonalDown、diagonalUp 与两者共用的线型，同时把旧 Fortune border-slash 解释为 斜下框线。由于 Fortune 只绘制区域斜线而不会绘制导入的单元格斜线，A3S 的可见单元格 Canvas 回调负责绘制这份规范记录；源数据中后出现的原生斜线或无框线区域仍按顺序覆盖。 选择性粘贴的“全部”和“格式”、内置样式、Yjs 协作、插入行、XLSX 导出与重新打开都会 精确保留两个方向；“除框线外的全部”会移除两者。

对角框线每个单元格需要一条记录，因此单次命令最多处理 4,096 个单元格。批量写入前只用 一次索引扫描读取已有方向，不会为每个目标单元格重复遍历全部框线。清除格式和清除全部会 删除选区框线，但不改变合并结构。聚焦 Rstest、真实 XLSX 与桌面/紧凑 Playwright Canvas 断言是 CI 门禁；tests/e2e/spreadsheet-diagonal-borders.acl 只在本地通过 A3S Test 1.0.0、 standalone agent-browser 0.26.0 和 Web 协议 15 运行，GitHub Actions 与 Pages 不安装也不 调用 A3S Test。

#高级下划线样式

开始选项卡的字体组把下划线做成 传统 Office 风格的拆分控件。主按钮切换当前单元格或选区， “更多下划线”菜单与“设置单元格格式”的字体页共用五种原生状态：

Cmd/Ctrl+U 会关闭任意已经启用的下划线，不会把双下划线或会计用下划线降级成单下划线； 当前选区没有下划线时，同一快捷键启用单下划线。功能区、菜单、设置单元格格式、快捷键、 撤销与受控宿主更新始终操作 Fortune 原生 un 值，不创建第二套显示标记。混合选区只有在 用户明确修改下划线选择器后才会统一，否则保留每个单元格原值。

原生 XLSX 导入导出会保留准确的 OOXML 下划线值，SheetJS 回退导入则把布尔、数字与命名 变体归一到同一套五状态模型。菜单使用 menuitemradio 状态，打开时聚焦首个可用选项， 执行后恢复工作表网格焦点，并通过 aria-keyshortcuts 暴露快捷键。Rstest 与桌面/紧凑 Playwright 覆盖浏览器和 XLSX 路径；确定性的 tests/e2e/spreadsheet-underline-styles.acl 仅作为本地 A3S Test 1.0.0 门禁，采集截图、 可访问性、控制台和页面错误证据。GitHub Actions 与 Pages 不安装也不调用 A3S Test。

#直接颜色重置、传统 Office 字体快捷键与 XLSX 颜色身份

开始选项卡的字体组现在提供两种无法用直接 RGB 色块表达的“未设置”状态。“自动颜色”会 删除 Fortune fc，让工作簿字体样式决定可见文字颜色；“无填充”会删除 Fortune bg， 而不是写入白色，因此继承样式、Table、条件格式与宿主外观仍可继续生效。两个动作都复用 现有类型化单元格格式命令，只产生一次受控更新和一条撤销记录，关闭颜色面板后把最终 Spreadsheet 命令焦点还给工作表网格。

同一命令目录还统一管理常用 传统 Office/Excel 字体强调快捷键：

这些别名只属于当前工作表网格。宿主输入框、公式栏、活动单元格编辑、对话框与弹出菜单保留 原生按键行为。功能区标题、aria-keyshortcuts、编辑器键位映射、命令可用性、单步撤销和 桌面/紧凑模式的按下状态都走同一条类型化格式命令路径。

导入的 XLSX 直接颜色会在 Fortune 可见 RGB 旁保留经过校验的语义来源。保留范围明确限制 为字体颜色、实心填充前景色、原生图案填充的前景色与背景色，以及可见边框线颜色；记录内容 包括 theme、indexed 或 automatic 身份、来源调色板颜色、渲染颜色与有效 tint。该嵌套 元数据与其他单元格字段一起通过扁平 JSON/Yjs 单元格传输，不会因实时协作而丢失。

导出只会在当前可见 RGB 仍与导入渲染值相同，且调色板槽位可以无冲突重建时复用语义来源。 因此只修改“加粗”仍可保留 <color theme="4" tint="0.5">、 <fgColor indexed="0"> 或 <color auto="1">。若用户修改了可见颜色、两个导入来源对 同一调色板槽位提出不同颜色，或颜色来自尚未支持的差异格式，导出会使用显式 RGB， 不会写出错误的语义引用。

聚焦 Rstest 使用真实 XLSX 完成导入、无关编辑、导出、重新打开、XML 身份与渲染 RGB 往返。tests/e2e/spreadsheet-font-colors-shortcuts.acl 使用 A3S Test 1.0.0、standalone agent-browser 0.26.0、可访问性与空控制台/页面错误证据验证两种功能区密度。该套件只作为 本地发布门禁；GitHub Actions 与 Pages 使用等价的桌面/紧凑 Playwright 测试，不安装也 不调用 A3S Test。

#原生 XLSX 图案填充

Spreadsheet 会保留完整的 OOXML 非实心 patternType 集合：

每个导入单元格只保存一个经过校验的 a3sXlsxPatternFill 值，其中包含准确图案类型、渲染后的 前景色与背景色，以及可选的 theme、indexed、automatic 或 tint 来源。Fortune bg 仍是普通 背景色投影。只有该投影继续匹配导入背景色时，图案元数据才生效，因此过期元数据不会覆盖用户 明确选择的新颜色。

工作表外观按条件格式填充、Table 样式、原生图案填充、普通单元格背景的顺序决定。Canvas 钩子只拦截 Fortune 对每个可见单元格的第一次背景绘制，在文字下方绘制背景与裁剪后的过程式 图案，并立即恢复上下文；隐藏或视口外单元格不会产生绘制工作。

格式刷和“选择性粘贴格式”会复制图案字段；无关的字体、框线、对齐、值、公式或数字格式修改 会保留它，Yjs 实时协作则把它作为原生单元格属性传输。选择新填充、“无填充”、“清除格式” 或内置单元格样式会在同一次受控更新中移除图案。导出会写回准确原生图案，并且只在渲染颜色与 调色板槽位仍一致时复用前景色和背景色的语义身份；发生冲突时回退为显式 RGB。缺失颜色元素 采用 OOXML 的黑白默认值，已出现但非法的颜色则安全失败。

“设置单元格格式”的填充页会直接编辑同一套原生模型。它提供无填充、纯色与全部 17 种图案， 可修改前景色和背景色，并使用生产 Canvas 渲染器显示准确预览。切换到其他填充类型时，未激活的 图案草稿会保留到对话框关闭。应用只产生一次受控工作簿更新和一条撤销记录；导出与重新打开会 保留用户创作的 patternType 和颜色。

在 Playground 打开 ?e2e=spreadsheet-pattern-fill 可查看全部 17 种图案，并可通过“设置单元格 格式”编辑当前单元格。聚焦 Rstest 覆盖 导入、Canvas 顺序、格式刷、选择性粘贴、Yjs、调色板冲突，以及导入、编辑、导出、重开保真度。 visual-tests/spreadsheet-pattern-fill.functional.spec.ts 提供桌面与紧凑 Canvas 像素证据，以及 编辑、应用、重开与撤销流程。 确定性的 tests/e2e/spreadsheet-pattern-fill.acl 通过本地 A3S Test 1.0.0 门禁采集可访问性、 控制台和页面错误；GitHub Actions 与 Pages 不安装也不调用 A3S Test。

#原生 XLSX 渐变填充

Spreadsheet 会保留两类 OOXML 渐变，不会把它们扁平化成实心颜色：

每个 a3sXlsxGradientFill 字段包含 2 到 256 个有序色标。每个色标都会保留位置、渲染颜色， 以及经过校验的 theme、indexed、automatic 或 tint 来源。Fortune bg 使用第一个色标作为投影， 让普通工具栏与 Table 逻辑仍有确定背景；只有 bg 继续匹配该投影时，原生字段才生效，因此过期 元数据不会覆盖用户明确选择的新颜色。

条件格式与 Table 填充在外观层级中继续高于原生渐变。共享 Canvas 钩子只拦截 Fortune 对可见 单元格的第一次背景绘制，并立即恢复原始 fillRect；隐藏或视口外单元格不会分配任何渐变工作。 即使单元格很大，路径渐变也固定限制在 96 层轮廓以内。

格式刷和“选择性粘贴格式”会复制渐变字段；无关的字体、框线、对齐、值、公式或数字格式修改， 以及 Yjs 实时协作都会保留它。选择新填充、“无填充”、“清除格式”或内置单元格样式，会在同一次 受控更新中同时移除原生图案与渐变元数据。导出会写回准确的线性/路径几何与色标，并且只在准备 后的调色板一致时复用语义颜色身份；冲突时使用显式 RGB。未知类型、非法颜色、倒序或越界色标、 非法路径边界、存在歧义的填充子节点，以及超过 256 个色标都会安全失败。

“设置单元格格式”的填充页可以创作两类渐变。线性模式暴露精确角度，路径模式暴露四条内矩形 边界；用户可在 2 到 256 个有序色标之间添加、删除、改色与调整位置。新增色标会插入最大间隔， 颜色由相邻色标插值得到，实时预览复用生产 Canvas 渲染器。倒序位置或交叉路径边界会把草稿标记 为非法，并在修改工作簿前禁用“应用”。切换填充类型不会丢失未激活的纯色、图案或渐变草稿。

在 Playground 打开 ?e2e=spreadsheet-gradient-fill 可查看 0°、45°、90°、135° 线性渐变和 两个路径渐变，并可通过“设置单元格格式”编辑当前示例。聚焦 Rstest 覆盖导入、Canvas 顺序、 编辑传播、协作、调色板冲突，以及导入、编辑、 导出、重开保真度。visual-tests/spreadsheet-gradient-fill.functional.spec.ts 提供桌面与紧凑 Canvas 像素证据，以及创作、响应式边界、应用、重开和撤销流程。确定性的 tests/e2e/spreadsheet-gradient-fill.acl 通过本地 A3S Test 1.0.0 门禁采集可访问性、控制台和页面错误；GitHub Actions 与 Pages 不安装也不调用 A3S Test。

#文字方向与行列显隐

开始选项卡的对齐组通过一个支持键盘的 menuitemradio 菜单提供六种 传统 Office 常用文字方向。 浏览器模型把数值旋转写入 Fortune rt；只有逐字堆叠的竖排文字使用 Fortune tr='3'。

自定义“设置单元格格式”角度也按同一规则无损映射。+30° 写为 30，-30° 写为 120，-45° 写为 135，-90° 写为 180。导入支持 OOXML 0 至 180 与竖排 255，也兼容 Fortune 旧 tr 预设 0 至 5 和数值 tr 6 至 180；当两个厂商字段同时 存在时，直接 rt 优先。数值命令会清除旧 tr，竖排命令会清除旧 rt。一次操作最多 覆盖 10,000 个单元格，只发送一次 batchCallApis，只产生一次受控更新和一条撤销记录， 随后恢复网格焦点。

开始选项卡的单元格组把行和列菜单扩展为隐藏与取消隐藏，并让同一组类型化命令拥有网格 快捷键：

命令会在分配原生字符串索引前检查上限，也不会隐藏工作表的全部逻辑行或列。宿主输入框、 公式栏、单元格文字编辑、弹出菜单、模态控件、只读视图和重复 keydown 都不会被接管。 聚焦 Rstest 与 XLSX 测试、桌面/紧凑 Playwright Canvas 像素断言，以及 tests/e2e/spreadsheet-ribbon-orientation-visibility.acl 共同保护该流程。ACL 仅在本地使用 A3S Test 1.0.0、agent-browser 0.26.0 与 Web 协议 15；GitHub Actions 与 Pages 不安装 也不调用 A3S Test。

工作簿 Extension 上下文目前还不是稳定公共 API。宿主流程应使用 fileActions， 结构化 AI 操作应使用 onAgentRequest；不要从包的内部路径导入命令运行时模块。

#协作与原生单元格修改

通过 collaboration 传入已初始化的 Spreadsheet OfficeCollaborationSession 后，字段级寻址的 Yjs 模型成为规范值。浏览器绑定按稳定 ID 管理工作表和已填充单元格，投影远端修改，并把撤销限制在当前挂载客户端自己的事务。 每张工作表的表格使用独立的 ID 记录映射和显式顺序数组；不可变创建声明阻止身份复用， 名称、样式、选项、列和筛选字段的独立修改可以收敛，而无需替换整张工作表。 presence 必须绑定同一个会话，用于发布区域并显示远端单元格选择。

Rust、CLI、标准 MCP 与 A3S Code 使用 spreadsheet-set-cell 创建或递归修改一个从零 开始的坐标，使用 spreadsheet-delete-cell 删除完整精确匹配的单元格。 一次粘贴、填充或其他多单元格手势应使用 spreadsheet-batch-cells，它接受同一工作表内 1 至 4096 个不同坐标。每一项都必须提供 nextCell；只有 nextCell: null 才表示带完整 保护的精确删除。 expectedCell: null 只用于创建已经确认为空的坐标；其他修改会递归比较观察值，因此 不同叶子的并发修改可以合并，同一叶子的过期修改会在写入前失败。密集工作表保留矩阵 投影，稀疏工作表和首次写入的空工作表继续使用 celldata。批次中的所有保护先基于 同一份共享快照检查，再在一个 Yjs 事务中提交完整结果；任一冲突都不会留下部分单元格、 Presence、尺寸或持久日志修改。