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 | 类型 | 默认 | 说明 |
|---|---|---|---|
disabled | boolean | false | 禁用,不触发任何交互事件 |
loading | boolean | false | 加载中:自动禁用交互并显示 spinner |
双向绑定
| 端 | 值类组件 | 布尔组件 |
|---|---|---|
Web(ruanno-ui) | v-model(Input、Select、DatePicker…) | v-model:checked(Switch、Checkbox) |
uni-app(@ruanno-ui/uniapp) | v-model | v-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 |
| 图标 | 内联 SVG | base64 <image>(小程序 / App 不支持内联 SVG) |
| 滚动 / 定位 / 存储 | window / document | uni.* 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或文档页。