自定义组件开发规范
本文说明使用 neo-cmp-cli 开发自定义组件时的工程目录、组件目录、目录规范、技术栈、模型配置、属性配置面板、样式与依赖等规范。
1. 项目工程目录说明
| 路径 | 说明 |
|---|---|
src/assets/ | 静态资源；默认含 css/common.scss、css/mixin.scss 等全局可注入样式 |
src/assets/img/ | 图片等素材 |
src/components/ | 自定义组件根目录；每个子目录为一个组件；可含 README.md 说明 |
src/components/<组件名>/ | 单个组件：index.*（实现）、model.*（设计器模型） |
public/ | 本地预览用 HTML 模板、基础脚本与样式（template.html、css/、scripts/ 等） |
@types/ | 平台或工程用到的补充类型声明（如 neo-ui-common） |
package.json | 项目元数据、framework（如 react-ts）、脚本（preview / linkDebug / pushCmp 等） |
tsconfig.json | TypeScript 编译配置（TS 模板适用） |
neo.config.js | neo-cmp-cli 工程配置（webpack、预览、外链调试、平台地址、公共样式注入等），无需显式配置 entry 时，CLI 会根据 src/components/ 下目录自动生成构建入口（可在命令行输出中查看生成的 entry）。 |
commitlint.config.js | GIT 提交信息规范（若模板启用） |
.prettierrc.js | 代码格式化规则 |
.npmrc | NPM 包管理配置，可用于添加默认的 NPM 安装源 |
.gitignore | GIT 版本控制忽略项 |
2. 组件目录说明
| 路径 | 说明 |
|---|---|
src/components/ | 自定义组件源码根目录 |
src/components/<组件名>/ | 单个组件目录，子目录名即组件名（cmpType 取值来源） |
src/components/<组件名>/index.* | 组件实现入口 |
src/components/<组件名>/model.* | 组件模型文件，与页面设计器相关的配置均在此模型文件中定义 |
3. 组件目录规范
CLI 按约定扫描 src/components/ 下的子目录与文件，发布时据此生成注册相关代码并注入构建流程，一般无需手写注册逻辑。
- 目录与命名：每个组件占有一个子目录；子目录名即组件名，并与模型中的
cmpType（构建时按目录名生成）保持一致。 - 组件入口文件：目录内须包含
index.ts/index.tsx/index.js/index.jsx/index.vue之一作为组件实现入口（以实际模板为准）。 - 模型文件：目录内须包含
model.ts/model.js作为组件模型文件。 - 发布与注册：发布流程会生成注册相关代码并接入构建；若需手动注册，请见 neo-register。
4. 技术栈说明
当前自定义组件支持 React 与 Vue 2 两种技术栈，初始化时选择的模板决定工程依赖与组件文件后缀；构建与发布流程由 neo-cmp-cli 统一处理。
4.1 React 自定义组件
Neo 平台前端使用 React 技术栈开发，自定义组件使用 React 技术栈开发 更容易和平台整合，自定义组件构建后的脚本资源更小（拥有更好的初次加载性能）。
- React 版本说明：请使用 react 16 版本，与平台预置依赖对齐（参见本文「复用平台预置依赖」中的
react/react-dom版本），避免本地与运行时版本不一致。 - 入口文件：
index.tsx/index.jsx/index.ts/index.js（与模型文件同目录）。 - 官方文档：使用 React 开发自定义组件 和 开发 React 业务组件的方式一样，可查看以下 React 官方使用文档学习开发方式：
4.2 Vue 2 自定义组件
如果团队以 Vue 2 技术栈为主、或需复用已有 Vue 2 组件逻辑时，可选用 vue2 技术栈开发自定义组件，CLI 内置 vue2 组件模板（见 CLI 使用说明 - 内置模板）。
- 入口文件：一般为单文件组件
index.vue（具体以模板与 CLI 扫描规则为准）。 - 暂不支持事件动作：若需要使用事件动作实现组件联动，请优先采用 React 技术栈；事件动作的概念与配置方式见 事件动作机制。
- 官方文档：使用 Vue 开发自定义组件 和 开发 Vue 业务组件的方式一样，可查看以下 Vue 官方使用文档学习开发方式：
5. 组件模型文件属性说明
通过 neo init 或 neo create cmp 创建的组件会自带组件模型文件，与页面设计器相关的配置均在模型文件中定义。
可配置属性一览
| 属性名 | 默认值 | 说明 |
|---|---|---|
cmpType | 构建时按目录名自动生成 | 组件类型标识，需保证唯一 |
label | - | 设计器左侧组件面板中显示的名称 |
description | - | 设计器左侧组件面板中显示的描述 |
iconUrl | - | 设计器左侧组件面板中显示的图标 |
tags | ['自定义组件'] | 分类标签，决定出现在哪个分类下 |
exposedToDesigner | true | 是否在页面设计器中可见 |
enableDuplicate | true | 是否允许在设计器中多次拖入 |
targetPage | ['all'] | 适配的页面类型 |
targetObject | ['all'] | 支持的实体类型 |
targetApplication | ['all'] | 支持的应用类型 |
targetDevice | 'all' | 支持的设备类型 |
defaultComProps | - | 首次拖入页面时的默认属性 |
propsSchema | [] | 数组，定义设计器右侧属性面板的配置项 |
页面类型（targetPage）说明
| 取值 | 含义 |
|---|---|
all | 所有页面类型 |
indexPage | 首页 |
entityListPage | 实体列表页 |
entityFormPage | 实体表单页 |
entityDetailPage | 实体详情页 |
customPage | 自定义页面 |
bizPage | 业务页面 |
6. 组件属性配置项
属性配置项在组件模型文件 propsSchema 中定义，用于在页面设计器中暴露可编辑项，使业务人员无需改代码即可调整展示与行为，从而提升组件复用度。
设计原则
- 少而精：配置项越多，使用者理解成本越高；应优先用少量语义清晰的配置项覆盖常见定制场景，复杂逻辑可收敛为「预设模式」枚举等。
- 与实现一致：
propsSchema中name对应传入组件的 props 字段名。 - 类型与控件匹配：文本、数字、开关、枚举、颜色等应选用合适的表单项类型，便于校验与联动（见下文文档）。
组件代码如何使用配置项
- React：所有属性配置项会作为 props 传入，类组件使用
this.props.xxx，函数组件使用函数参数或 Hooks 依赖的 props。 - Vue 2：一般在
index.vue的props中声明同名属性，由运行时注入。
当前自定义组件模型文件中可添加的属性配置类型见 可用属性配置项。
7. 组件样式规范
7.1 命名与结构
- 根节点类名：最外层容器使用与组件目录名一致的类名（例如
xx-cmpType），其下样式写在同一 BEM 风格命名空间内，减少与其他自定义组件、平台全局样式的冲突。 - 避免过深嵌套：优先在根作用域下使用平铺选择器（2～3 层以内为宜），便于维护与覆盖。
- 可维护性：颜色、间距、字号等建议抽成 SCSS 变量或复用
src/assets/css中的公共片段。
7.2 构建时样式隔离
发布或 linkDebug 时，CLI 会为组件做样式隔离（默认处理组件目录下的 (index|style).(scss|less)），降低自定义样式对 Neo 平台全局样式的影响。
隔离方式为给样式增加作用域（如 [data-scope=组件目录名]）。组件根节点请使用与组件目录名一致或约定的唯一类名，避免被样式隔离策略误伤。
如需关闭该行为，在 neo.config.js 或 webpack 配置中将 disableAutoAddStyleScope 设为 true。
7.3 弹层类组件的样式
Popover、Tooltip、Modal 等挂载在 body 等位置的 Ant Design 组件，其自定义样式建议放在组件目录下的 common.scss 或 reset.scss 中，避免与隔离策略冲突。
7.4 SCSS 简要使用说明
工程默认支持 Sass/SCSS。组件样式内容默认放 index.scss / style.scss 中，在 JS/TS/Vue 中按模板方式引入即可。
常用能力简述：
- 变量：
$primary-color: #1890ff;，便于主题统一。 - 嵌套：按 DOM 层级书写，注意勿嵌套过深。
&父选择器：用于伪类、修饰符，如&:hover、.root &。@mixin/@include：抽取重复样式片段；空模板中mixin.scss可集中定义混入。@import/@use：拆分文件；具体语法以项目构建链支持的 Sass 版本为准。
全局注入：neo.config.js 的 webpack.sassResources 可将 src/assets/css/common.scss、mixin.scss 等自动注入每个 SCSS 文件，无需在每个组件重复 @import 公共变量与混入（修改配置后需重新启动本地调试）。
8. 组件模块共享
多个自定义组件项目之间，可通过 模块联邦 方式在 neo.config.js 中配置 neoCommonModule：由组件 A 导出共享模块，组件 B 声明 remoteDeps / externals 后按需 import，从而避免重复打包、统一维护公共逻辑。
配置步骤、数组与对象两种 exports 写法、与 externals 的配合等，见 组件模块共享。
9. 使用平台实体数据源
自定义组件内可通过 OpenAPI SDK 访问平台实体数据，详见 平台实体数据源。
10. 复用平台预置依赖
CLI 构建时默认会把平台已使用的依赖模块（如react、axios、lodash、antd等）作为外部依赖从打包中排除、不再重复打入构建产物，可显著缩小自定义组件包体积、提高自定义组件首次加载速度。
发布时默认会剔除的平台依赖
自定义组件可直接使用下列依赖（版本需与平台一致，否则可能出现运行时问题）：
| 依赖包 | 版本 |
|---|---|
| react | ^16.13.1 |
| react-dom | ^16.13.1 |
| mobx | ^6.3.0 |
| mobx-react | ^7.0.0 |
| mobx-state-tree | ^5.4.0 |
| axios | ^0.27.2 |
| classnames | ^2.3.2 |
| qs | ^6.11.0 |
| lodash | ^4.17.21 |
| amis | ^1.1.5 |
| neo-ui-common | - |
注意：请与上表版本对齐；版本不一致可能导致运行异常。
H5 端可复用的依赖
| 依赖包 | 版本 |
|---|---|
| antd-mobile | 2.3.4 |
| neo-ui-component-h5 | - |
PC / Web 端可复用的依赖
| 依赖包 | 版本 |
|---|---|
| antd | 4.9.4 |
| @ant-design/icons | ^4.8.0 |
| neo-ui-component-web | - |
注意：H5 端自定义组件默认使用 antd-mobile UI 组件库，PC 端自定义组件默认使用的 antd UI 组件库。