cy-element-ui 组件开发指南

环境要求

| 工具 | 版本要求 | 说明 | |------|---------|------| | Node.js | >= 14.x（推荐 16.x） | 项目使用 webpack 4 + Babel 6，需 Node.js 支持 | | npm | >= 6.x | 包管理器，也可使用 yarn | | Git | 任意版本 | 用于版本管理和发布流程 | | Make | 可选 | Linux/macOS 原生支持；Windows 下可用 Gow、MinGW 或直接用 node build/bin/new-cy.js 替代 make 命令 |

Windows 用户注意：make new-cy xxx 可替换为 node build/bin/new-cy.js xxx，效果完全相同。

一、在项目中安装使用

1.1 安装依赖

# 使用 npm
npm install cy-element-ui --save

# 使用 yarn
yarn add cy-element-ui

# 使用淘宝镜像
npm install cy-element-ui --save --registry=https://registry.npmmirror.com

1.2 全局引入

// main.js
import Vue from 'vue';
import CyElementUI from 'cy-element-ui';
import 'cy-element-ui/lib/theme-chalk/index.css';

Vue.use(CyElementUI);

1.3 按需引入

方法一：手动引入

import Vue from 'vue';
import { CyTreeSelect, CyTabDialog, ElButton } from 'cy-element-ui';
import 'cy-element-ui/lib/theme-chalk/cy/treeSelect.css';
import 'cy-element-ui/lib/theme-chalk/cy/tabDialog.css';
import 'cy-element-ui/lib/theme-chalk/button.css';

Vue.use(CyTreeSelect);
Vue.use(CyTabDialog);
Vue.use(ElButton);

方法二：使用 babel-plugin-component

安装插件：

npm install babel-plugin-component --save-dev

配置 .babelrc：

{
  "plugins": [
    ["component", {
      "libraryName": "cy-element-ui",
      "styleLibraryName": "theme-chalk"
    }]
  ]
}

使用：

import Vue from 'vue';
import { CyTreeSelect, CyTabDialog, ElButton } from 'cy-element-ui';

Vue.use(CyTreeSelect);
Vue.use(CyTabDialog);
Vue.use(ElButton);

1.4 使用示例

<template>
	<div class="app-container">
		<!-- 使用 Element UI 组件 -->
		<el-button type="primary">Element Button</el-button>
		
		<!-- 使用产研自定义组件 -->
		<cy-tree-select
			v-model="selectedIds"
			:data="treeData"
			placeholder="请选择"
		></cy-tree-select>
		
		<cy-tab-dialog
			title="标签对话框"
			:visible="dialogVisible"
			@close="dialogVisible = false"
		>
			<div slot="tab1">标签1内容</div>
			<div slot="tab2">标签2内容</div>
		</cy-tab-dialog>
	</div>
</template>

<script>
export default {
	name: 'App',
	data() {
		return {
			selectedIds: [],
			dialogVisible: false,
			treeData: [
				{
					id: '1',
					label: '一级节点',
					children: [
						{ id: '1-1', label: '二级节点' }
					]
				}
			]
		};
	}
};
</script>

二、项目架构

2.1 整体架构

chanyan-ui/                              # 项目根目录
├── build/                                # 构建工具目录
│   ├── bin/                              # 脚本命令
│   │   ├── build-entry.js                # 生成入口文件脚本
│   │   ├── gen-cy-types.js               # 生成cy组件类型定义
│   │   ├── new.js                        # 创建el组件脚本
│   │   └── new-cy.js                     # 创建cy组件脚本
│   ├── dist.js                           # 完整构建脚本（Node API方式，替代CLI）
│   ├── webpack.conf.js                   # UMD构建配置
│   ├── webpack.common.js                 # CommonJS构建配置
│   ├── webpack.component.js              # 组件单独构建配置
│   └── webpack.demo.js                   # 示例站点构建配置
├── examples/                             # 示例文档站点
│   ├── docs/                             # 文档内容
│   │   └── zh-CN/                        # 中文文档
│   │       └── cy/                       # 产研组件文档
│   ├── pages/zh-CN/                      # 页面容器
│   │   ├── component.vue                 # 组件页容器（Element UI组件+开发指南等）
│   │   ├── independent.vue               # 独立菜单通用容器（如产研）
│   │   └── index.vue                     # 首页
│   ├── nav.config.json                   # 导航配置
│   └── route.config.js                   # 路由配置（自动识别独立菜单标记）
├── packages/                             # 组件源码目录
│   ├── cy/                               # 产研自定义组件
│   │   ├── treeSelect/                   # 树形选择器
│   │   ├── tabDialog/                    # 标签对话框
│   │   ├── subTitle/                     # 副标题
│   │   └── selectDisplayInput/           # 选择显示输入框
│   └── theme-chalk/                      # 主题样式源码
│       └── src/                          # SCSS源码
│           └── cy/                       # cy组件样式
├── src/                                  # 核心源码
│   └── index.js                          # 组件库主入口（自动生成）
├── types/                                # 类型定义
│   └── cy/                               # cy组件类型定义
├── components.json                       # 组件配置清单
└── Makefile                              # 命令脚本

2.2 目录职责说明

| 目录层级 | 目录路径 | 职责 | 详细说明 | |----------|----------|------|----------| | 一级 | build/ | 构建工具 | 包含所有构建脚本和webpack配置文件 | | 二级 | build/bin/ | 命令脚本 | new.js创建el组件，new-cy.js创建cy组件 | | 二级 | build/dist.js | 完整构建脚本 | 统一管理完整构建流程（替代CLI方式） | | 一级 | examples/ | 示例站点 | 组件展示文档和示例代码 | | 二级 | examples/docs/zh-CN/cy/ | 产研组件文档 | cy组件的中文文档目录 | | 二级 | examples/pages/zh-CN/ | 页面容器 | component.vue(组件页)、independent.vue(独立菜单通用容器) | | 一级 | packages/ | 组件源码 | 所有el和cy组件的源代码 | | 二级 | packages/cy/ | 产研组件 | 自定义的cy-*组件，独立目录管理 | | 三级 | packages/cy/treeSelect/ | 树形选择器 | CyTreeSelect组件源码 | | 二级 | packages/theme-chalk/src/cy/ | cy样式 | 产研组件的SCSS样式文件 | | 一级 | src/ | 核心入口 | 自动生成的组件注册入口文件 | | 一级 | types/cy/ | 类型定义 | cy组件的TypeScript类型定义 |

2.3 组件结构规范

产研自定义组件结构（cy组件）：

packages/
└── cy/                        # cy组件根目录
    ├── treeSelect/            # 组件目录（驼峰式）
    │   ├── index.js           # 组件导出文件
    │   └── src/               # 源码目录
    │       └── main.vue       # 主组件文件（必须）
    ├── tabDialog/
    ├── subTitle/
    └── selectDisplayInput/

组件目录命名规则：

• cy组件：驼峰式（如 treeSelect）

三、创建新组件

3.1 创建 cy 组件（产研自定义）

使用 Makefile 命令创建组件：

make new-cy <component-name> [中文名]

示例：

make new-cy advancedSelect 高级选择器

执行该命令后自动完成以下操作：

3.1.1 自动创建的文件

| 文件路径 | 说明 | 是否必须修改 | |----------|------|-------------| | packages/cy/advancedSelect/index.js | 组件导出文件 | 否（自动生成） | | packages/cy/advancedSelect/src/main.vue | 组件实现文件 | 是（必须编写逻辑） | | examples/docs/zh-CN/cy/advancedSelect.md | 中文文档文件 | 是（必须编写文档） | | packages/theme-chalk/src/cy/advancedSelect.scss | 组件样式文件 | 是（必须编写样式） | | examples/demo-styles/cy/advancedSelect.scss | 示例页面样式文件 | 否（可选） | | types/cy/advancedSelect.d.ts | 类型定义文件（不带 cy- 前缀） | 否（自动生成） |

3.1.2 自动修改的文件

| 文件路径 | 修改内容 | 说明 | |----------|---------|------| | packages/theme-chalk/src/cy/index.scss | 添加 @import "./advancedSelect.scss"; | 引入组件样式到主题 | | examples/demo-styles/cy/index.scss | 添加 @import "./advancedSelect.scss"; | 引入组件样式到示例 | | components.json | 添加组件配置项 | 注册组件到构建系统 | | examples/nav.config.json | 添加导航菜单项 | 注册组件到文档导航 |

3.1.3 开发人员需要完成的工作

| 步骤 | 工作内容 | 文件 | 优先级 | |------|---------|------|--------| | 1 | 编写组件逻辑和模板 | packages/cy/advancedSelect/src/main.vue | 高 | | 2 | 编写组件样式 | packages/theme-chalk/src/cy/advancedSelect.scss | 高 | | 3 | 编写组件文档 | examples/docs/zh-CN/cy/advancedSelect.md | 高 | | 4 | 重新生成入口 | npm run build:file | 必须 |

3.1.4 生成的文件内容示例

packages/cy/advancedSelect/index.js：

import CyAdvancedSelect from './src/main';

/* istanbul ignore next */
CyAdvancedSelect.install = function(Vue) {
	Vue.component(CyAdvancedSelect.name, CyAdvancedSelect);
};

export default CyAdvancedSelect;

packages/cy/advancedSelect/src/main.vue：

<template>
	<div class="cy-advanced-select"></div>
</template>

<script>
export default {
	name: 'CyAdvancedSelect'
};
</script>

3.2 创建 el 组件（Element UI 风格）

使用 Makefile 命令创建组件：

make new <component-name> [中文名]

示例：

make new custom-button 自定义按钮

执行该命令后自动完成以下操作：

3.2.1 自动创建的文件

| 文件路径 | 说明 | 是否必须修改 | |----------|------|-------------| | packages/custom-button/index.js | 组件导出文件 | 否（自动生成） | | packages/custom-button/src/main.vue | 组件实现文件 | 是（必须编写逻辑） | | examples/docs/zh-CN/custom-button.md | 中文文档文件 | 是（必须编写文档） | | packages/theme-chalk/src/custom-button.scss | 组件样式文件 | 是（必须编写样式） | | examples/demo-styles/custom-button.scss | 示例页面样式文件 | 否（可选） |

3.2.2 自动修改的文件

| 文件路径 | 修改内容 | 说明 | |----------|---------|------| | packages/theme-chalk/src/index.scss | 添加 @import "./custom-button.scss"; | 引入组件样式到主题 | | examples/demo-styles/index.scss | 添加 @import "./custom-button.scss"; | 引入组件样式到示例 | | components.json | 添加组件配置项 | 注册组件到构建系统 |

3.2.3 开发人员需要完成的工作

| 步骤 | 工作内容 | 文件 | 优先级 | |------|---------|------|--------| | 1 | 编写组件逻辑和模板 | packages/custom-button/src/main.vue | 高 | | 2 | 编写组件样式 | packages/theme-chalk/src/custom-button.scss | 高 | | 3 | 编写组件文档 | examples/docs/zh-CN/custom-button.md | 高 | | 4 | 添加导航配置 | examples/nav.config.json | 高 | | 5 | 重新生成入口 | npm run build:file | 必须 |

3.3 组件配置文件详解

components.json

组件配置清单，定义所有需要打包的组件：

[
  { "name": "CyTreeSelect", "path": "./packages/cy/treeSelect/index.js" },
  { "name": "CyTabDialog", "path": "./packages/cy/tabDialog/index.js" },
  { "name": "CySubTitle", "path": "./packages/cy/subTitle/index.js" },
  { "name": "CySelectDisplayInput", "path": "./packages/cy/selectDisplayInput/index.js" },
  { "name": "Button", "path": "./packages/button/index.js" },
  { "name": "Input", "path": "./packages/input/index.js" }
]

字段说明：

• name：组件名称（使用 PascalCase，cy组件以Cy开头，el组件首字母大写）
• path：组件导出文件路径（相对于项目根目录）

自动生成入口文件

运行 npm run build:file 自动生成 src/index.js，包含：

1. 所有组件的 import 语句
2. 组件数组定义（components）
3. install 函数（注册所有组件、指令、原型方法）
4. 默认导出对象（包含版本号、install方法、所有组件）

3.4 组件命名规范

| 类型 | 前缀 | 命名方式 | 示例 | |------|------|---------|------| | Element UI 组件 | El | PascalCase | ElButton, ElInput | | 产研自定义组件 | Cy | PascalCase | CyTreeSelect, CyTabDialog | | 组件目录（el） | - | 小写连字符 | custom-button | | 组件目录（cy） | - | 驼峰式 | treeSelect | | 样式文件 | - | 小写连字符 | button.scss, tree-select.scss | | 文档文件 | - | 驼峰式 | treeSelect.md |

四、修改现有组件

4.1 修改组件代码

步骤 1：定位组件文件

# 修改 cy 组件
vi packages/cy/treeSelect/src/main.vue

# 修改 el 组件
vi packages/button/src/button.vue

步骤 2：修改组件逻辑

<script>
export default {
	name: 'CyTreeSelect',
	props: {
		// 添加或修改属性
		allowClear: {
			type: Boolean,
			default: false
		}
	},
	methods: {
		// 添加或修改方法
		clearSelection() {
			if (this.allowClear) {
				this.selectedValues = [];
				this.$emit('input', []);
			}
		}
	}
};
</script>

4.2 修改组件样式

// packages/theme-chalk/src/cy/treeSelect.scss
.cy-tree-select {
	// 添加新样式
	&__clear-btn {
		position: absolute;
		right: 30px;
		top: 50%;
		transform: translateY(-50%);
		cursor: pointer;
		color: #909399;
	}
}

4.3 更新组件文档

同步更新对应的文档文件，添加新属性和方法的说明。

五、编写组件文档

5.1 创建文档文件

中文文档路径：

examples/docs/zh-CN/cy/<component-name>.md

文档内容结构：

## CyAdvancedSelect 高级选择器

### 介绍

高级选择器组件，支持多选、搜索过滤、标签展示等功能。

### 基本用法

```html
<cy-advanced-select
  v-model="selectedValues"
  :options="options"
  placeholder="请选择"
></cy-advanced-select>

export default {
	data() {
		return {
			selectedValues: [],
			options: [
				{ value: '1', label: '选项1' },
				{ value: '2', label: '选项2' },
				{ value: '3', label: '选项3' }
			]
		};
	}
};

属性

| 属性 | 说明 | 类型 | 默认值 | |------|------|------|--------| | value / v-model | 选中值数组 | Array | [] | | options | 选项列表 | Array | [] | | placeholder | 占位提示 | String | '请选择' |

事件

| 事件名 | 说明 | 参数 | |--------|------|------| | input | 选中值变化时触发 | 选中的值数组 | | change | 选中值变化时触发 | 选中的选项对象数组 |

### 5.2 配置导航

修改 `examples/nav.config.json`：

> **注意**：产研等独立菜单使用 `independent` + `pathPrefix` 标记，路由会自动处理。详见 [九、新增独立菜单](#九新增独立菜单类似产研)。

**普通组件（添加到"组件"菜单下）：**

在 `"name": "组件"` 的 groups 中找到对应分组，添加一项：

```json
{
  "path": "/advancedSelect",
  "title": "AdvancedSelect 高级选择器"
}

独立菜单（如"产研"）：

{
  "name": "产研",
  "independent": true,
  "pathPrefix": "/cy",
  "groups": [
    {
      "groupName": "基础组件",
      "list": [
        { "path": "/cy/treeSelect",     "title": "TreeSelect 下拉树" },
        { "path": "/cy/tabDialog",      "title": "TabDialog 页签对话框" },
        { "path": "/cy/subTitle",       "title": "SubTitle 副标题" },
        { "path": "/cy/selectDisplayInput", "title": "SelectDisplayInput 选择显示输入框" }
      ]
    }
  ]
}

六、打包构建

6.1 完整构建

npm run dist

构建内容：

| 文件路径 | 说明 | |----------|------| | lib/index.js | UMD格式主入口 | | lib/element-ui.common.js | CommonJS格式入口 | | lib/theme-chalk/ | 主题样式目录 | | lib/[component].js | 各组件单独打包文件 |

6.2 分步构建

注意：当前 dist 命令已统一由 build/dist.js 管理（使用 webpack Node API），以下为内部流程说明。

完整构建（推荐）：

npm run dist

该命令自动依次执行：

| 步骤 | 命令/操作 | 说明 | |------|----------|------| | 1 | npm run clean | 清理 lib 目录 | | 2 | npm run build:file | 自动生成 src/index.js 入口文件 | | 3 | eslint + lint | 代码质量检查 | | 4 | Webpack UMD | 打包 lib/index.js | | 5 | Webpack CommonJS | 打包 lib/element-ui.common.js | | 6 | Webpack Component | 各组件单独打包到 lib/ | | 7 | npm run build:utils | 构建工具函数 | | 8 | npm run build:umd | UMD 补充处理 | | 9 | npm run build:theme | 编译 SCSS 主题样式 |

手动单步执行（调试用）：

# 清理
npm run clean

# 生成入口文件
npm run build:file

# 单独执行某一步webpack构建
npx webpack --config build/webpack.conf.js        # UMD
npx webpack --config build/webpack.common.js      # CommonJS
npx webpack --config build/webpack.component.js   # 组件单独打包

# 样式编译
npm run build:theme

6.3 内存不足问题处理

如果构建时出现内存不足错误（退出码 -1073741510），可以增加 Node.js 内存限制：

# 方式一：临时设置环境变量
$env:NODE_OPTIONS="--max-old-space-size=8192"
npm run dist

# 方式二：直接使用 node 命令
node --max-old-space-size=8192 node_modules/webpack/bin/webpack.js --config build/webpack.component.js

七、发布到 npm

7.1 更新版本号

# 升级补丁版本（1.1.3 → 1.1.4）
npm version patch

# 升级次要版本（1.1.3 → 1.2.0）
npm version minor

# 升级主要版本（1.1.3 → 2.0.0）
npm version major

7.2 登录 npm

npm login

7.3 发布

# 发布（scoped 包需要 --access public）
npm publish --access public

发布后在其他项目中更新：

# 清除缓存，确保拉取最新版
rmdir /s /q node_modules\cy-element-ui
npm cache clean --force
del package-lock.json
npm install cy-element-ui@latest

八、开发流程最佳实践

8.1 开发流程

1. 创建组件    → make new-cy <name> [中文名]
2. 编写代码    → 修改 packages/cy/<name>/src/main.vue
3. 编写样式    → 修改 packages/theme-chalk/src/cy/<name>.scss
4. 编写文档    → 修改 examples/docs/zh-CN/cy/<name>.md
5. 生成入口    → npm run build:file
6. 启动开发    → npm run dev
7. 完整构建    → npm run dist
8. 发布 npm    → npm publish

8.2 注意事项

1. 不使用单元测试：本项目不编写单元测试，所有组件通过示例站点验证
2. 类型定义：cy组件的类型定义文件不带 cy- 前缀，使用连字符命名（如 tree-select.d.ts）
3. 样式命名：使用 BEM 命名规范，cy组件样式类名以 cy- 开头
4. 文档语言：仅提供中文文档，不提供其他语言版本
5. async/await：项目支持 async/await（babel-preset-env + stage-2 自动转译）

九、新增独立菜单（类似产研）

9.1 概念说明

本项目支持在顶部导航栏中添加独立的菜单分类，与"组件"菜单完全隔离。例如现有的"产研"菜单就是一个独立菜单——它有自己的路由容器、侧边栏、文档目录，不会与"组件"页面混在一起。

9.2 工作原理

| 文件 | 作用 | |------|------| | examples/nav.config.json | 通过 independent: true + pathPrefix 标记独立菜单 | | examples/route.config.js | 自动识别标记，生成独立父路由 + 容器 | | examples/pages/zh-CN/independent.vue | 通用容器组件（自动过滤侧边栏数据） |

无需为每个独立菜单单独创建 vue 文件！

9.3 新增步骤详解

以新增一个名为"数据平台"、路径前缀 /dp 的独立菜单为例：

步骤 1：修改 nav.config.json

在 "zh-CN" 数组末尾添加一个新对象：

{
	"name": "数据平台",
	"independent": true,
	"pathPrefix": "/dp",
	"groups": [
		{
			"groupName": "基础组件",
			"list": [
				{
					"path": "/dp/dataTable",
					"title": "DataTable 数据表格"
				},
				{
					"path": "/dp/dataChart",
					"title": "DataChart 数据图表"
				}
			]
		}
	]
}

关键字段说明：

| 字段 | 是否必须 | 说明 | |------|---------|------| | name | 必须 | 导航栏显示名称，也是容器匹配的标识 | | independent | 必须 | 固定为 true，标记为独立菜单 | | pathPrefix | 必须 | URL 路径前缀，如 /dp → 最终路径 /zh-CN/dp/dataTable | | groups | 必须（或用 children） | 子项分组列表（与组件菜单结构一致） | | groups[].list[].path | 必须 | 必须以 pathPrefix 开头，如 /dp/dataTable |

步骤 2：创建文档文件

每个子组件需要对应的 md 文档：

examples/docs/zh-CN/
├── dp/                          # 新建目录（与 pathPrefix 对应）
│   ├── dataTable.md             # DataTable 组件文档
│   └── dataChart.md             # DataChart 组件文档
└── cy/                          # 已有的产研文档
    ├── treeSelect.md
    └── ...

文档格式参照 五、编写组件文档。

步骤 3：创建组件源码（如果是有代码的新组件）

如果这个独立菜单下包含全新的自定义组件：

# 使用 Makefile 创建组件
make new-cy dataTable 数据表格
make new-cy dataChart 数据图表

这会自动创建：

• packages/cy/dataTable/src/main.vue
• packages/theme-chalk/src/cy/dataTable.scss
• 并更新 components.json、样式 index.scss 等

如果只是引用已有组件做展示页，则不需要创建组件源码，只需写文档即可。

步骤 4：（可选）添加 i18n 翻译

如果导航栏文字需要国际化，修改 examples/i18n/component.json：

[
  {
    "lang": "zh-CN",
    "header": {
      "guide": "指南",
      "components": "组件",
      "chanyan": "产研",
      "dataPlatform": "数据平台",     // ← 新增
      ...
    }
  }
]

然后修改 examples/components/header.vue 中的导航链接：

<li class="nav-item">
    <router-link :to="`/${ lang }/dp`">{{ langConfig.dataPlatform }}</router-link>
</li>

步骤 5：验证

# 启动开发服务器
npm run dev

访问 http://localhost:8086/#/zh-CN/dp，应能看到：

1. 顶部导航栏新增"数据平台"入口
2. 点击后进入独立页面，侧边栏只显示"基础组件"分组下的子项
3. 点击子项能正常显示对应文档内容

9.4 路由生成规则

当 route.config.js 遇到 independent: true 的菜单时，自动执行以下操作：

输入：name="数据平台", pathPrefix="/dp"

自动生成的路由结构：
/zh-CN/dp                    (redirect → /zh-CN/dp/dataTable)
  ├── dataTable              → examples/docs/zh-CN/dp/dataTable.md
  └── dataChart              → examples/docs/zh-CN/dp/dataChart.md

与"产研"的路由完全平行：

/zh-CN/component            (component.vue 容器)
  ├── installation, button, ...   (Element UI 组件)

/zh-CN/cy                   (independent.vue 容器)
  ├── treeSelect, tabDialog, ... (产研组件)

/zh-CN/dp                   (independent.vue 容器)    ← 新增
  ├── dataTable, dataChart       (数据平台组件)

9.5 注意事项

1. pathPrefix 必须唯一：不能有两个独立菜单使用相同的 pathPrefix
2. 子项 path 必须以 pathPrefix 开头：否则路由无法正确剥离前缀
3. 文档目录名与 pathPrefix 一致：如 /dp 的文档放在 docs/zh-CN/dp/ 下
4. 不需要手动改 route.config.js 或创建新的 vue 容器：全部自动处理

版本: v1.1.26 最后更新: 2026年5月