创建应用

每个 Vitarx 项目都从创建一个应用实例开始。本页介绍如何使用 createApp 创建、挂载和配置应用。

基本用法

createApp 接受一个根组件作为参数，返回一个应用实例。调用 mount 方法将应用挂载到页面上。

最佳实践：分离组件与入口

为了避免开发模式下热更新导致应用重复挂载，推荐将组件定义和应用入口分离：

src/App.tsx - 定义根组件：

tsx
// 根组件定义，使用默认导出
export default function App() {
  return <div>Hello, Vitarx!</div>
}

src/main.tsx - 应用入口：

tsx
import { createApp } from 'vitarx'
import App from './App'

// 创建应用并挂载到 #app 元素
createApp(App).mount('#app')

单一文件示例（快速原型）

如果只是快速原型开发或学习，可以在单个文件中完成：

tsx
import { createApp } from 'vitarx'

function App() {
  return <div>Hello, Vitarx!</div>
}

createApp(App).mount('#app')

提示

开发环境建议：使用分离式写法，这样热更新时只会重新渲染组件，不会重新创建整个应用实例，避免内容重复或状态丢失。

挂载应用

mount 方法支持两种参数形式：

  • CSS 选择器字符串：如 '#app'，框架会自动查找对应元素
  • DOM 元素：直接传入一个 Element 对象
tsx
const app = createApp(App)

// 使用选择器字符串
app.mount('#app')

// 或直接传入 DOM 元素
app.mount(document.getElementById('app')!)

WARNING

如果传入的选择器在页面中找不到对应元素，会抛出错误。请确保挂载目标在调用 mount 时已经存在于页面中。

卸载应用

调用 unmount 方法可以卸载应用，释放所有相关资源：

tsx
const app = createApp(App)
app.mount('#app')

// 需要时卸载应用
app.unmount()

卸载后，页面上的 DOM 会被清除，所有响应式副作用和监听器也会被自动清理。

应用配置

createApp 的第二个参数可以传入配置对象，用于自定义应用行为：

tsx
import { createApp } from 'vitarx'

function App() {
  return <div>Hello</div>
}

const app = createApp(App, {
  // 全局错误处理器
  errorHandler(error, info) {
    console.error('应用错误:', error)
    console.error('错误来源:', info)
  },
  // 自动生成 ID 的前缀
  idPrefix: 'my-app'
})

app.mount('#app')

errorHandler

全局错误处理器，当组件渲染或生命周期中抛出未捕获的错误时触发。

  • error：错误对象
  • info：错误来源信息

如果不配置，默认会在控制台输出错误日志。

idPrefix

框架内部自动生成 ID 时使用的前缀，默认值为 'v'。如果你需要在同一页面运行多个 Vitarx 应用，可以为每个应用设置不同的前缀以避免 ID 冲突。

完整示例

下面是一个包含配置的完整应用示例：

tsx
import { createApp, ref } from 'vitarx'

function App() {
  const count = ref(0)

  return (
    <div>
      <h1>计数器</h1>
      <p>当前计数: {count}</p>
      <button onClick={() => count.value++}>+1</button>
    </div>
  )
}

const app = createApp(App, {
  errorHandler(error, info) {
    console.error('[全局错误]', error, info)
  },
  idPrefix: 'counter'
})

app.mount('#app')

// 5 秒后卸载应用
setTimeout(() => {
  app.unmount()
  console.log('应用已卸载')
}, 5000)

API 参考

typescript
declare function createApp(root: Component | View, config?: AppConfig): App

declare interface AppConfig {
  errorHandler?: (error: unknown, info: ErrorInfo) => void
  idPrefix?: string // 默认 'v'
}

declare class App {
  mount(container: string | Element): this
  unmount(): void
  readonly config: Required<AppConfig>
  readonly version: string
}

下一步