跳到主要内容

API 约定 ​

ruanno-ui 的核心设计目标是「学会一个组件就等于学会所有组件」——无论 Web 端还是 uni-app 端,全部组件遵循同一套命名与行为约定。本页是完整约定清单,也是给 AI 编码助手的速查表(同 llms.txt 中的使用约束)。

组件命名 ​

  • 组件名即本名:Button、Input、DatePicker,不加库前缀;
  • Web 端与 uni-app 端同名组件一一对应(97/97);
  • 仅 CSS 类名带 rn- 前缀,BEM 风格:rn-button、rn-button--primary、rn-button__icon;
  • 事件为 kebab 语义命名:update:modelValue、change、click、close、confirm、cancel。

尺寸与变体 ​

prop取值默认说明
size'sm' | 'md' | 'lg''md'全库统一三档尺寸;控件高度对应 28 / 36 / 44px
variant各组件自定义语义集多为 'primary'如 Button:primary / secondary / ghost / danger;Tag:default / primary / success / warning / danger

移动端(H5 / uni-app)建议 md 或 lg,保证触摸目标 ≥ 36px。

状态 ​

prop类型默认说明
disabledbooleanfalse禁用,不触发任何交互事件
loadingbooleanfalse加载中:自动禁用交互并显示 spinner

双向绑定 ​

端值类组件布尔组件
Web(ruanno-ui)v-model(Input、Select、DatePicker…)v-model:checked(Switch、Checkbox)
uni-app(@ruanno-ui/uniapp)v-modelv-model(Switch、Checkbox 直接绑 boolean)

这是两端唯一需要特别注意的 API 差异。其余差异见下方 跨端差异表。

弹层类组件的显隐 ​

Dialog / Drawer / ActionSheet / Toast 等一律 v-model(boolean)控制显隐,@close 回调关闭后触发;遮罩可关闭的组件提供 maskClosable(默认 true)。

样式与 Tokens ​

  • 组件样式全部消费 --rn-* CSS 变量(来自 @ruanno-ui/tokens),不硬编码颜色 / 间距 / 圆角;
  • 业务侧覆盖变量即可定制,见 设计 Tokens 与 主题定制;
  • 主题通过 data-rn-theme 属性挂载:Web 端挂在 <html>,uni-app 端挂在页面根节点。

断点与响应式 ​

sm 640 / md 768 / lg 1024 / xl 1280。布局组件支持响应式 prop:

vue
<Stack :gap="{ base: 8, md: 16 }">...</Stack>

JS 侧用 useBreakpoint(),详见 响应式与断点。

跨端差异表 ​

维度Web(ruanno-ui)uni-app(@ruanno-ui/uniapp)
运行环境浏览器(桌面 + H5)uni-app H5 / 微信小程序 / App(含鸿蒙)
渲染层DOM + CSS 变量 + Pointer Events<view> / <text> / <image> / <canvas> 跨端标签
布尔绑定v-model:checked(Switch/Checkbox)v-model
图标内联 SVGbase64 <image>(小程序 / App 不支持内联 SVG)
滚动 / 定位 / 存储window / documentuni.* API
主题挂载<html data-rn-theme>页面根节点 :data-rn-theme
国际化useLocale() + <ConfigProvider locale>组件内置文案随包,暂无独立语言包体系
图表 / 富文本SVG 图表引擎 / contenteditable<canvas type="2d"> / <editor>

给 AI 编码助手 ​

  • 每个组件目录自带 meta.json 机器可读契约(props / events / slots / examples);
  • 文档站产物 llms.txt(索引)与 llms-full.txt(全量内联)可直接投喂;
  • 生成代码时优先使用上表约定;不确定某 prop 是否存在,先查对应组件的 meta.json 或文档页。