# 快速开始

## 安装

```bash
# npm
npm i miao-design

# pnpm
pnpm add miao-design

# yarn
yarn add miao-design
```

`vue@^3.5` 是 peerDependency，由业务侧自行安装，组件库不会重复引入一份 Vue。

## 引入样式

组件库的样式是一个单独的文件，**必须显式引入一次**（放在应用入口即可）：

```ts
import 'miao-design/style.css'
```

这个文件里既有各组件的样式，也有挂在 `:root` 上的全部 `--m-*` 设计令牌，因此引入一次即可全局生效。

## 完整引入

最省事的方式，适合中小型项目：

```ts
// main.ts
import { createApp } from 'vue'
import MiaoDesign from 'miao-design'
import 'miao-design/style.css'
import App from './App.vue'

createApp(App).use(MiaoDesign).mount('#app')
```

`app.use(MiaoDesign)` 会一次性注册 32 个组件与 `v-ripple` 指令，之后在任意模板里直接写 `<m-button />` 就行，不需要 import。

```vue
<script setup lang="ts">
import { toast } from 'miao-design'

function submit() {
  toast.success('保存成功')
}
</script>

<template>
  <div class="m-row-demo">
    <MButton variant="contained" color="primary" @click="submit">保存</MButton>
    <MButton variant="outlined" color="primary">取消</MButton>
  </div>
</template>
```

## 按需引入

需要更小的包体时，用具名导入。组件内部不依赖全局注册，两种方式可以混用：

```vue
<script setup lang="ts">
import { MButton, MTooltip } from 'miao-design'
</script>

<template>
  <MTooltip content="带提示的按钮">
    <MButton variant="tonal" color="primary">悬停看看</MButton>
  </MTooltip>
</template>
```

::: tip 树摇说明
组件库产物的模块图是「一个组件一个 chunk」的结构，配合支持 tree-shaking 的打包器（Vite / Rollup / webpack 5）时，未使用的组件不会进入最终产物。
:::

## 使用 v-ripple 指令

如果你没有 `app.use(MiaoDesign)`，需要单独注册指令：

```ts
import { createApp } from 'vue'
import { vRipple } from 'miao-design'

createApp(App).directive('ripple', vRipple).mount('#app')
```

之后可以给任意元素加水波纹反馈：

```vue
<template>
  <div v-ripple class="card">点我</div>
  <button v-ripple="{ color: '#fff', duration: 300 }">自定义参数</button>
</template>
```

详见 [v-ripple 涟漪](/components/ripple)。

## 编程式 Toast

`toast` 是一个独立的编程式 API，首次调用时会自动把容器挂载到 `body`，无需在模板里放组件：

```ts
import { toast } from 'miao-design'

toast.success('保存成功')
toast.error('网络异常，请重试', { title: '错误', duration: 5000, position: 'top-right' })

const id = toast.show('可手动关闭的提示', { closable: true })
toast.close(id)
```

完整参数见 [Toast 轻提示](/components/toast)。

## TypeScript

组件的类型定义随包发布，直接可用：

```ts
import type { MButtonProps, ButtonColor, MiaoDesign } from 'miao-design'
```

::: tip 全局组件类型提示
完整引入时，模板里的 `<MButton>` 不会有类型报错，因为组件是通过 `app.component()` 在运行时注册的，Volar 无法静态推断。如果需要严格的模板类型检查，改用具名导入，或者在 `env.d.ts` 里补一份全局组件声明：

```ts
// env.d.ts
declare module 'vue' {
  export interface GlobalComponents {
    MButton: typeof import('miao-design')['MButton']
    MInput: typeof import('miao-design')['MInput']
    // …按需补充
  }
}
```
:::

## 无需构建工具（UMD）

组件库同时提供 UMD 产物，可以直接在浏览器里用 `<script>` 引入：

```html
<link rel="stylesheet" href="https://unpkg.com/miao-design/dist/miao-design.css" />

<script src="https://unpkg.com/vue@3/dist/vue.global.prod.js"></script>
<script src="https://unpkg.com/miao-design/dist/miao-design.umd.cjs"></script>

<div id="app">
  <m-button variant="contained" color="primary">Hello Miao</m-button>
</div>

<script>
  const app = Vue.createApp({})
  // UMD 全局变量名为 MiaoDesign，插件对象在其命名导出上
  app.use(MiaoDesign.MiaoDesign)
  app.mount('#app')
</script>
```

## 下一步

- [主题定制](/guide/theme) —— 覆写 `--m-*` 令牌、接入深色模式。
- [组件总览](/components/) —— 全部组件与指令的实时预览与 API。
- [AI 阅读](/guide/ai) —— 把整份文档投喂给 AI 助手。