本地与云端组件开发与管理-移动开发平台 mPaaS-阿里云

说明

ACT 请使用 4.0 及以上版本。
ACT 在编译过程中使用了组件的卡片时需要依赖 npm 8.0 及以上版本，如果当前 npm 版本过低可能会导致编译异常，请及时升级 npm 工具。
- 查看 npm 当前版本：npm --version
- 升级 npm 至最新版本：npm install npm -g

概述

卡片组件（以下简称组件）是一种卡片结构化组织的形式。利用 Cube 卡片提供的组件能力，可以将一个大的卡片效果分拆为多个原子组件进行管理和维护，同时组件允许被不同的卡片引用，从而提高了卡片通用效果的复用能力。

构成

一个组件就像一个迷你的卡片，主要由 组件主体（main.vue） 和 组件配置（manifest.json）两个文件构成。

同一个卡片的能力一样，适用于卡片的布局、样式、标签、逻辑处理等基础功能，以及 css import、js import 等进阶功能也同样适用于组件。

说明

组件本身并不能独立存在，必须应用到卡片中时才会在编译阶段被识别并解析，相应的以下类型文件的使用方式组件与卡片将有所区别。

文件	作用	组件场景	卡片场景
.act.config.json	ACT 编译配置文件	不需要	需要
mock.json	模板预览时的 mock 数据	不需要，可以直接在卡片对应的 mock.json 内设置。	需要

使用

组件按照管理维护的方式可以分为 本地组件 和 云端组件。

本地组件

开发人员可以在一个卡片的源码工程内维护一个卡片使用到的组件源码，这类组件源码被称为 本地组件。

文件构成

一个本地组件主要由 main.vue 和 manifest.json 两个文件构成。

.
├── main.vue
└── manifest.json

创建组件

在需要存放组件的文件夹内执行 act 命令。

➜  ~ act init
? 请选择应用类型
  Cube 模板卡片 (VUE格式)
❯ Cube 卡片组件 (VUE格式)


➜  ~ act init
? 请选择应用类型 Cube 卡片组件 (VUE格式)
? 请输入组件名称 local-component
? 请选择组件管理形式 (Use arrow keys)
❯ 内置于卡片工程
  分享到NPM云端

卡片关联组件

在需要使用组件的卡片中可以通过配置卡片 manifest.json 文件的 useComponents 字段来声明关联组件。

# 卡片的 manifest.json 文件

{
    ...
    "useComponents": {
        "local-component": "./components/LocalComponent",
        "local-component-2": {
            "path": "./components/LocalComponent2",
            "type": "local"
        }
    },
    ...
}

# 卡片的 main.vue 文件

<template>
  <div class="root">
  	<local-component class="comp"></local-component>
  	<local-component-2 class="comp2"></local-component-2>
  </div>
</template>

useComponents 的取值为一个 Key-Value 键值对，其中 Key 为组件应用到 卡片中的标签名，Value 为关联 组件的来源信息。

Value 支持 String 和 Object 两种格式。

String：关联组件的根目录路径（即组件 manifest.json 文件所在的目录路径）
- 相对路径：表示组件根目录相对于卡片 manifest.json 文件的路径。
- 绝对路径：表示组件根目录的绝对路径。
Object：关联组件的来源配置。
- path：关联组件的根目录路径（即组件 manifest.json 文件所在的目录路径），也同样支持相对路径和绝对路径两种格式。
- type：local（可选字段，当使用路径配置时 type 字段默认取值即为 local）。

组件关联组件

如同在卡片中关联组件一样，也可以在组件中关联组件。为了方便表述，我们把使用组件的组件称之为宿主组件，把被关联的组件称为关联组件。

在需要使用关联组件的宿主组件中也可以通过配置宿主组件 manifest.json 文件的 useComponents 字段来声明关联组件。

# 宿主组件的 manifest.json 文件

{
  ...
  "isComponent": true,
  "useComponents": {
    "other-component": "../LocalComponent2"
  },
  ...
}

# 宿主组件的 main.vue 文件

<template>
  <div class="root">
    <other-component class="comp"></other-component>
  </div>
</template>

重要

配置中关联组件的相对路径应该指代的是 关联组件根目录 相对于 宿主组件 manifest.json 文件的路径。

云端组件

开发人员可以通过 npm 包管理平台将组件的源码发布到云端维护，这类组件源码被称为 云端组件。

文件构成

一个云端组件主要由 组件主体（main.vue）、组件配置（manifest.json）、npm 配置（package.json）三个文件构成。

.
├── main.vue
├── manifest.json
└── package.json

说明

npm 配置文件的使用技巧详情请参考 npm Docs。

创建组件

在需要存放组件的文件夹内执行 act 命令。

➜  ~ act init
? 请选择应用类型
  Cube 模板卡片 (VUE格式)
❯ Cube 卡片组件 (VUE格式)


➜  ~ act init
? 请选择应用类型 Cube 卡片组件 (VUE格式)
? 请输入组件名称 cloud-component
? 请选择组件管理形式
  内置于卡片工程

卡片关联组件

在需要使用组件的卡片中可以通过配置卡片 manifest.json 文件的 useComponents 字段来声明关联组件。

# 卡片的 manifest.json 文件

{
  ...
  "useComponents": {
    "cloud-component": "@ali/card-component-cloud-component",
    "cloud-component-2": {
      "path": "@ali/card-component-cloud-component-2",
      "type": "cloud"
    }
  },
  ...
}

# 卡片的 main.vue 文件

<template>
  <div class="root">
  	<cloud-component class="comp"></cloud-component>
  	<cloud-component-2 class="comp2"></cloud-component-2>
  </div>
</template>

useComponents 的取值为一个 Key-Value 键值对，其中 Key 为组件应用到 卡片中的标签名，Value 为关联 组件的来源信息。

Value 支持 String 和 Object 两种格式。

String：关联组件的 npm 包名。
Object：关联组件的来源配置。
- path：关联组件的 npm 包名。
- type：cloud（可选字段，当使用 npm 包名时 type 字段默认取值即为 cloud）。

组件关联组件

如同在卡片中关联组件一样，也可以在组件中关联组件。为了方便表述，我们把使用组件的组件称之为 宿主组件，把被关联的组件称为 关联组件。

在需要使用关联组件的宿主组件中也可以通过配置 宿主组件 manifest.json 文件的 useComponents 字段来声明关联组件。

# 宿主组件的 manifest.json 文件

{
  ...
  "isComponent": true,
  "useComponents": {
    "cloud-component": "@ali/card-component-cloud-component"
  },
  ...
}

# 宿主组件的 main.vue 文件

<template>
  <div class="root">
    <cloud-component class="comp"></cloud-component>
  </div>
</template>

安装云端组件

在卡片工程中，同本地组件的使用方式不同，由于云端组件源码都是在 npm 平台维护，在编译卡片之前，需要先将卡片依赖的云端组件下载到卡片本地工程中，这个过程在 npm 机制中被称为安装依赖。

在卡片工程安装组件依赖之前，需要先在卡片工程的根目录（即卡片 .act.config.json 文件所在目录）下创建 package.json 文件。

可以通过 npm init 命令创建 package.json 文件，也可以手动创建 package.json，只要符合 JSON 格式即可。

➜  ~ npm init -h

npm init [--force|-f|--yes|-y|--scope]
npm init <@scope> (same as `npx <@scope>/create`)
npm init [<@scope>/]<name> (same as `npx [<@scope>/]create-<name>`)

aliases: create, innit

初次安装 某个云端组件的 npm 包时，可在卡片工程根目录下执行 npm install [<@scope>/]<pkg>@<tag> --save 命令，这样云端组件包将自动被放置到卡片工程根目录的 node_modules 文件夹下；同时会在工程 package.json 文件的 dependencies 字段中自动添加上关联的云端组件 npm 包依赖信息。

说明

node_modules 为 npm 包管理工具通过 install 命令临时生成的文件夹，无需维护到 Git 仓库，请及时添加 .gitignore 即可。
为了确保组件在被卡片使用到时的行为能符合最新预期，请将云端组件 npm 包依赖版本强制更改为 latest。

代码示例

重要

package 不一定能通过 npm下载到。

npm install @ali/card-component-my-cloud-component@latest --save

# 卡片工程根目录下的 package.json 文件

{
  ...
  "dependencies": {
    "@ali/card-component-my-cloud-component": "latest"
  },
  ...
}

需要更新 或 重新安装 已经在卡片工程根目录下 package.json 内配置的云端组件包时，在卡片工程根目录下直接执行 npm install 即可。

说明

为了确保再次安装时已配置的组件都能得到及时更新，请在执行 npm install 前将 node_modules 文件夹删除，或执行如下命令：

macOS：rm -rf ./node_modules && npm install
Windows：rm ./node_modules -r -fo, npm install

发布云端组件

发布一个云端组件同发布一个普通的 npm 包相同，详情请参考 npm 发布。

说明

云端组件发布时请确保必要的 main.vue、manifest.json 文件均包含在被发布的文件列表中。