Vant

繁體中文

简体中文
English
日本語

繁體中文

简体中文
English
日本語

Appearance

貢獻指南 ​

介紹 ​

🎉 歡迎來到 Vant 大家庭！感謝你選擇 Vant 作為你的開發夥伴。

Vant 就像一個充滿活力的開源社群花園，每一位開發者都是這個花園的園丁。無論你是想要回報一個小蟲子🐛，還是想要貢獻一朵美麗的程式碼之花🌸，我們都熱烈歡迎！

在你準備向 Vant 提交 issue 或者 PR 之前，請先花幾分鐘時間閱讀這份貢獻指南。就像園丁需要了解花園的規則一樣，這些指南將幫助你更好地參與到 Vant 的建設中來。讓我們一起讓這個開源花園更加繁榮美麗！🌺

Issue 規範 - 問題回饋的藝術 🎨 ​

發現問題就像發現花園裡的小蟲害，及時回饋能讓我們的花園更加健康！

  • 🔍 先做個小偵探：遇到問題時，請先在 issue 清單中搜尋一下，看看這個問題是否已經有其他園丁發現並記錄了，或者已經被我們的園藝師修復了。
  • 📝 寫一份清晰的問題報告：提 issue 時，請用簡潔明瞭的語言描述遇到的問題。就像給醫生看病一樣，詳細描述症狀、發生環境和重現步驟，這樣我們就能快速定位問題並對症下藥！

參與開發 - 成為程式碼園丁 👨‍💻 ​

本地開發 - 搭建你的專屬工作台 🛠️ ​

想要在 Vant 花園裡種植程式碼之花嗎？首先我們需要準備好園藝工具！

在開始你的園藝之旅前，請確保你的工具箱裡有 Node.js >= 18 這把萬能鏟子。

準備好了嗎？讓我們一步步搭建你的專屬開發工作台：

bash
# 複製倉庫
git clone git@github.com:vant-ui/vant.git

# 啟用 pnpm 套件管理器
corepack enable

# 安裝相依性
pnpm i

# 進入開發模式，瀏覽器訪問 localhost
pnpm dev

🌳 選擇你的開發分支 - 就像選擇合適的花圃一樣重要：

  • main 分支 🌟 - Vant 4 版本的主花園，專為 Vue 3 打造的現代化花圃
  • 3.x 分支 🌿 - Vant 3 版本的經典花園，同樣適用於 Vue 3 的穩定花圃
  • 2.x 分支 🌱 - Vant 2 版本的傳統花園，為 Vue 2 量身定制的經典花圃

目錄結構 - 探索花園的佈局 🗺️ ​

Vant 就像一個精心規劃的植物園，採用 monorepo 的方式進行管理。所有的花圃都整齊地排列在 packages 目錄這個大花園裡：

root
└─ packages
   ├─ vant        # 元件庫
   ├─ vant-cli    # 腳手架
   ├─ vant-icons  # 圖示庫
   ├─ vant-use    # Composition API
   └─ ....        # 其他周邊 npm 套件

其中，packages/vant 目錄就是我們花園的心臟 💖，這裡存放著元件庫的核心程式碼：

vant
├─ docs             # 文件
├─ src              # 元件原始碼
├─ test             # 單測工具類
└─ vant.config.mjs  # 文件網站設定

而 packages/vant/src 目錄就像是元件們的溫室大棚 🏠，每個資料夾都是一個獨立的小花圃，精心培育著一個元件：

src
└─ button
   ├─ demo             # 範例程式碼
   ├─ test             # 單元測試
   ├─ Component.tsx    # 元件
   ├─ index.ts         # 元件入口
   ├─ index.less       # 樣式
   ├─ README.md        # 英文文件
   └─ README.zh-CN.md  # 中文文件

程式碼規範 - 讓程式碼像詩一樣優雅 ✨ ​

寫程式碼就像寫詩一樣，需要遵循一定的韻律和格式。讓我們一起讓程式碼變得更加優雅：

  • 🔍 ESLint 是你的好朋友：確保程式碼可以通過倉庫的 ESLint 校驗，就像詩歌需要押韻一樣，程式碼也需要符合規範。
  • 🎨 Prettier 讓程式碼更美麗：使用 prettier 進行程式碼格式化，讓你的程式碼像精心排版的詩集一樣整潔美觀。
  • ⚡ 相容性是關鍵：確保沒有使用超出相容性範圍的 API（比如 async, await），讓你的程式碼能在各種環境中優雅地執行。

提交 Pull Request - 分享你的程式碼之花 🌸 ​

參考指南 - 新手園丁的入門寶典 📚 ​

第一次在開源花園裡種花嗎？別擔心，每個園藝大師都有第一次！這裡有兩本貼心的入門指南：

Pull Request 規範 - 精心包裝你的禮物 🎁 ​

提交 Pull Request 就像給朋友送禮物，需要精心包裝才能讓人感受到你的用心：

  • 🎯 專注而精準：保持你的 PR 足夠小巧精緻，一個 PR 只解決一個問題或新增一個功能，就像一份禮物只表達一個心意。
  • 🛡️ 品質保證很重要：新增或修改元件時，別忘了為它們編寫單元測試，就像給禮物加上保護包裝一樣，確保程式碼的穩定性。
  • 📝 貼心的說明卡片：在 PR 中新增詳細的描述，並關聯相關的 Issue，讓審核者能快速理解你的貢獻。

Pull Request 流程 - 你的貢獻之旅 🚀 ​

讓我們一步步走過這個充滿成就感的貢獻之旅：

1. 🍴 Fork 專案

bash
# 在 GitHub 上點擊 Fork 按鈕，將專案複製到你的帳戶下
# 然後複製你的 fork 到本地
git clone https://github.com/your-username/vant.git

2. 🌿 建立功能分支

bash
# 基於 main 分支建立新分支
git checkout -b feature/your-feature-name

# 或者基於其他分支（如修復 3.x 版本的 bug）
git checkout -b fix/your-fix-name 3.x

3. 💻 開發你的功能

bash
# 進行你的程式碼修改
# 記住要遵循我們的程式碼規範哦！

# 執行測試確保一切正常
pnpm test

# 檢查程式碼風格
pnpm lint

4. 📝 提交你的更改

bash
# 新增修改的檔案
git add .

# 提交時使用清晰的提交資訊
git commit -m "feat(Button): 新增載入狀態支援"

5. 🚀 推送並建立 PR

bash
# 推送到你的 fork
git push origin feature/your-feature-name

# 然後在 GitHub 上建立 Pull Request

Pull Request 標題格式 - 給你的作品起個好名字 📝 ​

一個好的標題就像花朵的名牌，能讓人一眼就知道這朵花的特色：

類型(元件名): 描述

範例：
feat(Button): 新增 loading 狀態
fix(Dialog): 修復 iOS 捲動穿透問題  
docs(README): 更新安裝文件
style(Button): 最佳化按鈕樣式

🏷️ 類型說明

  • feat: 新功能（一朵新花綻放）
  • fix: Bug 修復（治癒花朵的病蟲害）
  • docs: 文件更新（為花朵寫說明牌）
  • style: 樣式調整（給花朵美容）
  • refactor: 程式碼重構（重新整理花圃）
  • test: 測試相關（檢查花朵的健康）
  • chore: 建置/工具相關（維護花園工具）

同步最新程式碼 - 保持花園藍圖最新 🔄 ​

在提交你的傑作之前，記得先更新一下花園藍圖，確保你的創作是基於最新的設計！請按照下面的步驟同步主倉庫的最新程式碼：

bash
# 新增主倉庫到 remote
git remote add upstream git@github.com:vant-ui/vant.git

# 拉取主倉庫最新程式碼
git fetch upstream

# 切換至 main 分支
git checkout main

# 合併主倉庫程式碼
git merge upstream/main

最佳實踐 - 成為優秀園丁的秘訣 🌟 ​

程式碼貢獻技巧 ​

🎯 專注單一功能

javascript
// ✅ 好的做法：專注於單一功能
// 為 Button 元件新增 loading 狀態
const Button = ({ loading, children, ...props }) => {
  return (
    <button disabled={loading} {...props}>
      {loading ? <Loading /> : children}
    </button>
  );
};

// ❌ 避免：在一個 PR 中修改多個不相關的功能

📝 編寫清晰的提交資訊

bash
# ✅ 好的提交資訊
feat(Button): add loading state support
fix(Dialog): resolve overlay z-index issue
docs: update Button component examples

# ❌ 模糊的提交資訊
update button
fix bug
change style

測試編寫指南 ​

🧪 為新功能編寫測試

javascript
// 為新功能編寫完整的測試用例
describe('Button Loading State', () => {
  test('should show loading icon when loading is true', () => {
    const { container } = render(<Button loading>Submit</Button>);
    expect(container.querySelector('.van-loading')).toBeTruthy();
  });

  test('should disable button when loading', () => {
    const { container } = render(<Button loading>Submit</Button>);
    expect(container.querySelector('button')).toBeDisabled();
  });
});

常見問題解決 🔧 ​

開發環境問題 ​

❓ 本地開發服務啟動失敗

bash
# 清理相依性並重新安裝
rm -rf node_modules package-lock.json
npm install

# 或者使用 pnpm
rm -rf node_modules pnpm-lock.yaml
pnpm install

❓ ESLint 檢查不通過

bash
# 自動修復可修復的問題
npm run lint:fix

# 手動檢查剩餘問題
npm run lint

❓ 單元測試失敗

bash
# 執行特定測試檔案
npm test -- Button

# 更新快照測試
npm test -- --updateSnapshot

Git 操作問題 ​

❓ 分支同步衝突

bash
# 使用 rebase 保持提交歷史整潔
git fetch upstream
git rebase upstream/main

# 解決衝突後繼續
git add .
git rebase --continue

❓ 提交歷史混亂

bash
# 使用 interactive rebase 整理提交
git rebase -i HEAD~3

# 合併多個提交為一個
# 在編輯器中將 pick 改為 squash

貢獻者成長路徑 🚀 ​

新手園丁 🌱 ​

  • 從修復文件錯誤開始
  • 提交簡單的 bug 修復
  • 參與 issue 討論

進階園丁 🌿 ​

  • 新增新的元件功能
  • 最佳化現有元件效能
  • 編寫詳細的測試用例

資深園丁 🌳 ​

  • 設計新的元件架構
  • 參與技術方案討論
  • 指導新貢獻者

園藝大師 🏆 ​

  • 主導重大功能開發
  • 制定程式碼規範
  • 維護專案生態

社群互動指南 💬 ​

參與討論的藝術 ​

🗣️ 在 Issue 中提供幫助

  • 重現並確認問題
  • 提供解決方案建議
  • 分享相關經驗

💡 提出建設性建議

  • 詳細描述使用場景
  • 提供設計方案
  • 考慮向後相容性

🤝 協作開發

  • 及時回應 Review 意見
  • 主動尋求幫助
  • 分享開發心得

設計靈感 🎨 ​

元件設計原則 ​

🎯 使用者體驗優先

  • 直觀的 API 設計
  • 一致的互動體驗
  • 完善的錯誤處理

🔧 開發者友善

  • 清晰的文件說明
  • 豐富的使用範例
  • 靈活的自訂選項

📱 行動端最佳化

  • 觸控友善的互動
  • 響應式設計
  • 效能最佳化

創新功能建議 ​

🌈 主題系統增強

  • 動態主題切換
  • 自訂主題產生器
  • 主題預覽功能

♿ 無障礙支援

  • 鍵盤導航最佳化
  • 螢幕閱讀器支援
  • 高對比度模式

🚀 效能最佳化

  • 按需載入最佳化
  • 虛擬捲動支援
  • 記憶體使用最佳化

延伸閱讀 📚 ​

技術文件 ​

開源貢獻 ​

設計資源 ​

🎉 感謝你的貢獻！ 每一個 PR、每一個 Issue、每一次討論都讓 Vant 變得更好。讓我們一起打造最優秀的行動端元件庫！

基於Vant構建的企業級移動端解決方案

Copyright © 2025 siex.cn ｜ sitemap