📋 目錄

• 簡介
• 核心特性
• 快速開始
• 安裝指南
• 基礎使用
• 主題系統
• 高級功能
• API 參考
• 最佳實踐
• 性能優化
• 故障排除
• 總結

---

🚀 簡介

YggJS RButton 是一個專門為 React 應用程序設計的高性能按鈕組件庫。它提供了兩套完整的設計主題：科技風主題和極簡主題，滿足不同項目的設計需求。

設計理念

• 🎨 雙主題設計：科技風主題展現現代感和科技感，極簡主題追求純凈簡潔的美學
• ? 高性能：基于 CSS-in-JS 的動態樣式系統，支持主題熱切換
• 🔧 TypeScript 原生支持：完整的類型定義，提供最佳的開發體驗
• ? 可訪問性優先：遵循 WCAG 2.1 標準，支持鍵盤導航和屏幕閱讀器
• 📱 響應式設計：完美適配各種屏幕尺寸和設備類型

---

? 核心特性

🎯 多主題支持

• 科技風主題：藍色基調、霓虹發光效果、科技感邊框
• 極簡主題：灰度色彩、微妙陰影、優雅過渡動畫

🎨 豐富的樣式配置

• 5種顏色變體：primary、secondary、success、danger、warning
• 3種尺寸規格：small、medium、large
• 4種填充模式：solid、outline、ghost、link
• 4種形狀樣式：default、rounded、circle、square

? 狀態管理

• 交互狀態：normal、hover、active、focus、disabled
• 加載狀態：支持異步操作的加載指示器
• 自定義狀態：可擴展的狀態系統

🔧 開發者體驗

• TypeScript 支持：完整的類型定義和 IntelliSense
• Tree Shaking：按需導入，減小打包體積
• 熱模塊替換：開發時支持樣式熱更新

---

🏁 快速開始

30秒快速體驗

import React from 'react';
import { TechButton } from 'yggjs_rbutton';function App() {return (<div><TechButton variant="primary" size="medium">點擊我</TechButton></div>);
}export default App;

---

📦 安裝指南

NPM 安裝

npm install yggjs_rbutton

Yarn 安裝

yarn add yggjs_rbutton

依賴要求

{"peerDependencies": {"react": "^19.1.1"}
}

TypeScript 配置

如果您使用 TypeScript，請確保在 tsconfig.json 中包含以下配置：

{"compilerOptions": {"jsx": "react-jsx","moduleResolution": "node","allowSyntheticDefaultImports": true,"esModuleInterop": true}
}

---

🎯 基礎使用

導入方式

完整導入

import { TechButton, MinimalButton } from 'yggjs_rbutton';

按需導入（推薦）

// 導入科技風主題
import { TechButton } from 'yggjs_rbutton/tech';// 導入極簡主題
import { MinimalButton } from 'yggjs_rbutton/minimal';

基礎示例

科技風按鈕

import React from 'react';
import { TechButton } from 'yggjs_rbutton/tech';export default function BasicExample() {return (<div style={{ display: 'flex', gap: '16px', padding: '20px' }}>{/* 基礎按鈕 */}<TechButton>默認按鈕</TechButton>{/* 不同變體 */}<TechButton variant="primary">主要按鈕</TechButton><TechButton variant="secondary">次要按鈕</TechButton><TechButton variant="success">成功按鈕</TechButton><TechButton variant="danger">危險按鈕</TechButton>{/* 不同尺寸 */}<TechButton size="small">小按鈕</TechButton><TechButton size="medium">中等按鈕</TechButton><TechButton size="large">大按鈕</TechButton></div>);
}

極簡主題按鈕

import React from 'react';
import { MinimalButton } from 'yggjs_rbutton/minimal';export default function MinimalExample() {return (<div style={{ display: 'flex', gap: '16px', padding: '20px' }}>{/* 極簡風格按鈕 */}<MinimalButton variant="primary">極簡主要</MinimalButton><MinimalButton variant="outline">輪廓按鈕</MinimalButton><MinimalButton variant="ghost">幽靈按鈕</MinimalButton></div>);
}

事件處理

import React, { useState } from 'react';
import { TechButton } from 'yggjs_rbutton/tech';export default function InteractiveExample() {const [loading, setLoading] = useState(false);const [count, setCount] = useState(0);const handleAsyncClick = async () => {setLoading(true);try {// 模擬異步操作await new Promise(resolve => setTimeout(resolve, 2000));setCount(prev => prev + 1);} finally {setLoading(false);}};return (<div style={{ padding: '20px' }}><TechButtonvariant="primary"loading={loading}disabled={loading}onClick={handleAsyncClick}>{loading ? '處理中...' : `點擊次數: ${count}`}</TechButton></div>);
}

---

🎨 主題系統

主題對比

特性	科技風主題	極簡主題
色彩基調	藍色科技感	灰度純凈感
視覺效果	霓虹發光、漸變	微妙陰影、簡潔
動畫風格	動感、科技感	溫和、優雅
使用場景	科技產品、游戲、創新應用	商務應用、內容平臺、工具軟件

科技風主題特性

import React from 'react';
import { TechButton } from 'yggjs_rbutton/tech';export default function TechThemeDemo() {return (<div style={{ padding: '20px', backgroundColor: '#0a0a0a' }}>{/* 霓虹發光效果 */}<TechButton variant="primary" glow>霓虹發光按鈕</TechButton>{/* 漸變背景 */}<TechButton variant="primary" gradient>漸變背景按鈕</TechButton>{/* 全寬按鈕 */}<TechButton variant="primary" fullWidth>全寬度按鈕</TechButton>{/* 自定義顏色 */}<TechButton variant="primary" customColors={{primary: '#ff6b35',primaryHover: '#ff8c42'}}>自定義顏色</TechButton></div>);
}

極簡主題特性

import React from 'react';
import { MinimalButton } from 'yggjs_rbutton/minimal';export default function MinimalThemeDemo() {return (<div style={{ padding: '20px', backgroundColor: '#fafafa' }}>{/* 純凈模式 */}<MinimalButton variant="primary"minimalConfig={{ pureMode: true }}>純凈模式</MinimalButton>{/* 內容優先 */}<MinimalButton variant="outline"minimalConfig={{ contentFirst: true }}>內容優先</MinimalButton>{/* 呼吸空間優化 */}<MinimalButton variant="ghost"minimalConfig={{ breathingSpace: true }}>呼吸空間優化</MinimalButton></div>);
}

深色模式支持

import React, { useState } from 'react';
import { TechButton } from 'yggjs_rbutton/tech';export default function DarkModeExample() {const [darkMode, setDarkMode] = useState(false);return (<div style={{ padding: '20px',backgroundColor: darkMode ? '#1a1a1a' : '#ffffff',color: darkMode ? '#ffffff' : '#000000',minHeight: '200px',transition: 'all 0.3s ease'}}><TechButton variant="secondary" onClick={() => setDarkMode(!darkMode)}>切換 {darkMode ? '淺色' : '深色'} 模式</TechButton><div style={{ marginTop: '20px', display: 'flex', gap: '12px' }}><TechButton variant="primary">主要按鈕</TechButton><TechButton variant="secondary">次要按鈕</TechButton><TechButton variant="success">成功按鈕</TechButton></div></div>);
}

---

🔥 高級功能

自定義樣式

import React from 'react';
import { TechButton } from 'yggjs_rbutton/tech';export default function CustomStylesExample() {return (<div style={{ padding: '20px' }}>{/* 自定義CSS樣式 */}<TechButton variant="primary"style={{background: 'linear-gradient(45deg, #ff6b35, #f7931e)',border: 'none',boxShadow: '0 4px 15px rgba(255, 107, 53, 0.3)'}}>自定義漸變</TechButton>{/* 使用className */}<TechButton variant="secondary"className="my-custom-button">自定義類名</TechButton></div>);
}

異步操作處理

import React, { useState } from 'react';
import { TechButton } from 'yggjs_rbutton/tech';export default function AsyncOperationsExample() {const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');const handleSubmit = async () => {setStatus('loading');try {// 模擬API調用const response = await fetch('/api/submit', {method: 'POST',headers: { 'Content-Type': 'application/json' },body: JSON.stringify({ data: 'example' })});if (response.ok) {setStatus('success');setTimeout(() => setStatus('idle'), 2000);} else {throw new Error('提交失敗');}} catch (error) {setStatus('error');setTimeout(() => setStatus('idle'), 2000);}};const getButtonProps = () => {switch (status) {case 'loading':return {loading: true,disabled: true,children: '提交中...'};case 'success':return {variant: 'success' as const,children: '? 提交成功'};case 'error':return {variant: 'danger' as const,children: '? 提交失敗'};default:return {variant: 'primary' as const,children: '提交數據'};}};return (<div style={{ padding: '20px' }}><TechButton {...getButtonProps()}onClick={handleSubmit}disabled={status !== 'idle'}/></div>);
}

表單集成

import React, { useState } from 'react';
import { TechButton, MinimalButton } from 'yggjs_rbutton';export default function FormIntegrationExample() {const [formData, setFormData] = useState({name: '',email: ''});const [errors, setErrors] = useState<Record<string, string>>({});const validateForm = () => {const newErrors: Record<string, string> = {};if (!formData.name.trim()) {newErrors.name = '姓名不能為空';}if (!formData.email.trim()) {newErrors.email = '郵箱不能為空';} else if (!/\S+@\S+\.\S+/.test(formData.email)) {newErrors.email = '郵箱格式不正確';}setErrors(newErrors);return Object.keys(newErrors).length === 0;};const handleSubmit = (e: React.FormEvent) => {e.preventDefault();if (validateForm()) {console.log('表單提交:', formData);// 處理表單提交}};const handleReset = () => {setFormData({ name: '', email: '' });setErrors({});};const isFormValid = formData.name.trim() && formData.email.trim();return (<form onSubmit={handleSubmit} style={{ padding: '20px', maxWidth: '400px' }}><div style={{ marginBottom: '16px' }}><label>姓名:</label><inputtype="text"value={formData.name}onChange={(e) => setFormData(prev => ({ ...prev, name: e.target.value }))}style={{width: '100%',padding: '8px',marginTop: '4px',border: errors.name ? '1px solid red' : '1px solid #ccc'}}/>{errors.name && <div style={{ color: 'red', fontSize: '12px' }}>{errors.name}</div>}</div><div style={{ marginBottom: '20px' }}><label>郵箱:</label><inputtype="email"value={formData.email}onChange={(e) => setFormData(prev => ({ ...prev, email: e.target.value }))}style={{width: '100%',padding: '8px',marginTop: '4px',border: errors.email ? '1px solid red' : '1px solid #ccc'}}/>{errors.email && <div style={{ color: 'red', fontSize: '12px' }}>{errors.email}</div>}</div><div style={{ display: 'flex', gap: '12px' }}><TechButton type="submit"variant="primary"disabled={!isFormValid}>提交</TechButton><MinimalButton type="button"variant="outline"onClick={handleReset}>重置</MinimalButton></div></form>);
}

---

📚 API 參考

TechButton API

Props

interface TechButtonProps {// 基礎屬性children?: React.ReactNode;variant?: 'primary' | 'secondary' | 'success' | 'danger' | 'warning';size?: 'small' | 'medium' | 'large';fill?: 'solid' | 'outline' | 'ghost' | 'link';shape?: 'default' | 'rounded' | 'circle' | 'square';// 狀態屬性disabled?: boolean;loading?: boolean;active?: boolean;// 樣式屬性fullWidth?: boolean;glow?: boolean;gradient?: boolean;customColors?: {primary?: string;primaryHover?: string;primaryActive?: string;};// 事件處理onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;onFocus?: (event: React.FocusEvent<HTMLButtonElement>) => void;onBlur?: (event: React.FocusEvent<HTMLButtonElement>) => void;// HTML 屬性type?: 'button' | 'submit' | 'reset';form?: string;name?: string;value?: string;tabIndex?: number;// 自定義屬性className?: string;style?: React.CSSProperties;id?: string;'data-testid'?: string;'aria-label'?: string;'aria-describedby'?: string;
}

MinimalButton API

interface MinimalButtonProps {// 基礎屬性children?: React.ReactNode;variant?: 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'outline' | 'ghost';size?: 'small' | 'medium' | 'large';// 狀態屬性disabled?: boolean;loading?: boolean;active?: boolean;// 極簡主題特殊配置minimalConfig?: {pureMode?: boolean;        // 純凈模式contentFirst?: boolean;    // 內容優先breathingSpace?: boolean;  // 呼吸空間優化};// 主題配置colorMode?: 'light' | 'dark' | 'auto';density?: 'compact' | 'comfortable' | 'spacious';borderStyle?: 'none' | 'subtle' | 'visible';shadowIntensity?: 'none' | 'subtle' | 'visible';textStyle?: 'light' | 'normal' | 'medium';// 其他屬性與 TechButton 相同...
}

工具函數

// 主題工具
import { createTheme, mergeThemes } from 'yggjs_rbutton/utils';// 創建自定義主題
const customTheme = createTheme({colors: {primary: '#ff6b35',secondary: '#4ecdc4'},animations: {duration: {fast: '100ms',normal: '200ms'}}
});// 合并主題
const mergedTheme = mergeThemes(baseTheme, customTheme);

---

💡 最佳實踐

1. 性能優化

import React, { memo, useMemo, useCallback } from 'react';
import { TechButton } from 'yggjs_rbutton/tech';// 使用 memo 優化重渲染
const OptimizedButton = memo(({ onClick, children, ...props }) => {// 使用 useCallback 緩存事件處理器const handleClick = useCallback((e) => {onClick?.(e);}, [onClick]);// 使用 useMemo 緩存復雜計算const buttonStyle = useMemo(() => ({margin: '4px',transition: 'all 0.2s ease'}), []);return (<TechButton{...props}onClick={handleClick}style={buttonStyle}>{children}</TechButton>);
});

2. 可訪問性優化

import React from 'react';
import { TechButton } from 'yggjs_rbutton/tech';export default function AccessibleButtons() {return (<div>{/* 使用語義化標簽和ARIA屬性 */}<TechButtonvariant="primary"aria-label="保存用戶數據"aria-describedby="save-help-text"role="button">保存</TechButton><div id="save-help-text">點擊保存當前用戶信息</div>{/* 鍵盤導航支持 */}<TechButtonvariant="secondary"onKeyDown={(e) => {if (e.key === 'Enter' || e.key === ' ') {e.preventDefault();// 處理鍵盤激活}}}>鍵盤友好按鈕</TechButton>{/* 狀態通知 */}<TechButtonvariant="success"aria-live="polite"aria-atomic="true">操作成功</TechButton></div>);
}

3. 主題一致性

import React, { createContext, useContext } from 'react';
import { TechButton, MinimalButton } from 'yggjs_rbutton';// 創建主題上下文
const ThemeContext = createContext<{theme: 'tech' | 'minimal';toggleTheme: () => void;
}>({theme: 'tech',toggleTheme: () => {}
});// 統一按鈕組件
const UnifiedButton: React.FC<any> = (props) => {const { theme } = useContext(ThemeContext);return theme === 'tech' ? <TechButton {...props} />: <MinimalButton {...props} />;
};// 使用示例
export default function ThemedApp() {const [theme, setTheme] = useState<'tech' | 'minimal'>('tech');return (<ThemeContext.Provider value={{theme,toggleTheme: () => setTheme(prev => prev === 'tech' ? 'minimal' : 'tech')}}><div><UnifiedButton variant="primary">統一主題按鈕</UnifiedButton><UnifiedButton variant="secondary" onClick={() => toggleTheme()}>切換主題</UnifiedButton></div></ThemeContext.Provider>);
}

4. 類型安全

import React from 'react';
import { TechButton } from 'yggjs_rbutton/tech';
import type { TechButtonProps } from 'yggjs_rbutton/tech/types';// 定義強類型的按鈕配置
interface ButtonConfig {variant: TechButtonProps['variant'];size: TechButtonProps['size'];label: string;action: () => void;
}const buttonConfigs: ButtonConfig[] = [{variant: 'primary',size: 'medium',label: '主要操作',action: () => console.log('主要操作')},{variant: 'secondary',size: 'small',label: '次要操作',action: () => console.log('次要操作')}
];export default function TypeSafeButtons() {return (<div>{buttonConfigs.map((config, index) => (<TechButtonkey={index}variant={config.variant}size={config.size}onClick={config.action}>{config.label}</TechButton>))}</div>);
}

---

? 性能優化

Bundle 大小優化

// ? 避免完整導入
import { TechButton, MinimalButton } from 'yggjs_rbutton';// ? 推薦按需導入
import { TechButton } from 'yggjs_rbutton/tech';
import { MinimalButton } from 'yggjs_rbutton/minimal';

樣式緩存

import React, { useMemo } from 'react';
import { TechButton } from 'yggjs_rbutton/tech';export default function OptimizedButtonList({ items }) {// 緩存樣式計算const buttonStyles = useMemo(() => ({container: {display: 'grid',gridTemplateColumns: 'repeat(auto-fit, minmax(120px, 1fr))',gap: '8px',padding: '16px'}}), []);return (<div style={buttonStyles.container}>{items.map((item, index) => (<TechButtonkey={item.id || index}variant={item.variant}size="medium"onClick={item.onClick}>{item.label}</TechButton>))}</div>);
}

虛擬化長列表

import React, { memo } from 'react';
import { FixedSizeList as List } from 'react-window';
import { TechButton } from 'yggjs_rbutton/tech';const ButtonItem = memo(({ index, style, data }) => (<div style={style}><TechButtonvariant="primary"size="small"onClick={() => data.onItemClick(index)}>按鈕 {index + 1}</TechButton></div>
));export default function VirtualizedButtonList({ itemCount }) {const handleItemClick = (index) => {console.log(`點擊了按鈕 ${index + 1}`);};return (<Listheight={400}itemCount={itemCount}itemSize={40}itemData={{ onItemClick: handleItemClick }}>{ButtonItem}</List>);
}

---

🐛 故障排除

常見問題

1. 樣式不生效

問題: 按鈕樣式沒有正確應用

解決方案:

// 確保正確導入CSS（如果需要）
import 'yggjs_rbutton/dist/styles.css';// 或者使用CSS-in-JS方案（推薦）
import { TechButton } from 'yggjs_rbutton/tech';

2. TypeScript 類型錯誤

問題: TypeScript 報告類型錯誤

解決方案:

// 確保安裝了類型定義
npm install @types/react// 在組件中正確使用類型
import type { TechButtonProps } from 'yggjs_rbutton/tech/types';const MyButton: React.FC<TechButtonProps> = (props) => {return <TechButton {...props} />;
};

3. 主題切換不生效

問題: 主題切換沒有視覺變化

解決方案:

// 確保主題提供器正確包裝組件
import { ThemeProvider } from 'yggjs_rbutton';function App() {return (<ThemeProvider theme="tech"><YourComponent /></ThemeProvider>);
}

4. 性能問題

問題: 大量按鈕渲染導致性能下降

解決方案:

import React, { memo } from 'react';
import { TechButton } from 'yggjs_rbutton/tech';// 使用 React.memo 優化
const OptimizedButton = memo(TechButton);// 或者使用虛擬化
import { FixedSizeList } from 'react-window';

調試技巧

開啟開發模式

// 在開發環境中啟用詳細日志
import { setDebugMode } from 'yggjs_rbutton/utils';if (process.env.NODE_ENV === 'development') {setDebugMode(true);
}

樣式調試

import { TechButton } from 'yggjs_rbutton/tech';// 使用 data-testid 便于調試和測試
<TechButton data-testid="submit-button" variant="primary">提交
</TechButton>

---

🎓 總結

YggJS RButton 是一個功能強大、設計精美的 React 按鈕組件庫，它為現代 Web 應用提供了完整的按鈕解決方案。

🎯 核心價值

1. 雙主題設計：科技風和極簡風兩套完整主題，滿足不同項目需求
2. TypeScript 原生支持：完整的類型定義，提供卓越的開發體驗
3. 高性能架構：基于 CSS-in-JS 的動態樣式系統，支持主題熱切換
4. 可訪問性優先：遵循 WCAG 標準，確保所有用戶都能正常使用
5. 企業級品質：經過嚴格測試，適用于生產環境

🚀 適用場景

• 科技產品：使用科技風主題展現創新和現代感
• 商務應用：使用極簡主題保持專業和簡潔
• 企業級應用：利用完整的類型支持和高性能架構
• 設計系統：作為設計系統的基礎組件進行擴展

📈 發展路線

未來版本計劃：

• 更多主題變體和自定義選項
• 動畫效果增強和微交互優化
• 更好的性能優化和 Bundle 大小控制
• 更豐富的無障礙訪問功能

🤝 社區支持

• 問題反饋：GitHub Issues
• 功能建議：GitHub Discussions
• 貢獻代碼：貢獻指南

---

感謝使用 YggJS RButton！

如果這個組件庫對您有幫助，請考慮給我們一個 ? Star！

📖 更多文檔 |
🐛 問題反饋 |
💡 功能建議

---

📝 文檔版本: v1.0.0
📅 更新日期: 2025年8月26日
👨?💻 作者: 源滾滾AI編程團隊