元件規範

這一頁說明一個元件要怎麼組織，才能被平台識別、預覽和發布。元件不是「一個檔案」，而是一個資料夾。

入口檔案

資料夾名稱就是元件名稱。入口檔案按框架固定：

框架	入口檔案	說明
Vue 2 / Vue 3	`index.vue`	存在即判定為 Vue
React 17 / 18	`index.jsx` / `index.tsx`	必須 `default export`
Web Component	`index.js`	原始碼裡必須註冊自訂元素

不要同時依賴 vue 與 react，否則平台無法判定框架。

資源引用

Vue / React：用相對路徑 import，不要用 @/ 之類的別名。

// 正確
import bg from "./assets/bg.png";

// 錯誤：平台無法解析專案別名
import bg from "@/assets/bg.png";

Web Component：原始碼是瀏覽器直接執行的 ESM，圖片、字型、樣式都不能 import。用 new URL 定位：

const bg = new URL("./assets/bg.png", import.meta.url);

預覽 HTML 裡的相對 src / href / srcset 由平台按元件目錄解析，直接寫相對路徑即可。

依賴宣告

第三方依賴不需要寫進 comp.json。平台會掃描原始碼裡的 import 語句自動提取，並從你本地專案的 node_modules 解析、預先編譯。

因此：元件用到的套件必須已經在本地安裝。

bash

npm install echarts

掃描結果會顯示在上傳頁的「元件依賴」中，發布前可以核對。

demo 與預覽

demo/index.vue：列表卡片裡的小窗預覽。
demo/full.vue：詳情頁的全螢幕預覽，建議提供。

Web Component 的預覽是普通 HTML：

html

<!-- demo/mini.html -->
<my-element text="Hello"></my-element>
<script type="module" src="../index.js"></script>

要求：

至少包含一個 <script type="module">。
模組腳本必須放在 <body> 裡，放在 <head> 會被忽略。
腳本 src 相對該 HTML 自身位置解析。

mini 預覽自動縮放

平台會自動量測 mini demo 的固定寬高，按 contain（等比、完整可見、置中）適配面板。demo 程式碼裡不需要寫任何縮放邏輯。

你只需要把內容固定成設計寬高：

vue

<template>
  <div class="mini-content">按 320 × 240 設計的內容</div>
</template>

<style scoped>
.mini-content {
  width: 320px;
  height: 240px;
  overflow: hidden;
}
</style>

不要寫 width: 100%

根元素撐滿容器會讓平台量到「自然尺寸」，縮放比例隨內容漂移。固定設計寬高即可。

main.js 的作用

main.js 只在預覽環境執行，用來放全域副作用：

Vue 2：註冊 UI 函式庫

import Vue from "vue";
import Antd from "ant-design-vue";
import "ant-design-vue/dist/antd.css";

Vue.use(Antd);

Vue 3：透過平台提供的 Vue.app 註冊

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：放全域樣式

import "antd/dist/reset.css";

不要把全域樣式寫進 index.jsx：使用方 import 元件入口時會連帶執行，導致重複引入。

命名規範

同一空間內唯一（公共平台或某個團隊內）。
只支援 PascalCase（UserGrowthChart）或 kebab-case（alipay-data-table）。
不支援 _、camelCase、數字開頭。
建議用前綴區分業務域：公司名-業務域-元件名。

體積與數量限制

限制項	上限
單一檔案	3 MB
元件總大小	10 MB
檔案數量	30 個（含子目錄）

超出時先壓縮靜態資源，或把大檔案改為外部連結。

最小範例

Vue

vue

<!-- MyButton/index.vue -->
<template>
  <button class="my-button" @click="$emit('click')">{{ text }}</button>
</template>

<script>
export default {
  name: "MyButton",
  props: { text: { type: String, default: "點擊我" } }
};
</script>

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

React

jsx

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

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

Web Component

// MyElement/index.js
class MyElement extends HTMLElement {
  connectedCallback() {
    this.innerHTML = `<span>${this.getAttribute("text") || "Hello"}</span>`;
  }
}

customElements.define("my-element", MyElement);

html

<!-- MyElement/demo/mini.html -->
<my-element text="Hello"></my-element>
<script type="module" src="../index.js"></script>

自檢清單

[ ] 資料夾名稱符合命名規範，且目前空間內不重名。
[ ] 入口檔案存在，React 有 default export。
[ ] 資源使用相對路徑；Web Component 使用 new URL。
[ ] 用到的依賴已在本地安裝。
[ ] mini demo 固定了設計寬高。
[ ] Web Component 的預覽 HTML 含 <script type="module"> 且位於 <body>。
[ ] 檔案大小與數量沒有超限。

下一步

把元件發到平台：上傳與發布
發布後繼續迭代：更新與版本

元件規範 ​

入口檔案 ​

推薦目錄結構 ​

資源引用 ​

依賴宣告 ​

demo 與預覽 ​

mini 預覽自動縮放 ​

main.js 的作用 ​

命名規範 ​

體積與數量限制 ​

最小範例 ​

自檢清單 ​

下一步 ​