Add multi-size screen adapt doc.
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index 8e5ee1a..8d91e78 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -83,7 +83,8 @@
children: [
['advanced/asset-path', 'Asset Path'],
['advanced/downgrade', 'Downgrade'],
- ['advanced/use-vuex-and-vue-router', 'Use Vuex and vue-router']
+ ['advanced/use-vuex-and-vue-router', 'Use Vuex and vue-router'],
+ ['advanced/multi-size-screen', 'Fit for multi-size screen']
]
},
{
@@ -253,7 +254,8 @@
children: [
['advanced/asset-path', '资源路径'],
['advanced/downgrade', '降级方案'],
- ['advanced/use-vuex-and-vue-router', '使用Vuex和vue-router']
+ ['advanced/use-vuex-and-vue-router', '使用Vuex和vue-router'],
+ ['advanced/multi-size-screen', '适应不同尺寸屏幕']
]
},
{
diff --git a/docs/guide/advanced/multi-size-screen.md b/docs/guide/advanced/multi-size-screen.md
new file mode 100644
index 0000000..294b2ba
--- /dev/null
+++ b/docs/guide/advanced/multi-size-screen.md
@@ -0,0 +1,174 @@
+---
+title: Fit for multi-size screens
+type: guide
+group: Advanced Guide
+order: 8.1
+version: 2.1
+has_chapter_content: true
+---
+
+## Summary
+
+In this article, we demonstrate how to fit Weex pages for different or changable screen sizes such as orientation switches.
+
+## How Weex convert a CSS style ot view coordinate
+
+Take iOS as example, when your application starts up, Weex acquires current device screen width as global variable. On iOS, this value is screen physical pixels divided by screen scale. For iPhone6, this value is 375.
+
+```C
+@implementation WXCoreBridge
+
++ (void)install
+{
+ static dispatch_once_t onceToken;
+ dispatch_once(&onceToken, ^{
+ WeexCore::WXCoreEnvironment* env = WeexCore::WXCoreEnvironment::getInstance();
+ env->SetPlatform(OS_iOS);
+ env->AddOption("scale", "1");
+
+ CGSize screenSize = [UIScreen mainScreen].bounds.size;
+ env->SetDeviceWidth(std::to_string(screenSize.width));
+ env->SetDeviceHeight(std::to_string(screenSize.height));
+ ...
+ ...
+}
+```
+
+When every WXSDKInstance is created, it's default viewPortWidth is 750px.
+
+```C
+// The default screen width which helps us to calculate the real size or scale in different devices.
+static const CGFloat WXDefaultScreenWidth = 750.0;
+```
+
+If you set a CSS style as "375px", in Weex, this value is automatically converted to a UIKit system value considering current screen width and the current instance's viewPortWidth.
+
+```C
+dimension(UIKit) = dimensionPx(CSS) / viewPortWidth(instance) * globalScreenWidth
+```
+
+We get:
+dimension(UIKit) = 375 / 750 * 375 = 187.5
+
+After that, Weex use value 187.5 for layout and set the final value after layout to an iOS UIView, no more conversion.
+
+## Why Weex does not support orientation switch
+
+As mentioned above, Weex converts a raw CSS style value to UI system's unit and dropped the raw style value. This is for historical reason, and could save a lot of memory for huge and complcated pages.
+
+At the same time, Weex does not support style value as percentage. Massive existing pages use 750px as the default viewPortWidth, and all sub elements in the page use coordinate values relative to 750 which is treated as full screen width.
+
+When screen rotated, as for iPhone6, the "width * height" would be "667 * 375". We need raw style value to calculate the new value for layout and UIView. But because there are no raw style values, we cannot proceed.
+
+For style value "375px" after rotation, the UIKit value would be:
+
+dimension(UIKit) = 375 / 750 * 667 = 333.5
+
+You can see that 333.5 is still half the screen width.
+
+## Interface for screen
+
+We provide a series of APIs to control layout parameter.
+
+### 1. Set viewPortWidth of a page
+
+#### a. Use Meta Module
+
+```Javascript
+const meta = weex.requireModule('meta');
+meta.setViewport({
+ width: 800
+});
+```
+
+#### b. Use WXSDKInstance
+
+```Objective-C
+WXSDKInstance* instance = [[WXSDKInstance alloc] init];
+[instance setViewportWidth:800.f];
+```
+
+### 2. Set deviceWidth of a page
+
+<Badge text="v0.25+" type="warning"/>
+
+#### a. Use Meta Module
+
+```Javascript
+const meta = weex.requireModule('meta');
+meta.setViewport({
+ deviceWidth: 375,
+ deviceHeight: 800
+});
+```
+
+#### b. Use WXSDKInstance
+
+```Objective-C
+WXSDKInstance* instance = [[WXSDKInstance alloc] init];
+[instance setPageRequiredWidth:375.f height:800.f];
+```
+
+#### c. Set global deviceWidth
+
+```Objective-C
+[WXSDKEngine setGlobalDeviceSize:CGSizeMake([UIScreen mainScreen].bounds.size.width, [UIScreen mainScreen].bounds.size.height)];
+```
+
+### 3. Let a page reserve all raw CSS styles
+
+<Badge text="v0.25+" type="warning"/>
+
+#### a. Use Meta Module
+
+```Javascript
+const meta = weex.requireModule('meta');
+meta.setViewport({
+ reserveCssStyles: true
+});
+```
+
+#### b. Use WXSDKInstance
+
+```Objective-C
+WXSDKInstance* instance = [[WXSDKInstance alloc] init];
+[instance setPageKeepRawCssStyles];
+```
+
+### 4. Force the page to relayout
+
+<Badge text="v0.25+" type="warning"/>
+
+```Objective-C
+[instance reloadLayout];
+```
+
+## Scenarios
+
+### 1. Applications that do not support screen rotation
+
+If your app does not support screen rotation, you can ignore all issues above. When Weex starts up, it will automatically get current screen width and after that all pages will use this global value as default.
+
+### 2. Support screen rotation for a specific page
+
+<Badge text="v0.25+" type="warning"/>
+
+1. Let the page reserve all CSS style values.
+2. After screen rotation is done, use the code below to reset screen width for the page and trigger relayout.
+
+```Objective-C
+CGFloat w = [UIScreen mainScreen].bounds.size.width;
+CGFloat h = [UIScreen mainScreen].bounds.size.height;
+[_instance setPageRequiredWidth:w height:h];
+[_instance reloadLayout];
+```
+
+You could use latest Playground to test the [demo](http://editor.weex.io/p/wqyfavor/scroller/commit/37810078ef963388b699b5ad7d5e9881)
+
+Remember to turn on screen rotation in control panel.
+
+[image](https://img.alicdn.com/tfs/TB1gWiTcvWG3KVjSZPcXXbkbXXa-240-427.gif)
+
+### 3. Notice
+
+For styles that should not be affected by screen width and viewPortWidth, you should use 'wx' as unit.
diff --git a/docs/zh/guide/advanced/multi-size-screen.md b/docs/zh/guide/advanced/multi-size-screen.md
new file mode 100644
index 0000000..4201d4b
--- /dev/null
+++ b/docs/zh/guide/advanced/multi-size-screen.md
@@ -0,0 +1,172 @@
+---
+title: 适配不同尺寸的屏幕
+type: guide
+group: 高阶特性
+order: 8.1
+version: 2.1
+has_chapter_content: true
+---
+
+## 简介
+
+本文将介绍 Weex 适配不同尺寸屏幕的方法以及横竖屏动态切换时如何自适应。
+
+## Weex 如何将前端样式值转换为系统坐标值
+
+以 iOS 为例，在应用启动时，Weex 获取当前屏幕宽度作为全局默认值。在 iOS 系统上该宽度为实际像素/屏幕比例后的 UIKit 宽度。比如 iPhone6 为 375。
+
+```C
+@implementation WXCoreBridge
+
++ (void)install
+{
+ static dispatch_once_t onceToken;
+ dispatch_once(&onceToken, ^{
+ WeexCore::WXCoreEnvironment* env = WeexCore::WXCoreEnvironment::getInstance();
+ env->SetPlatform(OS_iOS);
+ env->AddOption("scale", "1");
+
+ CGSize screenSize = [UIScreen mainScreen].bounds.size;
+ env->SetDeviceWidth(std::to_string(screenSize.width));
+ env->SetDeviceHeight(std::to_string(screenSize.height));
+ ...
+ ...
+}
+```
+
+创建的每个 WXSDKInstance，其默认的 viewPortWidth 为 750px。
+```C
+// The default screen width which helps us to calculate the real size or scale in different devices.
+static const CGFloat WXDefaultScreenWidth = 750.0;
+```
+
+当指定 CSS 样式值为 "375px" 时，Weex 在接收到该样式后，自动根据当前屏幕宽度和当前 Instance 的 viewPortWidth 计算出在 iOS 系统上，对应的 UIKit 坐标值为：
+
+```C
+dimension(UIKit) = dimensionPx(CSS) / viewPortWidth(instance) * globalScreenWidth
+```
+
+代入后：
+dimension(UIKit) = 375 / 750 * 375 = 187.5
+
+之后 Weex 排版引擎使用 187.5 来排版，并最终将排版后的结果设置给 iOS UIView。之后没有坐标转换过程了。
+
+## 为什么 Weex 页面不支持横竖屏切换
+
+如上文所述，Weex 最终将原始样式值转换为平台 UI 系统的坐标值，之后原始样式值被丢弃。这个有一定历史原因，且当页面非常大或复杂时，丢弃后可以节省很多内存，因此原始样式值被丢弃。
+
+同时，目前 Weex 不支持百分比布局，大量竖屏页面使用 750px 的 viewPortWidth 值为基准进行开发，页面里的坐标值都是根据 750px 为一个屏幕宽度换算后的值。
+
+当屏幕发生旋转后，比如 iPhone6 手机，旋转后的 “宽 * 高” 为 “667 * 375”。此时我们需要原始的样式值来重新计算出设置给排版引擎的坐标值，如前文所说，排版引擎接收的是 iOS UIKit 的坐标值。这个时候对于仍然为 "375px" 的样式，其计算出的 UIKit 坐标值为：
+
+dimension(UIKit) = 375 / 750 * 667 = 333.5
+
+仍然为宽屏下的屏幕宽度一半。
+
+但是因为原始样式值被丢弃，我们不能支持横竖屏切换。
+
+## 屏幕参数接口
+
+我们通过添加一系列接口让 Weex 使用者可以控制排版参数。
+
+### 一、设置页面使用的 viewPortWidth
+
+#### 1. 使用 Meta Module
+
+```Javascript
+const meta = weex.requireModule('meta');
+meta.setViewport({
+ width: 800
+});
+```
+
+#### 2. 使用 WXSDKInstance 的接口
+
+```Objective-C
+WXSDKInstance* instance = [[WXSDKInstance alloc] init];
+[instance setViewportWidth:800.f];
+```
+
+### 二、设置页面使用的 deviceWidth
+
+<Badge text="v0.25+" type="warning"/>
+
+#### 1. 使用 Meta Module
+
+```Javascript
+const meta = weex.requireModule('meta');
+meta.setViewport({
+ deviceWidth: 375,
+ deviceHeight: 800
+});
+```
+
+#### 2. 使用 WXSDKInstance 的接口
+
+```Objective-C
+WXSDKInstance* instance = [[WXSDKInstance alloc] init];
+[instance setPageRequiredWidth:375.f height:800.f];
+```
+
+#### 3. 设置全局的 deviceWidth
+
+```Objective-C
+[WXSDKEngine setGlobalDeviceSize:CGSizeMake([UIScreen mainScreen].bounds.size.width, [UIScreen mainScreen].bounds.size.height)];
+```
+
+### 三、设置页面保留原始 CSS 样式值
+
+<Badge text="v0.25+" type="warning"/>
+
+#### 1. 使用 Meta Module
+
+```Javascript
+const meta = weex.requireModule('meta');
+meta.setViewport({
+ reserveCssStyles: true
+});
+```
+
+#### 2. 使用 WXSDKInstance 的接口
+
+```Objective-C
+WXSDKInstance* instance = [[WXSDKInstance alloc] init];
+[instance setPageKeepRawCssStyles];
+```
+
+### 四、强制页面重新排版
+
+<Badge text="v0.25+" type="warning"/>
+
+```Objective-C
+[instance reloadLayout];
+```
+
+## 使用场景
+
+### 一、不可旋转屏幕的应用
+
+如果应用不支持屏幕旋转，你可以不用关心以上问题。当 Weex 启动时，会自动获取当前屏幕宽度作为全局宽度，所有之后创建的 Weex 页面都会使用该宽度。
+
+### 二、某个特殊页面支持横竖屏切换
+
+<Badge text="v0.25+" type="warning"/>
+
+1、设置页面保留原始 CSS 样式值
+2、当屏幕旋转完成后，调用以下接口设置新的屏幕尺寸，并重新排版
+```Objective-C
+CGFloat w = [UIScreen mainScreen].bounds.size.width;
+CGFloat h = [UIScreen mainScreen].bounds.size.height;
+[_instance setPageRequiredWidth:w height:h];
+[_instance reloadLayout];
+```
+
+你可以使用最新 Playground 扫码[示例](http://editor.weex.io/p/wqyfavor/scroller/commit/37810078ef963388b699b5ad7d5e9881)
+要在控制面板里允许屏幕自动旋转。
+
+[image](https://img.alicdn.com/tfs/TB1gWiTcvWG3KVjSZPcXXbkbXXa-240-427.gif)
+
+### 三、注意
+
+对于不希望受屏幕宽度和 viewPortWidth 影响的尺寸，请使用 'wx' 单位。
+
