跨端接入
ruanno-ui 目前提供两条产品线:
ruanno-ui:面向 Web 平台的完整组件库(桌面浏览器 + 移动端 H5)。@ruanno-ui/uniapp:面向 uni-app / uni-app X 的跨端组件包,覆盖 H5、微信小程序、App 三端。
支持矩阵
| 平台 | 支持情况 | 说明 |
|---|---|---|
| 桌面 Web | ✅ 完整支持 | 主战场,全部组件可用 |
| 移动端 H5(浏览器 / WebView) | ✅ 完整支持 | 响应式 + 触摸交互 + 刘海屏安全区适配 |
| uni-app(H5 平台) | ✅ 可用 | 使用 ruanno-ui 或 @ruanno-ui/uniapp 均可 |
| uni-app(微信小程序 / App) | ✅ 完整支持 | 使用 @ruanno-ui/uniapp,97/97 个组件已覆盖 |
| 微信原生小程序 | ❌ 暂不支持 | 无 DOM 环境,见下文原因 |
为什么微信原生小程序暂不支持
ruanno-ui 的 Web 组件基于 DOM + CSS 变量 + Pointer Events 实现,样式靠 :root / [data-rn-theme] 上的 --rn-* CSS 变量驱动。而微信原生小程序运行在没有 DOM、没有 CSS 变量的环境里,直接引入无法运行。
@ruanno-ui/uniapp 则是从小程序/App 渲染层重新实现的组件,不依赖 DOM,因此可以在uni-app 全平台运行。
Web 端接入(桌面 / H5)
bash
npm install ruanno-uits
// main.ts
import { createSSRApp } from "vue";
import { createRuannoUI, setRnTheme } from "ruanno-ui";
import "ruanno-ui/style.css";
import App from "./App.vue";
export function createApp() {
const app = createSSRApp(App);
app.use(createRuannoUI());
setRnTheme("classic");
return { app };
}完整示例参考仓库 apps/playground(本地 pnpm dev 启动)与 apps/h5。
uni-app 接入(推荐 @ruanno-ui/uniapp)
安装
@ruanno-ui/uniapp当前为实验性预览、暂未发布 npm,安装命令在包首发后可用。
bash
npm install @ruanno-ui/uniapp引入样式
在 App.vue 的 <style> 中引入:
vue
<style>
@import "@ruanno-ui/uniapp/styles";
</style>全局注册组件
ts
// main.ts
import { createSSRApp } from "vue";
import * as Ruanno from "@ruanno-ui/uniapp";
import App from "./App.vue";
export function createApp() {
const app = createSSRApp(App);
for (const [name, comp] of Object.entries(Ruanno)) {
if (typeof comp === "object" && "render" in comp) {
app.component(name, comp);
}
}
return { app };
}页面中使用
vue
<template>
<view class="page">
<Button variant="primary" size="md">主要按钮</Button>
<Cell title="用户名" value="Ruanno" arrow />
<Badge content="5">
<Icon name="bell" :size="24" />
</Badge>
</view>
</template>
<script setup lang="ts">
import { Button, Cell, Badge, Icon } from "@ruanno-ui/uniapp";
</script>主题切换
vue
<template>
<view class="page" :data-rn-theme="theme">
<!-- ... -->
</view>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { setRnTheme } from "@ruanno-ui/uniapp";
const theme = ref("classic");
setRnTheme(theme.value);
</script>完整示例
参考仓库 apps/uniapp-demo,支持:
bash
pnpm --filter @ruanno-ui/uniapp-demo dev:app # App
pnpm --filter @ruanno-ui/uniapp-demo dev:mp-weixin # 微信小程序
pnpm --filter @ruanno-ui/uniapp-demo dev:h5 # H5注:实际运行需要使用 HBuilderX 4.85+ 或
@dcloudio/uni-app-cli环境。本仓库 CI 目前仅做类型检查,真机编译请在本地 uni-app 开发环境中进行。
完整的 uni-app 组件清单和迁移进度见 uni-app 组件支持 与仓库中的 packages/uniapp/ROADMAP.md。
微信小程序
- 原生小程序:无法直接引入 ruanno-ui(渲染模型不同,见上文)。
- 替代方案:
- 使用
@ruanno-ui/uniapp编写uni-app项目,编译到微信小程序; - 商城、活动页等场景可用小程序
web-view组件内嵌 H5 页面——ruanno-ui 的 H5 适配可以直接使用。
- 使用
App 混合开发(WebView 内嵌 H5)
原生 App 通过 WebView 内嵌 H5 页面是完全支持的场景,ruanno-ui 已内置移动端适配:
- 刘海屏 / 底部指示条:组件已消费
env(safe-area-inset-*),页面根容器加上padding-bottom: env(safe-area-inset-bottom)即可 - 触摸交互:统一使用 Pointer Events,同时兼容鼠标与触摸
- 移动视口:确保
index.html有<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
完整移动端示例参考仓库 apps/h5(本地 pnpm --filter @ruanno-ui/h5 dev 启动)。