Handsontable 文档代码示例编写指南:从 TypeScript 源文件到四框架可运行示例

原创2026-09-22 18:26:261,606 阅读
文章标签:前端UI组件企业应用

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 示例为 .vue SFC,使用 <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、运行时挂载、页面交互——是写出稳定可运行示例的关键。

登录后查看全文
handsontable