Adnaan UI

一个现代化的 React UI 组件库，具有精美的动画效果和主题支持。

English | 简体中文

✨ 特性

• 🎨 现代设计 - 诗意简约的设计风格
• 🌈 主题支持 - 深色/浅色模式切换
• 🎭 流畅动画 - 基于 Framer Motion 的精美动画
• 📦 开箱即用 - 完整的 TypeScript 类型支持
• 🔧 灵活定制 - 使用 Emotion 样式系统
• 🚀 零抖动 - 完美的滚动锁定方案
• ⚡️ 高性能 - 优化的渲染和动画性能

📦 安装

npm install adnaan-ui
# 或
yarn add adnaan-ui
# 或
pnpm add adnaan-ui

🚀 快速开始

1. 初始化组件库

import { initAdnaanUI } from "adnaan-ui";
import "adnaan-ui/styles";

// 在应用入口初始化
initAdnaanUI();

2. 使用组件

import { Button, Modal, Toast, Input } from "adnaan-ui";

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div>
      <Button onClick={() => setIsOpen(true)}>打开弹窗</Button>

      <Modal isOpen={isOpen} onClose={() => setIsOpen(false)} title="示例弹窗">
        <p>这是弹窗内容</p>
      </Modal>
    </div>
  );
}

3. 使用全局工具

import { adnaan } from "adnaan-ui/tools";

// Toast 提示
adnaan.toast.success("操作成功");
adnaan.toast.error("操作失败");

// Modal 弹窗
adnaan.modal.show({
  title: "提示",
  content: "这是一个弹窗",
});

// Confirm 确认框
adnaan.modal.confirm({
  title: "确认",
  message: "确定要删除吗？",
  onConfirm: () => console.log("已确认"),
});

// Alert 警告
adnaan.alert.info("提示信息");

📚 组件列表

基础组件

• Button - 按钮组件

  <Button variant="primary" size="medium">
    点击我
  </Button>

• Input - 输入框组件

  <Input
    placeholder="请输入内容"
    value={value}
    onChange={(e) => setValue(e.target.value)}
  />

• Textarea - 多行文本框

  <Textarea placeholder="请输入多行文本" rows={5} />

反馈组件

• Modal - 模态框

  <Modal
    isOpen={isOpen}
    onClose={() => setIsOpen(false)}
    title="标题"
    size="medium"
  >
    内容
  </Modal>

• Toast - 消息提示

  import { ToastProvider, ToastListener } from "adnaan-ui";
  
  <ToastProvider>
    <ToastListener />
    <App />
  </ToastProvider>;

• Alert - 警告提示

  <Alert type="success" closable>
    操作成功！
  </Alert>

• Confirm - 确认对话框

  <ConfirmDialog
    open={isOpen}
    title="确认"
    message="确定要执行此操作吗？"
    onConfirm={handleConfirm}
    onCancel={handleCancel}
  />

其他组件

• Badge - 徽章
• Tabs - 标签页
• Pagination - 分页器
• InfiniteScroll - 无限滚动
• Tooltip - 工具提示

🎨 设计令牌

import {
  designTokens,
  zIndex,
  duration,
  easing,
  motionEasing,
  radius,
  spacing,
  shadow,
} from "adnaan-ui/utils";

// Z-index 层级
zIndex.modal; // 1050
zIndex.toast; // 1080

// 动画时长
duration.fast; // 200ms
duration.normal; // 300ms

// 缓动函数
easing.ease; // CSS 字符串
motionEasing.spring; // Framer Motion 数组

// 圆角
radius.md; // 8px
radius.lg; // 12px

// 间距
spacing["4"]; // 1rem
spacing["8"]; // 2rem

🔧 工具函数

滚动锁定

import { scrollLock } from "adnaan-ui/utils";

// 锁定滚动（支持多次调用）
scrollLock.lock();

// 解锁滚动
scrollLock.unlock();

// 强制解锁所有
scrollLock.forceUnlock();

// 检查锁定状态
scrollLock.isLocked(); // boolean

🌟 核心优势

零抖动滚动锁定

Adnaan UI 采用业界领先的滚动锁定方案：

• ✅ position: fixed 方案 - 滚动条始终可见，零抖动
• ✅ 引用计数管理 - 完美支持多弹窗切换
• ✅ 延迟解锁机制 - 等待动画完成再解锁
• ✅ 滚动位置保持 - 打开/关闭弹窗后位置不变

// 原理
锁定时:
body {
  position: fixed;
  top: -scrollY;
  overflow-y: scroll; // 保持滚动条
  padding-right: scrollbarWidth; // 补偿宽度
}

解锁时:
恢复原始样式 + window.scrollTo(0, scrollY)

设计系统

• 统一的设计令牌系统
• 一致的动画和过渡效果
• 诗意简约的视觉风格
• 完善的响应式支持

开发体验

• 完整的 TypeScript 类型
• 简洁明了的 API
• 详细的代码注释
• 灵活的自定义能力

📖 更新日志

查看 CHANGELOG.md 了解详细更新记录。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT © Adnaan

🔗 相关链接

• GitHub
• npm
• 文档