Stencil 编译器不能直接处理 HTML 文件，仅识别带 @Component 装饰器的 TypeScript/JSX 类文件；需将 HTML 重构为符合 Web Components 规范的组件，包括影子 DOM 隔离、属性驱动和生命周期管理。
不能在 HTML 中直接调用 Stencil 编译器生成 Web Components——stencil build 是一个构建时 CLI 工具，只作用于 TypeScript/JSX 源码，对纯 HTML 文件完全无感知。
为什么直接扔 HTML 进去没反应
Stencil 不是静态 HTML 转换器，也不是模板渲染引擎。它只识别带 @Component 装饰器的 TypeScript 类文件（如 my-button.tsx）。你把 index.html 或 card.html 放进 src/components/ 目录下，stencil build 会跳过它们，不报错也不处理。
- 常见错误现象：
npm run build成功但输出目录里没有对应组件，dist/下找不到my-card.js - 根本原因：Stencil 的编译入口是
src/components/**/*.{tsx,ts}，且必须导出被@Component修饰的类 - 如果你已有现成 HTML 片段，得手动拆解：结构 →
render()返回 JSX，行为 → 写成 class 成员方法，样式 → 移入styleUrl或styles
如何把现有 HTML 正确转成 Stencil 组件
关键不是“转换 HTML”，而是按 Web Components 规范重构封装边界：影子 DOM 隔离、属性驱动、生命周期可控。
- 标签名必须是短横线分隔（kebab-case），如
<product-card>，对应类名写成ProductCard（首字母大写 PascalCase） - 原 HTML 中的
class="btn primary"在 JSX 里要写成class={this.variant}，不能留字符串硬编码 - 内联事件如
onclick="doX()"必须改为onClick={() => this.doX()}，且doX方法需定义在类体内 -
id="modal-root"这类全局 ID 在 Shadow DOM 中失效，改用this.el.shadowRoot.querySelector('.modal-root') - 原 HTML 里的
<style>块必须抽离到独立 CSS 文件，并通过styleUrl: 'my-component.css'引入
构建后怎么在 HTML 中使用
编译完成的组件是标准 Custom Element，可直接在任意 HTML 页面中通过 script 标签引入并使用，无需框架。
立即学习“前端免费学习笔记（深入）”；
- 先运行
npm run build，产物默认在dist/下，含loader.js和组件 JS 文件 - 在 HTML 中引入 loader：
<script type="module" src="/build/my-component.esm.js"></script>（ESM）或<script nomodule src="/build/my-component.js"></script>（UMD） - 然后就能写：
<my-component name="Stencil"></my-component>，属性名全小写，不加on前缀（onclick→click） - 注意：如果组件启用了
shadow: true，外部 CSS 无法穿透影响内部元素，需用:host或::slotted显式控制
最容易被忽略的一点：Stencil 组件的属性响应不是自动的。比如你动态改 el.setAttribute('name', 'new')，组件内部不会自动更新 this.name——除非你用 @Prop() 装饰该字段，并确保它在 render() 中被读取，Stencil 才会在属性变更时触发重渲染。
