快速开始

安装

# npm
npm i miao-design

# pnpm
pnpm add miao-design

# yarn
yarn add miao-design

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

引入样式

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

import 'miao-design/style.css'

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

完整引入

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

// 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。

<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>

按需引入

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

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

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

树摇说明

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

使用 v-ripple 指令

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

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

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

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

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

详见 v-ripple 涟漪。

编程式 Toast

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

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 轻提示。

TypeScript

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

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

全局组件类型提示

完整引入时，模板里的 <MButton> 不会有类型报错，因为组件是通过 app.component() 在运行时注册的，Volar 无法静态推断。如果需要严格的模板类型检查，改用具名导入，或者在 env.d.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> 引入：

<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>

下一步

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