Handsontable 文档代码示例编写指南:从 TypeScript 源文件到四框架可运行示例
Handsontable 文档代码示例编写指南:从 TypeScript 源文件到四框架可运行示例
本指南面向在 Handsontable 文档仓库中编写嵌入式可运行示例的开发者,系统讲解示例文件的结构组织、TypeScript 优先的编写规范、JavaScript/React/Angular/Vue 3 四种框架各自的代码模式与约束,以及如何通过 ::: example 指令将示例嵌入指南页面。读完本文,你将掌握一套可直接落地的文档示例生产流程,包括 JS 变体的自动生成命令、Angular JIT 模式下的五条硬性限制,以及 Vue 3 单文件组件(SFC)的推荐写法。
示例文件结构:每个指南页一个专属示例目录
Handsontable 文档站(基于 Astro Starlight 构建,见 docs/package.json)为每一个指南页维护一套按框架拆分的示例文件,目录约定如下:
docs/content/guides/category/feature/
feature.md # The guide page
javascript/ # JS examples
example1.js # Generated from TS - do not edit directly
example1.ts # Primary source - edit this first
react/ # React variants
example1.jsx # Generated from TSX
example1.tsx # Primary source
angular/ # Angular variants
example1.ts
example1.html # Template file
vue/ # Vue 3 variants
example1.vue # TypeScript SFC (`<script setup lang="ts">`)
仓库中真实存在的示例,例如 cell-editor/javascript/example1.ts、cell-editor/react/example1.tsx、cell-editor/angular/example1.ts 与 cell-editor/vue/example1.vue,都遵循这一布局。
运行时,页面中的示例由 docs/src/scripts/example-runner.ts 统一加载:它通过 import.meta.glob 扫描 /content/**/example*.js、*.jsx、*.vue、*.ts、*.html 与 *.css,按页面上的 data-example-js、data-example-jsx、data-example-vue、data-example-angular 标记动态导入并执行对应模块,最后调用 renderInstances() 等待实例挂载并修复零高度容器下的渲染尺寸问题。
核心编写规则
控制体量与粒度
- 每个示例控制在 25–60 行,保持聚焦、可快速扫读。
- 一个示例只讲一个概念,用递增编号表达复杂度阶梯:
example1为基础搭建,example2为某个配置变体,example3为进阶用法。这一约定在仓库的 cell-editor 示例中体现得十分清楚(example1基础、example2自定义样式、example3进阶编辑器)。
TypeScript 优先,JS 一律生成
- JavaScript 与 React 示例必须先编写
.ts/.tsx源文件,JS 变体通过脚本生成,严禁手工编辑生成产物。 - 在
docs/目录下执行(路径相对于docs/):
npm run docs:code-examples:generate-js -- <path-to-ts-file>
该命令对应 docs/package.json 中的 docs:code-examples:generate-js 脚本,实际执行 docs/scripts/transpile-doc-example.mjs。它的实现细节值得了解:先用 TypeScript 编译器 API 做纯转译(不类型检查、不解析路径),再用 Prettier 格式化以保证生成的 .js 与 .ts 源在换行和 JSX 属性布局上保持一致;空行通过哨兵注释 /*__HOT_BLANK__*/ 绕过 ts.transpileModule 丢弃空行的行为,而字符串模板与 JSX 内部的空行会被保护、不受影响。
- Vue 示例没有独立的 JS 变体:直接在
.vue文件中使用<script setup lang="ts">编写 TypeScript。
使用真实感数据
优先使用 createSpreadsheetData() 或贴合业务领域的样例数据(产品名、日期、货币),避免 [1, 2, 3] 这类无意义数组。例如 cell-editor/javascript/example1.ts 使用的就是含姓名、邮箱、角色、密码的账户数据。
每个示例必备的三要素
无论哪种框架,以下内容缺一不可:
1. 导入方式:base 导入 + 显式注册
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
registerAllModules();
需要演示 tree-shaking 的示例则改为按需导入单个插件与单元格类型,而不是调用 registerAllModules()。
2. 许可证密钥
licenseKey: 'non-commercial-and-evaluation'
3. 容器元素:约定使用 #example 容器
const container = document.querySelector('#example');
React(TSX/JSX)模式
import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
registerAllModules();
const App = () => {
return <HotTable data={data} licenseKey="non-commercial-and-evaluation" />;
};
运行时层面,example-runner 对 JSX 示例采用 createRoot(container).render(createElement(Component)) 挂载(见 docs/src/scripts/example-runner.ts 中 JSX 分支),React 与 react-dom 运行时只在页面存在 JSX 示例时才动态加载。
Angular 模式:standalone 组件与 JIT 五条铁律
Angular 示例要求全部使用 standalone 组件(standalone: true,imports: [HotTableModule]),并采用 app.config.ts(而非 app.module.ts)+ ApplicationConfig 的现代形态,通过全局 HOT_GLOBAL_CONFIG 注入许可证密钥,因此不要在单个 <hot-table> 绑定上重复设置 licenseKey。模板控制流一律使用 @if / @for (x of list; track x.id),禁用 *ngIf / *ngFor;组件类名统一为 AppComponent。
文档站以 JIT 方式在浏览器中引导 Angular 示例,而 JIT 无法在运行时加载外部文件,由此派生出五条必须遵守的限制:
| 限制 | 原因 | 正确做法 |
|---|---|---|
禁用 styleUrls |
JIT 无法加载外部样式文件 | 用内联 styles: ['...'];页面级 CSS 由 example-runner 通过 --css 槽全局注入 |
禁用 templateUrl |
JIT 无法加载外部模板 | 组件模板用 template: \...`` 内联定义 |
| 禁止构造函数注入 | JIT 缺少装饰器元数据,会抛 NG0202 |
一律使用 inject() |
| 禁止模板中绑定 Hooks | 事件绑定在 JIT 下不可靠 | 将 (afterInit) 等 Hooks 放进 gridSettings |
| 只导入实际用到的符号 | 未使用的导入会引发模块解析错误 | 如 RowObject、ViewChild、NgFor 等不用就不导入 |
单文件双段结构
Angular 的 .ts 文件用 /* file: ... */ 与 /* end-file */ 标记分隔 app.component.ts 与 app.config.ts 两个逻辑文件:
/* file: app.component.ts */
import { Component } from '@angular/core';
import { GridSettings, HotTableModule } from '@handsontable/angular-wrapper';
@Component({
standalone: true,
imports: [HotTableModule],
selector: 'example1-feature-name',
template: `
<div>
<hot-table [data]="data" [settings]="gridSettings"></hot-table>
</div>
`,
})
export class AppComponent {
readonly data = [...];
readonly gridSettings: GridSettings = { ... };
}
/* end-file */
/* file: app.config.ts */
import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
import { registerAllModules } from 'handsontable/registry';
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
registerAllModules();
export const appConfig: ApplicationConfig = {
providers: [
provideZoneChangeDetection({ eventCoalescing: true }),
{ provide: HOT_GLOBAL_CONFIG, useValue: { license: NON_COMMERCIAL_LICENSE } as HotGlobalConfig },
],
};
/* end-file */
对应的 angular/example1.html 是外层包裹(选择器标签),由 example-runner 消费,并非组件模板:
<div>
<example1-feature-name></example1-feature-name>
</div>
HOT_GLOBAL_CONFIG 令牌与 NON_COMMERCIAL_LICENSE 常量的真实定义位于 wrappers/angular-wrapper/projects/hot-table/src/lib/services/hot-global-config.service.ts。
JIT 引导链路
example-runner 中 Angular 的加载顺序严格约定(docs/src/scripts/example-runner.ts):先加载 zone.js(带一次性守卫),再显式导入 @angular/compiler —— 否则 Vite 会把编译器从生产包中 tree-shake 掉,导致 "JIT compiler not available" 错误。随后根据模块导出形态选择引导方式:导出 AppModule 走 platformBrowserDynamic().bootstrapModule()(旧 NgModule 兼容路径),导出 AppComponent 走 bootstrapApplication()(standalone 新路径)。
关于 "Edit on StackBlitz"
启用 Edit on StackBlitz 时,docs/public/example-tabs.js 会把每个框架的伴生 example*.html 合并进生成的应用外壳:parseDocsExampleHtmlForStackBlitz 用浏览器 DOMParser 收集 style 节点放入 <head>、并丢弃 body 片段中的 script 节点;mergeCompanionHtmlForStackBlitz 再将其接入 StackBlitz 模板。没有 HTML 标签页的示例保留默认挂载标记。
Vue 3 模式:TypeScript SFC + Composition API
所有新建或更新的 Vue 示例都必须是 TypeScript 单文件组件,使用 Composition API 与 <script setup lang="ts">。文档站的 example-runner 会加载 vue/example*.vue 模块并用 createApp() 挂载(见 docs/src/scripts/example-runner.ts 的 Vue 分支)。旧式 exampleN.js + exampleN.html 拆分写法已废弃,改动旧示例时应迁移为 .vue SFC。
SFC 骨架
<script setup lang="ts">
import { ref } from 'vue';
import { HotTable } from '@handsontable/vue3';
import { registerAllModules } from 'handsontable/registry';
import type { GridSettings } from 'handsontable/settings';
registerAllModules();
const hotSettings = ref<GridSettings>({
data: [
['Acme Corp', 'Q1 2025', '$4.2M'],
['Vertex Industries', 'Q1 2025', '$18.7M'],
],
colHeaders: true,
height: 'auto',
licenseKey: 'non-commercial-and-evaluation',
});
</script>
<template>
<div id="example1">
<HotTable :settings="hotSettings" />
</div>
</template>
Vue 专属规则速查
- 必须使用
<script setup lang="ts">;用handsontable/settings导出的GridSettings类型标注网格配置;对象行数据可加本地type别名。 registerAllModules()在<script setup>顶层调用一次,不要放进onMounted。HotTable、HotColumn从@handsontable/vue3导入后直接用在<template>中即完成注册,无需全局app.component()。licenseKey放在传给HotTable的 settings 对象内部。<template>根<div>的id必须与指南中的示例容器匹配(如::: example #example1 :vue3对应#example1)。- 网格选项优先使用单个
:settings对象;只有指南正文强调某个具体 prop 时才用独立 prop。 - Handsontable Hooks(
afterChange、beforeDataProviderFetch等)放在 settings 对象内,而不是<HotTable>上的 Vue 事件监听器。 - 响应式状态用
ref();若深度响应式更新会触发多余的updateSettings()调用(比如只在网格旁更新状态标签),则用普通const声明hotSettings。 - 模板引用统一使用
useTemplateRef(),禁止用ref()绑定模板 ref:
import { useTemplateRef } from 'vue';
const hotRef = useTemplateRef<InstanceType<typeof HotTable>>('hotRef');
// <HotTable ref="hotRef" :settings="hotSettings" />
// 访问实例:hotRef.value?.hotInstance
const dropdownRef = useTemplateRef<HTMLDivElement>('dropdownRef');
// <div ref="dropdownRef" class="theme-dropdown">...</div>
// 访问 DOM 节点:dropdownRef.value
传入 useTemplateRef(...) 的字符串必须与模板中的 ref 属性完全一致。HotColumn 应嵌套在 <HotTable> 内,列选项通过每个 HotColumn 的 :settings 传入。示例专属 UI(按钮、状态文本)允许使用 <style scoped>,但指南 --css 槽注入的 example-runner CSS 依然全局生效。
预设(Preset)与 SFC 嵌入
::: example 指令上的预设决定示例的依赖集::vue3(默认)、:vue3-languages、:vue3-vuex,按页面演示的特性选择匹配的预设。
单标签页、不带 --html / --js 的 SFC 嵌入写法:
::: example #example1 :vue3
@<a href="https://link.gitcode.com/i/3aa1393364b747077c9eb8c3bde89342" target="_blank">code</a>
:::
将示例嵌入指南页面
创建示例文件后,用 @<a href="https://link.gitcode.com/i/163e38d0e1be52e2aeac10b5dd021d90" target="_blank">code] 指令配合 ::: example 容器嵌入指南 .md 文件,容器语法详见 [.claude/skills/writing-docs-pages/SKILL.md。其中 --js 1 --ts 2 之类的参数用于控制标签页顺序,Angular 使用 :angular 加 --ts 1 --html 2:
::: only-for javascript
::: example #example1 --js 1 --ts 2
@<a href="https://link.gitcode.com/i/b747a3bb3b70d44e3d0e679424f40a3f" target="_blank">code</a>
@<a href="https://link.gitcode.com/i/3d56997e487959820a0b3599baea7f6d" target="_blank">code</a>
:::
:::
::: only-for react
::: example #example1 :react --tsx 1 --jsx 2
@<a href="https://link.gitcode.com/i/d67beef76523b03a752014bf02dbd1f8" target="_blank">code</a>
@<a href="https://link.gitcode.com/i/370b0a45becd38bcdc4ef85ab54fee9e" target="_blank">code</a>
:::
:::
页面端,docs/public/example-tabs.js 负责把渲染出的 expressive-code 代码面板组装进 .hot-example 容器:构建带 role="tablist" 的标签栏、处理 JS/TS 变体的语言下拉(当示例同时有 JS 与 TS 面板时,Tab 0 变为脚本变体选择器,并联动 "Run" 链接指向对应语言的 demo 地址)、实现 "Source code" 显示/隐藏切换,以及 npm/Yarn/pnpm 等代码组标签。这些交互均遵循 ARIA 规范(aria-selected、aria-expanded、role="option" 等)。
交付前 Checklist
对照以下清单逐项自检,确保示例可直接合入:
- [ ] TypeScript 源文件已编写并测试(
.ts/.tsx,或 Vue 的.vue且带lang="ts")。 - [ ] JavaScript/React 示例的 JS 变体已由脚本生成(非手写);Vue 示例无 JS 变体。
- [ ] 已包含
licenseKey: 'non-commercial-and-evaluation'。 - [ ] 导入遵循
handsontable/base+ 注册模式。 - [ ] 示例保持在 25–60 行内。
- [ ] 一个示例一个概念,使用真实感数据。
- [ ] Vue 示例为
.vueSFC,使用<script setup lang="ts">与 Composition API(无拆分.js/.html,无 Options API)。
这套规范同时服务于 docs/scripts/transpile-doc-example.mjs、docs/src/scripts/example-runner.ts 与 docs/public/example-tabs.js 三个运行环节,理解三者的职责边界——生成 JS、运行时挂载、页面交互——是写出稳定可运行示例的关键。