一、酷应用沉浸式容器介绍

移动端半屏

在移动端是半屏效果，可以达到轻交互，不打断当前对话的效果，所以比较适合酷应用的沉浸式交互场景。
半屏的设置需要遵循一些标准规范，如半屏的关闭按钮位置、自定义内容区位置、二级页面按钮位置以及如何切换全/半屏等。半屏的高度规范默认为83%（若内容较少可以设置为50%）。

桌面端侧边栏

沉浸容器（在桌面端被称之为侧边栏）在桌面端也需要遵循一些规范标准，如侧边栏标题、侧边栏关闭、自定义内容区、操作按钮、二级页面按钮等。同时因为侧边栏为从右向左滑出，所以没有高度的限制，但是有宽度的规范，例如有时想要页面内容在桌面端展示的更多一些时，可以适当的扩大宽度，另外宽度有最大最小限制，防止容器出现过宽过窄的情况。

打开协议（H5）

在移动端6.5.25以后的版本会提供一个新的协议，这个协议自带返回、关闭、全屏切换、分享功能，标题可通过 jsapi 设置。
页面内容可以通过URL参数方式传递进去，因为整个协议是URL链接，而H5页面也是一个URL，所以这个URL需要进行一次编码。
高度可以设为为83%，如果内容较少，也可以通过 &mobileHeight=semi 来设置一半的高度。
之前的版本有旧版本协议，这个协议与新版本的区别是，旧版本没有把返回、关闭、全屏切换、分享等功能做好，所以导航栏和前端的样式可以通过前端的组件来实现。
高度需要用 &panelHeight=percent83 设置较高的尺寸，50%也可以。
桌面端协议也为老版本协议，自带一个关闭按钮，但没有返回及其他功能。为了更加灵活的控制导航栏的功能样式，一般不使用桌面端自带的头，可以通过&bShowHeader=false 来隐藏头，同时样式也可以通过前端组件来实现。

打开协议小助手

手动去梳理规范及拼接沉浸式容器困难较大，容易出错，接下来介绍一个工具

只需要关心H5页面的URL是什么以及沉浸式容器的尺寸，就可以自动生成半屏和侧边栏的一个链接。这个工具是对外开放的，可以通过访问以下网站进行使用。
https://n.dingtalk.com/dingding/cool-developer/index.html

二、高效应用开发，官方应用体验

开发过程中可能会遇到的问题
- 问题1：沉浸式容器不光支持移动端，还要支持桌面端，所以会遇到桌面端和移动端交互有差异的问题。在上传协议的时候，需要写两套代码，移动端一套组件，桌面端一套组件。两套组件带来的问题是组件API也必须为两套，在使用组件的时候也需要写两套适配逻辑。
- 问题2：桌面端及移动端尺寸（例如字号、间距，移动端字号多为17px，而桌面端多为14px）有差异。需要写两套样式去适配。存在效率低下的情况。
- 问题3：开发效率低下会带来页面体验（如加载慢）问题。
- 问题4：沉浸式容器与其他容器不同的是沉浸式，在钉钉平台内部去交互使用，如果UI和钉钉UI差距较大，对用户来说体验感不好。
- 问题5：很多用户习惯切换为深色模式，但目前很多应用在深色模式下不可见。
  总结起来，为效率和体验的矛盾现象。
解决核心方案
1. 基础样式
  重点解决如深色模式适配、基础尺寸适配等。
  - 定义标准 Token 库
  - 自适配深色模式
  - 自适配桌面移动样式尺寸
  - 统一 reset.css
2. 组件
  尝试使用一套组件，让组件内部去解决移动桌面的差异，同时组件的UI标准又与钉钉官方标准保持一致。
  - 页面布局组件
  - 定义标准沉浸式容器组件库
  - 一套组件自适配桌面移动
3. JSAPI
  很多时候需要大量的调用钉钉平台的API，可能会因为不同平台的容器的差异可能存在API不一致需要适配的问题。
  定义标准 JSAPI 四端一致（规划）
技术架构
1. 最底层：为沉浸式容器，容器会提供半屏打开协议、侧边栏打开协议及运行H5页面的环境
2. 前端基础能力：
  - 基础样式：为主题，主题定义标准的一个token库，token库包含一些基础的颜色、字号。这样不需要关心不同平台的主题差异，著需要在token设置好后，让token内部去适配各平台差异。相应的主题背后做环境监测，如深色/浅色等，以此达到token动态适配。
  - 组件:只需要一套组件，不用关心平台差异。为了兼容桌面，重点解决桌面交互差异，单独的进行轻量桌面适配。
3. 场景化模板库：如列表、表单等常见模板，可以达到快速复用的效果。
4. 酷应用：酷应用也可以基于基础能力及组件样式进行适配。
主题适配原理
1. 提供token库：less变量背后绑定css
2. Css变量不同环境映射不同值
3. 运行时进行环境识别
每个less变量绑定一个css变量，需要提前定义好css变量规则，例如在移动端正文字号为17px，在桌面端为14px，需要提前把这些变量提前定义好，在运行的时候会监测当前的适配平台。从而实现让css变量生效的目的。
主题适配案例
以下用一个简单的 hello world 来举例：
hello world 适配设计到两点：一是字号、二是颜色。
字号可以看到，hello world 在移动端为17px，在桌面端为14px。可以绑定相应字号的 token ，这个token 包括文字大小、行高等。

import React from 'react';
import { PageContainer } from 'dingtalk-design-mobile';
import './index.less';

const Demo: React.FC = () => {
return (
<PageContainer
title="页面名称“
hasBack
strongMainAction
actions={[
{
text:'取消'，
type: 'cancel',
}，
text:'确定，，
type: 'ok',
onClick: () => console.log('onClick submit'),
},
]}
>
<div className="container">Hellof world!</div>
</PageContainer>
)；
}
export default Demo;

?import (reference) "~dingtalk?theme/dingtalk?x/mob.less";
.container {
color: @common_levell_base_color;
.common_body_text_style();
}

组件适配原理
1. 样式抹平
  组件本身也涉及样式，例如按钮字号等。
2. 交互抹平
  举例子如移动端的滑动操作，在桌面端通过点击的方式进行交互。
组件适配案例
以下面的表单案例举例，此表单已经做好了桌面端和移动端的适配，可以通过代码看出，使用了一套组件做了版本兼容的处理。

import React from 1 react1;
import { Switch, Input, Picker, PageContainer, Form } from 'dingtalk-design-mobile';
const Index =()=>(
<PageContainer
hasBack={true}
title”="标题"
actions={[
text:'取消',
type: 'cancel',
},
{
text:’确定',
type: 'ok',
onClick: () => console.log('onClick submit'),
},
]}

<Form
initialValues={{ p1: true }}
onFinish={(values)=>
console.log(‘values’、values)
}
onValuesChange={console.log}

<Form.Group renderHeader=“列表”〉
<Form.ltem labels“主标题文案”name=“pl”
<Switch
onChange={(v: any)=>
console.log(‘onChange1’, v)}
</Form.Item>
<Form.Item label="季度” name="season"〉
<Picker
data={seasons}
title=“季度”
okText=“确定“
cascade={false}
value={season}
onChange={setSeason}
extra="请选择（可选）"
>
<List.Item arrow="horizontal”〉
标题文字
</List.Item>
</Picker>
</Form.Item>
</Form.Group>
</Form>
</PageContainer>
）；

更多场景化模板
会根据实际的开发场景，呈现出场景化模板。有三个目标：
- 通过模板的帮助能够帮助快速的去理解能力如何使用，如组件如何使用等；
- 通过模板方式，将钉钉官方的产品设计最佳实践提供参考
- 开发者如何在类似场景中快速复用
官网参考
首先参考ding.design，通过文档的多端一致可以快速的接入能力
- 第一步：移动端开发基础配置
  页面 HTML 添加以下 meta 标签
- 第二步：接入钉钉主题 sdk（如基础样式的适配）
  如刚才举例的 hello world 如何使用 token 进行快速的适配、组件如何进行基础适配，都需要依赖主题能力。
  - 安装主题 token 变量包
  npm i dingtalk-theme@6.x --save
  - 然后在 html head 部分引入以下资源
  - 或者直接引入 npm 资源
  import 'dingtalk-theme/entry';import 'dingtalk-theme/dingtalk-x/mob.css'; // 保证在业务样式代码之前引入
  - 第三步：安装 dingtalk-design-mobile 2.x
  npm i dingtalk-design-mobile --save
实操演示

Import react from ‘react’;
Import styles form ‘./index.less’;

Function pages(){
Return {
<div classname={styles.home}>
Hello,world
</div>
);
}

Export default pages;

@import (reference)“~dingtalk-theme/dingtalk-x/mob.less”;

.home{
.common_body/_text_style();
}

此时输入 umi-demo npm start 执行，可以看到 hello world 已经运行

此时验证一下在各端口的适配能力，可以根据沉浸式容器打开协议的工具去生成打开协议

拿到协议后，可以复制到钉钉消息聊天里，通过聊天的方式去唤起沉浸式容器。
此时验证，发现已经可以生效。

可以看到基本样式已经完成适配。接下来查看组件适配。组件适配的代码如下：

Import react from ‘react’;
Import {Button} form ‘dingtalk-design-mobile’;
Import styles form ‘./index.less’;

Function pages(){
Return {
<div classname={styles.home}>
<Button>Hello,world</Button>
</div>
);
}

Export default pages;

此时运营可以看到组件的适配效果。移动端默认的是快捷结构。同时切换到桌面，也可以看到桌面的样式也已经适配。

后续规划
- 基础样式
主要有两个方向：
- 一是主题的样式颜色，如目前默认颜色为钉钉蓝，若需要定义自己的品牌色，就需要靠定制来完成。目前是支持定义，但是想要知道主题色的变更需要修改哪些 token 还是比较困难，导致接入成本过高。所以后续会提供主题包以弥补此问题。
- 二是多端适配，对目前可以解决大多书问题，但多端适配还处于起步阶段，为了更好的完成桌面体验升级，就需要多增加适配 token 。降低适配成本。

组件
- 随着越来越多的开发者接入，最直接的问题是使用咨询量加大。之后会提供咨询服务，帮助客户自助解决问题。
- 目前已经提供了90% 的桌面配件，未来会随着产品的迭代去丰富组件。沉淀更多跟高级的组件，及场景化模板。
- DIE 打通，目前需要跳转平台站点去进行学习，之后在 IDE 可以完成一站式研发体验。
JSAPI
- 主要解决四端一致问题
- API开放度扩大，希望把自定义能力更多的开放给客户。

三、常见问题

酷应用的覆盖面积是定高还是自定义高？尺寸多少？
两种高度：50%和83%。（推荐）
能否支持半浮层？或能否全页面覆盖？
支持半浮层，两种高度：50%和83%，考虑交互的连贯性不推荐全页面覆盖。
微应用受气候能否保留或者有入口继续上次的状态或进度？
支持收起操作，用户点击右上角缩小态的按钮，则将半屏容器向右下角收入浮窗，同时保活。
浮层类时调用钉钉系统的还是自定义？
（1）如果是从卡片打开浮层，使用钉钉系统能力，PC端推荐使用侧边栏，移动端使用半浮层50%高度和83%两种高度规格。
（2）如果是微应用浮层，推荐使用https://ding.design/#/cate/64/page/685抽屉组件
整个酷应用布局是完全自定义的嘛，是否具有导航、返回、菜单等操作？
有统一的导航、返回、菜单等操作，其他区域可使用
https://ding.design/#/cate/64/page/826页面容器组件进行开发。
全屏的资源预览能否支持，能否调用钉钉系统的（视频、图片、音频、Word、PPT等）？
可通过JSAPI预览文件，文件需要上传到钉盘，详细参考
https://open.dingtalk.com/document/orgapp-client/preview-nail-plate-file
除已知的选人组件外，还有哪些可以调用的系统级组件？
(1)普通组件，推荐使用https://ding.design/移动端组件
(2)钉钉容器类组件/API：
https://open.dingtalk.com/document/isvapp-client/jsapi-overview
顶部的组件样式在哪儿看？是否支持自定义？
系统支持统一的导航、返回、菜单等操作，可以自定义菜单操作

四、Q&A

Q：已经在开发酷应用，且已有自己方式方法，现在接入和迁移新的体系，接入成本会不会很高？
A：如果已经使用了ding design 的一些能力，那么可以直接升级。如果使用的是其他 react 技术栈，推荐产品大改版时把这块能力接入。

Q：有没有配套调试工具，如何在钉钉真实环境下做调试？
A:目前介绍的能力本身也是基于 web 技术，所以和正常的 H5 一样，可以基于之前的调试方式、使用浏览器的开发者工具去模拟移动端和桌面端的分辨率场景，来进行调试UI界面。另外如果依赖钉钉平台的 API 能力，想在钉钉的真实环境下调试，此时可以去钉钉开放平台下载钉钉开发者包，包可以唤起一些开发者工具。之后计划会针对开发者提供完整的开发者工具，包括酷应用的完成开发流程SOP。届时会解决调试问题。

Q：使用了ding design 组件后部分需求满足不了，还有没有什么最佳实践可以分享？
A：满足不了的场景的确存在。第一，目前ding design 内部一直在持续迭代，在使用过程中现有的组件活能力满足不了的时候，可以进行反馈。第二，会考虑陆续把钉钉的一些组件及能力开放出来。希望可以达到复用的效果。例如刚才提到的开发者工具，都会集成下来，最大化的支持尝尽给。最后，如果有场景实在满足不了，此类场景一般为偏业务场景，此时我们鼓励大家去封装一些偏业务的组件和能力。

Q：基于 vue开发的应用是不是不能接入酷应用？一定要是 ding design 重构才可以么？
A：目前是这样。如果未来很多开发者是使用 vue在开发，那么会考虑支持 vue框架。