快速上手 · Morya UI

快速上手

在线文档：morya-space.github.io/morya-ui · 源码：GitHub · npm：morya-ui

安装

在应用项目中（npm / pnpm / yarn）：

pnpm add morya-ui

也可以用：

npx @morya-ui/setup app

会安装依赖，并尽量在入口注入样式。更多命令与选项见 一键接入。需要 Vue 3（推荐 3.5 及以上）。主题 token、亮暗切换与动效 API 均包含在 morya-ui 中。Agent Skill / MCP 见 AI 接入。

选择使用方式

本库同时支持全量与按需两种消费方式，按项目需求任选其一（同一应用内建议保持一致）。

全量用法

1. 插件注册（推荐的全量方式）

在应用入口引入全量样式，并通过插件一次注册所有组件：

import MoryaUI from 'morya-ui'
import { createApp } from 'vue'
import App from './App.vue'
import 'morya-ui/styles.css'

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

模板中可直接使用 <MButton>、<MInput> 等，无需逐个 import。

2. 按名导入 + 全量样式

不注册插件、在 SFC 中按需写 import，JS 可由构建工具 tree-shake，但样式仍需全量 CSS：

import { createApp } from 'vue'
import App from './App.vue'
import 'morya-ui/styles.css'

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

<script setup lang="ts">
import { MButton, MInput } from 'morya-ui'
import { ref } from 'vue'

const name = ref('')
</script>

<template>
  <div style="display: grid; gap: 1rem; max-width: 20rem">
    <MInput v-model="name" label="名称" placeholder="输入名称" />
    <MButton label="提交" @click="() => undefined" />
  </div>
</template>

按需用法

1. 子路径导入

从 kebab-case 子路径导入（如 button、input-password、tree-select）。会带上组件 JS、类型声明、内部依赖与对应样式，无需再引 morya-ui/styles.css。Props 等类型从同一路径导入，例如 import type { ButtonProps } from 'morya-ui/button'。

import { MButton } from 'morya-ui/button'
import { MInput } from 'morya-ui/input'

仅要样式时：

import 'morya-ui/button/style'
import 'morya-ui/button/style.css'

2. 自动按需（Vite）

安装 unplugin-vue-components 后，在 vite.config.ts 中配置解析器，模板里可直接写 <MButton>：

import { MoryaUIResolver } from 'morya-ui/resolver'
import Components from 'unplugin-vue-components/vite'

export default defineConfig({
  plugins: [
    vue(),
    Components({
      dts: 'src/components.d.ts',
      resolvers: [MoryaUIResolver()],
    }),
  ],
})

dts 会写出组件声明，编辑器和 vue-tsc 据此识别模板里的组件；该文件需落在 tsconfig.json 的 include 中。按需模式下，createMoryaUI({ components: false }) 仍可注入全局配置而不注册组件。

可选：应用级全局配置

createMoryaUI 会写入全局默认值，并默认注册全部组件：

import { createMoryaUI } from 'morya-ui'
import { createApp } from 'vue'
import App from './App.vue'
import 'morya-ui/styles.css'

createApp(App)
  .use(
    createMoryaUI({
      appendTo: 'body',
      size: 'small',
      zIndex: 1100,
    }),
  )
  .mount('#app')

仅配置、不注册组件时使用 components: false。

更多说明见 全局配置。

主题 API

亮暗切换等能力从同一包引入：

import { useTheme } from 'morya-ui'

const { toggleTheme } = useTheme()

详见 主题。

启动本仓库文档站

pnpm --filter morya-ui dev
# http://localhost:5182

# 构建静态文档站
pnpm --filter morya-ui build:docs