# 生命周期

- Human documentation: [https://docs.univer.ai/zh-CN/guides/docs/getting-started/lifecycle](https://docs.univer.ai/zh-CN/guides/docs/getting-started/lifecycle)

- Agent Markdown: [https://docs.univer.ai/zh-CN/guides/docs/getting-started/lifecycle.md](https://docs.univer.ai/zh-CN/guides/docs/getting-started/lifecycle.md)

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

- Source: [docs/getting-started/lifecycle.zh-CN.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/docs/getting-started/lifecycle.zh-CN.mdx)

---

在 Univer 应用运行过程中，系统会经历一系列有序的生命周期阶段。了解这些生命周期对于开发者来说非常重要，因为这有助于判断何时可以安全地访问业务实例、DOM 元素或进行耗时的异步操作。不同阶段适合执行不同类型的初始化、渲染和性能优化任务。通过监听生命周期变化，开发者能够在最佳时机响应系统状态的变化，实现功能扩展、性能提升或用户体验优化。

Univer 的生命周期主要包括以下四个阶段：

```mermaid
flowchart LR; A([Starting]) --> B([Ready]) --> C([Rendered]) -->D([Steady])
```

1. **Starting**：系统开始初始化，插件内部会进行依赖注入和基础配置。
2. **Ready**：第一个业务实例已创建，插件内部会进行核心功能的初始化。
3. **Rendered**：界面首次渲染完毕，可以安全操作 DOM 或进行界面相关的初始化。
4. **Steady**：系统进入稳定状态，适合执行延迟加载、非关键性任务等优化操作。

不同类型的插件或组件，其生命周期启动时机可能不同，但整体流程遵循上述顺序。开发者可以通过生命周期事件，精准把控功能的加载与执行时机。

> [!NOTE]
> 想要深入了解 Univer 的生命周期设计以及具体的插件启动时机，可以在 [《Univer
> 架构#插件生命周期》](/blog/univer#plugin-lifecycle) 中找到相关内容。

## Facade API

### 添加监听器

Univer 提供了统一的事件订阅接口，开发者可以通过 Facade API 监听生命周期的变化：

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {
  if (stage === univerAPI.Enum.LifecycleStages.Steady) {
    // 在 Steady 阶段执行自定义逻辑
  }
})
```

### 移除监听器

要移除监听器，可以使用返回的 `disposable` 对象：

```typescript
disposable.dispose()
```

### 生命周期事件与枚举

Univer 提供了以下生命周期事件和枚举，供开发者使用：

* 事件名：`univerAPI.Event.LifeCycleChanged`

* 生命周期阶段枚举：
  * `univerAPI.Enum.LifecycleStages.Starting`
  * `univerAPI.Enum.LifecycleStages.Ready`
  * `univerAPI.Enum.LifecycleStages.Rendered`
  * `univerAPI.Enum.LifecycleStages.Steady`

### 生命周期监听示例

> [!WARNING: 注意事项]
> `univerAPI.Event.LifeCycleChanged` 只会反应生命周期的变化，因此在 `Starting` 阶段不会触发任何事件。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {
  switch (stage) {
    case univerAPI.Enum.LifecycleStages.Ready:
      console.log('业务实例已创建，可以进行核心初始化')
      break
    case univerAPI.Enum.LifecycleStages.Rendered:
      console.log('界面渲染完成，可以安全操作 DOM')
      break
    case univerAPI.Enum.LifecycleStages.Steady:
      console.log('系统已稳定，可进行延迟加载等优化操作')
      break
  }
})

// 移除监听器
disposable.dispose()
```