uni-app 快速开始
本页介绍 @ruanno-ui/uniapp 在 uni-app / uni-app X 项目中的完整接入流程。组件总览与平台适用性见 uni-app 组件总览。
环境要求
- uni-app 3.x(Vue 3 版本),
@dcloudio/uni-app≥ 3.0.0-4020…(本仓库基于3.0.0-5020420260813003验证) - Vue
>= 3.5 - 目标平台:H5 / 微信小程序 / App(iOS、Android、鸿蒙);uni-app X 项目使用
.uvue实现
状态说明:
@ruanno-ui/uniapp当前为实验性预览、暂未发布 npm,下文安装命令在包首发后可用;当前可在本仓库内直接联调(参考apps/uniapp-demo)。
安装
npm install @ruanno-ui/uniapp
# 或
pnpm add @ruanno-ui/uniapp引入样式
在 App.vue 的根样式中引入一次:
<style>
@import "@ruanno-ui/uniapp/styles";
</style>该入口包含:--rn-* tokens 变量(挂载在 page 选择器)、5 套主题的 [data-rn-theme] 覆盖、组件公共样式。
注册组件
方式一:按需导入(推荐)
<script setup lang="ts">
import { Button, Cell, Icon } from "@ruanno-ui/uniapp";
</script>
<template>
<view>
<Button variant="primary">确定</Button>
<Cell title="账号安全" arrow />
</view>
</template>方式二:全局注册
// 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" && comp !== null && "render" in comp) {
app.component(name, comp);
}
}
return { app };
}页面中使用
<template>
<view class="page">
<NavBar title="设置" />
<Cell title="用户名" value="Ruanno" arrow />
<Cell title="消息通知" arrow>
<template #value><Switch v-model="notify" /></template>
</Cell>
<Button block variant="primary" size="lg" @click="save">保存</Button>
</view>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { NavBar, Cell, Switch, Button } from "@ruanno-ui/uniapp";
const notify = ref(true);
function save() {
uni.showToast({ title: "已保存" });
}
</script>注意与 Web 端的绑定差异:uni-app 端 Switch / Checkbox 用 v-model 直接绑布尔值(Web 端为 v-model:checked)。
主题切换
主题通过页面根节点的 data-rn-theme 属性生效:
<!-- App.vue -->
<template>
<view class="app" :data-rn-theme="theme">
<slot />
</view>
</template>
<script setup lang="ts">
import { useRnTheme, setRnTheme } from "@ruanno-ui/uniapp";
const theme = useRnTheme(); // Ref<string>,响应式
setRnTheme("aurora"); // classic / mono / mono-dark / aurora / aurora-dark
</script>setRnTheme(name):更新当前主题(只改响应式状态,需由根节点绑定消费);getRnTheme():读取当前主题名;useRnTheme():拿到响应式引用,绑到:data-rn-theme。
内置 5 套主题与 Web 端同名同源(tokens 共享),自定义主题同样只需覆盖 --rn-* 变量。
uni-app X(.uvue)
每个组件同时提供 <Name>.uvue 实现(<script setup lang="uts">),API 与 .vue 版本一致:
- 经典 uni-app 项目:直接用默认导出的
.vue组件; - uni-app X 项目:导入
XxxUvue别名,或按平台条件编译:
import { Button, ButtonUvue } from "@ruanno-ui/uniapp";
// #ifdef APP-X
const Btn = ButtonUvue;
// #endif模板仅使用 <view> / <text> / <image> / <scroll-view> 等跨端标签,容器 / 文本分离(文字样式写在 <text> 上),可直接通过 uni-app X 编译。
平台注意事项
| 能力 | 实现方式 | 注意 |
|---|---|---|
| 图标 | base64 <image>(小程序 / App 不支持内联 SVG) | 图标名与 Web 端一致 |
| 图表 / 验证码 / 水印 | <canvas type="2d"> | 小程序 / App 端交互受限,建议 H5 使用 |
| 富文本编辑 | <editor> 组件 | 仅小程序 / App / H5 支持的基础能力 |
| 存储 / 导航 / 反馈兜底 | uni.* API | 组件内不出现 window / document |
| 安全区 | --rn-safe-area-* 变量 | 页面自行消费 env(safe-area-inset-*) |
表单值组件统一 v-model;日期 / 时间 / 滑块类组件优先封装 uni-app 原生能力(picker / slider)以保证各端手感。
示例工程与在线预览
pnpm --filter @ruanno-ui/uniapp-demo dev:h5 # H5 开发
pnpm --filter @ruanno-ui/uniapp-demo build:h5 # H5 构建
pnpm --filter @ruanno-ui/uniapp-demo dev:mp-weixin # 微信小程序
pnpm --filter @ruanno-ui/uniapp-demo dev:app # Appapps/uniapp-demo 按组件生成独立演示页(/pages/<组件>/index),文档站每个 uni-app 组件页的手机框预览即深链到对应页面,所见即所得。在线体验见 在线预览。