Aurora Mini UI 使用教程

Aurora Mini 是一個超輕量移動端展示型組件庫，專為移動端展示型應用設計。

📦 安裝

使用 npm 安裝

npm install aurora-mini-ui

使用 pnpm 安裝

pnpm add aurora-mini-ui

使用 yarn 安裝

yarn add aurora-mini-ui

🚀 快速開始

1. 引入樣式

在你的應用入口文件（如 src/main.tsx 或 src/index.tsx）中引入樣式：

import 'aurora-mini-ui/styles';

這會導入完整的 CSS 樣式文件（位於 dist/index.css）。

2. 使用組件

import { Button, Input, Toast } from 'aurora-mini-ui';

function App() {
  const handleClick = () => {
    Toast.show({ content: '點擊成功！', type: 'success' });
  };

  return (
    <div>
      <Button type="primary" onClick={handleClick}>
        點擊我
      </Button>
      <Input placeholder="請輸入內容" />
    </div>
  );
}

export default App;

🧩 組件使用示例

Button 按鈕

import { Button } from 'aurora-mini-ui';

function ButtonExample() {
  return (
    <div>
      <Button type="primary">主要按鈕</Button>
      <Button type="default">默認按鈕</Button>
      <Button type="danger">危險按鈕</Button>
      <Button disabled>禁用按鈕</Button>
      <Button block>塊級按鈕</Button>
      <Button size="small">小按鈕</Button>
      <Button size="large">大按鈕</Button>
    </div>
  );
}

Input 輸入框

import { Input } from 'aurora-mini-ui';

function InputExample() {
  return (
    <div>
      <Input placeholder="基本輸入框" />
      <Input placeholder="帶前綴" prefix="🔍" />
      <Input placeholder="帶後綴" suffix="元" />
      <Input placeholder="可清空" clearable />
      <Input placeholder="密碼輸入" type="password" />
      <Input placeholder="字數統計" maxLength={20} showCount />
    </div>
  );
}

Textarea 多行輸入

import { Textarea } from 'aurora-mini-ui';

function TextareaExample() {
  return (
    <div>
      <Textarea placeholder="請輸入內容" rows={4} />
      <Textarea 
        placeholder="帶字數限制" 
        maxLength={200} 
        showCount 
      />
    </div>
  );
}

Checkbox 復選框

import { Checkbox } from 'aurora-mini-ui';

function CheckboxExample() {
  return (
    <div>
      <Checkbox>單個復選框</Checkbox>
      <Checkbox checked>已選中</Checkbox>
      <Checkbox disabled>禁用狀態</Checkbox>
      
      <Checkbox.Group value={['1', '2']}>
        <Checkbox value="1">選項一</Checkbox>
        <Checkbox value="2">選項二</Checkbox>
        <Checkbox value="3">選項三</Checkbox>
      </Checkbox.Group>
    </div>
  );
}

Radio 單選框

import { Radio } from 'aurora-mini-ui';

function RadioExample() {
  return (
    <div>
      <Radio>單個單選框</Radio>
      <Radio checked>已選中</Radio>
      <Radio disabled>禁用狀態</Radio>
      
      <Radio.Group value="1">
        <Radio value="1">選項一</Radio>
        <Radio value="2">選項二</Radio>
        <Radio value="3">選項三</Radio>
      </Radio.Group>
    </div>
  );
}

Switch 開關

import { Switch } from 'aurora-mini-ui';

function SwitchExample() {
  const [checked, setChecked] = useState(false);
  
  return (
    <div>
      <Switch />
      <Switch checked />
      <Switch disabled />
      <Switch checked={checked} onChange={setChecked} />
    </div>
  );
}

Form 表單

import { Form, Input, Button } from 'aurora-mini-ui';

function FormExample() {
  const handleFinish = (values) => {
    console.log('表單數據:', values);
    Toast.show({ content: '提交成功！', type: 'success' });
  };

  const handleFinishFailed = (errors) => {
    const firstError = Object.values(errors)[0];
    Toast.show({ content: firstError, type: 'error' });
  };

  return (
    <Form 
      layout="horizontal"
      onFinish={handleFinish} 
      onFinishFailed={handleFinishFailed}
      initialValues={{ username: '', password: '' }}
    >
      <Form.Item 
        name="username" 
        label="用戶名"
        rules={[{ required: true, message: '請輸入用戶名' }]}
        required
      >
        <Input placeholder="請輸入用戶名" />
      </Form.Item>
      
      <Form.Item 
        name="password" 
        label="密碼"
        rules={[
          { required: true, message: '請輸入密碼' },
          { min: 6, message: '密碼至少6位' }
        ]}
        required
      >
        <Input placeholder="請輸入密碼" type="password" />
      </Form.Item>
      
      <Button type="primary" htmlType="submit" block>
        提交
      </Button>
    </Form>
  );
}

Toast 輕提示

import { Toast, Button } from 'aurora-mini-ui';

function ToastExample() {
  return (
    <div>
      <Button onClick={() => Toast.show('基本提示')}>
        基本提示
      </Button>
      <Button onClick={() => Toast.success('操作成功')}>
        成功提示
      </Button>
      <Button onClick={() => Toast.error('操作失敗')}>
        錯誤提示
      </Button>
      <Button onClick={() => Toast.loading('加載中...')}>
        加載提示
      </Button>
    </div>
  );
}

Dialog 對話框

import { Dialog, Button } from 'aurora-mini-ui';

function DialogExample() {
  const handleConfirm = () => {
    Dialog.show({
      title: '提示',
      content: '這是一個對話框',
      confirmText: '確定',
    });
  };

  const handleConfirmCancel = () => {
    Dialog.show({
      title: '確認操作',
      content: '確定要執行此操作嗎？',
      showCancel: true,
      confirmText: '確定',
      cancelText: '取消',
    });
  };

  return (
    <div>
      <Button onClick={handleConfirm}>基本對話框</Button>
      <Button onClick={handleConfirmCancel}>確認對話框</Button>
    </div>
  );
}

ActionSheet 底部菜單

import { ActionSheet, Button } from 'aurora-mini-ui';

function ActionSheetExample() {
  const handleShow = () => {
    ActionSheet.show({
      title: '選擇操作',
      items: [
        { name: '選項一' },
        { name: '選項二' },
        { name: '選項三', danger: true },
      ],
      cancelText: '取消',
      onSelect: (item, index) => {
        console.log('選擇:', item, index);
      },
    });
  };

  return <Button onClick={handleShow}>顯示底部菜單</Button>;
}

Card 卡片

import { Card } from 'aurora-mini-ui';

function CardExample() {
  return (
    <Card title="卡片標題">
      <p>這是卡片內容</p>
    </Card>
  );
}

Icon 圖標

import { Icon } from 'aurora-mini-ui';

function IconExample() {
  return (
    <div>
      <Icon name="check" size={24} />
      <Icon name="close" size={24} />
      <Icon name="plus" size={24} />
      <Icon name="search" size={24} />
    </div>
  );
}

Loading 加載

import { Loading } from 'aurora-mini-ui';

function LoadingExample() {
  return (
    <div>
      <Loading />
      <Loading size="small" />
      <Loading size="large" />
    </div>
  );
}

Empty 空狀態

import { Empty, Button } from 'aurora-mini-ui';

function EmptyExample() {
  return (
    <div>
      <Empty description="暫無數據" />
      <Empty 
        description="暫無數據"
        action={<Button>去添加</Button>}
      />
    </div>
  );
}

Divider 分割線

import { Divider } from 'aurora-mini-ui';

function DividerExample() {
  return (
    <div>
      <div>內容一</div>
      <Divider />
      <div>內容二</div>
      <Divider text="文字分割線" />
      <div>內容三</div>
    </div>
  );
}

Badge 徽標

import { Badge, Button } from 'aurora-mini-ui';

function BadgeExample() {
  return (
    <div>
      <Badge count={5}>
        <Button>按鈕</Button>
      </Badge>
      <Badge dot>
        <Button>按鈕</Button>
      </Badge>
    </div>
  );
}

Tag 標籤

import { Tag } from 'aurora-mini-ui';

function TagExample() {
  return (
    <div>
      <Tag>默認標籤</Tag>
      <Tag type="primary">主要標籤</Tag>
      <Tag type="success">成功標籤</Tag>
      <Tag type="warning">警告標籤</Tag>
      <Tag type="danger">危險標籤</Tag>
    </div>
  );
}

Grid 網格

import { Grid } from 'aurora-mini-ui';

function GridExample() {
  return (
    <Grid columns={3} gap={16}>
      <div>項目 1</div>
      <div>項目 2</div>
      <div>項目 3</div>
      <div>項目 4</div>
      <div>項目 5</div>
      <div>項目 6</div>
    </Grid>
  );
}

Cell 單元格

import { Cell } from 'aurora-mini-ui';

function CellExample() {
  return (
    <div>
      <Cell title="標題" content="內容" />
      <Cell title="標題" content="內容" extra="額外信息" />
      <Cell title="標題" content="內容" clickable />
    </div>
  );
}

Image 圖片

import { Image } from 'aurora-mini-ui';

function ImageExample() {
  return (
    <div>
      <Image 
        src="https://example.com/image.jpg" 
        alt="圖片"
        width={200}
        height={200}
      />
    </div>
  );
}

Mask 遮罩層

import { Mask, Button } from 'aurora-mini-ui';

function MaskExample() {
  const [visible, setVisible] = useState(false);
  
  return (
    <div>
      <Button onClick={() => setVisible(true)}>顯示遮罩層</Button>
      <Mask visible={visible} onClick={() => setVisible(false)} />
    </div>
  );
}

Picker 選擇器

import { Picker, Button } from 'aurora-mini-ui';

function PickerExample() {
  const handleShow = () => {
    Picker.show({
      columns: {
        values: [
          { label: '選項一', value: '1' },
          { label: '選項二', value: '2' },
          { label: '選項三', value: '3' },
        ],
      },
      title: '請選擇',
      onConfirm: (values) => {
        console.log('選中:', values);
      },
    });
  };

  return <Button onClick={handleShow}>顯示選擇器</Button>;
}

DatePicker 日期選擇器

import { DatePicker, Button } from 'aurora-mini-ui';

function DatePickerExample() {
  const handleShow = () => {
    DatePicker.show({
      type: 'date',
      title: '選擇日期',
      onConfirm: (date) => {
        console.log('選中日期:', date);
      },
    });
  };

  return <Button onClick={handleShow}>顯示日期選擇器</Button>;
}

🎨 主題配置

Aurora Mini UI 支持亮色、暗色和跟隨系統三種主題。

使用主題 Hook

import { useTheme } from 'aurora-mini-ui';

function ThemeExample() {
  const { theme, setTheme } = useTheme();
  
  return (
    <div>
      <Button onClick={() => setTheme('light')}>亮色主題</Button>
      <Button onClick={() => setTheme('dark')}>暗色主題</Button>
      <Button onClick={() => setTheme('auto')}>跟隨系統</Button>
      <p>當前主題: {theme}</p>
    </div>
  );
}

自定義 CSS 變量

你可以通過覆蓋 CSS 變量來自定義主題：

:root {
  --au-primary: #1890ff;
  --au-success: #52c41a;
  --au-warning: #faad14;
  --au-error: #ff4d4f;
  --au-text-primary: #333333;
  --au-text-secondary: #666666;
  --au-bg-primary: #ffffff;
  --au-bg-secondary: #f5f5f5;
}

📱 響應式設計

Aurora Mini UI 專為移動端設計，建議在移動設備上使用。如果你需要在桌面端使用，可以通過 CSS 限制最大寬度：

.app-container {
  max-width: 480px;
  margin: 0 auto;
  min-height: 100vh;
}

🔧 TypeScript 支持

Aurora Mini UI 完整支持 TypeScript，所有組件都有類型定義：

import { Button } from 'aurora-mini-ui';

const handleClick: React.MouseEventHandler<HTMLButtonElement> = () => {
  console.log('點擊');
};

return <Button onClick={handleClick}>點擊我</Button>;

📚 完整示例

import React, { useState } from 'react';
import { 
  Button, 
  Input, 
  Form, 
  Toast, 
  Dialog,
  ActionSheet 
} from 'aurora-mini-ui';
import 'aurora-mini-ui/styles';

function App() {
  const [formData, setFormData] = useState({ username: '', password: '' });

  const handleSubmit = (values) => {
    console.log('表單數據:', values);
    Toast.success('提交成功！');
  };

  const handleActionSheet = () => {
    ActionSheet.show({
      title: '選擇操作',
      items: [
        { name: '編輯' },
        { name: '刪除', danger: true },
      ],
      cancelText: '取消',
    });
  };

  return (
    <div className="app-container">
      <h1>Aurora Mini UI 示例</h1>
      
      <Form 
        onFinish={handleSubmit}
        initialValues={formData}
      >
        <Form.Item 
          name="username" 
          label="用戶名"
          rules={[{ required: true, message: '請輸入用戶名' }]}
          required
        >
          <Input placeholder="請輸入用戶名" />
        </Form.Item>
        
        <Form.Item 
          name="password" 
          label="密碼"
          rules={[
            { required: true, message: '請輸入密碼' },
            { min: 6, message: '密碼至少6位' }
          ]}
          required
        >
          <Input placeholder="請輸入密碼" type="password" />
        </Form.Item>
        
        <div style={{ display: 'flex', gap: '10px' }}>
          <Button type="primary" htmlType="submit" flex={1}>
            提交
          </Button>
          <Button onClick={handleActionSheet}>
            更多操作
          </Button>
        </div>
      </Form>
    </div>
  );
}

export default App;

🌟 最佳實踐

1. 引入樣式：確保在應用入口處引入 aurora-mini-ui/styles
2. 響應式設計：為移動端優化，建議限制最大寬度
3. 表單驗證：充分利用 Form 組件的驗證功能
4. 主題切換：使用 useTheme Hook 實現主題切換
5. 類型安全：充分利用 TypeScript 類型定義

📖 更多資源

• npm 包：https://www.npmjs.com/package/aurora-mini-ui
• GitHub：（如果有的話）
• 在線演示：（如果有的話）

🤝 貢獻

歡迎提交 Issue 和 Pull Request！

📄 許可證

MIT License

Aurora Mini UI - 超輕量移動端展示型組件庫

升級到最新版本

cd packages/core && npm version patch

cd packages/core && npm run build

cd packages/core && npm run build && npm publish --registry https://registry.npmjs.org/