cy-element-ui 1.1.25 → 1.1.27

package/LICENSE

@@ -1,21 +1,21 @@
-The MIT License (MIT)
-
-Copyright (c) 2016-present ElemeFE
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+The MIT License (MIT)
+
+Copyright (c) 2016-present ElemeFE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,18 @@
 # 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](https://github.com/bmatzku/gow)、[MinGW](http://www.mingw.org/) 或直接用 `node build/bin/new-cy.js` 替代 make 命令 |
+
+> Windows 用户注意：`make new-cy xxx` 可替换为 `node build/bin/new-cy.js xxx`，效果完全相同。
+
+---
+
 ## 一、在项目中安装使用
 
 ### 1.1 安装依赖
@@ -129,13 +142,14 @@ export default {
 ### 2.1 整体架构
 
 ```
-element-dev/                              # 项目根目录
+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              # 组件单独构建配置
@@ -144,8 +158,12 @@ element-dev/                              # 项目根目录
 │   ├── docs/                             # 文档内容
 │   │   └── zh-CN/                        # 中文文档
 │   │       └── cy/                       # 产研组件文档
+│   ├── pages/zh-CN/                      # 页面容器
+│   │   ├── component.vue                 # 组件页容器（Element UI组件+开发指南等）
+│   │   ├── independent.vue               # 独立菜单通用容器（如产研）
+│   │   └── index.vue                     # 首页
 │   ├── nav.config.json                   # 导航配置
-│   └── route.config.js                   # 路由配置
+│   └── route.config.js                   # 路由配置（自动识别独立菜单标记）
 ├── packages/                             # 组件源码目录
 │   ├── cy/                               # 产研自定义组件
 │   │   ├── treeSelect/                   # 树形选择器
@@ -169,8 +187,10 @@ element-dev/                              # 项目根目录
 |----------|----------|------|----------|
 | 一级 | `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组件源码 |
@@ -223,7 +243,7 @@ make new-cy advancedSelect 高级选择器
 |----------|------|-------------|
 | `packages/cy/advancedSelect/index.js` | 组件导出文件 | 否（自动生成） |
 | `packages/cy/advancedSelect/src/main.vue` | 组件实现文件 | 是（必须编写逻辑） |
-| `examples/docs/zh-CN/cy/cy-advancedSelect.md` | 中文文档文件 | 是（必须编写文档） |
+| `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- 前缀） | 否（自动生成） |
@@ -243,7 +263,7 @@ make new-cy advancedSelect 高级选择器
 |------|---------|------|--------|
 | 1 | 编写组件逻辑和模板 | `packages/cy/advancedSelect/src/main.vue` | 高 |
 | 2 | 编写组件样式 | `packages/theme-chalk/src/cy/advancedSelect.scss` | 高 |
-| 3 | 编写组件文档 | `examples/docs/zh-CN/cy/cy-advancedSelect.md` | 高 |
+| 3 | 编写组件文档 | `examples/docs/zh-CN/cy/advancedSelect.md` | 高 |
 | 4 | 重新生成入口 | `npm run build:file` | 必须 |
 
 #### 3.1.4 生成的文件内容示例
@@ -358,7 +378,7 @@ make new custom-button 自定义按钮
 | 组件目录（el） | - | 小写连字符 | `custom-button` |
 | 组件目录（cy） | - | 驼峰式 | `treeSelect` |
 | 样式文件 | - | 小写连字符 | `button.scss`, `tree-select.scss` |
-| 文档文件 | - | `cy-`前缀+小写连字符 | `cy-tree-select.md` |
+| 文档文件 | - | 驼峰式 | `treeSelect.md` |
 
 ---
 
@@ -432,7 +452,7 @@ export default {
 **中文文档路径：**
 
 ```
-examples/docs/zh-CN/cy/cy-<component-name>.md
+examples/docs/zh-CN/cy/<component-name>.md
 ```
 
 **文档内容结构：**
@@ -489,27 +509,37 @@ export default {
 
 修改 `examples/nav.config.json`：
 
+> **注意**：产研等独立菜单使用 `independent` + `pathPrefix` 标记，路由会自动处理。详见 [九、新增独立菜单](#九新增独立菜单类似产研)。
+
+**普通组件（添加到"组件"菜单下）：**
+
+在 `"name": "组件"` 的 groups 中找到对应分组，添加一项：
+
 ```json
 {
-  "zh-CN": {
-    "title": "组件",
-    "children": [
-      {
-        "path": "/chanyan",
-        "title": "产研组件",
-        "children": [
-          {
-            "path": "/chanyan/treeSelect",
-            "title": "TreeSelect 树形选择器"
-          },
-          {
-            "path": "/chanyan/advancedSelect",
-            "title": "AdvancedSelect 高级选择器"
-          }
-        ]
-      }
-    ]
-  }
+  "path": "/advancedSelect",
+  "title": "AdvancedSelect 高级选择器"
+}
+```
+
+**独立菜单（如"产研"）：**
+
+```json
+{
+  "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 选择显示输入框" }
+      ]
+    }
+  ]
 }
 ```
 
@@ -534,26 +564,43 @@ npm run dist
 
 ### 6.2 分步构建
 
+> **注意**：当前 `dist` 命令已统一由 `build/dist.js` 管理（使用 webpack Node API），以下为内部流程说明。
+
+**完整构建（推荐）：**
+
 ```bash
-# 清理构建目录
-npm run clean
+npm run dist
+```
 
-# 生成入口文件
-npm run build:file
+该命令自动依次执行：
+
+| 步骤 | 命令/操作 | 说明 |
+|------|----------|------|
+| 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 主题样式 |
 
-# 构建 UMD 版本
-npx webpack --config build/webpack.conf.js
+**手动单步执行（调试用）：**
 
-# 构建 CommonJS 版本
-npx webpack --config build/webpack.common.js
+```bash
+# 清理
+npm run clean
 
-# 构建组件单独文件
-npx webpack --config build/webpack.component.js
+# 生成入口文件
+npm run build:file
 
-# 构建工具函数
-npm run build:utils
+# 单独执行某一步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
 ```
 
@@ -596,7 +643,18 @@ npm login
 ### 7.3 发布
 
 ```bash
-npm publish
+# 发布（scoped 包需要 --access public）
+npm publish --access public
+```
+
+**发布后在其他项目中更新：**
+
+```bash
+# 清除缓存，确保拉取最新版
+rmdir /s /q node_modules\cy-element-ui
+npm cache clean --force
+del package-lock.json
+npm install cy-element-ui@latest
 ```
 
 ---
@@ -609,7 +667,7 @@ npm publish
 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/cy-<name>.md
+4. 编写文档    → 修改 examples/docs/zh-CN/cy/<name>.md
 5. 生成入口    → npm run build:file
 6. 启动开发    → npm run dev
 7. 完整构建    → npm run dist
@@ -622,8 +680,173 @@ npm publish
 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"` 数组末尾添加一个新对象：
+
+```json
+{
+	"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：创建组件源码（如果是有代码的新组件）
+
+如果这个独立菜单下包含全新的自定义组件：
+
+```bash
+# 使用 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`：
+
+```json
+[
+  {
+    "lang": "zh-CN",
+    "header": {
+      "guide": "指南",
+      "components": "组件",
+      "chanyan": "产研",
+      "dataPlatform": "数据平台",     // ← 新增
+      ...
+    }
+  }
+]
+```
+
+然后修改 `examples/components/header.vue` 中的导航链接：
+
+```html
+<li class="nav-item">
+    <router-link :to="`/${ lang }/dp`">{{ langConfig.dataPlatform }}</router-link>
+</li>
+```
+
+#### 步骤 5：验证
+
+```bash
+# 启动开发服务器
+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.0
-**最后更新**: 2024年
+**版本**: v1.1.26
+**最后更新**: 2026年5月