AVM组件开发规范

一、AVM 组件介绍

AVM (Application-View-Model) 跨端框架是一个移动优先的高性能跨端 JavaScript 框架，支持一次编写多端渲染。 它提供更趋近于原生的编程体验，通过简洁的模型来分离应用的用户界面、业务逻辑和数据模型，适合高度定制的应用开发。

AVM 中的绝大多数代码和部件都是以组件化的方式组织的，在这个条件下，可以产出大量可复用、实用性强的功能组件和业务组件。

因此我们希望在平台现有的模块生态下，新增 “AVM 组件” ，为开发者建立 AVM 组件代码复用的桥梁。 该类型模块要求提交 AVM 组件源码，该源码可以是某个基础组件的框架，例如自定义渲染的选择器组件、日历等， 也可以是某个业务场景的封装，例如收货地址地图选点、联系人信息卡片和购物车页面交互等，或是对原生功能模块的 UI 封装，例如基于融云 IM 模块封装的会话列表，聊天窗口等。 开发者通过平台获取到该模块的源码后，可以通过 Studio3 导入自身 APP 项目中直接使用。

以下规范旨在统一 AVM 组件的的标准和形式，同时帮助审核人员提高审核效率，保证组件品质。

二、组件审核规范

0. 总则

AVM 组件包需要尽可能能支持多端运行，包含 STML（或者是 JS ）、CSS、 JS 代码以及所依赖的图片等资源文件和帮助文档。 应遵循简洁，抽象，低耦合的原则，避免冗余的 CSS/JS 代码。 充分考虑拓展性和普适性，能够对多种场景和业务做到最大程度适用。

1. 组件包资源结构

目录中 ${component-name} 为变量，即组件名称。

┌─${component-name}/                    // 组件根目录 以组件名称命名
│  ├─asset/                             // 组件附件资源目录 包括图片资源 字体等
│  ├─demo-${component-name}/            // 组件演示目录 格式为demo-组件名称
│  │  ├─demo-${component-name}.stml     // 组件演示页面文件 与父文件夹同名
│  ├─${component-name}.stml/js          // 组件入口文件 (可以是 STML / JS )
│  ├─${component-name}.css              // 组件依赖的独立外部css文件
│  ├─readme.md                          // 组件的说明文档
│  ├─package.json                       // 包信息文件
└────────────────
1.0. 最外层目录和压缩包

1.0.1. 模块包的最外层目录必须为该组件名。

1.0.2. 压缩格式为 zip 包，请右键根目录进行压缩，而不是在文件夹类全选进行压缩。

1.1. 组件包最佳实践

1.1.1. 应尽可能的确保组件的轻量，避免引入大的外部样式表、字体文件等外部资源

1.1.2. 对于使用图片等外部资源的组件，应将外部资源以 API 形式开放给使用者，避免将资源打包在组件包内

1.1.3. 本组件如果依赖其他组件，应将依赖的组件打包在本组件包内

1.2. 组件包处理流程

1.2.1. 组件包可通过开发工具导入到项目中直接使用。

1.2.2. 组件包中代码及资源在开发工具调试或云编译过程中将被还原至 widget 对应的目录中，具体规则为：

  • asset 下图片/视频等多媒体资源拷贝至 widget 的 image 目录
  • css/字体文件拷贝至 widget 的 css 目录
  • js 资源:使用 script 引用的 js 拷贝至 widget 的 script 目录，import 模块化引入的 js 资源留在组件目录内即可。
  • demo 演示目录会拷贝到 pages 目录，所以在 demo 中的组件资源的引用路径层级，以在 pages 目录下的情况为准。

2. 组件包内包信息 package.json 模板说明

{
  "name": "a-button",
  "version": "1.0.0",
  "description": "一个按钮组件的描述",
  "main": "test.stml",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "YonBuilder",
  "license": "MIT",
  "avm": {
    "platform": ["app","web","mp"],
    "systemType": ["ios","android"],
    "keywords": ["ui","input","component"],
    "site":"https://example.com",
    "price":100,
    "meta":{...}
  }
}

2.1. 使用标准的 json 格式创建包信息文件 (建议使用 npm init 生成模板)

  • name [String] 组件名称

  • version [String] 当前版本

  • description [String] 简介

  • main [String] 组件入口

  • author 作者/联系邮箱

    2.2. 添加 avm 字段，包含以下信息：

  • platform [Array] 适配平台 {app:native,web:h5 网页,mp:小程序}

  • systemType [Array] 支持的系统类型 {ios,android}

  • keywords [Array] 组件关键字

  • site [String] 支持网站网址

  • price [Number] 整数售价(单位 分)

  • meta [Object] 组件元信息，详情请参考 2.3

    2.3. meta 组件元信息说明

为了更好的规范组件属性和方法信息，特此新增 avm.meta 字段，用于结构化规范组件内容。

其结构如下：

{
  "component": "a-button",
  "desc": "一个快速定义样式尺寸的按钮组件",
  "type": 2,
  "nativeModules": ["aMap", "bMap"],
  "event": [
    {
      "name": "myEvent",
      "desc": "按钮的一个自定义事件",
      "params": [
        {
          "name": "$event",
          "desc": "事件源对象",
          "type": "Event"
        },
        {
          "name": "paramX",
          "tip": "回调参数的说明",
          "type": "string",
          "enum": ["primary", "success", "warning", "danger"],
          "default": "success"
        }
      ]
    }
  ],
  "props": [
    {
      "name": "color",
      "tip": "按钮的颜色",
      "type": "string",
      "enum": ["primary", "success", "warning", "danger"],
      "default": "success"
    }
  ],
  "methods": [
    {
      "name": "myMethod",
      "desc": "一个可以对外使用的方法",
      "params": [
        {
          "name": "paramX",
          "tip": "回调参数的说明",
          "type": "string",
          "enum": ["primary", "success", "warning", "danger"],
          "default": "success"
        }
      ]
    }
  ]
}

上面是一个典型的组件元信息。重点关注以下字段：

  • component 组件名称
  • desc 组件描述（可选，不填取 package.json 的 description）
  • type 组件类型 1：容器类 2：普通类 3：弹窗类
  • nativeModules 组件依赖的原生组件
  • event 组件事件列表 详情参考示例
  • props 组件属性列表 详情参考示例
  • methods 组件提供的外部方法列表 详情参考示例

3. 组件命名规范

3.1. 组件包名即为组件名，并代表该组件的命名空间，组件名需要和 2.1 中提到的 package.json 的 name 保持一致。 组件名称使用全小写，多个单词使用 - （中划线）分割。

3.2. 组件名称需要在 YonBuilder云市场平台全局独立，建议使用个性化特殊前缀来作为组件命名空间。

例如写了一个输入框组件 ，如果直接叫做 input ，则比较泛，需要增加自己的个性标识，或者是使用意图性质的限定词语。

例如：my-input tom-input password-input

3.3. 使用单语言模式的 js 组件的入口文件名推荐使用 index.js ，这样在引入的时候可以只书写到组件根目录即可。

3.4. [重要] 组件样式目前需要附带组件名称作为前缀来形成 scope 。样式规则推荐使用 BEM 规范。

例如组件名称叫做 simple-sfc 那么样式需要附带 simple-sfc 作为前缀

按照 B__E--M 的规范来组织 css 结构，例如：

simple-sfc__title-text--disabled 表示组件（simple-sfc）内的标题的文本（title-text），是禁用状态（disabled）。

3.5. 其他资源和 js 函数命名等无严格要求，建议遵循语言特性和标准编程风格即可。

注：如果组件引入了外部 js 文件，该 js 文件须按照 ES6 规范编写，即该 js 文件可通过 export | import 配对使用。

3.6. 组件中不能携带包括不限于 view text 这类通配选择器，避免干扰页面其他元素样式。 所有出现的 css 选择器必须携带前缀。

4. 组件包 README.MD 文档规范说明

说明文档是组件的说明书，有助于其他开发者更高效便捷地使用组件。请遵循以下示例文档：

请重点关注格式的样式级别。

## 使用方式

import AButton from "../../components/act/a-button.stml";
import AButton from "../../components/act/a-button.js";
或
import "../../components/act/a-button.stml";
import "../../components/act/a-button.js";

## 代码示例

### 按钮类型

按钮支持 default、primary、success、warning、danger 五种类型，默认为 default。

<a-button type="primary">主要按钮</a-button>
<a-button type="success">成功按钮</a-button>
<a-button type="default">默认按钮</a-button>
<a-button type="warning">警告按钮</a-button>
<a-button type="danger">危险按钮</a-button>

[对应的运行效果图]

### 朴素按钮

通过 plain 属性将按钮设置为朴素按钮，朴素按钮的文字为按钮颜色，背景为白色。

<a-button plain type="primary">朴素按钮</a-button>
<a-button plain type="primary">朴素按钮</a-button>

[对应的运行效果图]

## 帮助说明 联系方式等

### 帮助说明

对本组件使用过程中需要特别注意或者额外信息等进行说明。

### 联系方式

如果您在使用本组件过程中，遇到任何问题，可通过 xxx 联系...
是否仍需要帮助？ 请保持联络！
最后更新于 2024/04/24