Angular 电子表格组件 | ng-hub-ui-spreadsheet
可编辑的 Angular 电子表格,支持 Excel 键盘操作、矩形选区、可与 Excel 双向往返的剪贴板、冻结窗格和合并单元格。MIT 许可,无障碍,没有付费版。
API 参考
这里是 spreadsheet 的完整契约:你可以绑定、监听、投影和设置主题的一切,都集中在一处。接入你需要的部分,自定义你想要的样式——它是 standalone 的,且对 signal 友好。
输入
通过 55 个输入项精细调校 spreadsheet。像绑定任意 Angular @Input 一样绑定它们。
| 名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
rows必填 | readonly TRow[] | — | 你所持有的行数据。表格不会写入这些数据。 |
columns必填 | readonly HubSpreadsheetColumn<TRow>[] | — | 每一列显示什么、允许什么。 |
rowKey必填 | (row: TRow) => string | — | 每行一个稳定的名称,使保存状态在重新加载后仍跟随它所属的行。 |
errors | Record<string, string> | {} | 每个单元格一条校验消息,键与 `states` 相同。由宿主负责,因为校验应属于了解数据含义的一方。单元格会被红框圈出,消息会在悬停或键盘聚焦时以提示框打开。 |
invalidDrafts | Record<string, string> | {} | 双向。读者留在单元格中、却不是该列能保存的值的文本,键与 states 相同。单元格会继续显示它,带有边框和一条说明未保存的消息;重新打开单元格可将其取回修改,Escape 放弃它,覆盖写入该单元格或删除其所在行、列则会清除它。读取它,就不会在不提示的情况下保存旧值。 |
states | Record<string, HubSpreadsheetCellState> | {} | 每个单元格的保存状态,键由行键和列别名以制表符连接而成。 |
decimalMark | ',' | '.' | ',' | 此读者输入小数时使用的字符。仅当粘贴的值不含原始数字时才会参考它。 |
emptyText | string | '' | 空表格显示的内容。 |
pageSize | number | 10 | Page Up 和 Page Down 每次移动的行数。 |
readonly | boolean | false | 关闭所有编辑器,无论各个单元格如何设置。 |
frozenColumns | number | 0 | 固定在起始边的列数,按 Excel 冻结窗格的方式计数。 |
frozenRows | number | 0 | 固定在表头下方的行数。 |
spans | readonly HubGridSpan[] | [] | 合并区块,每个区块由其左上角和范围来命名。 |
disjointSelection | boolean | true | 按住 Ctrl(Mac 上是 Cmd)点击时,是往选区里再加一个区块,还是重新开始选择。默认开启:表格软件就是这么做的,而且这个手势本来空着——普通点击已经能选中,Ctrl 无话可说。每个区块都有标记,Delete 会把它们全部清空,任何普通点击或方向键都会重新开始选择。只有当这些区块能拼成一张表时才会复制,否则被拒绝;选中多个区块时填充手柄会消失——填充延续的是一个区块,延续哪一个没有答案。 |
fillHandle | boolean | false | Whether the sheet offers the fill handle at the corner of the selection.同时启用 Ctrl+D(Mac 上为 Cmd+D)向下填充。 |
canUndo | boolean | false | 撤销是否可用。表格只负责询问;历史记录由所有者保管。 |
canRedo | boolean | false | 重做是否可用。 |
resizableColumns | boolean | false | 读者是否可以拖动列的尾边来加宽或收窄该列。 |
reorderableColumns | boolean | false | 读者是否可以拖动表头,把该列放到别处。 |
reorderableRows | boolean | false | 读者是否可以拖动一行将其放到别处。用键盘时,Alt+Shift 加上下方向键会把光标所在行移动一位,并朗读新的位置。 |
rowHandleLabel | string | '' | 行拖动把手的无障碍名称。 |
columnWidths | Record<string, number> | {} | 每列的宽度,单位为像素,以别名为键。双向:读者拖动时表格会写入它,你也可以将其持久化。 |
minColumnWidth | number | 48 | 列可被拖动到的最窄宽度。 |
virtual | boolean | false | 只画视口覆盖到的行,并为其余的行预留高度,适合成千上万行的表。默认关闭,而且有代价:视野之外的行不在文档里,浏览器自带的查找和打印只能触及画出来的部分,且各行高度必须一致。开启时还会给表 24rem 的高度,因为任其生长的表和内容一样高,那样就没有东西可虚拟化了。 |
rowHeight | number | 0 | 虚拟化时一行的高度,单位像素。0 表示量第一行画出来的行;只要各行相仿就没问题。表若是在隐藏状态下搭起来的,请明确写出:从未布局过的行量出来是 0,而从 0 推出的窗口就是整张表。 |
formulas | boolean | false | 值以 = 开头的单元格算不算公式。不主动开启:文本列完全可能就把 =1+1 当作某人写下的内容。公式可以用别名指代列——=[units] * [price]、=SUM([total:])——挑动列或改写表头之后意思依旧;也可以用表格软件那种坐标——=ROUND(SUM(E1:E4), 2)——坐标说的是列“在哪里”而不是“是哪一列”,所以 rewriteRowFormulas() 会让它们随表格的形状一起移动,而指向已删除内容的引用会变成 #REF!,而不是默默读旁边一列。冒号读取整列并排除发问的那个单元格;其他的环会显示为 #CYCLE!,而不是一路追下去。 |
mergeable | boolean | false | 读者能否合并单元格并再拆开,通过右键菜单提供,所以也需要 contextMenu。和所有改变结构的功能一样,不主动开启。 |
editOn | 'click' | 'double-click' | 'double-click' | 用指针打开编辑器的方式。默认是双击,即表格的惯例:单击只选中单元格,不动它的值;键入的第一个字符会打开编辑器并落在里面;带列表或日期的单元格会显示一个标记,单击它即可打开。设为 click 则第一次单击就打开,适合本来就是用来录入的表。两种方式下编辑器都在松开时打开,且仅在指针没有移动时,所以拖出区域照常可用。 |
expansion | TemplateRef<HubSpreadsheetExpansionContext<TRow>> | null | null | 绘制在已展开行下方的模板,用于呈现该行在数字背后所包含的内容。 |
expandedRow | string | null | null | 双向。以行的键指明哪一行已展开;一次只能展开一行。 |
expandToggle | boolean | false | 在会打开明细的每一行边缘绘制一个小按钮,读者无需所有者放置按钮即可打开。 |
expandToggleLabel | string | '' | 该按钮的无障碍名称;表格不带字典。 |
rowLevel | (row: TRow) => number | undefined | () => 0 | 行在大纲中的深度:1 表示一层折叠内,2 表示两层内,0 或无表示不在任何折叠内。 |
collapsedRows | readonly string[] | [] | 双向。哪些行组被折叠,按组 id。 |
collapsedColumns | readonly string[] | [] | 双向。哪些列组被折叠,按组 id。 |
rowToggleLabel | string | '' | 行组按钮的无障碍名称。 |
columnToggleLabel | string | '' | 列组按钮的无障碍名称。 |
direction | 'auto' | 'ltr' | 'rtl' | 'auto' | 表格的排列方向。auto 跟随页面——位于从右到左文章中的表格会像文章一样阅读,因为 dir 是继承的——而 ltr 和 rtl 则强制用于必须与周围页面相反的表格。 |
contextMenu | boolean | false | 右键单击时是否提供结构性更改菜单。每个条目仍须通过权限检查,且菜单绝不会以空内容打开。 |
columns[].kind | 'text' | 'number' | 'currency' | 'date' | 'boolean' | 'select' | 'text' | 该列如何显示其值,以及如何读回输入的内容。select 列会打开一个列表,并拒绝不在列表中的内容;boolean 会绘制一个单击即可翻转的复选框;date 会打开日期字段。 |
columns[].formula | string | — | 本列每个单元格据以算出的公式,写在代码里而不是存在数据中:行小计、税额、滚动余额。与读者敲入的公式正好相反,那种是行持有的值,可以像别的值一样改。这种列的单元格根本打不开:替换掉一个会只在那一行丢掉公式,而这要等到合计对不上才会被发现。需要表上的 formulas。 |
columns[].placeholder | string | — | 当指针停在该列的空单元格上时显示的提示。绝不取代值:一整列始终显示在屏幕上的提示,看起来就像一列内容。 |
columns[].append | HubSpreadsheetAppend<TRow> | — | 显示在主值之后、从短列表中选择的第二个值:数量后的单位,折扣数值后的折扣类型。对它的修改以 commit 的形式到达,其列键为 append.key。复制会写出两部分;CSV 和 XLSX 只导出主值。 |
columns[].options | readonly HubSpreadsheetOption[] | — | select 列提供的选项。单元格显示匹配的标签而不是存储的值;没有匹配时回退为原始值,因此持有已停用选项的行仍然可读。 |
structure | HubSpreadsheetStructureOptions<TRow> | {} | 读者可以请求哪些结构性更改。在获得允许之前,一律拒绝。 |
retiredColumnKeys | readonly string[] | [] | 已删除列的别名,使新列不会继承已失效的标识。 |
hubSpreadsheetCell (directive on ng-template)必填 | string | — | 列的别名,该列的单元格由此模板绘制,而不是默认渲染器。作为指令属性本身绑定:hubSpreadsheetCell="state"。 |
hubSpreadsheetCellRows (hubSpreadsheetCell) | readonly TRow[] | [] | 传给表格的同一组行。不会被读取;它们只是让编译器能够为模板上下文中的行确定类型。 |
hubSpreadsheetCellAction (hubSpreadsheetCell) | string | ((row: TRow) => boolean) | '' | 将该列标记为其单元格可以打开其他内容的列,并给出该入口的无障碍名称。可通过函数按行决定。Enter 键保留用于打开,按键事件通过 opened 上报。 |
hubSpreadsheetEditor (directive on ng-template)必填 | string | — | 列的别名,该列的编辑器由此模板绘制,而不是内置编辑器。作为指令属性本身绑定:hubSpreadsheetEditor="assignee"。 |
hubSpreadsheetEditorRows (hubSpreadsheetEditor) | readonly TRow[] | [] | 传给表格的同一组行。不会被读取;它们只是让编译器能够为模板上下文中的行确定类型。 |
hubSpreadsheetControl (directive on ng-container)必填 | HubSpreadsheetControlConfig | — | 通过 provideHubSpreadsheetControls() 注册的控件适配器渲染单元格编辑器。配置在编辑器打开时只读取一次。 |
value (hub-spreadsheet-field, ng-hub-ui-spreadsheet/signals) | TRow[] | [] | 双向模型(使用 [(value)]),以 Signal Forms 字段值的形式保存各行;用户每次修改单元格时都会写回。触发 valueChange。 |
disabled (hub-spreadsheet-field) | boolean | false | 由 Signal Forms FormField 指令绑定;禁用所有编辑器。 |
errors (hub-spreadsheet-field) | readonly ValidationError.WithOptionalFieldTree[] | [] | 由 Signal Forms FormField 指令绑定。这里只会收到数组字段自身的错误,因此作为整体显示,而不是按单元格显示。hub-spreadsheet-field 还接受 columns、rowKey、states、decimalMark、emptyText、pageSize、readonly、frozenColumns、frozenRows 和 spans,含义与 hub-spreadsheet 相同,并触发 selectionChange。 |
输出
响应 spreadsheet 的行为——有 21 个事件可供你挂接逻辑。
| 名称 | 类型 | 描述 |
|---|---|---|
commit | HubSpreadsheetCommit<TRow> | 某个单元格取得了新值,且与它原来持有的值不同。 |
pasted | HubSpreadsheetPaste<TRow> | 粘贴了一个区块,并附带落在表格之外的数量和不是数字的数量。 |
cleared | HubSpreadsheetCellRef<TRow>[] | 在多个单元格上,或在列表或是/否单元格上按下了 Delete 或 Backspace;携带它所覆盖的可编辑单元格。单个文本单元格则会打开一个空的编辑器。 |
opened | HubSpreadsheetCellRef<TRow> | 单元格的 action 被使用——用指针,或在没有可编辑字段处用 Enter。 |
selectionChange | HubGridRange | null | 所选矩形发生了变化。 |
filled | HubSpreadsheetPaste<TRow> | 填充手柄的一次拖动结束,整个手势只报告为一个事件。 |
undoRequested | void | 读者请求撤销。 |
redoRequested | void | 读者请求重做。 |
columnMoved | { from: number; to: number; key: string; keys: string[] } | 某列被放到了别处。只报告,不应用:载荷中带有已重新排序的别名。 |
rowMoved | { from: number; to: number; key: string; keys: string[] } | 一行被放到了别处。只报告,不自行应用:负载中已经携带了重新排序后的键。 |
invalidDraftsChange | Record<string, string> | 未保存的文本发生变化:读者带着该单元格无法保存的文本离开,或修正、放弃、覆盖了这样的文本。 |
mergeRequested | HubSpreadsheetMergeRequest | 读者要求合并一片选区。负载里有要创建的合并块,以及它吞掉的那些块的锚点:只追加而不移除它们,就会有两个块争同一个单元格。applySpanMerge() 一行搞定。 |
unmergeRequested | readonly HubGridCoords[] | 读者要求拆开选区碰到的合并块,以锚点指明。用 applySpanUnmerge() 应用。 |
selectionRangesChange | readonly HubGridRange[] | 选区里的每一个矩形,只要它变化就发出。它与 selectionChange 并存,后者继续报告光标所在的那一个:要显示「所选区域合计」的一方需要全部,要显示「你在 B4」的一方不需要。除非用 Ctrl 加过区块,否则只有一个元素。 |
insertRequested | HubSpreadsheetInsertRequest | The reader asked to add rows or columns.比表格更长的粘贴也会这样请求缺少的行,count 为所需行数。 |
deleteRequested | HubSpreadsheetDeleteRequest | 读者请求删除行或列,并给出涉及的别名。 |
valueChange (hub-spreadsheet-field) | TRow[] | 各行发生变化时,由双向 value 模型触发。 |
columnWidthsChange | Record<string, number> | 用户调整列宽时,由双向 columnWidths 模型触发。 |
expandedRowChange | string | null | 行展开或折叠时,由双向 expandedRow 模型触发。 |
collapsedColumnsChange | readonly string[] | 列分组折叠或展开时,由双向 collapsedColumns 模型触发。 |
collapsedRowsChange | readonly string[] | 行分组折叠或展开时,由双向 collapsedRows 模型触发。 |
方法
通过代码驱动 spreadsheet——其编程接口提供 19 个方法。
| 名称 | 签名 | 返回值 | 描述 |
|---|---|---|---|
HubSpreadsheetComponent.focusCell | focusCell(rowKey: string, column?: string): void | — | 按行键和列别名把光标和键盘放到某个单元格上。会等待刚添加的行;未给别名时落在该行第一个可输入的单元格,下一次按键即可打开它。 |
HubSpreadsheetComponent.editCell | editCell(rowKey: string, column?: string): void | — | 从代码中打开单元格的编辑器并保留其值,与 F2 相同。和 focusCell 一样会等待刚添加的行;对不可编辑的单元格只放置光标。 |
sheetToXlsx | sheetToXlsx<TRow>(rows, columns, options?: HubXlsxOptions): Uint8Array | Uint8Array | 把表格写成真正的 .xlsx,返回字节。数字仍是数字,日期列就是日期,这是 CSV 装不下的。写出的是单元格显示的内容:列表列导出它的标签,公式导出它的结果;要行里存的原值就传 values: 'stored'。 |
downloadXlsx | downloadXlsx(filename: string, bytes: Uint8Array): void | — | 把那个工作簿交给读者保存,名字里缺 .xlsx 就补上。放在这里是因为每个宿主都要写同样的六行,而且都忘了释放 object URL。 |
xlsxToRecords | xlsxToRecords<TRow>(bytes, columns, options?: HubXlsxReadOptions): Promise<Array<Record<string, string>>> | Promise<Array<Record<string, string>>> | 把工作簿的第一张表读成以列别名为键的行,并还原 CSV 里根本不存在的两件事:共享字符串,以及以天数保存的日期。它是异步的,因为真正的工作簿是压缩的,解压用的是平台自带的能力。 |
sheetToCsv | sheetToCsv<TRow>(rows, columns, options?: HubCsvOptions): string | string | 把表格写成 CSV。不指定分隔符时由小数点符号决定——逗号不能既当小数点又当分隔符——所以给写 1.234,56 的人看的文件用分号。 |
downloadText | downloadText(filename: string, text: string, type?: string): void | — | 把一个文本文件交给读者保存,带上让表格软件按 UTF-8 打开的字节序标记,不会变成乱码。 |
csvToRecords | csvToRecords<TRow>(text, columns, options?: HubCsvOptions): Array<Record<string, string>> | Array<Record<string, string>> | 把 CSV 读成以列别名为键的行,分隔符是从第一行嗅出来的,不是猜的。表头先按表头、再按别名匹配,忽略大小写和两端空格。 |
sheetValues | sheetValues<TRow>(rows, columns, options?: HubSheetValuesOptions): HubSpreadsheetValue[][] | HubSpreadsheetValue[][] | 每个单元格的内容,公式已经算好,算不出来的按表格软件的写法写。两个导出读的都是它,公开出来给要自己写文件的宿主用。 |
evaluateSheet | evaluateSheet<TRow>(input: HubFormulaSheetInput<TRow>): HubFormulaSheet | HubFormulaSheet | 按依赖要求的顺序跑完表里所有公式,用到才算,算过就记住。环一闭合就被抓住,不会一路追下去。公开出来给只要结果、不需要绘制的宿主用。 |
rewriteRowFormulas | rewriteRowFormulas<TRow extends object>(rows, change: HubFormulaShapeChange): TRow[] | TRow[] | 表格变形之后——列挪了位置,或者插入、删除了行列——把行里所有坐标都挪过去。指向已删除内容的引用会变成 #REF!,而不是默默去读旁边一列。由宿主调用,因为行是宿主的。 |
mergeRequestFor | mergeRequestFor(spans, range): HubSpreadsheetMergeRequest | null | HubSpreadsheetMergeRequest | null | 一个选区会变成的合并块,以及它吞掉的锚点;只有一个单元格时返回 null。被吞掉的锚点正是宿主自己容易做错的地方:加了块却不去掉它们,两个块就会争同一个单元格。 |
applySpanMerge | applySpanMerge(spans, request: HubSpreadsheetMergeRequest): HubGridSpan[] | HubGridSpan[] | 这次合并之后的块列表,被吞掉的已经去掉。 |
applySpanUnmerge | applySpanUnmerge(spans, anchors: readonly HubGridCoords[]): HubGridSpan[] | HubGridSpan[] | 把那些块拆开之后的列表。 |
spreadsheetRecords | spreadsheetRecords<TRow>(rows, columns): HubSpreadsheetRecord[] | HubSpreadsheetRecord[] | 每一行都是以列别名为键的纯数据,于是可以直接用 { price: 12, units: 3 },而不用按位置把坐标对到自己的字段上。 |
parseForColumn | parseForColumn<TRow>(text, column, decimalMark: ',' | '.'): HubSpreadsheetValue | undefined | HubSpreadsheetValue | undefined | 一段敲进去或粘进来的文字在某一列里值多少:值本身,空单元格是 null,这一列装不了的东西是 undefined——于是调用方可以拒绝,而不是把垃圾存下来。 |
nextColumnKey | nextColumnKey(taken: Iterable<string>, prefix?: string): string | string | 一个从来不属于别的列的别名。新列不会重用退役的名字,任何已保存的引用也就不可能指到别处去。 |
danglingColumnKeys | danglingColumnKeys<TRow>(referenced: Iterable<string>, columns): string[] | string[] | 已经解析不到任何列的引用,也就是一次删除会留下的悬空指向。 |
provideHubSpreadsheetControls | provideHubSpreadsheetControls(adapter: HubSpreadsheetControlsAdapter): EnvironmentProviders | EnvironmentProviders | 注册一个控件适配器,之后每个列表列都用它打开——带搜索、已经展开,打开单元格的那个字符也落在搜索框里。没有适配器时表格画自己的原生列表,这正是这个库能单独安装的原因。 |
模板
打造你自己的样式——3 个模板插槽让你可以投影自定义标记。
| 名称 | 描述 | 示例 |
|---|---|---|
hubSpreadsheetEditor | 替换某一列的编辑器,按别名指定。模板会拿到值、commit 与 cancel 这一对、用于在不关闭的情况下暂存值的 draft,以及 `seed`——读者以键入方式打开单元格时的那个字符,它该进选择器的搜索框。表格像关闭自己的编辑器一样关闭它:按 Escape 时保持原样(其中打开的列表先关闭);按 Tab 时提交 draft 暂存的值;焦点移到别处时同样如此,除非移入其某个控件通过 aria-controls 指明的弹出层,hub-select 的列表就是这样。其他按键都归编辑器,包括 Enter。表格不依赖你放进去的东西。 | <ng-template hubSpreadsheetEditor="assignee" let-value let-seed="seed" let-commit="commit">
<hub-select [items]="people" autoOpen [initialSearchTerm]="seed ?? null" [ngModel]="value" (ngModelChange)="commit($event)" />
</ng-template> |
hubSpreadsheetCell | 在不处于编辑状态时,自己来画某一列的单元格:状态徽章、名字旁的头像、一排操作。它和 hubSpreadsheetEditor 是一对,后者管单元格的另一半时间。剪贴板带走的仍是值而不是画面,键盘落点也仍是单元格。用 hubSpreadsheetCellRows 把行交出去,编译器就知道 `row` 是什么。 | <ng-template hubSpreadsheetCell="state" let-value>
<hub-badge variant="soft" [color]="colourOf(value)">{{ labelOf(value) }}</hub-badge>
</ng-template> |
hubSpreadsheetHeader | 自行绘制列标题:名称旁的图标、编辑该列的按钮。它是 hubSpreadsheetCell 在标题上的对应物。<th> 仍归表格所有,保留其宽度、冻结、粘性位置和全选复选框。其中的按钮、链接或输入框可以按下而不会拖动列。模板会收到列、其 index、key 和纯文本 header。 | <ng-template hubSpreadsheetHeader="price" let-column>
{{ column.header }} <button type="button" (click)="editPrice()">Edit</button>
</ng-template> |