快速上手Getting started

四步：装包、引入样式、挂 Provider、写组件。库只依赖 react 和 react-dom（18 及以上）。

1. 安装

bash

npm install oink-ui

react 和 react-dom 是 peer 依赖，版本不低于 18。包里同时带 ESM、CJS 和类型声明，不需要另装 @types。

2. 引入样式

tsx

// 应用入口（main.tsx）里引入一次
import 'oink-ui/styles.css';

组件的 JS 不带样式，要在入口里自己引入。最省事的是整包：这一个文件里有全部设计令牌（--ok-*）和组件样式（.ok-*）；只想引用到的组件，见下面的“按需引入样式”。全局层面它只做两件事：给所有元素设 box-sizing: border-box，在 :root 上声明变量。页面的底色和字体需要自己接到令牌上：

css

body { margin: 0; background: var(--ok-bg); color: var(--ok-text); font: 450 15px/1.6 var(--ok-font); }

按需引入样式

组件不会自动带上样式，需要在入口文件里自己引入。下面两种方式选一种，不要混用。

tsx

// 方式一：整包——令牌、基础样式和全部组件（约 170 KB，gzip 后约 28 KB）
import 'oink-ui/styles.css';

tsx

// 方式二：按需——base 最先引、只引一次（令牌、基础样式、关键帧、主题切换，所有组件都依赖）
import 'oink-ui/styles/base.css';

// 再引用到的组件家族：先引被依赖的，再引自己
import 'oink-ui/styles/button.css';
import 'oink-ui/styles/floating-card.css';
import 'oink-ui/styles/dialog.css';

每个入口是 oink-ui/styles/<名字>.css，名字是组件家族名的短横线写法：button、slider、chip、group、dialog、select、calendar……

入口文件里不重复打包依赖，依赖由使用者自己引一次；建议按“base → 被依赖的 → 自己”的顺序引入。常见的依赖：

Dialog / Drawer / Sheet / confirm()：button、floating-card
Toaster / toast() / CodeBlock：button
Alert：button、group
Select：popup、menu
Combobox：popup、menu、input
DatePicker / Calendar：button、popup、popover、input
Table：checkbox、pagination
Card：image
Count / Progress / Reaction：roll

完整的对照表在包里 CONTRIBUTING.md 的“按需引入样式”一节；每个入口文件开头的注释也写着要先引入哪些入口。

3. 挂上 OinkProvider

Provider 负责主题、强调色和动效偏好，把结果写到 <html> 的 data-theme / data-accent / data-motion 上。

main.tsxtsx

import { createRoot } from 'react-dom/client';
import { Confirmer, OinkProvider, Toaster } from 'oink-ui';
import 'oink-ui/styles.css';
import { App } from './App';

createRoot(document.getElementById('root')!).render(
  <OinkProvider defaultTheme="system" defaultAccent="pink" storageKey="my-app-theme">
    <App />
    <Toaster />
    <Confirmer />
  </OinkProvider>,
);

defaultTheme：'light' | 'dark' | 'system'，默认 'system'（跟随系统）。
defaultAccent：五种预设强调色之一，或任意颜色（'#3fa7c4'），默认 'pink'。
defaultMotion：'auto' | 'full' | 'reduced'，默认 'auto'（跟随系统的“减弱动态效果”）。
storageKey：传了就把用户的选择记在 localStorage 的这个键下，刷新后恢复。
locale：'zh-CN' | 'en-US'，默认 'zh-CN'。切换组件自带的文案：关闭、确认之类的按钮、aria-label、占位文字、日历的月份名等。

不包 Provider 组件也能渲染（浅色加默认强调色），只是 useOink() 拿到的是只读的默认值，切换主题的方法不会生效。

4. 第一个示例

名字

几个贯穿全库的约定：onChange 的第一个参数是新值而不是事件；尺寸统一叫 size（sm / md / lg），变体叫 variant，状态色叫 tone；ref、className、style 和其余原生属性都透传到根节点。

Toaster 与 Confirmer

通知和确认框是命令式调用的：toast() 和 confirm() 只负责把请求放进队列，真正渲染的是这两个出口组件。

Toaster：在应用根部挂一个。没挂的时候 toast() 不会报错，通知先攒着，等 Toaster 出现再显示。位置、同时显示的条数、停留时间都在它的属性上配。
Confirmer：挂在 Provider 里面，确认框就能拿到你的 React 上下文（路由、国际化等）。没挂的话，第一次调用 confirm() 时库会自己在 body 下建一个独立的根来渲染，功能一样，只是拿不到上下文。
两者都只挂一份。挂多个 Confirmer 时只有一个负责渲染。