钉钉开发指南-前端全栈入门篇

前言

初衷

既然你能看到这段内容, 那就是抱着好奇、或观望、或已发现钉钉的商机无限, 有目的深入了解钉钉微应用开发的.
如果已经发现钉钉的商机无限, 那么我们一起学习成长吧!

适合的读者

前端培训毕业生: 如果你对html/css有过学习,初步了解.
初级前端工程师: 如果你对html/css有过1年左右的开发经验, 不了解Node/React.
中级前端工程师: 如果你对Node+React已经有所了解,并进行过一个成熟React项目的的开发经验.

目标

通过分享和交流, 帮助钉钉微应用开发者减少踩坑, 能缩短学习周期, 尽快进入项目开发阶段.

前端培训毕业生: 大约需要1-2个月的时间, 逆向学习,可以开发demo应用
初级前端工程师: 大约需要2周-4周时间,可以了解demo, 开发简单轻量级小应用.
中级前端工程师: 大约需要1-2周时间, 熟悉开发流程, 能设计架构,进行客户项目的开发.

据了解,当前掌握钉钉微应用开发能力的团队,整个项目团队经历了2-3个月熟悉才可以进行项目开发.

学习交流群

理念分享

分享一下本人对钉钉微应用产品的理解:

钉钉生态

钉钉是一个生态环境,是一个商务生产的大生态环境,与社交的生态不同,社交生态是消费型的,商务生产的生态是创造型的. 钉钉的微应用,应该是一个适合服务/工具属性的产品.

微应用定位

微应用从宏观上是处在整个生态的中间层,也是最重要的层次. 阿里的所掌控的云端资源通过微应用与实体企业实现商务活动.

产品使命

为用户提供”单一高效”的业务处理逻辑和交互体验的同时, 与非竞产品合作形成”乐高积木”的解决方案.

个人认为:
对钉钉生态有了正确的认知,才能做出 有意义 的产品; 对客户业务有了深度的体验才能做出 有价值 的产品. 所以,请你和你的团队,真正的去了解钉钉,进行体验和学习,真正了解客户的需求,才能充分发挥钉钉+微应用独特的魅力值.

教程发布的小结

2017.04-05:
教程发布近1个月了,群内的同学已经增加到40名(12名为阿里钉钉及阿里其他部门的支持工程师), 小结一下大家的类型
1. 一部分为已有客户的产品,需要移植到钉钉微应用
  建议重点,和后台同学放到钉钉的鉴权和免登的学习和了解, 先不接触其他学习,避免干扰掉入问题不断涌现的坑
2. 一部分为已确定产品的架构和依赖库,需要定制开发产品的钉钉微应用
  已经掌握react的团队,请反馈建议项目经理在估一下react的依赖库, noaw的开发效率倍增, noflux比redux更好理解好用, react-kepper的更便捷…, 我个人理解学习的成本还是可以有经济效益的, 毕竟这几个库都是阿里同学维护的,开发者都在群内.
  还不了解react的团队,先上手吧,先按教程的react依赖库用, 能跑通理解了.然后再说router-router / redux 等通用的大型的库,
  (偷偷说一下: 找他们请教,还可以得到更多方面的帮助,他们很热心的)

部署开发环境

安装应用程序

Chrome: 安卓WebApp开发必备工具 (点击下载应用)

坑提示: 一定选择稳定版呀,别因个人好奇心出现问题找大家帮助,连带坑了帮你的同学.

移动端:WEB调试 (点击浏览教程)

移动端:真机调试 (点击浏览教程)

Node: 是一个基于 Chrome V8 引擎的 JavaScript 运行环境 (点击下载应用).

坑提示: Mac用户用pkg包安装,用命令行安装的话,可能会遇到权限或者环境变量的手动配置的麻烦.

node.js入门学习指南

VScode: 是由微软研发的一款免费，开源的跨平台文本（代码）编辑器。(点击下载应用)

坑提示: win系统安装时,请注意 全部选择安装选项 , 就可以在项目文件夹右键打开,进行项目编辑了.

VScode的基础使用教程

Git: 是一个开源的分布式版本控制系统，可以有效、高速的处理从很小到非常大的项目版本管理。(点击下载应用)

坑提示: MacO的git包含在Xcode的工具集中,安装Xcode即可

Git简明教程

Cnpm: 完整npmjs.org镜像，你可以用此代替官方版本(只读) (点击浏览官方文档)

npm install -g cnpm --registry=https://registry.npm.taobao.org

坑提示: npm 是随同node.js一起安装的包管理工具, cnpm 是只读的镜像(访问国内淘宝的镜像当然快了.)

npm 简明使用教程

安装开发工具

Nowa: 是阿里内外前端组的静态资源构建工具, 基于webpack的前端开发解决方案集合。(点击浏览官方文档)

安装: https://nowa-webpack.github.io/
下载系统对应版本,进行安装

桌面窗口版教程:https://nowa-webpack.github.io/nowa/
命令行版本教程:https://nowa-webpack.github.io/docs/

参考教程, 创建项目
钉钉开发入门同学,请用dingyou-dingtalk-mobile’ 模板创建项目

模板源码: https://github.com/caohaijiang/dingyou-dingtalk-mobile
模板教程: https://nowa-webpack.github.io/docs/jiao_shou_jia.html
说明: 善用定义自己的脚手架,可以帮助代码开发效率倍增

了解项目demo

打开项目

本教程使用的是VScode, 其他编辑器也可以

win打开项目: 打开’资源管理器’窗口,找到’/appdev/myproj/mobile/‘文件夹,右键使用vscode打开即可 >
mac打开项目: 打开VScode, 在顶部菜单中,选择’文件-打开’,选择项目文件夹,即可.

浏览和启动项目

├── html   
|   └── index.html   
├── src   
|   ├── apis  => api资源配置
|   ├── assets  => 静态资源
|   |   ├── icon  => Svg图标
|   |   └── img  => 图片
|   ├── components  => 公共组件库
|   ├── config  => 多环境配置文件
|   ├── dings  => 钉钉的jsapi接口优化
|   ├── pages  
|   |   └── home  
|   |       ├── components  => Page的私有组件
|   |       ├── pages  => 子页面(路由)
|   |       ├── index.js  => 路由配置
|   |       ├── PageHome.js  => 连接view 和 state的进行业务处理的Page组件
|   |       ├── PageHome.less  => 页面的样式文件
|   |       ├── PageLogic.js  => React状态的逻辑处理
|   |       └── PageConst.js  => 页面的常量状态设置.
|   ├── utils 
|   |    ├── index.js  => 通用函数
|   |    ├── middleware.js  => api处理中间件
|   |    └── shortcuts.js  => 待测试....
|   ├── index.js  => 
|   ├── api.js  => api配置,
|   ├── ding.js  => 钉钉的配置和初始化,
|   ├── noflux.js  => noflux配置,可给组件对象塞全局对象呀,
|   ├── storage.js  => 本地存储初始化,
|   └── routers.js  => 前端顶层路由
├── .eslintrc  
├── .gitignore  => 排出git上传的文件/目录列表
├── abc.json  => nowa环境配置
├── package.json  => node的项目配置
└── webpack.config.js  => antd的适配

启动项目

VScode的基础使用教程

提醒: 请务必勾选设置VScode: 菜单-文件-自动保存 (自动保存后,浏览器会自动刷新)

打开VScode的集成控制台

ctrl+` 注意: 是ESC下方的反引号

输入启动项目命令

npm start

预览项目

1. chrome浏览器打开: http://localhost:3000 . 至此, 您已经启动了一个基于 React开发的钉钉单页微应用,
1. 打开调试控制台: Win系统用 ‘F12’ , Mac系统用 ‘option + command + i ‘ , 并设置为控制台为右侧栏模式
1. 调整预览方式: 点击控制台顶部菜单左侧的按钮’ toggle ‘,设置为 ‘iPhone 6’ 尺寸

阅读代码

基础文件

/.gitignore
我们是用git来推动到代码库的, 如果有不想推送到服务器的文件/目录,就在这里设置.具体可以看 .gitignore配置教程
abc.json
刚刚入门,不需要了解和改动,想深度了解,可以看 Nowa官方文档
- 开发环境和测试(生产)环境如何使用不同配置的秘密,就在里面的 ‘vars’ 和 ‘buildvars’ 配置上.
- 项目开发中,不需要../../../image/a.png 这样多层引用文件,用 src/image/a.png,就可以了, 秘密在’alias’的配置上.

package.json
如果你已经看了node.js入门学习指南这个教程, 自然会明白这个文件的内容.这个demo项目所选的依赖包,都是本着易学好懂,简单好用的原则挑选出来的.
- antd-mobile: 如果你不想在项目的前端开发上,走坑能走到无路的话, 只能用这个ui了. 本人是实践了多个ui,踩坑数月才换到antd上的.
- iscroll: 一个实现可以滑动组件的底层依赖包, 比如可以左右滑动的面包屑 ( Antd官方没有提供,只能自己开发组件 )
- monment: 一个操作’日期时间’的数据非常好用的依赖包
- natty-storage: 一个操作浏览器 localStorage 对象的依赖包
- no-flux: 一个简单的,操作组件交互的依赖包. 初学react,如何操作交互处理呢? 如果要用大众货reflux/redux来处理,你的项目周期就延长一个月吧.
- react-keepr: 替代了大众教程的react-router, 原因是用这个配置和管理前端路由很方便.
- unity-api: 支持restful Api管理的依赖包, 把后台api资源,都装到对象里面用,访问api会非常方便.
webpack.config.js
请勿修改, 这是 Nowa 为使用 Antd / Antd-mobile 的UI库所增加的适配文件

框架文件

src/index.js
很简单,框架核心的按顺序加载,
src/api.js
没有吃透前,请勿修改.使用unity-api的依赖包, 封装了对后台api资源的访问.

作用: 判断环境变量,读取配置文件,创建api对象.

说明: 所引用的 ‘middlewar’是中间件模块. 对api访问进行处理,有log(打印日志), fix(json的过滤处理),mock(使用模拟api资源)
src/ding.js
钉钉官方的demo中,前端index.html获取jsapi的鉴权,真是苦涩难懂. 对此,进行了封装,

通过设置config中的json配置文件, 开发环境和编译可以用两套不同配置.()

jsapi.json文件,方便对了jsapi众多方法的是否使用管理

钉钉api的异步链式调用,封装了同步的方法.

注意 :本处使用的是post提交微应用的url是为了方便多人使用一个微应用协同开发调试,生产环境后台要增加白名单进行限制保障安全.
src/noflux.js
不得不说,从最初的reflux来处理react的状态,到风闻redux是王道去学习,整个搞的头晕脑胀. 阿里无线的同学及时提供了no-flux这个依赖包.前后的学习对比后, no-flux真的是简单好用. 本文件,是对项目中全局状态对象的初始化. 当前的代码实际用途并不是很大.仅供参考.

加载了 api 对象, 这样任意的page中,都可以方便的访问api资源了.

本人,把no-flux的初始化状态对象的特性,理解成预设全局对象的用法了,(呵呵)
src/routers.js
这个是,任何react单页应用,必不可少的前端路由配置文件了. 常用的是React-router这个依赖库, 需要把所有页面的路由规则,都写到这一个文件里面.看起来好繁琐. 自从用了react-keeper后,路由表可以分家用了,感觉维护起来很方便.

作用: 加载路由依赖包, 配置App组件,设置顶层路由表, 将整个单页应用开发的代码,注入到index.html里面,index.html也就是项目提供浏览器的一个壳了.

如果不添加顶层页面,这个文件基本不不需要修改.

pages(页面)文件夹

就理解成mvc,都浓缩到这个5个文件吧. 页面路由,页面开发,业务逻辑都在下面这3个主文件,两个辅文件中.
创建页面的命令是:

# 创建一个页面(一组5个文件)
nowa init page 
# 输入文件名

说明:如文件名’home’,则按模板生成’PageHome.js’等文件, 如果是’home-nav’,则生成”PageHomeNav.js”, 请测试一下,体会区别.

index.js
页面路由定义文件, 定义本页的路由和子页的路由路径;
- 奇怪的写法:
  本人将页面模块和路由规则,封装成了一个json对象, 形成了一个特殊的写法, 个人感觉维护会很方便.
- 页面之间的路由关系:
  相对于上级页面(路由)而言,当前页面存在了单条路由, 包含关系(有子路由),并行关系(不包含). 建议同学深入的去通过看react-router的教程,深入的理解一下路由, 如果是包含关系, /home/nav的结果就是nav这个页面在home里面是嵌如的子组件.明白这个关系后,才能理解demo中,tabbar这个组件,是如何切换嵌入页面的写法. 否则,你的tabbar组件的代码,就要写成百上千行了,维护性非常差.
PageConst.js
仅仅一个常量对象, 在PageLogic中,用assign函数,绑定到这个页面的this.state的状态中.拆分开是方便阅读和维护.
PageHome.js
最重要的就是这个文件了, 这个文件把logic(状态处理)、less（样式表）、commponent（复用组件)等团结到了一起.实现了我们的业务交互。
- import部分：导入页面所需的各种模块，不用担心各个页面导入多了，编译构建的时候不会有冗余代码。
- constructor: 状态已经被logic剥离出去管理了, 这里的作用就是绑定事件了,照抄格式来写事件吧,慢慢就明白,如果不这样绑定事件到this对象上,会有可能调入this坑就郁闷了. 什么是this坑? 看看这个
- render: 终于看到渲染了, 页面显示什么,核心的就是这个了,其他代码都是为render服务的.
  
  const 定义展开this.state | this.props | this.pr ,是个人习惯怕忘记变量都有什么,也方便下面代码精简使用. (展开,我认为是个好习惯)
  
  render和return之间如果,你调试写入 console.log(111)的话,在浏览器控制你会发现突突突,输出好几遍.多次输出是否代码写错了? 这是正常的别掉坑,当初我就为这个纠结了一个星期. 真正的去理解了react的状态改变的机制,才明白.setState是唯一改变状态的方法这句话;才明白react的单向数据流.
- return: html标签里面嵌套js的混合代码开始了. {}里面是js代码, 外面包裹的是html标签写法,很新奇吧.
  
  注意 : return里面最外层标签只能是一对, 不能写多个呀.
- componentDidMount: 生命周期函数登场了. 参考文档看这个. 生命周期好多函数,其实最常用的是:
  
  componentWillMount: 在完成首次渲染之前调用，此时仍可以修改组件的state。加载数据可以放这里
  
  componentDidMount: 真实的DOM被渲染出来后调用,
Pagehome.less 被渲染组件的样式默认的不合适,需要修改? 写到这个里面吧.
关于样式修改,不用less的话, 还可以这么写( 注意css中text-align, 在style中要写成 textAlign 这种格式 )
1
2
3
<div style = {{ display:'inline-block' }}
...
</div>
PageLogic.js

components(组件) 文件夹

创建组件命令

# 创建函数组件(无状态和生命周期的组件)
nowa init mod 
# 创建react组件(有内部状态和生命周期的组件)
nowa init rmod

任务1: 写一个函数组件.

参考demo和antd-mobile文档,写一个list组的组件
用数组灌入多个list.item的属性, 运用js的map函数循环渲染, 实现一组list.item的组件.
任务2: 写一个react组件.

同上,区别是用react组件实现.
思考: 两类组件区别是什么?
本人建议尽量用函数组件来实现比较好,如果组件内部必须有状态或者生命周期的话用react组件

学习方法

到这个时候, 想必你已经花了半小时,甚至半天时间了, 如果要看其他目录的代码的话, 估计没有学习过react的同学会很晕, 这么多代码要搞懂何年月了?
接下来怎么了解呢? 接下来个人认为要经历几个阶段.

破坏学习:

不同位置,添加大量的console.log(111),onsole.log(222),onsole.log(333),了解js的异步和react的各个模块的执行顺序.
修改删除demo, 造成一些破坏,观察控制台出错代码,了解各种错误和起因.

探究学习: 带着下面的问题学习.

修改和添加demo中的 button 组件的状态,看看变化? => antd的组件简单用法
修改demo中的 button 组件的处理函数,看看变化? => noflux的简单用法
在demo中的创建一个简单的公共组件,看看怎么封装复用组件? => 函数组件的创建和React组件的创建用法?
新建一个页面,怎么挂到路由能访问? => react-keeper的简单用法
怎么从api中获取json数据,在页面里面使用呢? => unity-api的简单用法

模仿学习:

对整个demo的所有代码,懂不懂,先浏览一下,各种函数/对象等的用法,
尤其是对nowa init mod / nowa init rmod / nowa init page,这三个命令创建的文件模板的代码,(都是最常用的)

基础学习: 经历过破坏学习,看到那么多不懂的代码的时候,会发现还有不少的基础知识要学习和了解.

JavaScript的问题
1. js的异步编程是怎么理解的?
2. js的闭包是怎么理解的?
3. [js的异步坑/回调坑是怎么回事?] (https://zhuanlan.zhihu.com/p/20322843?columnSlug=FrontendMagazine)
4. 回调处理=>链式调用(Promise) => 异步变同步 (async/await)的进化
5. js的import/export的理解和使用
6. 对js新版本ES6的了解(作为参考工具吧)
React的问题
1. 组件是什么? 怎么是代码混合的? 组件的父子关系?
2. 什么是组件的属性, 什么事组件的状态?
3. 单向数据流是怎么回事? 它和状态是什么关系?
4. 组件的生命周期有哪些? 常用的那几个?
5. 组件式怎么定义的? 函数组件和react组件的区别是什么?

钉钉微应用开发

上面啰嗦那么多,其实都是js+react的教程. 当然,有同学会问,钉钉的微应用前端开发必须是react吗?

传统的html+js+css+jq可以吗? => 可以的
vue可以吗? => 可以的

为什么要用react?

当今,前端工程化的发展,传统的技能落后了, 产品的体验和开发效率要求高多了. 不用主流技术不行呀.
迄今为止,antd的ui库,是最棒的中文库(英文不知道,本人见识少), 从文档详细/demo生动, 到组件的齐全性. 基本上css+div代码都不用写.拿来就用直接做产品1.0版本没有啥问题.这开发是什么效率? 想用吗? 嘻嘻嘻,它是react的. 你不用能行吗?
阿里技术栈以node+react/vue为主,钉钉这边是react. 咱们的群支持的有阿里牛,在难的问题有后盾呀.
其他各种就不争论了, 本人不会其他的,只能在react+antd前行了一小步, 能分享大家这些经验.

硬件环境

android: 安卓手机一台 + USB数据线一条 + win/mac/linux开发电脑一台
iphone: MacMini(8G) / Macbook / iMac 一台

4G内存的mac mini,我一直是在内存99%情况运行, 同学你用不用8G内存看着办吧.
!!!,以上均建议多屏显示器(2个/3个)开发.会比较方便.

同时要开的窗口: 编辑器(2栏/2窗) | 浏览器 | devtools | 钉钉(QQ/微信) | … 哎屏太小了,就忙着切换窗口了.

调试环境

当你调用到钉钉的jsapi的时候, 需要在钉钉微应用里面执行, 单纯的使用浏览器的调试,已经不能呈现报错信息了.因此: 建议用安卓真机调试做主开发,MacOS做兼容性测试.

安卓手机: 真机安装开发版或者内测版,USB线连接电脑, chrome浏览器地址输入: chrome://inspect/#devices ,使用devtools进行调试

苹果手机: MacOS系统,安装xcode, 使用虚拟机进行调试(没有再好的办法了)
下载钉钉iphone开发版到 ~/App/ 目录

# 启动模拟器 
xcrun instruments -w 'iPhone 6 Plus'
# 安装dingtalk开发版；
xcrun simctl install booted ~/App/Dingtalk.app 
# 安装应用： 
xcrun simctl install booted Calculator.app

启用钉钉jsap sdk

src/config/develop.json

1	DINTALK_API": true,

如果没有这个设置,上面的基础教程学习过程,钉钉的鉴权报错看起来不舒服.

进入学习体验环境

加入钉钉开发学习团:

启用应用

启动设备: android用真机用usb数据线,连接开发电脑,iPhone用模拟器启动应用,
打开应用: 切换工作台到’钉钉开发学习团队’, 打开微应用’入门demo’;

进入调试

打开chrmoe浏览器,地址栏输入: chrome://inspect/#devices

坑提示: 如捕获不到,彻底关闭浏览器或插拔Usb,就好了.

应用钉钉jsapi

用法: 项目中直接使用 (dd这个类是全局类了,jsapi鉴权正常,就可以用了)
1
dd.biz.navigation.setTitle({ title:'Home' })
如果直接使用无效,就用dd.ready包裹起来用
dd.ready( function () {
dd.biz.navigation.setTitle({ title:’Home’ })
});

坑提示: 尽早掌握好ES6/7的async/await用法, 变异步为同步,避免调入回调坑.

部署篇 (简述)

测试服务器: { centos + node + mysql + nginx } + { authServer + appServer + jsonServer }

authServer: 独立的钉钉鉴权api服务,与应用服务剥离开.

jsonServer: 模拟数据api服务 ( 拜托后台进度的制约,并且有助于后台参考进行高效开发 )

appServer: 独立的应用api服务

后台支持

当前没有后台工程师给开发钉钉jsapi的鉴权服务怎么办?

为了帮助前端开发初学在缺少后台工程师的支持下, 进行自建微应用,学习钉钉微应用的开发, 本人搭建了一个’钉钉开发学习团’的学习鉴权服务, 以供搭建学习体验,

使用方法

工作台-审批-微应用申请: 提交开发电脑的ip地址和微应用中文名称

钉钉开发学习团的后台管理员,为您创建微应用,并授权您为该应用的子管理员
审批返回,您所需要在config中填写参数.

建议,产品经理&前端开发,一起了解和体验体验jsapi的使用.有助于产品少走弯路;

建议: antd-mobile ui非常棒,产品需求没有高标准的美化情况下,尽量不安排专业ui设计师介入,因为缺乏钉钉了解,反而会拖慢进度.做很多无用功.

前言

初衷