跳到主要内容

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)。

安装 ​

bash
npm install @ruanno-ui/uniapp
# 或
pnpm add @ruanno-ui/uniapp

引入样式 ​

在 App.vue 的根样式中引入一次:

vue
<style>
@import "@ruanno-ui/uniapp/styles";
</style>

该入口包含:--rn-* tokens 变量(挂载在 page 选择器)、5 套主题的 [data-rn-theme] 覆盖、组件公共样式。

注册组件 ​

方式一:按需导入(推荐) ​

vue
<script setup lang="ts">
import { Button, Cell, Icon } from "@ruanno-ui/uniapp";
</script>

<template>
  <view>
    <Button variant="primary">确定</Button>
    <Cell title="账号安全" arrow />
  </view>
</template>

方式二:全局注册 ​

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" && comp !== null && "render" in comp) {
      app.component(name, comp);
    }
  }
  return { app };
}

页面中使用 ​

vue
<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 属性生效:

vue
<!-- 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 别名,或按平台条件编译:
ts
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)以保证各端手感。

示例工程与在线预览 ​

bash
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        # App

apps/uniapp-demo 按组件生成独立演示页(/pages/<组件>/index),文档站每个 uni-app 组件页的手机框预览即深链到对应页面,所见即所得。在线体验见 在线预览。