简介

KK Web 应用指的是能够在 手机 KK 平台当中运行的 Web 应用。这些 Web 应用运行在 KK 平台的 Webview (可视为浏览器)中，不仅可以使用浏览器运行环境提供的绝大多数 API，还可以通过 javascript 调用平台的提供的原生能力接口，另外还能通过客户端访问平台的数据。KK Web 应用目前有离线应用和在线应用两种 Web 应用形态。

该文档目的是便于让 KK Web 应用开发者熟悉整个 KK Web 应用开发的流程以便于实现快速开发 KK Web 应用的目的。我们接下来会分开重点以及详细地阐述每一个开发阶段，并且会对每一个开发阶段可能会遇到或者存在的问题，提供详细的解答。

Web 应用开发流程

整个 Web 应用开发可以简单地分为如下几个流程：

  1. 环境搭建 --- 搭建 Web 应用开发所需的工具和环境

  2. 开发前期 --- 应用立项，产品经理确定需求和原型；设计师根据原型和需求确定设计；前端和后端协商，最后由后端拟定接口

  3. 应用开发 --- 根据应用原型、设计和接口文档，开始应用前端代码撰写，开发进入实质性的阶段

  4. 应用调试 --- 对 Web 应用进行调试

  5. 应用测试 --- Web 应用部署到测试环境当中，进行小范围或者公开测试

  6. 应用发布 --- Web 应用通过测试，到 KK 控制台配置应用上线

环境搭建

所谓工欲善其事，必先利其器。借助强大的开发工具搭建起来的开发环境，可以让我们在 Web 应用开发的工作更有效、更专业、更具质量。有些开发工具甚至是不可或缺的，失去了它们的支持，会导致我们的 Web 应用开发无法完成

IDE/编辑器

Web 应用的开发，可使用 WebStorm、Sublime Text（推荐）、Atom 等工具进行开发，开发者可根据自身对开发工具的熟悉程度选择合适的开发工具。

  1. Visual Studio Code --- 集 Sublime Text 和 Westorm 优点于一身的 web 编辑器，其内置丰富的插件
  2. Sublime Text (推荐) --- 功能丰富的轻量级编辑器
  3. Webstorm --- 非常强大的 Web 重量级开发工具
  4. Atom — github 出品功能丰富的 web 编辑器

介于 Sublime Text 更为轻便和易于上手的特点，我们推荐刚入门 Web 应用开发的开发者使用它作为自己的第一款开发编辑器

Sublime Text

安装

  1. 访问 Sublime Text 下载地址，选择下载与系统对应的版本

  2. 根据引导完成安装

配置

  1. 安装 Package Control，通过 Package Control ，我们可以管理和安装 Sublime Text 其它相应的插件

    1. 通过键入 ctrl + ` 或是通过菜单项 View -> show console 的方式打开 Sublime Text编辑器的控制台

    2. 在控制台中输入以下相应的代码，并按回车执行

      import urllib.request,os,hashlib; h = ‘2915d1851351e5ee549c20394736b442’ + ‘8bc59f460fa1548d1514676163dafc88’; pf = ‘Package Control.sublime-package’; ipp = sublime.installed_packages_path(); urllib.request.install_opener( urllib.request.build_opener( urllib.request.ProxyHandler()) ); by = urllib.request.urlopen( ‘http://packagecontrol.io/‘ + pf.replace(‘ ‘, ‘%20’)).read(); dh = hashlib.sha256(by).hexdigest(); print(‘Error validating download (got %s instead of %s), please try manual install’ % (dh, h)) if dh != h else open(os.path.join( ipp, pf), ‘wb’ ).write(by)

      如出现报错，可到官网参考详细的说明

  2. 由 Sublime Text 菜单项 Preferences -> Settings-User，进入编辑器的自定义偏好设置, 在配置中插入以下配置项并保存：

    {
  // 设置在80字符宽度处显示竖线，提示单行代码不要过长
  "rulers":[80],
  // 单个tab大小为2个空格
  "tab_size": 2,
  // 自动将tab转换为空格
  "translate_tabs_to_spaces": true,
  // 自动换行
  "word_wrap": true
}

  3. 由 Sublime Text 菜单项 Preferences -> Package-Settings -> Package Control -> Settings-User， 进入 Package Control 的自定义偏好设置, 在配置中插入以下配置项, 保存并重启 Sublime Text ：

    {
  "bootstrapped": true,
  "in_process_packages": [],
  "installed_packages": [
    // 代码对齐工具
    "AlignTab",
    // 编码输入字符串时 自动提示文件路径／文件名
    "AutoFileName",
    // 括号高亮
    "BracketHighlighter",
    // 将不同编码的代码文件转换至utf8
    "ConvertToUTF8",
    // 快速生成代码注释块
    "DocBlockr",
    // html, css 快捷输入
    "Emmet",
    // html, js, css 美化
    "HTML-CSS-JS Prettify",
    // 常用js代码片段
    "JS Snippets",
    // less语言高亮
    "LESS",
    // 提升sublime text 编辑markdown的体验
    "MarkdownEditing",
    // sublime text插件管理工具
    "Package Control",
    // sidebar 右键菜单增强工具
    "SideBarEnhancements",
    // 代码自动提示
    "SublimeCodeIntel",
    // 代码语法错误校验引擎
    "SublimeLinter",
    // css 语法校验
    "SublimeLinter-csslint",
    // html 语法校验
    "SublimeLinter-html-tidy",
    // js 语法校验
    "SublimeLinter-jshint",
    // js 编码风格校验
    "SublimeLinter-jscs",
    // 根据设定的代码风格，快速格式化代码
    "JSCS-Formatter",
    // 快速清除空白字符
    "Trimmer",
    // 字符串URL编码及解码工具
    "URLEncode"
  ]
}

  4. 重启 Sublime Text ，Sublime Text 陆续安装刚才配置的插件

使用

  1. Sublime Text 全程指南
  2. Sublime Text 教程
  3. 如何优雅地使用 Sublime Text

这里还提供便携版本的 Sublime Text 。便携版本的 Sublime Text 已经完成了对上述内容的配置，你只需要把压缩包下载下来，解压之后就能运行使用

注意：便携版本的 Sublime Text 只适用于 Windows 操作系统

浏览器

  1. Chrome（推荐）— 由 Google 开发的网页浏览器
  2. Firefox — 由 Mozilla 开发的网页浏览器

Node.js

Node.js 是一个基于Chrome V8 引擎的 JavaScript 运行时

在这里，我们演示安装 Node.js 的方法：

  1. 访问 Node.js 官方安装包下载地址：Node.js Download

    ​

  2. 根据你当前电脑操作系统的不同，选择所需要的 Node.js 安装包

    推荐下载 Node.js 的LTS(Long-term Support) 版本作为安装的使用版本，LTS 版本更为稳定，也更适合用于生产环境当中。当前的 LTS 版本为 “6.11.1”。

  3. 安装包下载到本地后，双击下载后得到的安装包，弹出软件的安装界面，如下所示：

    ​

  4. 根据引导，完成对 Node.js 的安装

    ​ ​

  5. 检测 Node.js 是否安装成功

    在 Windows 下键入 win + r ，输入 cmd ，打开命令提示符（在 macOS 下则是打开 terminal ）；在命令行中输入 node -v 检查 Node.js 版本：

    ​

    如果正常输出显示你刚才的安装版本，则表示 Node.js 安装完成！

详细的关于 Node.js 的学习和使用，请访问：

  1. 七天学会 Node.js

应用开发

Web 应用开发阶段是整个最核心，同时也是最关键的阶段。为了简化和便于开发者实现快速开发 KK Web 应用，我们搭建了两套工具：Solo 和 KK JS-SDK 去实现这样的目的。

Solo 应用开发框架

Solo 是一款基于 Vue 构建的移动 web 应用框架。它与 Vue 核心深入整合，使 Vue 构建体验接近于原生应用的单页应用程序变得轻而易举。Solo 核心功能点包括：

  • 应用路映射应用页面
  • 提供多种页面过渡动画，为页面间切换时提供良好的过渡效果
  • 内置 debounce , throttle , formatTime 格式化时间等实用工具函数

关于 Solo 应用开发框架的具体使用和详细文档请移步参考：Solo Web 应用框架

KK JS-SDK

KK JS-SDK 根据 native API 的功能在 js 层封装了多个方法，Web 应用开发人员只需调用 KK JS-SDK 中提供的 API 方法即可实现对平台端 native API 的调用。

关于 KK JS-SDK 的具体使用和详细文档请移步参考： KK JS SDK

应用调试

https://developers.google.cn/web/tools/chrome-devtools/

在开发工程中，很多方面都需要借助调试工具，如显示有问题、逻辑问题、语法错误等，这里介绍浏览器、模拟器和设备真机三类调试的途径。

在电脑上使用 Chrome 模拟器调试

通过浏览器直接调试，Chrome 和 Firefox 的开发者工具都很好用。

这里推荐使用 Chrome DevTools(Chrome开发者工具)，Chrome 的渲染引擎是 webkit，而 Android 浏览器和 Safari 的内核也是 webkit，所以更接近真机的运行环境，我们只介绍下 Chrome 模拟移动端进行调试。

开启移动设备模拟

首先开启一个 Web 服务，在浏览器打开项目地址，界面下如图。

F12 打开浏览器 开发者工具，或者手动打开浏览器 开发者工具，操作如下：

设置成移动设备视图后，选择一种设备，开启模拟触摸屏，这样就可以在 Chrome 中模拟移动设备轻松调试了。

使用Chrome调试

Chrome 调试需借助内置的Chrome DevTools(开发者工具)，开发工具的使用方法可参考：

直接用Chrome调试方便快捷。但是也存在一些局限：

  • 无法调用客户端能力，涉及到能力的部分也无法调试。
  • 调试接口时往往需要使用到用户身份信息(即需要登录之后应用才能正常使用)，直接使用Chrome调试可能需要手动在浏览器中注入用户信息，略显繁复。而客户端有SSO机制，在客户端中直接打开应用无需登录即可正常使用
  • 一些浏览器兼容问题往往也只能在特定的移动设备上重现

直接使用Chrome调试更适合调试用户界面(UI)及与能力无关的业务逻辑，开发到了后期阶段我们还是更加需要在真机上调试。

真机测试

很多时候，我们在浏览器中，模拟器中运行和显示都正常的应用，发布后用真机测试出现不少异常，也有在不同机型上不一致的现象，所以真机测试是非常有必要的，并且需在不同平台以及不同机型下分别进行。

这里仅以安卓为例作介绍，与iOS的操作基本一致。

下载安装KK客户端

客户端的下载地址： http://[地址]:[端口]/download/download

  • 地址：域名或ip地址, 默认与KK管理台所在的域名或者IP一致
  • 端口：端口号，默认为8000

设置服务器

首次运行客户端需要设置服务器，如图所示。

  • 服务器地址，默认与KK管理台所在的域名或者IP一致，地址不要带http或者https等协议前缀
  • 端口号，默认为5100

登陆

打开应用

点击底部工具栏 工作 按钮就能看到当前用户的被授权的的所有应用。找到准备测试的应用，打开应用后，尽可能走一下各种业务逻辑。

手机连接PC远程实时调试

在电脑上使用 Chrome (版本不小于32) 可使用Chrome DevTools调试 android (版本不小于4.0)上 打开的Web页面(Web App)，详细可参阅官方文档.

操作前，请先配置好手机KK客户端，配置客户端 ->

使用步骤如下(先保证android和chrome版本满足要求):

  1. 开启 android 的开发者调试功能: 进入 设置 -> 开发者选项 -> 启用USB 调试。由于国产定制的android UI混乱，设置各不一样，如若找不到相关设置项，请自行搜索解决
  2. 打开android 版手机KK，切换到工作 页签，点击右上角省略号 ... 进入 设置 -> 通用 -> 系统能力，打开 第三方应用调试
  3. 使用 USB 链接电脑和手机, 请务必保证电脑已安装手机相关驱动，能正常识别连接的， 并在手机弹出的对话框上信任电脑，即允许电脑调试
  4. 在电脑 chrome 上打开地址 chrome://inspect/(需手动拷贝然后复制到地址栏打开), 在该页面即可看到已连接的手机及手机上打开的网页，点击 Inspect 即可调试, 调试方法与使用Chrome调试 ->一致。

如果你在中国大陆，电脑网络未进行特殊设置，那么毫无意外，点开 Inspect 后你会看到一个空白页面，这是因为远程调试用到了Google的一个服务，需解除屏蔽即可正常调试。可尝试使用该hosts文件（GitHub地址）替换本机host解决.

开启与查看调试日志

KK客户端会默认将应用JS代码中使用以下方法打印的的日志输出到日志文件中，方便查阅定位问题。

  • console.log('...')
  • console.debug('...')
  • console.error('...')

若应用中使用了JS SDK, 默认也会打印能力调用的日志，也可以在日志文件中查阅。同时还可以通过调用 kk.config 来开启更加详细的能力调用日志。

// 开启能力调用日志，默认已开启
kk.config('debug', true);
// 开启能力调用的详细日志，即打印出成功回调接收的所有参数, 只有 debug 为true时，detailLog 的设置才有效
kk.config('detailLog', true);

查看应用详细日志

在KK管理台->应用管理->移动端应用下的 移动在线应用管理或者 移动混合应用管理上添加Web应用之后，会得到一个应用ID，在手机上日志文件的名称即以该ID命名。

Android和iOS的日志在手机上路径是不一样的。

Android日志文件位置

[Andorid内部存储空间]/Andorid/data/com.landray.kkplus/files/log/applog/ 目录下以 应用ID命名(无文件后缀)的文件，该文件为纯文本文件，可用任何能打开纯文本文件的软件查看

iOS日志文件位置

查看iOS的日志必须借助iTunes。在电脑上安装iTunes后，使用数据线连接iOS设备，在iTunes中点击已连接的iOS设备，管理其中的应用，在 文件共享 下找到 KK 5.0 并选中它，在右侧 KK 5.0 的文稿列表中即可找到 以应用ID命名(文件后缀为 .log)的文件，该文件为纯文本文件，将其拖拽至电脑上，即可使用文本编辑器查看。

其他调试方法

移动端页面调试是一个比较麻烦的是，查看日志需要不停的 alert 输出信息，调试通过后还要去掉 alert 代码，为了方便调试这里介绍一些工具方法。

Debuggap

Debuggap 客户端是一个基于 node-webkit 的调试工具，支持Windows、Mac 、Linux。

具体请查阅官网说明或下面提供中文简易使用教程。

官方首页 简易使用教程

Debuggap 也可以在不需要客户端在移动端页面单独使用来查看 Dom 结构、console信息等等，虽然操作不太方面，有时确是非常有用。

JSConsole

通过在自己的web app中引入JSConsole的js, 即可在电脑浏览器中查看在手机上打印出的日志.

官方网站: http://jsconsole.com/

Error 事件

在开发及测试阶段，在应用中监听页面 window 的 error 事件来快速定位代码中的错误，当应用运行出错时，弹出错误信息，代码如下, 通常应该将该部分代码放置于index.html(或其他应用的入口页面)所有 script 标签之前，这样方可监听到所有的代码错误，包括JS文件加载初始化时候的错误。

// message 为错误信息
// source 为报错的JS文件路径
// lineno 为报错位置在JS文件中的行号，即位于第几行
// colno 为报错位置在JS文件中的列号，即位于第几列
// error 为错误对象
// 详细可参考 https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror
window.onerror = function (message, source, lineno, colno, error) {
    var errmsg = 'error message: ' + message + ', ' + 'filename : ' + source + ', lineno: ' + lineno  + ', colno: ' + colno;
    // 这里可用一个是否是开发模式的布尔值变量来做控制
    if ( true ) {
        alert( errmsg );
    }else{
        console.log( errmsg );
    }
};

应用发布

KK控制台是 KK 平台的后台管理系统，Webapp 是通过KK控制台来发布和配置，下面介绍KK控制台中与 Webapp 有关的操作。

KK控制台介绍

登陆

通过管理员账号登陆KK控制台，登陆界面如下图。

主页介绍

KK控制台主页共有 6 个模块；

其中，有关 Webapp 的模块有用户管理和应用管理，后面操作流程再详细介绍。

创建部门和用户

如果开发者没有用户账号（ EKP 或者 KK 账号）或者需要多个测试账号，可以在KK控制台中创建用户。

可以直接在某个已有部门下面创建一个用户，或者创建一个新的部门后，再在该部门下创建用户。

下面分别介绍创建部门和创建用户。

创建部门

进入首页的 用户管理 ，如下图，在左侧的组织架构里选择一个部门，选中部门列表，点击 创建子部门 后进入编辑界面。

填写部门相关信息，*号为必填项，保存，创建成功。

配置说明:

字段 描述
上级部门 选择部门的上级部门
部门名称（简体） 部门中文名称
部门排序编号 部门在同级部门中的排序号
部门名称（英文） 部门英文名称

创建用户

进入 用户管理，如下图，选择一个部门，选中人员列表，点击 新建 后进入编辑界面。

填写个人信息后，保存，创建成功。

配置说明:

字段 描述
部门名称 选择用户的所属部门
登录账号 用户的登陆账号
登录密码 登录密码
用户姓名 用户的显示名称
排序号 用户的部门中的排序号
用户等级
用户认证方式 KK

新增应用

KK 平台的 Webapp 分为混合应用和在线应用。

创建并配置混合应用

进入应用管理，如下图，左侧菜单选择 移动混合应用管理，点击右上角 新建 按钮进入编辑界面。

填写应用信息后，点击 保存 按钮。

上传应用包

首先将应用项目压缩为 zip 格式。

进入KK控制台 应用管理，选择 移动混合应用管理，找到对应的 app，点击后面的 安装包 按钮，进入安装包记录界面。

在安装包记录界面，点击 新建 按钮。

进入安装包上传页面，填写下图中必填的4项，点击保存。

配置说明:

字段 描述
设备类型 选择设备类型，全部/手机/平板
操作系统 选择操作系统类型，全部/安卓/iOS
安装包上传 选择需要上传的安装包
应用版本号 应用的版本好，格式自己定义
安装包描述 当前安装包的描述

应用发布

应用发布

应用更新

查看离线应用更新 ->

创建并配置在线应用

进入应用管理，如下图，左侧菜单选择 移动在线应用管理，点击右上角 新建 按钮进入编辑界面。

填写应用信息后，点击 保存 按钮。

配置说明:

字段 描述
应用代码 识别应用的标示符，创建后不可更改
应用名称 应用的显示名称
应用描述 应用的描述信息
应用分类 应用的类别，从列表选取
提供商 应用供应商名称
联系人 供应商联系人
应用图标 应用在客户端显示的应用图标
强制使用
排序号 应用在客户端显示的顺序号
URL地址 在线应用的访问URL地址

应用发布

应用发布

应用更新

在线应用更新只需更新应用所在的服务器即可，无需在KK管理台上操作

上线 / 下线应用

离线应用和在线应用操作一致，都是在应用列表对应的应用点击 上线（下线）按钮，如图：

授权应用

创建发布应用后，若没有在创建应用时选择强制使用，需要关联用户后，才能在相应用户客户端的工作台显示。

进入KK控制台 应用管理，选择 移动在线应用管理，找到对应的 app，点击后面的 授权 按钮，进入授权编辑界面。

在编辑页面可以选择 全体人员，也可以指定某个部门或者某个人员，然后添加到授权人员列表。

配置说明:

字段 描述
授权范围 是否授权全体成员
部门范围 选择授权一个或多个部门
人员范围 选择授权一个或多个员工

在手机上查看授权的应用

  1. 首先 安装KK客户端

  2. 然后 查看授权应用

更新与发布应用

  1. 在KK管理台上重新创建混合应用或者在线应用
  2. 配置为正式发布的相关参数
  3. 授权给相应用户
  4. 上线
  5. 用户在手机上查看(重新登录或杀掉KK后再启动）

详细操作可参考新增应用及授权应用.

更新应用

混合应用更新

上传应用包，用户在下次打开KK（重新登录／杀掉KK后再启动）即更新。

在线应用更新

在线应用直接更新应用服务器即可。