跳到主要内容

跨端接入 ​

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-ui
ts
// 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(渲染模型不同,见上文)。
  • 替代方案:
    1. 使用 @ruanno-ui/uniapp 编写uni-app项目,编译到微信小程序;
    2. 商城、活动页等场景可用小程序 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 启动)。