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—每行一个稳定的名称,使保存状态在重新加载后仍跟随它所属的行。
errorsRecord<string, string>{}每个单元格一条校验消息,键与 `states` 相同。由宿主负责,因为校验应属于了解数据含义的一方。单元格会被红框圈出,消息会在悬停或键盘聚焦时以提示框打开。
invalidDraftsRecord<string, string>{}双向。读者留在单元格中、却不是该列能保存的值的文本,键与 states 相同。单元格会继续显示它,带有边框和一条说明未保存的消息;重新打开单元格可将其取回修改,Escape 放弃它,覆盖写入该单元格或删除其所在行、列则会清除它。读取它,就不会在不提示的情况下保存旧值。
statesRecord<string, HubSpreadsheetCellState>{}每个单元格的保存状态,键由行键和列别名以制表符连接而成。
decimalMark',' | '.'','此读者输入小数时使用的字符。仅当粘贴的值不含原始数字时才会参考它。
emptyTextstring''空表格显示的内容。
pageSizenumber10Page Up 和 Page Down 每次移动的行数。
readonlybooleanfalse关闭所有编辑器,无论各个单元格如何设置。
frozenColumnsnumber0固定在起始边的列数,按 Excel 冻结窗格的方式计数。
frozenRowsnumber0固定在表头下方的行数。
spansreadonly HubGridSpan[][]合并区块,每个区块由其左上角和范围来命名。
disjointSelectionbooleantrue按住 Ctrl(Mac 上是 Cmd)点击时,是往选区里再加一个区块,还是重新开始选择。默认开启:表格软件就是这么做的,而且这个手势本来空着——普通点击已经能选中,Ctrl 无话可说。每个区块都有标记,Delete 会把它们全部清空,任何普通点击或方向键都会重新开始选择。只有当这些区块能拼成一张表时才会复制,否则被拒绝;选中多个区块时填充手柄会消失——填充延续的是一个区块,延续哪一个没有答案。
fillHandlebooleanfalseWhether the sheet offers the fill handle at the corner of the selection.同时启用 Ctrl+D(Mac 上为 Cmd+D)向下填充。
canUndobooleanfalse撤销是否可用。表格只负责询问;历史记录由所有者保管。
canRedobooleanfalse重做是否可用。
resizableColumnsbooleanfalse读者是否可以拖动列的尾边来加宽或收窄该列。
reorderableColumnsbooleanfalse读者是否可以拖动表头,把该列放到别处。
reorderableRowsbooleanfalse读者是否可以拖动一行将其放到别处。用键盘时,Alt+Shift 加上下方向键会把光标所在行移动一位,并朗读新的位置。
rowHandleLabelstring''行拖动把手的无障碍名称。
columnWidthsRecord<string, number>{}每列的宽度,单位为像素,以别名为键。双向:读者拖动时表格会写入它,你也可以将其持久化。
minColumnWidthnumber48列可被拖动到的最窄宽度。
virtualbooleanfalse只画视口覆盖到的行,并为其余的行预留高度,适合成千上万行的表。默认关闭,而且有代价:视野之外的行不在文档里,浏览器自带的查找和打印只能触及画出来的部分,且各行高度必须一致。开启时还会给表 24rem 的高度,因为任其生长的表和内容一样高,那样就没有东西可虚拟化了。
rowHeightnumber0虚拟化时一行的高度,单位像素。0 表示量第一行画出来的行;只要各行相仿就没问题。表若是在隐藏状态下搭起来的,请明确写出:从未布局过的行量出来是 0,而从 0 推出的窗口就是整张表。
formulasbooleanfalse值以 = 开头的单元格算不算公式。不主动开启:文本列完全可能就把 =1+1 当作某人写下的内容。公式可以用别名指代列——=[units] * [price]、=SUM([total:])——挑动列或改写表头之后意思依旧;也可以用表格软件那种坐标——=ROUND(SUM(E1:E4), 2)——坐标说的是列“在哪里”而不是“是哪一列”,所以 rewriteRowFormulas() 会让它们随表格的形状一起移动,而指向已删除内容的引用会变成 #REF!,而不是默默读旁边一列。冒号读取整列并排除发问的那个单元格;其他的环会显示为 #CYCLE!,而不是一路追下去。
mergeablebooleanfalse读者能否合并单元格并再拆开,通过右键菜单提供,所以也需要 contextMenu。和所有改变结构的功能一样,不主动开启。
editOn'click' | 'double-click''double-click'用指针打开编辑器的方式。默认是双击,即表格的惯例:单击只选中单元格,不动它的值;键入的第一个字符会打开编辑器并落在里面;带列表或日期的单元格会显示一个标记,单击它即可打开。设为 click 则第一次单击就打开,适合本来就是用来录入的表。两种方式下编辑器都在松开时打开,且仅在指针没有移动时,所以拖出区域照常可用。
expansionTemplateRef<HubSpreadsheetExpansionContext<TRow>> | nullnull绘制在已展开行下方的模板,用于呈现该行在数字背后所包含的内容。
expandedRowstring | nullnull双向。以行的键指明哪一行已展开;一次只能展开一行。
expandTogglebooleanfalse在会打开明细的每一行边缘绘制一个小按钮,读者无需所有者放置按钮即可打开。
expandToggleLabelstring''该按钮的无障碍名称;表格不带字典。
rowLevel(row: TRow) => number | undefined() => 0行在大纲中的深度:1 表示一层折叠内,2 表示两层内,0 或无表示不在任何折叠内。
collapsedRowsreadonly string[][]双向。哪些行组被折叠,按组 id。
collapsedColumnsreadonly string[][]双向。哪些列组被折叠,按组 id。
rowToggleLabelstring''行组按钮的无障碍名称。
columnToggleLabelstring''列组按钮的无障碍名称。
direction'auto' | 'ltr' | 'rtl''auto'表格的排列方向。auto 跟随页面——位于从右到左文章中的表格会像文章一样阅读,因为 dir 是继承的——而 ltr 和 rtl 则强制用于必须与周围页面相反的表格。
contextMenubooleanfalse右键单击时是否提供结构性更改菜单。每个条目仍须通过权限检查,且菜单绝不会以空内容打开。
columns[].kind'text' | 'number' | 'currency' | 'date' | 'boolean' | 'select''text'该列如何显示其值,以及如何读回输入的内容。select 列会打开一个列表,并拒绝不在列表中的内容;boolean 会绘制一个单击即可翻转的复选框;date 会打开日期字段。
columns[].formulastring—本列每个单元格据以算出的公式,写在代码里而不是存在数据中:行小计、税额、滚动余额。与读者敲入的公式正好相反,那种是行持有的值,可以像别的值一样改。这种列的单元格根本打不开:替换掉一个会只在那一行丢掉公式,而这要等到合计对不上才会被发现。需要表上的 formulas。
columns[].placeholderstring—当指针停在该列的空单元格上时显示的提示。绝不取代值:一整列始终显示在屏幕上的提示,看起来就像一列内容。
columns[].appendHubSpreadsheetAppend<TRow>—显示在主值之后、从短列表中选择的第二个值:数量后的单位,折扣数值后的折扣类型。对它的修改以 commit 的形式到达,其列键为 append.key。复制会写出两部分;CSV 和 XLSX 只导出主值。
columns[].optionsreadonly HubSpreadsheetOption[]—select 列提供的选项。单元格显示匹配的标签而不是存储的值;没有匹配时回退为原始值,因此持有已停用选项的行仍然可读。
structureHubSpreadsheetStructureOptions<TRow>{}读者可以请求哪些结构性更改。在获得允许之前,一律拒绝。
retiredColumnKeysreadonly 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)booleanfalse由 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 个事件可供你挂接逻辑。

名称类型描述
commitHubSpreadsheetCommit<TRow>某个单元格取得了新值,且与它原来持有的值不同。
pastedHubSpreadsheetPaste<TRow>粘贴了一个区块,并附带落在表格之外的数量和不是数字的数量。
clearedHubSpreadsheetCellRef<TRow>[]在多个单元格上,或在列表或是/否单元格上按下了 Delete 或 Backspace;携带它所覆盖的可编辑单元格。单个文本单元格则会打开一个空的编辑器。
openedHubSpreadsheetCellRef<TRow>单元格的 action 被使用——用指针,或在没有可编辑字段处用 Enter。
selectionChangeHubGridRange | null所选矩形发生了变化。
filledHubSpreadsheetPaste<TRow>填充手柄的一次拖动结束,整个手势只报告为一个事件。
undoRequestedvoid读者请求撤销。
redoRequestedvoid读者请求重做。
columnMoved{ from: number; to: number; key: string; keys: string[] }某列被放到了别处。只报告,不应用:载荷中带有已重新排序的别名。
rowMoved{ from: number; to: number; key: string; keys: string[] }一行被放到了别处。只报告,不自行应用:负载中已经携带了重新排序后的键。
invalidDraftsChangeRecord<string, string>未保存的文本发生变化:读者带着该单元格无法保存的文本离开,或修正、放弃、覆盖了这样的文本。
mergeRequestedHubSpreadsheetMergeRequest读者要求合并一片选区。负载里有要创建的合并块,以及它吞掉的那些块的锚点:只追加而不移除它们,就会有两个块争同一个单元格。applySpanMerge() 一行搞定。
unmergeRequestedreadonly HubGridCoords[]读者要求拆开选区碰到的合并块,以锚点指明。用 applySpanUnmerge() 应用。
selectionRangesChangereadonly HubGridRange[]选区里的每一个矩形,只要它变化就发出。它与 selectionChange 并存,后者继续报告光标所在的那一个:要显示「所选区域合计」的一方需要全部,要显示「你在 B4」的一方不需要。除非用 Ctrl 加过区块,否则只有一个元素。
insertRequestedHubSpreadsheetInsertRequestThe reader asked to add rows or columns.比表格更长的粘贴也会这样请求缺少的行,count 为所需行数。
deleteRequestedHubSpreadsheetDeleteRequest读者请求删除行或列,并给出涉及的别名。
valueChange (hub-spreadsheet-field)TRow[]各行发生变化时,由双向 value 模型触发。
columnWidthsChangeRecord<string, number>用户调整列宽时,由双向 columnWidths 模型触发。
expandedRowChangestring | null行展开或折叠时,由双向 expandedRow 模型触发。
collapsedColumnsChangereadonly string[]列分组折叠或展开时,由双向 collapsedColumns 模型触发。
collapsedRowsChangereadonly string[]行分组折叠或展开时,由双向 collapsedRows 模型触发。

方法

通过代码驱动 spreadsheet——其编程接口提供 19 个方法。

名称签名返回值描述
HubSpreadsheetComponent.focusCellfocusCell(rowKey: string, column?: string): void—按行键和列别名把光标和键盘放到某个单元格上。会等待刚添加的行;未给别名时落在该行第一个可输入的单元格,下一次按键即可打开它。
HubSpreadsheetComponent.editCelleditCell(rowKey: string, column?: string): void—从代码中打开单元格的编辑器并保留其值,与 F2 相同。和 focusCell 一样会等待刚添加的行;对不可编辑的单元格只放置光标。
sheetToXlsxsheetToXlsx<TRow>(rows, columns, options?: HubXlsxOptions): Uint8ArrayUint8Array把表格写成真正的 .xlsx,返回字节。数字仍是数字,日期列就是日期,这是 CSV 装不下的。写出的是单元格显示的内容:列表列导出它的标签,公式导出它的结果;要行里存的原值就传 values: 'stored'。
downloadXlsxdownloadXlsx(filename: string, bytes: Uint8Array): void—把那个工作簿交给读者保存,名字里缺 .xlsx 就补上。放在这里是因为每个宿主都要写同样的六行,而且都忘了释放 object URL。
xlsxToRecordsxlsxToRecords<TRow>(bytes, columns, options?: HubXlsxReadOptions): Promise<Array<Record<string, string>>>Promise<Array<Record<string, string>>>把工作簿的第一张表读成以列别名为键的行,并还原 CSV 里根本不存在的两件事:共享字符串,以及以天数保存的日期。它是异步的,因为真正的工作簿是压缩的,解压用的是平台自带的能力。
sheetToCsvsheetToCsv<TRow>(rows, columns, options?: HubCsvOptions): stringstring把表格写成 CSV。不指定分隔符时由小数点符号决定——逗号不能既当小数点又当分隔符——所以给写 1.234,56 的人看的文件用分号。
downloadTextdownloadText(filename: string, text: string, type?: string): void—把一个文本文件交给读者保存,带上让表格软件按 UTF-8 打开的字节序标记,不会变成乱码。
csvToRecordscsvToRecords<TRow>(text, columns, options?: HubCsvOptions): Array<Record<string, string>>Array<Record<string, string>>把 CSV 读成以列别名为键的行,分隔符是从第一行嗅出来的,不是猜的。表头先按表头、再按别名匹配,忽略大小写和两端空格。
sheetValuessheetValues<TRow>(rows, columns, options?: HubSheetValuesOptions): HubSpreadsheetValue[][]HubSpreadsheetValue[][]每个单元格的内容,公式已经算好,算不出来的按表格软件的写法写。两个导出读的都是它,公开出来给要自己写文件的宿主用。
evaluateSheetevaluateSheet<TRow>(input: HubFormulaSheetInput<TRow>): HubFormulaSheetHubFormulaSheet按依赖要求的顺序跑完表里所有公式,用到才算,算过就记住。环一闭合就被抓住,不会一路追下去。公开出来给只要结果、不需要绘制的宿主用。
rewriteRowFormulasrewriteRowFormulas<TRow extends object>(rows, change: HubFormulaShapeChange): TRow[]TRow[]表格变形之后——列挪了位置,或者插入、删除了行列——把行里所有坐标都挪过去。指向已删除内容的引用会变成 #REF!,而不是默默去读旁边一列。由宿主调用,因为行是宿主的。
mergeRequestFormergeRequestFor(spans, range): HubSpreadsheetMergeRequest | nullHubSpreadsheetMergeRequest | null一个选区会变成的合并块,以及它吞掉的锚点;只有一个单元格时返回 null。被吞掉的锚点正是宿主自己容易做错的地方:加了块却不去掉它们,两个块就会争同一个单元格。
applySpanMergeapplySpanMerge(spans, request: HubSpreadsheetMergeRequest): HubGridSpan[]HubGridSpan[]这次合并之后的块列表,被吞掉的已经去掉。
applySpanUnmergeapplySpanUnmerge(spans, anchors: readonly HubGridCoords[]): HubGridSpan[]HubGridSpan[]把那些块拆开之后的列表。
spreadsheetRecordsspreadsheetRecords<TRow>(rows, columns): HubSpreadsheetRecord[]HubSpreadsheetRecord[]每一行都是以列别名为键的纯数据,于是可以直接用 { price: 12, units: 3 },而不用按位置把坐标对到自己的字段上。
parseForColumnparseForColumn<TRow>(text, column, decimalMark: ',' | '.'): HubSpreadsheetValue | undefinedHubSpreadsheetValue | undefined一段敲进去或粘进来的文字在某一列里值多少:值本身,空单元格是 null,这一列装不了的东西是 undefined——于是调用方可以拒绝,而不是把垃圾存下来。
nextColumnKeynextColumnKey(taken: Iterable<string>, prefix?: string): stringstring一个从来不属于别的列的别名。新列不会重用退役的名字,任何已保存的引用也就不可能指到别处去。
danglingColumnKeysdanglingColumnKeys<TRow>(referenced: Iterable<string>, columns): string[]string[]已经解析不到任何列的引用,也就是一次删除会留下的悬空指向。
provideHubSpreadsheetControlsprovideHubSpreadsheetControls(adapter: HubSpreadsheetControlsAdapter): EnvironmentProvidersEnvironmentProviders注册一个控件适配器,之后每个列表列都用它打开——带搜索、已经展开,打开单元格的那个字符也落在搜索框里。没有适配器时表格画自己的原生列表,这正是这个库能单独安装的原因。

模板

打造你自己的样式——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>