文档

1. 快速开始

更新时间:
重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

本文介绍开发自定义组件的流程。

环境准备

本地需要安装如下内容:

  1. node.js 16.X版本。

脚手架工具安装

  1. 点击下载脚手架工具包(v0.0.8 2023.9.5)。

  2. 解压到合适的目录。

  3. 打开命令行工具,安装脚手架工具。

    // 下载并解压mobi-cli.zip,进入到mobi-cli目录
    % cd path/to/mobi-cli
    // 查看目录绝对位置
    % pwd
    /Users/xxx/path/to/mobi-cli
    // 本地安装 /Users/xxx/path/to/mobi-cli 替换为上一步获取的路径
    % npm install -g /Users/xxx/path/to/mobi-cli
  4. 执行 mobi -V 命令,查看安装结果,正确输出版本号,安装成功。

    % mobi -V
    0.0.8

脚手架工具更新

当脚手架工具更新时,需要手动卸载,然后再安装。 卸载命令:

% npm uninstall -g @ali/mobi-cli-cloud

然后下载新版本的脚手架工具,重新安装即可。

说明

部分电脑因为权限限制,需要添加 sudo 命令,才能在全局安装和卸载脚手架工具。

添加 sudo 命令后的安装和卸载命令:

// 安装
% sudo npm install -g /Users/xxx/path/to/mobi-cli
// 卸载
% sudo npm uninstall -g @ali/mobi-cli-cloud

初始化项目

  1. 创建一个文件夹,用于存放自定义组件代码,打开命令行工具,进入文件夹:

    // path/to/somewhere 为准备存放自定义组件的目录
    % cd path/to/somewhere
    警告

    初始化项目时会清空当前文件夹。

    建议新建一个文件夹来存放项目。

    每个项目必须单独一个文件夹。

  2. 执行 mobi init 命令,并根据提示操作:

    % mobi init
    开始初始化组件...
    ? 请选择物料类型: (Use arrow keys)
    ❯ PC组件 
      多端小程序组件 
    
    // 回车 选择PC组件
    
    开始初始化组件...
    ? 请选择物料类型: PC组件
    ? 请选择仓库形式: (Use arrow keys)
    ❯ 单个组件 
    
    // 回车选择单个组件
    
    开始初始化组件...
    ? 请选择物料类型: PC组件
    ? 请选择仓库形式: 单个组件
    ? 请选择物料模版: (Use arrow keys)
      基础模版 
    ❯ 文本组件 
      容器组件 
      List组件 
      数据选择框组件 
    
    // 按向上键 切换到基础模版,回车 
    
    开始初始化组件...
    ? 请选择物料类型: PC组件
    ? 请选择仓库形式: 单个组件
    ? 请选择物料模版: 基础模版
    ? 请输入物料英文名称:(会自动添加`@mobix/mobi-xxx-`前缀) (test) 
    
    // 输入一个合适的名字 这里以ComponentABC为例
    
    开始初始化组件...
    ? 请选择物料类型: PC组件
    ? 请选择仓库形式: 单个组件
    ? 请选择物料模版: 基础模版
    ? 请输入物料英文名称:(会自动添加`@mobix/mobi-xxx-`前缀) @mobix/mobi-pc-ComponentABC
    设置完成,开始下载组件模板...
    下载组件模板成功, 开发替换模板
    开始安装依赖...
    
    added 2947 packages in 50s
    
    4 packages are looking for funding
      run `npm fund` for details
    
    ************************************************
     _          _ _                         _     _ 
    | |__   ___| | | ___    _ __ ___   ___ | |__ (_)
    | '_ \ / _ \ | |/ _ \  | '_ ` _ \ / _ \| '_ \| |
    | | | |  __/ | | (_) | | | | | | | (_) | |_) | |
    |_| |_|\___|_|_|\___/  |_| |_| |_|\___/|_.__/|_|
    
    依赖安装成功!
    项目初始化成功!
    执行 mobi dev ,开始愉快的搬砖之旅吧 ~ ~
    ************************************************
  3. 最终看到 hello mobi 的图案,表示初始化项目成功。

编译构建

  1. 执行 mobi build 命令,生成自定义组件产物。

    % mobi build
    @alib/build-scripts 0.1.32
    info file index.scss copy successfully! 
    info generate style.js to es 
    info file index.scss copy successfully! 
    info generate style.js to lib 
    info Compiling ts declaration ... 
    info Generate es and lib successfully! 
                                             100% 
    info WEBPACK Hash: 6bdc37fa3543f75d5516
    info WEBPACK Version: webpack 4.46.0
    info WEBPACK Child
    info WEBPACK     Hash: 6bdc37fa3543f75d5516
    info WEBPACK     Time: 2057ms
    info WEBPACK     Built at: 2023/08/24 10:46:42
    info WEBPACK                      Asset       Size  Chunks             Chunk Names
    info WEBPACK     MobiPcComponentABC.css  144 bytes       0  [emitted]  MobiPcComponentABC
    info WEBPACK      MobiPcComponentABC.js   3.89 KiB       0  [emitted]  MobiPcComponentABC
    info WEBPACK Compiled successfully
    开始构建压缩包
    构建完成
    开始构建压缩包
    构建完成
    打包完成,产物已构建至:/path/to/somewhere/dist.zip,请将此文件上传至mobi控制台
  2. 构建完成后,会在当前目录下生成 dist.zip 文件,为自定义组件产物。

发布

  1. 打开并登录控制台 https://mobi.console.aliyun.com/home

  2. 创建一个测试自定义组件的应用,或者打开一个现有的应用。

  3. 点击组件面板的添加自定义组件按钮。image.png

  4. 在弹窗中,上传自定义组件图标,输入自定义组件名称和使用说明,点击下一步。image.png

  5. 上传构建产生的 dist.zip 文件,点击完成新建。image.png

  6. 新建完成后,在自定义组件面板会显示新建的自定义组件,表示发布成功。image.png

  7. 现在,就可以正常使用自定义组件。image.png

调试

在应用搭建时调试本地自定义组件

  1. 使用合适的前端编辑器打开自定义组件项目,这里以 VScode 为例。src 目录是自定义组件的源码目录。image.png

  2. 打开 src/index.tsx 文件,修改显示的文字内容。image.png

  3. 打开命令行工具,执行 mobi dev 命令:

    % mobi dev
    @alib/build-scripts 0.1.32
                                             100% 
                                             100% 
    info Hash: bb2d5cd1fd006ee108ed8b3c7697ae4e7e13b902
    Version: webpack 4.46.0
    Child
        Hash: bb2d5cd1fd006ee108ed
        Built at: 2023/08/24 11:06:10
                    Asset       Size  Chunks                   Chunk Names
            css/index.css   18.7 KiB   index  [emitted]        index
        css/index.css.map   26.4 KiB   index  [emitted] [dev]  index
               index.html  345 bytes          [emitted]        
              js/index.js   3.11 MiB   index  [emitted]        index
          js/index.js.map   2.85 MiB   index  [emitted] [dev]  index
        Child HtmlWebpackCompiler:
                                  Asset      Size               Chunks  Chunk Names
            __child-HtmlWebpackPlugin_0  5.02 KiB  HtmlWebpackPlugin_0  HtmlWebpackPlugin_0
    Child
        Hash: 8b3c7697ae4e7e13b902
        Built at: 2023/08/24 11:06:13
                         Asset       Size  Chunks             Chunk Names
        MobiPcComponentABC.css  144 bytes       0  [emitted]  MobiPcComponentABC
         MobiPcComponentABC.js    178 KiB       0  [emitted]  MobiPcComponentABC 
    info 
    info  Starting the development server at: 
    info    - Local  :  http://127.0.0.1:3333/
    info    - Network:  undefined
    

    此时会自动打开浏览器,打开 http://127.0.0.1:3333/image.png

  4. 根据在线测试组件提示,浏览器切回刚才发布自定义组件的应用,打开浏览器的开发者工具(以Chrome为例按F12),点击控制台(Console)标签,输入命令:

    localStorage.setItem('CCS_NAME', 'MobiPcComponentABC')
    localStorage.setItem('CCS_MobiPcComponentABC', 'http://127.0.0.1:3333/MobiPcComponentABC.js,http://127.0.0.1:3333/MobiPcComponentABC.css')
    image.png
  5. 刷新页面,等待页面加载完成。image.png

  6. 应用会加载本地开发中的组件,这样就可以在应用中调试自定义组件。

在预览环境调试本地自定义组件

  1. 打开应用的设计时页面,点击预览,预览成功后,点击访问应用。image.png

  2. 此时加载的是自定义组件的正式版本。image.png

  3. 打开浏览器的开发者工具(以Chrome为例按F12),点击控制台(Console)标签,输入命令:

    localStorage.setItem('CCS_NAME', 'MobiPcComponentABC')
    localStorage.setItem('CCS_MobiPcComponentABC', 'http://127.0.0.1:3333/MobiPcComponentABC.js,http://127.0.0.1:3333/MobiPcComponentABC.css')
    image.png
  4. 重新加载页面。会加载本地自定义组件,即可进行调试。image.png

停止调试本地自定义组件

  1. 如果要切换回自定义组件的正式版本,在浏览器的开发者工具控制台(Console)标签下,输入以下命令,重新刷新页面即可:

    localStorage.removeItem('CCS_NAME')

接下来

在进一步开发自定义组件之前,请查看2. 自定义组件说明了解自定义组件。