元件上傳指南

上傳元件到 comp-hub 只需三個步驟：選擇資料夾、設定預覽、點擊發佈。

前置條件

上傳前，請確保元件符合以下條件：

資料夾格式：元件必須以資料夾形式存在，資料夾名稱為元件名稱
入口檔案：必須有入口檔案 —— Vue 元件為 index.vue，React 元件為 index.jsx / index.js / index.tsx
可獨立執行：元件應自包含，依賴透過相對路徑匯入

建議目錄結構：

MyComponent/           # 元件名稱
├── index.vue         # 入口檔案（必填）
├── README.md         # 元件文件（建議）
├── comp.json         # 設定檔（自動產生）
└── assets/           # 靜態資源（如有）
    └── logo.png

上傳限制

上傳元件時適用以下限制：

限制	說明
單一檔案大小	每個檔案不得超過 3MB。上傳前請壓縮大檔案（音訊、視訊、高解析度圖片）
總大小	所有元件檔案合計不得超過 10MB
檔案數量	檔案總數（含子目錄）不得超過 30

如果提交時出現檔案大小錯誤，請檢查是否有過大的靜態資源並進行壓縮或刪除後再重試。

UI 框架支援

元件預覽可以在 Vue 或 React 上執行。任一生態系統中的所有 UI 框架都可以直接使用。

框架如何識別

框架不需要在任何地方宣告，comp-hub 會根據元件原始碼中掃描到的依賴自動判定：

元件引入了 vue → 判定為 Vue 元件
元件引入了 react → 判定為 React 元件
同時引入 vue 和 react → 無法判定框架，上傳頁將無法檢查與渲染該元件

Vue 元件

對於 Vue 元件，請在元件根目錄新增 main.js 檔案並註冊所需的 UI 框架：

Vue 2

import Vue from 'vue';
import Antd from 'ant-design-vue';
import 'ant-design-vue/dist/antd.css';
Vue.use(Antd);

Vue 3

注意：Vue 3 預設不匯出 app 實例。此處的 Vue.app 由工具內部建立並掛載到 Vue 上。這與自行呼叫 createApp() 的官方方式不同——直接使用即可。

import * as Vue from 'vue'
import ArcoVue from '@arco-design/web-vue';
import '@arco-design/web-vue/dist/arco.css';

Vue.app.use(ArcoVue);

React 元件

React 元件不需要 main.js 檔案，依賴也不需要在 comp.json 中宣告 —— 直接在元件中照常 import 即可：

jsx

import { Button, Card } from "antd";
import { LikeOutlined } from "@ant-design/icons";

export default function MyCard() {
  return <Card>Hello</Card>;
}

在上傳頁選取元件資料夾後，comp-hub 會掃描原始碼中的 import 語句，從本機專案的 node_modules 解析每個依賴並預先編譯，供預覽使用。因此：

元件用到的依賴必須已安裝在本機專案中（npm install <pkg>），否則預覽會提示依賴缺失
掃描到的依賴及其版本會顯示在設定區的「元件依賴」分頁中，發佈前可核對
入口檔案必須有 default export，僅有具名匯出會報 Component has no default export
同時支援 React 18（react-dom/client）與 React 17（react-dom），渲染 API 會自動適配

命名規範

元件名稱在同一空間內唯一（公開平台，或某個團隊內），不能與現有名稱重複
僅支援兩種格式：PascalCase（UserGrowthChart）或 kebab-case（alipay-data-table）
不支援底線 _、camelCase（myComponent），也不能以數字開頭
建議使用前綴命名，例如：company-business-domain-component-name：alipay-data-table

重複元件處理

平台會對上傳的元件進行相似度偵測。如果判定為重複元件：

不會進入「推薦」、「熱門」、「最新」等公開列表
只能在「我的元件」中查看和管理
會出現在相似元件的推薦列表中
更新也不享有推薦權重

建議上傳前先檢查是否已有功能相似的元件，避免重複造輪子。

上傳步驟

1. 進入上傳頁面

啟動 comp-hub 後，點擊左側選單中的「上傳元件」。

2. 選擇元件

左側檔案樹顯示 .comphub.json 或 .comphub.js 中 dir 指定的目錄
瀏覽到元件資料夾並選擇它
點擊「選擇」確認

3. 設定預覽

上傳頁面分為上下兩個區域：

上方預覽區

即時顯示元件渲染效果
支援重新整理和背景顏色切換

下方設定區

小窗預覽：選擇用於列表頁顯示的檔案，約定為 demo/index.vue（也可以是元件入口本身）
全螢幕預覽：選擇用於詳情頁顯示的檔案，約定為 demo/full.vue（建議設定）
元件依賴：從原始碼自動掃描出的依賴及其本機版本，可在此核對
備註：簡要描述元件功能和適用場景
其他資訊：詳細描述，支援搜尋關鍵字

元件資料夾內任何以 .vue、.jsx、.tsx 結尾的檔案都可以選作預覽檔案，demo/ 目錄只是約定而非強制。React 元件請使用 .jsx / .tsx 檔案。

4. 產生設定

點擊「產生設定」按鈕，系統會自動建立包含以下內容的 comp.json 檔案：

json

{
  "__id__": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "MyComponent",
  "version": "1.0.0"
}

comp.json 只有這三個欄位。首次發佈成功後伺服器會寫入 __id__，請勿手動修改。依賴來自原始碼掃描，不寫在這個檔案裡。

5. 發佈元件

確認設定無誤後，點擊「發佈」按鈕即可完成上傳。

最小範例

這是一個最簡單的可上傳元件：

vue

<!-- MyButton/index.vue -->
<template>
  <button class="my-button" @click="handleClick">
    {{ text }}
  </button>
</template>

<script>
export default {
  name: 'MyButton',
  props: {
    text: {
      type: String,
      default: 'Click Me'
    }
  },
  methods: {
    handleClick() {
      this.$emit('click')
    }
  }
}
</script>

<style scoped>
.my-button {
  padding: 8px 16px;
  background: #409eff;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}
</style>

最小 React 範例

jsx

// MyCard/index.jsx
import { Card } from "antd";

export default function MyCard({ title = "Hello" }) {
  return <Card>{title}</Card>;
}

antd 必須已安裝在本機專案中；default export 為必要條件。

最佳實務

編寫 README：詳細說明元件的使用方式、屬性、事件和範例
提供 Demo：建立 demo 目錄展示元件的典型用法
語意化版本：遵循 major.minor.patch 規範
處理依賴：第三方依賴只需在本機安裝，無需打包進元件

元件上傳指南 ​

前置條件 ​

上傳限制 ​

UI 框架支援 ​

框架如何識別 ​

Vue 元件 ​

Vue 2 ​

Vue 3 ​

React 元件 ​

命名規範 ​

重複元件處理 ​

上傳步驟 ​

1. 進入上傳頁面 ​

2. 選擇元件 ​

3. 設定預覽 ​

4. 產生設定 ​

5. 發佈元件 ​

最小範例 ​

最小 React 範例 ​

最佳實務 ​