You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@weex.apache.org by ha...@apache.org on 2019/01/03 11:07:54 UTC
[incubator-weex-site] branch draft updated: Add Chinese and English
documents of downgrade (#297)
This is an automated email from the ASF dual-hosted git repository.
hanks pushed a commit to branch draft
in repository https://gitbox.apache.org/repos/asf/incubator-weex-site.git
The following commit(s) were added to refs/heads/draft by this push:
new bab4b52 Add Chinese and English documents of downgrade (#297)
bab4b52 is described below
commit bab4b5283149a7bec6786cb08e8ed574699b6137
Author: Hanks <zh...@gmail.com>
AuthorDate: Thu Jan 3 19:07:50 2019 +0800
Add Chinese and English documents of downgrade (#297)
---
docs/.vuepress/config.js | 6 +-
docs/guide/advanced/downgrade.md | 166 +++++++++++++++++++++++++++++++++---
docs/zh/guide/advanced/downgrade.md | 164 +++++++++++++++++++++++++++++++++++
3 files changed, 321 insertions(+), 15 deletions(-)
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index 588c166..9937d0f 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -73,8 +73,7 @@ module.exports = {
['extend/extend-android', 'Extend Android'],
['extend/extend-ios', 'Extend iOS'],
['extend/extend-ios-with-swift', 'Extend iOS with swift'],
- ['extend/extend-web', 'Extend Web Renderer'],
- ['extend/extend-framework', 'Extend JS framework']
+ ['extend/extend-web', 'Extend Web Renderer']
]
},
{
@@ -240,8 +239,7 @@ module.exports = {
['extend/extend-android', '扩展Android能力'],
['extend/extend-ios', '扩展iOS能力'],
['extend/extend-ios-with-swift', '使用Swift进行module 扩展'],
- ['extend/extend-web', '扩展Web组件'],
- ['extend/extend-framework', '扩展JS framework']
+ ['extend/extend-web', '扩展Web组件']
]
},
{
diff --git a/docs/guide/advanced/downgrade.md b/docs/guide/advanced/downgrade.md
index e491a21..efd5ac5 100644
--- a/docs/guide/advanced/downgrade.md
+++ b/docs/guide/advanced/downgrade.md
@@ -1,16 +1,160 @@
----
-title: Downgrade
-type: guide
-group: Advanced Guide
-order: 8.2
-version: 2.1
----
+# Downgrade
-<!-- toc -->
-Due to the continuous development of Weex, some version fragmentation problems occur inevitably . For example, certain new features are not fully supported in the historical version. In this case, we need to degrade Weex to HTML and render through web.
+"Downgrade" means to rendering Weex's pages as the normal web page.
-Currently, there are many conditions and rules for the degradation which triggered by Weex definition, including operating system version, app version, SDK version, etc.
+Weex supports cross-platform (Android, iOS, Web), with different SDK but same APIs, under the hood, it's using platform capability to render pages. However with the iteration of the platforms and app, version fragmentation problem is inevitable. If you are using the feature which only supported in a higher version, you can let your page "downgrade" at the lower versions (The web renderer of Weex, or the "WebSDK", is implemented in Javascript, so it can be updated dynamically).
+> “Downgrade” is not a technical limitation, but it's useful to handle real world problems.
-Weex 2.0 downgrade change to module，please refer to [downgrade](https://www.npmjs.com/package/@weex-project/downgrade)
+## Emit Downgrade
+In Weex, the "downgrade" behavior is emitted at the front-end and is implemented by the native. The trigger of it is by calling the `error` method of the `instanceWrap` module.
+
+```js
+const instanceWrap = weex.requireModule('instanceWrap')
+instanceWrap.error(errorType, errorCode, message)
+```
+
+The `instanceWrap` only contains one API which is `error`, the arguments of it will be used to differentiate the type and reason of the downgrade behavior, they are not restrictions but conventions.
+
+* `errorType`: `Number` Error type, usually be `1` when it was emitted at front-end.
+* `errorCode`: `Number` Error code, the meaning are as follows:
+ * `1001`: The version of os (Android or iOS) is not satisfied.
+ * `1002`: The version of app is not satisfied.
+ * `1003`: The version of WeexSDK is not satisfied.
+ * `1004`: The device mode is not satisfied.
+* `message`: `String` Error message.
+
+> Calling the API anywhere in the page will trigger the downgrade immediately. It a common way to determine whether to downgrade at the beginning of the page by checking if environment meets the requirements.
+
+## Useful Tools
+
+### Npm module
+
+* npm module: [https://www.npmjs.com/package/@weex-project/downgrade](https://www.npmjs.com/package/@weex-project/downgrade)
+* source code: [https://github.com/weexteam/downgrade](https://github.com/weexteam/downgrade)
+
+First install the `@weex-project/downgrade` package, the import it to your code.
+
+```js
+import downgrade from '@weex-project/downgrade'
+```
+
+The APIs of this package are as follows:
+
+#### `force()`
+
+Force downgrade. Will downgrade immediately once you call this API.
+
+```js
+downgrade.force()
+```
+
+#### `check(options)`
+
+Check if the environment satisfies the `options`, return the diagnose result, and **will not emit downgrade.**
+
+The format of `options` will be explained later, the return value is as follow:
+
+* `isDowngrade`: Should downgrade or not. (It's `true` of the environment not satisfies the `options`)
+* `errorType`: Error type, only exist when `isDowngrade` is `true`.
+* `code`: Error code, only exist when `isDowngrade` is `true`.
+
+```js
+const result = downgrade.check({ ios: { osVersion: '<=9.0' } })
+if (!result.isDowngrade) {
+ // Do something
+}
+```
+
+#### `condition(options)`
+
+**Emit downgrade** when the environment is not satisfies the `options`.
+
+```js
+downgrade.condition({
+ android: {
+ appVersion: '<=7.8.0',
+ weexVersion: '<0.16.0'
+ }
+})
+```
+
+### Webpack Plugin
+
+Weex provides a Webpack plugin [`webpack-plugin-downgrade`](https://www.npmjs.com/package/webpack-plugin-downgrade) to inject downgrade codes to the generated file.
+
+```js
+// webpack.config.js
+var DowngradePlugin = require('webpack-plugin-downgrade')
+
+module.exports = {
+ // other configs ...
+
+ plugins: [
+ new DowngradePlugin({ /* downgrade options */ })
+ ]
+}
+```
+
+Supported options as as follows:
+
+* `force`: `Boolean` Whether to force downgrade.
+* `condition`: `Object` The condition to emit downgrade.
+
+```js
+// Force downgrade
+new DowngradePlugin({ force: true })
+
+// Downgrade if the environment satisfies the condition
+new DowngradePlugin({
+ condition: {
+ ios: {
+ deviceModel: ['iPhone5,1']
+ },
+ android: {
+ osVersion: '<=4.4',
+ weexVersion: '<0.16.0'
+ }
+ }
+})
+```
+
+## Downgrade Options
+
+The downgrade configuration is a plain object which contains `ios` and `android` options, the config properties within them are the same. The page will be downgrade once any of the option is satisfied.
+
+| Option | Data Format | Note |
+| --- | ------- | --- |
+| `osVersion` | Semantic Version | Version range of mobile OS (Android or iOS). |
+| `appVersion` | Semantic Version | Version range of App. |
+| `weexVersion` | Semantic Version | Version range of Weex SDK. |
+| `deviceModel` | String Array | Device model list. |
+
+```js
+const options = {
+ android: {
+ // Downgrade if Android version is lower than 4.5
+ osVersion: '<4.5',
+
+ // Only downgrade in the v8.1.10 of App
+ appVersion: '8.1.10'
+ },
+
+ ios: {
+ // Downgrade in WeexSDK v0.18.2 or lower
+ weexVersion: '<=0.18.2',
+
+ // Downgrade in iPhone 5 or iPhone 5s
+ deviceModel: [ 'iPhone5,1', 'iPhone6,1' ]
+ }
+}
+```
+
+### Semantic Version
+
+In the npm package and Webpack plugin, they are using a simple version of [Semantic Versioning](https://semver.org/) to verify the version number, but **only supports `>`, `<`, `=`, `>=`, `<=` those five compare operator**
+
+### Device Model
+
+The device mode string in defined by mobile device manufacturer.
diff --git a/docs/zh/guide/advanced/downgrade.md b/docs/zh/guide/advanced/downgrade.md
index e69de29..fe222ad 100644
--- a/docs/zh/guide/advanced/downgrade.md
+++ b/docs/zh/guide/advanced/downgrade.md
@@ -0,0 +1,164 @@
+# 页面降级
+
+“降级” 通常是指以普通 Web 页面的模式渲染 Weex 的页面。
+
+Weex 本身是支持跨三种平台的（Android、iOS、Web），在不同平台中集成不同版本的 SDK 来实现原生渲染，然而随着平台和应用版本的迭代，会出现版本碎片化的情况。如果你使用了较高版本中的特性，但是又无法升级已经存在的低版本 App，就可以使用“降级”的方式在低版本 App 中以普通 Web 页面的模式来渲染（在 Web 模式中，渲染器或者说“SDK”也是用 Javascript 实现的，可以动态更新）。
+
+> 降级是一个与业务属性相关的功能，这里仅提供一份建议和约定，而非技术限制。
+
+## 触发降级
+
+在 Weex 里，“降级”行为是在前端（页面代码）中触发的，由客户端来实现。触发方式是调用客户端提供的 `instanceWrap` 模块中的 `error` 方法来实现。
+
+```js
+const instanceWrap = weex.requireModule('instanceWrap')
+instanceWrap.error(errorType, errorCode, message)
+```
+
+`instanceWrap` 模块仅包含 `error` 这一个接口，传递的参数主要用于区分降级的类型和原因，与具体业务场景相关，不做强限制，大致的约定如下。
+
+* `errorType`: 【数字】 错误类型。由前端触发的降级通常约定为 `1`。
+* `errorCode`: 【数字】 错误代码。
+ * `1001`: 系统版本不满足条件。
+ * `1002`: 应用版本不满足条件。
+ * `1003`: WeexSDK 版本不满足条件。
+ * `1004`: 设备型号不满足条件。
+* `message`: 【字符串】 错误信息。
+
+> 在页面代码任意位置调用了降级接口都会立即触发降级，比较常见的做法是在渲染页面之前，先判断环境信息是否满足需求，然后触发降级。
+
+## 辅助工具
+
+为了方便使用，Weex 提供了一系列辅助模块/插件来实现降级功能。
+
+### Npm 模块
+
+* npm 模块主页： [https://www.npmjs.com/package/@weex-project/downgrade](https://www.npmjs.com/package/@weex-project/downgrade)
+* 源码地址： [https://github.com/weexteam/downgrade](https://github.com/weexteam/downgrade)
+
+首先安装 `@weex-project/downgrade` 模块，然后在页面代码中引入，调用其中的接口即可触发降级。
+
+```js
+import downgrade from '@weex-project/downgrade'
+```
+
+提供的接口如下：
+
+#### `force()`
+
+强制降级。调用该接口可以无条件立即降级。
+
+```js
+downgrade.force()
+```
+
+#### `check(options)`
+
+检查环境信息是否满足 `options` 的描述，返回校验结果，**并不会触发降级**。
+
+`options` 的格式见下文详解，返回值的格式如下：
+
+* `isDowngrade`: 是否应该降级（不满足 `options` 中的条件则为 `true`）。
+* `errorType`: 错误类型，语义同上，仅 `isDowngrade` 为 `true` 时才包含。
+* `code`: 错误代码，语义同上，仅 `isDowngrade` 为 `true` 时才包含。
+
+```js
+const result = downgrade.check({ ios: { osVersion: '<=9.0' } })
+if (!result.isDowngrade) {
+ // Do something
+}
+```
+
+#### `condition(options)`
+
+检查环境信息是否满足 `options` 的描述，**不满足条件则触发降级**。 `options` 的格式见下文详解，没有返回值。
+
+```js
+downgrade.condition({
+ android: {
+ appVersion: '<=7.8.0',
+ weexVersion: '<0.16.0'
+ }
+})
+```
+
+### Webpack 插件
+
+Weex 提供了一个 Webpack 插件 [`webpack-plugin-downgrade`](https://www.npmjs.com/package/webpack-plugin-downgrade) 支持在打包时注入触发降级的代码。
+
+```js
+// webpack.config.js
+var DowngradePlugin = require('webpack-plugin-downgrade')
+
+module.exports = {
+ // other configs ...
+
+ plugins: [
+ new DowngradePlugin({ /* downgrade options */ })
+ ]
+}
+```
+
+插件支持的配置项如下：
+
+* `force`: `Boolean` 是否强制降级。
+* `condition`: `Object` 满足特定条件时才触发降级。具体的配置项见下文详解。
+
+```js
+// 强制降级
+new DowngradePlugin({ force: true })
+
+// 满足某些条件时降级
+new DowngradePlugin({
+ condition: {
+ ios: {
+ deviceModel: ['iPhone5,1']
+ },
+ android: {
+ osVersion: '<=4.4',
+ weexVersion: '<0.16.0'
+ }
+ }
+})
+```
+
+## 降级配置项
+
+降级配置项是一个普通的 JS 对象，包含 `ios` 和 `android` 两个字段，这两个字段内部的配置项的语义都是一样的。满足配置项中的任意一个条件就会触发降级。
+
+| 字段 | 数据格式 | 含义 |
+| --- | ------- | --- |
+| `osVersion` | 语义化版本号 | 手机操作系统的版本范围 |
+| `appVersion` | 语义化版本号 | App 应用的版本范围 |
+| `weexVersion` | 语义化版本号 | WeexSDK 的版本范围 |
+| `deviceModel` | 由设备机型字符串构成的数组 | 需要降级的机型列表 |
+
+```js
+const options = {
+ // 在 Android 中的配置项
+ android: {
+ // 在低于 4.5 的安卓系统中降级
+ osVersion: '<4.5',
+
+ // 仅在 8.1.10 版本的 App 中降级
+ appVersion: '8.1.10'
+ },
+
+ // 在 iOS 中的配置项
+ ios: {
+ // 在小于等于 WeexSDK 0.18.2 的版本中降级
+ weexVersion: '<=0.18.2',
+
+ // 在 iPhone 5 和 iPhone 5s 中降级
+ deviceModel: [ 'iPhone5,1', 'iPhone6,1' ]
+ }
+}
+```
+
+### 语义化版本号
+
+在辅助降级的工具包中，实现了简版的 [Semantic Versioning](https://semver.org/)（语义化版本号）来匹配版本，**仅支持使用 `>` 、 `<` 、 `=` 、 `>=` 、 `<=` 这五种比较符。**
+
+### 设备型号
+
+设备型号由手机设备厂商定义，降级配置项中需要列举出所有想要降级的设备型号。