当前位置：首页 > news >正文

零基础入门StencilJS：30分钟打造你的第一个跨框架组件

news 2026/7/27 21:54:09

零基础入门StencilJS：30分钟打造你的第一个跨框架组件

【免费下载链接】awesome-stenciljsList of Awesome Web Components Built with StencilJS项目地址: https://gitcode.com/gh_mirrors/aw/awesome-stenciljs

StencilJS是一个强大的Web Components编译器，它结合了TypeScript、JSX、虚拟DOM等现代前端技术，让开发者能够构建高性能、跨框架的组件。本指南将带你快速入门StencilJS，在30分钟内完成你的第一个跨框架组件开发。

为什么选择StencilJS？

StencilJS由Ionic团队开发，它解决了Web组件开发中的多个痛点：

跨框架兼容性：构建的组件可在React、Angular、Vue等任何框架中使用
高性能：采用异步渲染管道和懒加载技术
现代化开发体验：支持TypeScript和JSX语法
标准化：生成符合Web Components标准的组件

快速安装与环境搭建

首先确保你的系统已安装Node.js（推荐v14+），然后通过以下命令快速创建Stencil项目：

npm init stencil

根据提示选择"component"模板，这将创建一个最小化的组件库项目结构。

项目结构解析

创建完成后，你会看到以下核心文件结构：

src/components/：存放组件源代码
src/index.ts：组件导出入口
stencil.config.ts：项目配置文件

Stencil使用TypeScript开发，每个组件通常由.tsx文件实现，包含JSX模板和业务逻辑。

创建你的第一个组件

让我们创建一个简单的"用户卡片"组件。在src/components/目录下创建user-card/文件夹，并添加user-card.tsx文件：

import { Component, Prop, h } from '@stencil/core'; @Component({ tag: 'user-card', styleUrl: 'user-card.css', shadow: true }) export class UserCard { @Prop() name: string; @Prop() avatar: string; @Prop() role: string; render() { return ( <div class="card"> <img src={this.avatar} alt={this.name} /> <div class="info"> <h3>{this.name}</h3> <p>{this.role}</p> </div> </div> ); } }

添加对应的CSS文件user-card.css：

.card { display: flex; align-items: center; padding: 16px; border: 1px solid #e0e0e0; border-radius: 8px; max-width: 300px; } .card img { width: 64px; height: 64px; border-radius: 50%; margin-right: 16px; } .info h3 { margin: 0 0 4px 0; color: #333; } .info p { margin: 0; color: #666; font-size: 0.9em; }

组件属性与事件

Stencil提供了丰富的装饰器来增强组件功能：

@Prop()：定义组件属性，支持类型检查
@State()：管理组件内部状态
@Event()：定义自定义事件
@Method()：暴露公共方法

例如，为用户卡片添加点击事件：

import { Component, Prop, Event, EventEmitter, h } from '@stencil/core'; // ... export class UserCard { @Event() userClick: EventEmitter<string>; onCardClick() { this.userClick.emit(this.name); } render() { return ( <div class="card" onClick={() => this.onCardClick()}> {/* ... */} </div> ); } }

本地开发与测试

使用以下命令启动开发服务器：

npm start

Stencil会自动编译代码并启动开发服务器，你可以在浏览器中访问http://localhost:3333查看组件示例。

构建与发布

完成组件开发后，使用以下命令构建生产版本：

npm run build

构建产物将生成在dist/目录下，包含多种格式的输出文件，适用于不同场景的集成需求。

在不同框架中使用

Stencil组件可以无缝集成到各种前端框架中：

React中使用

import { defineCustomElements } from 'your-component-library/loader'; defineCustomElements(); function App() { return ( <div> <user-card name="John Doe" avatar="https://example.com/avatar.jpg" role="Frontend Developer" /> </div> ); }

Angular中使用

// 在app.module.ts中 import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'; @NgModule({ // ... schemas: [CUSTOM_ELEMENTS_SCHEMA] }) // 在模板中 <user-card name="John Doe" avatar="https://example.com/avatar.jpg" role="Frontend Developer" ></user-card>