快速开始
ruanno-ui 是基于 Vue 3 的跨端组件库:一套代码同时支持桌面 Web、移动端 H5 与 uni-app(含 uni-app X)。本页介绍 Web 端(ruanno-ui)的安装与接入;uni-app 端请看 uni-app 快速开始。
环境要求
- Vue
>= 3.5 - 现代浏览器(Chrome / Edge / Firefox / Safari 近两年版本),移动端 WebView 同理
- 构建工具不限:Vite / Webpack / Nuxt 均可,ESM 产物
- TypeScript 可选:全量类型声明,开箱即用
安装
bash
# npm
npm install ruanno-ui
# pnpm
pnpm add ruanno-ui
# yarn
yarn add ruanno-ui@ruanno-ui/tokens 会作为依赖自动安装,无需单独处理。
全量引入
适合快速原型、管理后台等不敏感包体积的场景:
ts
// main.ts
import { createApp } from "vue";
import { createRuannoUI } from "ruanno-ui";
import "ruanno-ui/style.css";
import App from "./App.vue";
const app = createApp(App);
app.use(createRuannoUI());
app.mount("#app");全量引入会全局注册全部 97 个组件(PascalCase 本名,如 <Button>、<DatePicker>),以及 v-loading、v-infinite-scroll 两个指令。
按需引入
手动引入单个组件:
vue
<script setup lang="ts">
import { Button, Input } from "ruanno-ui";
import "ruanno-ui/style.css";
</script>
<template>
<Input v-model="value" placeholder="请输入" />
<Button variant="primary">确定</Button>
</template>样式文件 ruanno-ui/style.css 全局引入一次即可(基于 --rn-* CSS 变量,体积很小,不做按组件拆分)。
使用 Vite 的项目推荐配合 unplugin-vue-components 实现「模板里写组件名即自动引入」,见 按需引入与 Resolver。
第一个示例
vue
<script setup lang="ts">
import { ref } from "vue";
import { Button, Input, showToast } from "ruanno-ui";
const name = ref("");
function submit() {
showToast(name.value ? `你好,${name.value}` : "请先输入姓名");
}
</script>
<template>
<div style="display: flex; gap: 8px; max-width: 360px;">
<Input v-model="name" placeholder="输入姓名" />
<Button variant="primary" @click="submit">打招呼</Button>
</div>
</template>统一 API 约定(30 秒版)
全库组件遵循同一套约定,学会一个组件就等于学会所有组件:
| 约定 | 说明 |
|---|---|
size | 'sm' | 'md' | 'lg',默认 'md' |
variant | 语义变体,如 Button 的 primary / secondary / ghost / danger |
disabled / loading | 布尔状态,默认 false;loading 自动禁用交互 |
v-model | 值类组件(Input、Select、DatePicker…) |
v-model:checked | 布尔组件(Web 端 Switch、Checkbox) |
| 事件 | kebab 语义命名:update:modelValue / change / click / close… |
完整约定与跨端差异见 API 约定。
服务函数
反馈类组件除组件式用法外,还提供从包入口直接导入的服务函数:
ts
import {
showToast, closeAllToasts, // 轻提示
showAlert, showConfirm, showPrompt, // 命令式对话框(返回 Promise)
showNotification, closeAllNotifications, // 通知
showImagePreview, // 图片预览
} from "ruanno-ui";
const ok = await showConfirm({ title: "删除确认", content: "删除后不可恢复" });
if (ok) showToast("已删除", { type: "success" });指令
vue
<template>
<div v-loading="loading">数据区域</div>
<ul v-infinite-scroll="loadMore">滚动到底部自动加载</ul>
</template>主题
内置 5 套主题,一行切换:
ts
import { setRnTheme } from "ruanno-ui";
setRnTheme("aurora"); // classic(默认)/ mono / mono-dark / aurora / aurora-dark自定义主题与原理见 主题定制。
国际化
默认简体中文,切换英文只需一行:
vue
<ConfigProvider locale="en">
<App />
</ConfigProvider>详见 国际化。
SSR 兼容
所有组件均通过 createSSRApp + renderToString 冒烟测试:setup 顶层不直接访问 window / document。Nuxt 3 中可直接使用(客户端引入样式即可)。