快速开始

本页假设项目由 pnpm create elfui@beta my-app --install 创建。脚手架已经配置好 Vite 插件，并生成 src/main.ts、src/App.ts 和 vite.config.ts。

这一页从零写一个计数器组件。

前置条件

本页假设你使用的是 ElfUI Macro 组件。创建项目时选择 Macro，并保留脚手架生成的 Vite 插件配置。

推荐：安装 VS Code 插件

推荐使用 ElfUI Language Tools

安装 ElfUI Language Tools，可获得模板补全、悬停类型信息、实时诊断、跳转定义、重命名和代码片段。

在 VS Code 扩展市场中搜索 ElfUI Language Tools，或直接打开链接安装。安装后打开项目中的 .ts、.tsx、.js 或 .jsx 组件文件即可自动启用。

在线体验

不想先搭建本地环境？打开 ElfUI 演练场，即可在浏览器中编辑、运行和预览示例。链接会创建你自己的 StackBlitz 工作区，不会修改官方 starter。

创建组件

// Counter.ts
import { defineHtml, useRef } from "@elfui/core";

const count = useRef(0);
const inc = (): void => count.set(count.peek() + 1);

export const Counter = defineHtml(`
  <button class="counter" @click=${inc}>Count: ${count}</button>
`);

顶层代码就是组件的 setup 逻辑。模板里的 ${count} 会被编译为响应式文本绑定，@click=${inc} 会成为事件监听。

挂载应用

// main.ts
import { createApp } from "@elfui/core";
import { Counter } from "./Counter";

createApp(Counter).mount("#app");

index.html 只需要一个普通容器，不需要手写组件 tag：

html

<div id="app"></div>

不要重复挂载根组件

createApp(Counter).mount("#app") 会自动注册根组件、创建实例并替换容器中的已有内容，返回值是真实的 Custom Element。导出名 Counter 仍会推断为 elf-counter，但应用入口不需要手写这个 tag。

将组件注册到已有 HTML

如果组件需要直接写进已有 HTML，或者组件库需要批量全局注册，可以继续使用 registerComponents()：

import { registerComponents } from "@elfui/core";

registerComponents(Counter);

如果需要自定义单个组件名，可以使用 defineName()；如果需要统一项目前缀，请在 Vite 插件里配置 tagPrefix。

加样式

import { defineHtml, defineStyle, useRef } from "@elfui/core";

defineStyle(`
  .counter {
    border: 0;
    border-radius: 8px;
    padding: 8px 12px;
  }
`);

const count = useRef(0);
const inc = (): void => count.set(count.peek() + 1);

export const Counter = defineHtml(`
  <button class="counter" @click=${inc}>Count: ${count}</button>
`);

样式默认隔离

组件样式默认注入当前 Custom Element 的 Shadow DOM，不会直接污染页面其余区域。

下一步

想写组件 API，看“组件”。
想写模板逻辑，看“模板语法”和“指令”。
想接入工程诊断，看“生态 / Vite 插件”。

快速开始 ​

推荐：安装 VS Code 插件 ​

创建组件 ​

挂载应用 ​

加样式 ​

下一步 ​

快速开始

推荐：安装 VS Code 插件

创建组件

挂载应用

加样式

下一步