跳到主要内容

快速开始 ​

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 中可直接使用(客户端引入样式即可)。

下一步 ​