组件规范

这一页说明一个组件要怎么组织，才能被平台识别、预览和发布。组件不是「一个文件」，而是一个文件夹。

入口文件

文件夹名就是组件名。入口文件按框架固定：

框架	入口文件	说明
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 的作用 ​

命名规范 ​

体积与数量限制 ​

最小示例 ​

自检清单 ​

下一步 ​