zshshr closed pull request #233: [doc] Add document for the guide and front-end frameworks URL: https://github.com/apache/incubator-weex-site/pull/233
This is a PR merged from a forked repository. As GitHub hides the original diff on merge, it is displayed below for the sake of provenance: As this is a foreign pull request (from a fork), the diff is supplied below (as it won't show otherwise due to GitHub magic): diff --git a/docs/guide/front-end-frameworks.md b/docs/guide/front-end-frameworks.md index e69de29bb..43d664552 100644 --- a/docs/guide/front-end-frameworks.md +++ b/docs/guide/front-end-frameworks.md @@ -0,0 +1,27 @@ +# Front-end Frameworks in Weex + +<!-- toc --> + + + +Front-end technologies seem flourishing and productive. Using front-end frameworks in production is a good way to write maintainable apps. + +However, **Weex is not a front-end framework**. Indeed, front-end frameworks are just the syntax layer or DSL (Domain-specific Language) of Weex, they are decoupled from native render engines. In another word, Weex does not rely on any specific front-end frameworks. With the evolution of the technology, Weex can integrate more widely used front-end frameworks as well. + +Currently, Weex mainly supports [Vue.js](https://vuejs.org/) and [Rax](https://alibaba.github.io/rax/), and those frameworks are already integrated into Weex SDK, you don't need to require them manually. + +> **Learn some basics of Vue.js or Rax could be very helpful when you are using Weex.** + +It is better to learn some basics of Vue.js or Rax before using Weex. + +## Vue.js + +Weex integrated the v2 version of Vue.js since WeexSDK [v0.10.0](https://github.com/alibaba/weex/releases/tag/v0.10.0) is released at 2017/02/17. Vue (pronounced /vjuː/, like view) is a progressive front-end framework for building user interfaces. Please refer to its [official website](https://vuejs.org/) for more information. + +Please refer to [Use Vue.js on Weex](./use-vue.html) document to learn more technics about Weex and Vue. + +## Rax + +Rax is a front-end framework with React-compatible APIs. + +Please refer to [Rax's official website](https://alibaba.github.io/rax/) to get more information. diff --git a/docs/guide/images/different-switch.png b/docs/guide/images/different-switch.png new file mode 100644 index 000000000..7407743ea Binary files /dev/null and b/docs/guide/images/different-switch.png differ diff --git a/docs/guide/images/flow.png b/docs/guide/images/flow.png new file mode 100644 index 000000000..c5a1b611c Binary files /dev/null and b/docs/guide/images/flow.png differ diff --git a/docs/guide/images/native-component.png b/docs/guide/images/native-component.png new file mode 100644 index 000000000..9dd5550e5 Binary files /dev/null and b/docs/guide/images/native-component.png differ diff --git a/docs/guide/images/toolkit-preview.png b/docs/guide/images/toolkit-preview.png new file mode 100644 index 000000000..504605251 Binary files /dev/null and b/docs/guide/images/toolkit-preview.png differ diff --git a/docs/guide/images/vue-rax.png b/docs/guide/images/vue-rax.png new file mode 100644 index 000000000..1e6e57eaa Binary files /dev/null and b/docs/guide/images/vue-rax.png differ diff --git a/docs/guide/images/weex-example-yo.png b/docs/guide/images/weex-example-yo.png new file mode 100644 index 000000000..81e78c14d Binary files /dev/null and b/docs/guide/images/weex-example-yo.png differ diff --git a/docs/guide/introduction.md b/docs/guide/introduction.md index 9a978743a..37ac473a7 100644 --- a/docs/guide/introduction.md +++ b/docs/guide/introduction.md @@ -1,15 +1,7 @@ ---- -title: Getting Started -type: guide -group: Overview -order: 1.1 -version: 2.1 ---- +# What is Weex? <!-- toc --> -## What is Weex? - > **Weex is a framework for building high-performance mobile applications with > a modern web development experience.** Weex enables developers to use modern web development experience to build Android, iOS, and web apps with a single codebase. In practice, you can use JavaScript and modern front-end frameworks to develop mobile apps after integrating the WeexSDK. diff --git a/docs/guide/platform-difference.md b/docs/guide/platform-difference.md index e69de29bb..249418ea2 100644 --- a/docs/guide/platform-difference.md +++ b/docs/guide/platform-difference.md @@ -0,0 +1 @@ +# Platform Difference with Web diff --git a/docs/guide/use-rax-in-weex.md b/docs/guide/use-rax-in-weex.md index e69de29bb..81b90b393 100644 --- a/docs/guide/use-rax-in-weex.md +++ b/docs/guide/use-rax-in-weex.md @@ -0,0 +1,5 @@ +# Use Rax in Weex + +Rax is a front-end framework with React-compatible APIs. + +Please refer to [Rax's official website](https://alibaba.github.io/rax/) to get more information. diff --git a/docs/guide/use-vue-in-weex.md b/docs/guide/use-vue-in-weex.md index e69de29bb..de3bfbeff 100644 --- a/docs/guide/use-vue-in-weex.md +++ b/docs/guide/use-vue-in-weex.md @@ -0,0 +1,262 @@ +# Use Vue.js in Weex + +<!-- toc --> + +Weex integrated the v2 version of Vue.js since WeexSDK [v0.10.0](https://github.com/alibaba/weex/releases/tag/v0.10.0) is released at 2016/02/17. Vue (pronounced /vjuː/, like view) is a progressive front-end framework for building user interfaces. Please refer to its [official website](https://vuejs.org/) for more information. + +> If there is no special instructions, the "Vue.js" or "Vue" in this article all refers to the v2 version of Vue.js. + +## Runtime-only Build + +If you are familiar with Vue.js, you should know that there are two available builds of Vue.js: [the **Runtime + Compiler** build and the **Runtime-only** build](https://vuejs.org/v2/guide/installation.html#Standalone-vs-Runtime-only-Build). The difference between them is whether to include the compiler which is able to compile the `template` option at runtime. + +Since the runtime-only builds are roughly 30% lighter-weight than their full-build counterparts, Weex is using the runtime-only build of Vue.js for better performance and less code size. + +Specifically, the differences are as follows: + ++ The [`template`](https://vuejs.org/v2/api/#template) option is not supported when defining a component. ++ Does not support using [`x-templates`](https://vuejs.org/v2/guide/components.html#X-Templates). ++ Does not support using [`Vue.compile`](https://vuejs.org/v2/api/#Vue-compile). + +## Platform Differences + +Vue.js was designed for the Web platform at the beginning. Although it can be based on Weex to develop native applications, there are still many [platform differences between Weex and web](../wiki/platform-difference.html). + +The key platform differences are context, DOM, styles and events. + +### Context + +Weex is mostly used to write multi-page applications, each page is a native *View* or *Activity* on mobile, and has its own context. In particular, the `Vue` instances are different in each pages, and even the "global" config of Vue (`Vue.config.xxx`) only affect the single page on Weex. + +On this basis, some SPA (single-page application) technologies of Vue, such as [Vuex](https://vuex.vuejs.org/en/) and [vue-router](https://router.vuejs.org/en/) will also take effect within the single page. More colloquially, the "page" concept is virtual in SPA technologies, but it is real on Weex. + +However, Vuex and vue-router are standalone libraries, they all have their own concept and usage scenario, you can still [use Vuex and vue-router](./advanced/use-vuex-and-vue-router.html) on Weex. + +### DOM + +Because there is no DOM (document object model) on Android and iOS, if you are manipulating and generating DOM elements manually, it may have some compatibility issues. It is a good practice to manipulate data and components instead of generated elements when you are using modern front-end frameworks. + +Some DOM-related features, such as `v-html`, `vm.$el`, `template` option, may not have the same behavior on different platforms. + +To be more specific, the type of [`vm.$el`](https://vuejs.org/v2/api/#vm-el) property is `HTMLElement` on the web, but it is not that type on mobile environments. Actually it's a special data structure defined by *Weex document object model*. + +### Styles + +The style sheet and CSS rules in managed by Weex js framework and native render engines. It would be very difficult and unnecessary to implement the whole CSSOM spec and support all CSS rules. + +For performance reasons, **Weex only support single class selector currently, and only support a subset of CSS Rules**. Please refer to *[common styles](../wiki/common-styles.html)* and *[text styles](../wiki/text-styles.html)* for more details. + +On Weex, styles are *[scoped](https://vue-loader.vuejs.org/en/features/scoped-css.html)* by force for each Vue component. + +### Events + +Event bubbling and capturing are not supported in Weex currently, therefore, [event modifiers](https://vuejs.org/v2/guide/events.html#Event-Modifiers) such as `.prevent`, ` .capture`, `.stop`, ` .self` are not supported on Weex native components. + +Moreover, the [keyboard event modifiers](https://vuejs.org/v2/guide/events.html#Key-Modifiers) and [system modifier keys](https://vuejs.org/v2/guide/events.html#System-Modifier-Keys), such as `.enter`, `.tab`, `.ctrl`, `.shift` mostly are meaningless on mobile device, which are also not supported in Weex. + +## The Web Renderer + +If you want to render your page on the web, you need to require the [weex-vue-render](https://github.com/weexteam/weex-vue-render) to achieve it. + +`weex-vue-render` is a web renderer for Vue DSL, it implemented the built-in components and built-in modules of Weex on the web. Please refer to [its repo](https://github.com/weexteam/weex-vue-render) for more details. + +## Single File Component + +[Single file component](https://vuejs.org/v2/guide/single-file-components.html) (as known as the `*.vue` files) of Vue is a special file format with a `.vue` extension. The template inside will be compiled into the `render` function at build time. + +Moreover, there are a good deals of [syntax highlight plugins](https://github.com/vuejs/awesome-vue#source-code-editing) for all kind of editors. + +> It's a good practice to use single file component syntax in Weex. + +### Compile Targets + +Because of the platform difference and to improve the performance on the web, the `*.vue` file should be compiled in two different ways: + ++ For the web platform, you can compile source files in any official way, such as [Webpack](https://webpack.js.org/) + [vue-loader](https://vue-loader.vuejs.org/en/) or Browserify + vueify. ++ For Android and iOS platforms, you should use [weex-loader](https://github.com/weexteam/weex-loader) to compile the `*.vue` files. + +Use different bundles for different platforms is to make good use of the platform original features and reduce compatibility code at build time. But the source code is still the same, the only difference is the way to compile it. + +### Use weex-loader + +[weex-loader](https://github.com/weexteam/weex-loader) is a [loader](https://webpack.js.org/concepts/loaders/#using-loaders) for webpack that can transform `*.vue` file into a plain javascript module for Android and iOS platform. All features and configurations of it are same with [vue-loader](https://vue-loader.vuejs.org/en/). + +One thing should be noted that if the *entry* option of your Webpack config is a `*.vue` file, you also need to pass an additional `entry` parameter. + +```js +const webpackConfig = { + // Add the entry parameter for the .vue file + entry: './path/to/App.vue?entry=true' + + /* ... */ + + use: { + loaders: [{ + // matches the .vue file path which contains the entry parameter + test: /\.vue(\?^^]+)?$/, + loaders: ['weex-loader'] + }] + } +} +``` + +**You don't need to write those additional parameters if you are using `.js` file as entry file.** It's a good practice to using javascript file as the entry file of webpack config. + +```Js +{ + entry: './path/to/entry.js' +} +``` + +## Supported Features + +### Global Config + +> The Vue "Global" config only affect the single page on Weex, the configuration will not be shared between different Weex pages. + +| Vue Global Config | Supported | Notes | +| -------------- | --------- | ----- | +| [Vue.config.silent](https://vuejs.org/v2/api/#silent) | <b class="tag-yes">Yes</b> | - | +| [Vue.config.optionMergeStrategies](https://vuejs.org/v2/api/#optionMergeStrategies) | <b class="tag-yes">Yes</b> | - | +| [Vue.config.devtools](https://vuejs.org/v2/api/#devtools) | <b class="tag-no">No</b> | Only supported on the web. | +| [Vue.config.errorHandler](https://vuejs.org/v2/api/#errorHandler) | <b class="tag-yes">Yes</b> | - | +| [Vue.config.warnHandler](https://vuejs.org/v2/api/#warnHandler) | <b class="tag-yes">Yes</b> | - | +| [Vue.config.ignoredElements](https://vuejs.org/v2/api/#ignoredElements) | <b class="tag-yes">Yes</b> | Not Recommend. | +| [Vue.config.keyCodes](https://vuejs.org/v2/api/#keyCodes) | <b class="tag-no">No</b> | Useless on the mobile. | +| [Vue.config.performance](https://vuejs.org/v2/api/#performance) | <b class="tag-no">No</b> | Same with *devtools*. | +| [Vue.config.productionTip](https://vuejs.org/v2/api/#productionTip) | <b class="tag-yes">Yes</b> | - | + +### Global API + +| Vue Global API | Supported | Notes | +| -------------- | --------- | ----- | +| [Vue.extend](https://vuejs.org/v2/api/#Vue-extend) | <b class="tag-yes">Yes</b> | - | +| [Vue.nextTick](https://vuejs.org/v2/api/#Vue-nextTick) | <b class="tag-yes">Yes</b> | - | +| [Vue.set](https://vuejs.org/v2/api/#Vue-set) | <b class="tag-yes">Yes</b> | - | +| [Vue.delete](https://vuejs.org/v2/api/#Vue-delete) | <b class="tag-yes">Yes</b> | - | +| [Vue.directive](https://vuejs.org/v2/api/#Vue-directive) | <b class="tag-yes">Yes</b> | - | +| [Vue.filter](https://vuejs.org/v2/api/#Vue-filter) | <b class="tag-yes">Yes</b> | - | +| [Vue.component](https://vuejs.org/v2/api/#Vue-component) | <b class="tag-yes">Yes</b> | - | +| [Vue.use](https://vuejs.org/v2/api/#Vue-use) | <b class="tag-yes">Yes</b> | - | +| [Vue.mixin](https://vuejs.org/v2/api/#Vue-mixin) | <b class="tag-yes">Yes</b> | - | +| [Vue.version](https://vuejs.org/v2/api/#Vue-version) | <b class="tag-yes">Yes</b> | - | +| [Vue.compile](https://vuejs.org/v2/api/#Vue-compile) | <b class="tag-no">No</b> | Weex is using the [runtime-only build](https://vuejs.org/v2/guide/installation.html#Runtime-Compiler-vs-Runtime-only). | + +### Options + +| Vue Option | Supported | Notes | +| ---------- | --------- | ----- | +| [data](https://vuejs.org/v2/api/#data) | <b class="tag-yes">Yes</b> | - | +| [props](https://vuejs.org/v2/api/#props) | <b class="tag-yes">Yes</b> | - | +| [propsData](https://vuejs.org/v2/api/#propsData) | <b class="tag-yes">Yes</b> | - | +| [computed](https://vuejs.org/v2/api/#computed) | <b class="tag-yes">Yes</b> | - | +| [methods](https://vuejs.org/v2/api/#methods) | <b class="tag-yes">Yes</b> | - | +| [watch](https://vuejs.org/v2/api/#watch) | <b class="tag-yes">Yes</b> | - | +| [el](https://vuejs.org/v2/api/#el) | <b class="tag-yes">Yes</b> | The value of `el` is meaningless on the mobile. | +| [template](https://vuejs.org/v2/api/#template) | <b class="tag-no">No</b> | Weex is using the [runtime-only build](https://vuejs.org/v2/guide/installation.html#Runtime-Compiler-vs-Runtime-only). | +| [render](https://vuejs.org/v2/api/#render) | <b class="tag-yes">Yes</b> | Not Recommend. | +| [renderError](https://vuejs.org/v2/api/#renderError) | <b class="tag-yes">Yes</b> | - | +| [directives](https://vuejs.org/v2/api/#directives) | <b class="tag-yes">Yes</b> | - | +| [filters](https://vuejs.org/v2/api/#filters) | <b class="tag-yes">Yes</b> | - | +| [components](https://vuejs.org/v2/api/#components) | <b class="tag-yes">Yes</b> | - | +| [parent](https://vuejs.org/v2/api/#parent) | <b class="tag-yes">Yes</b> | Not Recommend. | +| [mixins](https://vuejs.org/v2/api/#mixins) | <b class="tag-yes">Yes</b> | - | +| [extends](https://vuejs.org/v2/api/#extends) | <b class="tag-yes">Yes</b> | - | +| [provide/inject](https://vuejs.org/v2/api/#provide-inject) | <b class="tag-yes">Yes</b> | Not Recommend. | +| [name](https://vuejs.org/v2/api/#name) | <b class="tag-yes">Yes</b> | - | +| [delimiters](https://vuejs.org/v2/api/#delimiters) | <b class="tag-yes">Yes</b> | Not Recommend. | +| [functional](https://vuejs.org/v2/api/#functional) | <b class="tag-yes">Yes</b> | - | +| [model](https://vuejs.org/v2/api/#model) | <b class="tag-yes">Yes</b> | - | +| [inheritAttrs](https://vuejs.org/v2/api/#inheritAttrs) | <b class="tag-yes">Yes</b> | - | +| [comments](https://vuejs.org/v2/api/#comments) | <b class="tag-no">No</b> | - | + +### Lifecycle Hooks + +Instance lifecycle hooks of Vue components will be emitted at particular stages, refer to the [lifecycle diagram](https://vuejs.org/v2/guide/instance.html#Lifecycle-Diagram) of Vue component for more details. + +| Vue Lifecycle Hook | Supported | Notes | +| ------------------ | --------- | ----- | +| [beforeCreate](https://vuejs.org/v2/api/#beforeCreate) | <b class="tag-yes">Yes</b> | - | +| [created](https://vuejs.org/v2/api/#created) | <b class="tag-yes">Yes</b> | - | +| [beforeMount](https://vuejs.org/v2/api/#beforeMount) | <b class="tag-yes">Yes</b> | - | +| [mounted](https://vuejs.org/v2/api/#mounted) | <b class="tag-yes">Yes</b> | Not exactly the same with web, because there is no actually DOM in Weex. | +| [beforeUpdate](https://vuejs.org/v2/api/#beforeUpdate) | <b class="tag-yes">Yes</b> | - | +| [updated](https://vuejs.org/v2/api/#updated) | <b class="tag-yes">Yes</b> | - | +| [activated](https://vuejs.org/v2/api/#activated) | <b class="tag-no">No</b> | Not support `<keep-alive>` yet. | +| [deactivated](https://vuejs.org/v2/api/#deactivated) | <b class="tag-no">No</b> | Not support `<keep-alive>` yet. | +| [beforeDestroy](https://vuejs.org/v2/api/#beforeDestroy) | <b class="tag-yes">Yes</b> | - | +| [destroyed](https://vuejs.org/v2/api/#destroyed) | <b class="tag-yes">Yes</b> | - | +| [errorCaptured](https://vuejs.org/v2/api/#errorCaptured) | <b class="tag-yes">Yes</b> | New in Vue 2.5.0+, Weex SDK 0.18+ | + +### Instance Properties + +| Vue Instance Property | Supported | Notes | +| --------------------- | --------- | ----- | +| [vm.$data](https://vuejs.org/v2/api/#vm-data) | <b class="tag-yes">Yes</b> | - | +| [vm.$props](https://vuejs.org/v2/api/#vm-props) | <b class="tag-yes">Yes</b> | - | +| [vm.$el](https://vuejs.org/v2/api/#vm-el) | <b class="tag-yes">Yes</b> | The value is not `HTMLElement` on the mobile. | +| [vm.$options](https://vuejs.org/v2/api/#vm-options) | <b class="tag-yes">Yes</b> | - | +| [vm.$parent](https://vuejs.org/v2/api/#vm-parent) | <b class="tag-yes">Yes</b> | - | +| [vm.$root](https://vuejs.org/v2/api/#vm-root) | <b class="tag-yes">Yes</b> | - | +| [vm.$children](https://vuejs.org/v2/api/#vm-children) | <b class="tag-yes">Yes</b> | - | +| [vm.$slots](https://vuejs.org/v2/api/#vm-slots) | <b class="tag-yes">Yes</b> | - | +| [vm.$scopedSlots](https://vuejs.org/v2/api/#vm-scopedSlots) | <b class="tag-yes">Yes</b> | - | +| [vm.$refs](https://vuejs.org/v2/api/#vm-refs) | <b class="tag-yes">Yes</b> | - | +| [vm.$isServer](https://vuejs.org/v2/api/#vm-isServer) | <b class="tag-yes">Yes</b> | Always `false`. | +| [vm.$attrs](https://vuejs.org/v2/api/#vm-attrs) | <b class="tag-yes">Yes</b> | - | +| [vm.$listeners](https://vuejs.org/v2/api/#vm-listeners) | <b class="tag-yes">Yes</b> | - | + +### Instance Methods + +| Vue Instance Method | Supported | Notes | +| ------------------- | --------- | ----- | +| [vm.$watch()](https://vuejs.org/v2/api/#vm-watch) | <b class="tag-yes">Yes</b> | - | +| [vm.$set()](https://vuejs.org/v2/api/#vm-set) | <b class="tag-yes">Yes</b> | - | +| [vm.$delete()](https://vuejs.org/v2/api/#vm-delete) | <b class="tag-yes">Yes</b> | - | +| [vm.$on()](https://vuejs.org/v2/api/#vm-on) | <b class="tag-yes">Yes</b> | - | +| [vm.$once()](https://vuejs.org/v2/api/#vm-once) | <b class="tag-yes">Yes</b> | - | +| [vm.$off()](https://vuejs.org/v2/api/#vm-off) | <b class="tag-yes">Yes</b> | - | +| [vm.$emit()](https://vuejs.org/v2/api/#vm-emit) | <b class="tag-yes">Yes</b> | - | +| [vm.$mount()](https://vuejs.org/v2/api/#vm-mount) | <b class="tag-no">No</b> | You don't need to mount Vue instance manually. | +| [vm.$forceUpdate()](https://vuejs.org/v2/api/#vm-forceUpdate) | <b class="tag-yes">Yes</b> | - | +| [vm.$nextTick()](https://vuejs.org/v2/api/#vm-nextTick) | <b class="tag-yes">Yes</b> | - | +| [vm.$destroy()](https://vuejs.org/v2/api/#vm-destroy) | <b class="tag-yes">Yes</b> | - | + +### Directives + +| Vue Directive | Supported | Notes | +| ------------- | --------- | ----- | +| [v-text](https://vuejs.org/v2/api/#v-text) | <b class="tag-yes">Yes</b> | - | +| [v-html](https://vuejs.org/v2/api/#v-html) | <b class="tag-no">No</b> | No HTML parser in Weex, and it is not good practice. | +| [v-show](https://vuejs.org/v2/api/#v-show) | <b class="tag-no">No</b> | Not support `display: none;` yet. | +| [v-if](https://vuejs.org/v2/api/#v-if) | <b class="tag-yes">Yes</b> | - | +| [v-else](https://vuejs.org/v2/api/#v-else) | <b class="tag-yes">Yes</b> | - | +| [v-else-if](https://vuejs.org/v2/api/#v-else-if) | <b class="tag-yes">Yes</b> | - | +| [v-for](https://vuejs.org/v2/api/#v-for) | <b class="tag-yes">Yes</b> | - | +| [v-on](https://vuejs.org/v2/api/#v-on) | <b class="tag-yes">Yes</b> | Not support [event modifiers](https://vuejs.org/v2/guide/events.html#Event-Modifiers). | +| [v-bind](https://vuejs.org/v2/api/#v-bind) | <b class="tag-yes">Yes</b> | - | +| [v-model](https://vuejs.org/v2/api/#v-model) | <b class="tag-yes">Yes</b> | - | +| [v-pre](https://vuejs.org/v2/api/#v-pre) | <b class="tag-yes">Yes</b> | - | +| [v-cloak](https://vuejs.org/v2/api/#v-cloak) | <b class="tag-no">No</b> | Only support single class selector. | +| [v-once](https://vuejs.org/v2/api/#v-once) | <b class="tag-yes">Yes</b> | - | + +### Special Attributes + +| Vue Special Attribute | Supported | Notes | +| --------------------- | --------- | ----- | +| [key](https://vuejs.org/v2/api/#key) | <b class="tag-yes">Yes</b> | - | +| [ref](https://vuejs.org/v2/api/#ref) | <b class="tag-yes">Yes</b> | - | +| [slot](https://vuejs.org/v2/api/#slot) | <b class="tag-yes">Yes</b> | - | +| [slot-scope](https://vuejs.org/v2/api/#slot-scope) | <b class="tag-yes">Yes</b> | New in Vue 2.5.0+, Weex SDK 0.18+ | +| [scope](https://vuejs.org/v2/api/#scope) | <b class="tag-yes">Yes</b> | Not Recommend. | +| [is](https://vuejs.org/v2/api/#is) | <b class="tag-yes">Yes</b> | - | + +### Built-In Components + +| Vue Built-In Component | Supported | Notes | +| ---------------------- | --------- | ----- | +| [component](https://vuejs.org/v2/api/#component) | <b class="tag-yes">Yes</b> | - | +| [transition](https://vuejs.org/v2/api/#transition) | <b class="tag-no">No</b> | The concept of *enter* and *leave* maybe different on the mobile, and Weex does not support `display: none;` yet. | +| [transition-group](https://vuejs.org/v2/api/#transition-group) | <b class="tag-no">No</b> | Same with *transition*. | +| [keep-alive](https://vuejs.org/v2/api/#keep-alive) | <b class="tag-no">No</b> | Native components on the mobile can not be cached at front-end. | +| [slot](https://vuejs.org/v2/api/#slot) | <b class="tag-yes">Yes</b> | - | diff --git a/docs/zh/guide/front-end-frameworks.md b/docs/zh/guide/front-end-frameworks.md index e69de29bb..ee6dc49bb 100644 --- a/docs/zh/guide/front-end-frameworks.md +++ b/docs/zh/guide/front-end-frameworks.md @@ -0,0 +1,23 @@ +# Weex 中的前端框架 + +<!-- toc --> + + + +前端技术看起来很繁荣，测试、打包、调试等工具都比较丰富，开发效率比原生开发要高很多。在大型项目中使用前端框架也是一个管理应用好方法，这样更方便于长期维护。 + +然而，**Weex并不是一个前端框架**。实际上，前端框架仅仅是 Weex 的语法层或称之为 DSL (Domain-specific Language)，它们与原生渲染引擎是分离的。换句话说，Weex 并不依赖于特定的前端框架，随着前端技术的发展，Weex 也可以集成更多广泛使用的前端框架。 + +目前 Weex 主要支持 [Vue.js](https://vuejs.org/) 和 [Rax](https://alibaba.github.io/rax/) 作为其内置的前端框架。这些框架已经集成到了 Weex SDK，你不需要在额外引入。 + +> **学习一些 Vue 和 Rax 的基础知识，对使用 Weex 非常有帮助。** + +## Vue.js + +Weex 从 [v0.10.0](https://github.com/alibaba/weex/releases/tag/v0.10.0)（发布于 2017/02/17）这个版本开始，就集成了 v2 版本的 Vue.js。Vue.js 是一套用于构建用户界面的渐进式框架，详情请参阅其[官方网站](https://vuejs.org/)。 + +关于在 Weex 中使用 Vue 的技巧请参阅：[《使用 Vue》](./use-vue.html)。 + +## Rax + +Rax 是一个兼容 React 接口的前端框架，请参考 [Rax 的官方网站](https://alibaba.github.io/rax/) 来获得更多信息。 diff --git a/docs/zh/guide/introduction.md b/docs/zh/guide/introduction.md index e10b99d01..1c32a3b30 100644 --- a/docs/zh/guide/introduction.md +++ b/docs/zh/guide/introduction.md @@ -1 +1,170 @@ -# Introduction +# 什么是 Weex ？ + +<!-- toc --> + +> **Weex 是一个使用 Web 开发体验来开发高性能原生应用的框架。** + +Weex 致力于使开发者能基于当代先进的 Web 开发技术，使用同一套代码来构建 Android、iOS 和 Web 应用。具体来讲，在集成了 WeexSDK 之后，你可以使用 JavaScript 和现代流行的前端框架来开发移动应用。 + +Weex 的结构是解耦的，渲染引擎与语法层是分开的，也不依赖任何特定的前端框架，目前主要支持 [Vue.js](https://vuejs.org/) 和 [Rax](https://alibaba.github.io/rax/) 这两个前端框架。 + +Weex 的另一个主要目标是跟进当代先进的 Web 开发和原生开发的技术，使生产力和性能共存。在开发 Weex 页面就像开发普通网页一样；在渲染 Weex 页面时和渲染原生页面一样。 + +## Overview + +如果你只是想尝试 Weex，你并不需要安装任何东西。 Weex有一个[在线编写代码的平台](http://dotwe.org/vue/)，你可以在上面写单个页面的例子，而不需要任何配置。在平台上源代码应该用 Vue.js 的[单文件组件](https://vuejs.org/v2/guide/single-file-components.html) 语法来编写，在 Web 平台的渲染结果将显示在一个模拟的手机壳中。 + +这里有一个使用 Weex 和 Vue.js 开发的[最简单的例子](http://dotwe.org/vue/8da01827631b21150a12dd54d7114380)： + + + +这个例子在屏幕正中间渲染了一个单词 “Yo”。 如果你想在移动设备上预览渲染结果，你只需要安装[Weex playground app](/cn/tools/playground.html) 或将 Weex SDK 集成到您自己的应用程序中，然后使用扫描网页右侧的二维码。 + +在源代码的 `<template>` 中，`<div>` 你应该很熟悉了，它在 Weex 平台上也是一个通用容器。但是 `<text>` 组件是由 Weex 特有的，它是一个块级的文本容器，可以用来渲染文字。 + +> 文本只能放在 `<text>` 标签里，否则将被忽略。 + +在 `<style>` 标签内，你可以写 CSS 来描述一个组件的样式，需要注意的是，这些样式在 Weex 里只能作用于当前组件。（强制 [**scoped**](https://vue-loader.vuejs.org/en/features/scoped-css.html)）。 + +### 原生组件 + +在上面的例子中，`<div>` 和 `<text>` 在移动端上渲染出来的都是原生组件，而不是 `HTMLElement`。 + + + +Weex 在 iOS 和 Android 上都实现了一个渲染引擎，并提供了一套基础的[内置组件](../references/components/)。基于这些组件，你可以用 js 封装更多的上层组件。 + +尽管 Weex 中的组件看起来很像 HTML 标签，但你无法使用所有 HTML 标签，只能使用内置组件和自定义组件。 + +在框架内部，Weex 使用的是原生系统提供的 Widget 来渲染的。尽管 Weex 强调每个跨平台的一致性，但我们仍然接受平台本身的行为和 UI 差异。 例如 [<switch> switch 组件](http://dotwe.org/vue/d96943452b6708422197c47920903823) 在 Android 和 iOS 上看起来是不同的（在 Web 端的外观模拟了 iOS）。 + + + +除了内置组件以外，Weex 也支持你扩展更多原生组件，但是你需要在每个平台上实现它们，并保持其行为一致。最实用的方法是将现有的本地组件集成到 Weex 平台中。 + +### 原生模块 + +对于那些不依赖于 UI 的功能，Weex 推荐将它们包装到**模块**中，然后使用 `weex.requireModule('xxx')` 来引入。 这是使用 javascript 调用原生功能的一种方法，如网络，存储，剪贴板和页面导航等功能。这里有一个[使用 `stream` 模块获取 Vue.js 的 star 数](http://dotwe.org/vue/2ae062b6a04124a35bbe2da3b1e5c07b) 的例子。 + +同样，Weex 也提供了一套基础的[内置模块](../references/modules/)，也支持将已有的原生模块集成到 Weex 中。 + +关于如何扩展 Weex 的原生组件和原生模块，可以参考下列文档： + ++ [扩展 Web 渲染器](./extend-web-render.html) ++ [扩展 Android](./extend-android.html) ++ [扩展 iOS](./extend-ios.html) + +### 一次编写，处处运行 + +Weex 可以只编写一份代码，开发出三端都可用的页面。 + +在多个端中使用相同的源代码可以显著提高开发效率，并简化测试，构建和发布流程。在此基础上，Weex 可以将前端的打包、测试流程与手机端监控、发布系统结合起来，提高开发效率。 + +尽管 Weex 多端都是用的同一份代码，但是仍然支持针对特定的平台开发功能。Weex 提供了 `weex.config.env` 和 `WXEnvironment`（它们是相同的）来获得当前的运行时环境。你可以用 `WXEnvironment.platform` 来确定代码运行在哪个平台上。除了平台以外，`WXEnvironment` 还包含其他环境信息，如 *osVersion* 和 *deviceModel*，参考 *[Weex variable](../references/weex-variable.html)* 了解更多详细信息。 + +## 支持多个前端框架 + +前端框架对 Weex 而言只是一个语法层，它们和原生渲染器是解耦的。Weex 并没有强绑定与某个特定的前端框架，而是可以把渲染原生 UI 的能力赋予某些前端框架。 + +目前 Weex 将 [Vue.js](https://vuejs.org/) 和 [Rax](https://alibaba.github.io/rax/) 作为其内置的前端框架。你可以阅读 *[前端框架](./front-end-frameworks.html)* 这篇文档了解更多信息。 + + + ++ **Vue.js** 是一套用于构建用户界面的渐进式框架。 ++ **Rax** 兼容 React 接口的前端框架。 + +> Vue.js 和 Rax 都已经集成进了 Weex SDK，你不需要再额外引入。 + +然而 Weex 也不是只支持 Vue 和 Rax，你也可以把自己喜欢的前端框架集成到 Weex 中。有一个文档*[扩展前端框架](/cn/guide/extend-js-framework.html)*描述了如何实现，但是这个过程仍然非常复杂和棘手，你需要了解关于 js-native 之间通信和原生渲染引擎的许多底层细节。 + +## 创建一个 App + +> 以下步骤假设您已经了解了 Node.js 和 npm 的基本知识。如果对它们不熟悉，可以访问 [https://docs.npmjs.com/](https://docs.npmjs.com/) 来了解更多关于 npm 的用法。 + +Weex 提供了一个命令行工具 [weex-toolkit](/cn/tools/toolkit.html) 来帮助开发者使用 Weex。它可以用来快速创建一个空项目、初始化 iOS 和 Android 开发环境、调试、安装插件等操作。 + +目前 `weex-toolkit` 只支持创建 Vue.js 的项目。创建 Rax 的项目可以使用 `rax-cli`，参考 [Rax 的官方网站](https://alibaba.github.io/rax/) 了解其用法。 + +### 初始化 + +请确保你已经安装了 [Node.js](https://nodejs.org/)，然后全局安装 `weex-toolkit`。 + +```bash +npm install weex-toolkit -g +``` + +这条命令会向你命令行环境中注册一个 `weex` 命令。你可以用 `weex create` 命令来创建一个空的模板项目： + +```bash +weex create awesome-app +``` + +命令执行完以后，在当前目录的 `awesome-app` 文件夹里就有了一个空的 **Weex + Vue.js** 项目。 + +### 开发 + +下一步就是进入刚刚创建的文件夹，并且安装依赖，然后执行 `npm start`： + +```bash +cd awesome-app +npm install +npm start +``` + +然后工具会启动一个本地的 web 服务，监听 `8081` 端口。你可以打开 `http://localhost:8081` 查看页面在 Web 下的渲染效果。 源代码在 `src/` 目录中，你可以像一个普通的 Vue.js 项目一样来开发. + + + +除此之外，你还可以打开 `http://localhost:8081/preview.html` 开启一个预览页面，它会把 web 端的页面放在一个 iframe 中渲染，而且在右侧生成一个二维码。用 [Weex playground app](/cn/tools/playground.html) 扫描这个二维码可以看到页面在手机上渲染的真实效果。 + +### 编译和运行 + +默认情况下 `weex create` 命令并不初始化 iOS 和 Android 项目，你可以通过执行 `weex platform add` 来添加特定平台的项目。 + +```bash +weex platform add ios +weex platform add android +``` + +由于网络环境的不同，安装过程可能需要一些时间，请耐心等待。如果安装失败，请确保自己的网络环境畅通。 + +为了能在本地机器上打开 Android 和 iOS 项目，你应该配置好客户端的开发环境。对于 iOS，你应该安装并且配置好 [Xcode](https://developer.apple.com/xcode/)。对于 Android，你应该安装并且配置好 [Android Studio](https://developer.android.com/studio/index.html)。当开发环境准备就绪后，运行下面的命令，可以在模拟器或真实设备上启动应用： + +```bash +weex run ios +weex run android +weex run web +``` + +### 调试 + +`weex-toolkit` 还提供了强大的调试功能，只需要执行： + +```bash +weex debug +``` + +这条命令会启动一个调试服务，并且在 Chrome （目前只支持基于 V8 引擎的桌面浏览器） 中打开调试页面。详细用法请参考 [weex-toolkit 的文档](../tools/toolkit.html)。 + +## 下一步 + +当你看到这里的时候，我相信你已经了解了 Weex的基本知识。下一步是深入了解 Weex 的其他特性，并且亲自尝试。 + +如果你想现在就用 Weex： + ++ [将 Weex 集成到已有应用](./integrate-to-your-app.html) ++ [配置开发环境](./set-up-env.html) ++ [手册](../references/) + +如果你想了解 Weex 背后的原理： + ++ [Weex 是如何工作的](../wiki/index.html) ++ [设计理念](../wiki/design-principles.html) ++ [和 Web 平台的差异](../wiki/platform-difference.html) + +如果你想让 Weex 变得更好： + ++ [Weex 的开发流程](../development-process.html) ++ [如何参与贡献](../contributing.html) + +此外，Weex 是一个跨栈的技术，开发人员也是多样化的，学习一些前端开发、Vue.js、iOS 和 Android 的基本知识，会对你开发 Weex 有很大的帮助。 diff --git a/docs/zh/guide/platform-difference.md b/docs/zh/guide/platform-difference.md index e69de29bb..54c2b0bb3 100644 --- a/docs/zh/guide/platform-difference.md +++ b/docs/zh/guide/platform-difference.md @@ -0,0 +1,62 @@ +# Weex 和 Web 的平台差异 + +Weex 是一个跨平台解决方案，Web 平台只是其一种运行环境，除此之外还可以在 Android 和 iOS 客户端中运行。原生开发平台和 Web 平台之间的差异，在功能和开发体验上都有一些差异。 + +## Weex 环境中没有 DOM + +DOM（Document Object Model），即文档对象模型，是 HTML 和 XML 文档的编程接口，是 Web 中的概念。Weex 的运行环境以原生应用为主，在 Android 和 iOS 环境中渲染出来的是原生的组件，不是 DOM Element。 + +### 不支持 DOM 操作 + +既然原生环境中不支持 Web API，没有 `Element` 、`Event` 、`File` 等对象，详细列表可以参考 [Web APIs on MDN](https://developer.mozilla.org/en-US/docs/Web/API)。不支持选中元素，如 `document.getElementById` 、 `document.querySelector` 等；当然也不支持基于 DOM API 的程序库（如 jQuery）。 + +### 有限的事件类型 + +Weex 支持在标签上绑定事件，和在浏览器中的写法一样，但是 Weex 中的事件是由原生组件捕获并触发的，行为和浏览器中有所不同，事件中的属性也和 Web 中有差异。 + ++ 并不支持 Web 中所有的事件类型，详情请参考[《通用事件》](./common-events.html)。 ++ 不区分事件的捕获阶段和冒泡阶段，相当于 DOM 0 级事件。 + +## Weex 环境中没有 BOM + +BOM（Browser Object Model），即浏览器对象模型，是浏览器环境为 javascript 提供的接口。Weex 在原生端没有并不基于浏览器运行，不支持浏览器提供的 BOM 接口。 + +### 没有 `window` 、`screen` 对象 + +Weex 中并未提供浏览器中的 `window` 和 `screen` 对象，不支持使用全局变量。如果是想要获取设备的屏幕或环境信息，可以使用 `WXEnvironment` 变量。 + ++ `WXEnvironment` + + `weexVersion`: WeexSDK 的版本。 + + `appName`: 应用的名称。 + + `appVersion`: 应用的版本。 + + `platform`: 运行平台，可能的值是 `Web` 、`Android` 、`iOS` 之一。 + + `osName`: 系统的名称。 + + `osVersion`: 系统版本。 + + `deviceWidth`: 设备宽度。 + + `deviceHeight`: 设备高度。 + +### 没有 `document` 对象 + +在浏览器中 `document` 表示了当前活动的文档模型，在 Android 和 iOS 环境中并没有这个对象，也不支持与其相关的 DOM 操作。 + +### 没有 `history` 、`location` 、`navigator` 对象 + ++ `history` 保存了当前页面的历史记录，并且提供了前进后退操作。 ++ `location` 记录了当前页面 URL 相关的信息。 ++ `navigator` 记录了当前浏览器中的信息。 + +这些接口与浏览器自身的实现有关，可以控制页面的前进后退并且获取状态信息。虽然在 Android 和 iOS 中也有“历史”和“导航”的概念，但是它是用于多个管理视图之间的跳转的。换句话说，在浏览器中执行“前进”、“后退”仍然会处于同一个页签中，在原生应用中“前进”、“后退”则会真实的跳转到其他页面。 + +此外 Weex 也提供了 `navigator` 模块来操作页面的跳转，使用方法参考[《navigator 导航控制》](/cn/references/modules/navigator.html)。 + +## 能够调用移动设备原生 API + +在 Weex 中能够调用移动设备原生 API，使用方法是通过注册、调用模块来实现。其中有一些模块是 Weex 内置的，如 clipboard 、 navigator 、storage 等。 + ++ [《clipboard 剪切板》](/cn/references/modules/clipboard.html) ++ [《navigator 导航控制》](/cn/references/modules/navigator.html) ++ [《storage 本地存储 》](/cn/references/modules/storage.html) + +为了保持框架的通用性，Weex 内置的原生模块有限，不过 Weex 提供了横向扩展的能力，可以扩展原生模块，具体的扩展方法请参考[《iOS 扩展》](/cn/index.html) 和[《Android 扩展》](/cn/guide/extend-android.html)。 + +> 有些接口在浏览器环境中也存在，不过在使用时应该注意浏览器的兼容性；如剪贴板功能，出于安全性考虑，绝大多数浏览器都限制其使用。 diff --git a/docs/zh/guide/use-rax-in-weex.md b/docs/zh/guide/use-rax-in-weex.md index e69de29bb..a110a7c26 100644 --- a/docs/zh/guide/use-rax-in-weex.md +++ b/docs/zh/guide/use-rax-in-weex.md @@ -0,0 +1,3 @@ +# 在 Weex 中使用 Rax + +> **Rax 是一个兼容 React 接口的前端框架，请访问 [Rax 的官方网站](https://alibaba.github.io/rax/) 了解更多信息。** diff --git a/docs/zh/guide/use-vue-in-weex.md b/docs/zh/guide/use-vue-in-weex.md index e69de29bb..cd029b562 100644 --- a/docs/zh/guide/use-vue-in-weex.md +++ b/docs/zh/guide/use-vue-in-weex.md @@ -0,0 +1,259 @@ +# 在 Weex 中使用 Vue.js + +<!-- toc --> + +自2016年2月17日发布 WeexSDK [v0.10.0](https://github.com/alibaba/weex/releases/tag/v0.10.0) 后， Weex 集成了 v2 版本的 Vue。Vue（读音 /vjuː/，类似于 view 的读音）是一套构建用户界面的渐进式框架。详情请参阅其[官方网站](https://cn.vuejs.org/)。 + +> 如果没有特别指示，文章中的 "Vue.js" 或者 "Vue" 都指的是 v2 版本的 Vue。 + +## 只含有运行时的构建版本 + +如果你熟悉 Vue.js，你应该知道 Vue.js 有两种构建版本: [**运行时 + 编译器** 与 **只包含运行时**](https://cn.vuejs.org/v2/guide/installation.html#%E8%BF%90%E8%A1%8C%E6%97%B6-%E7%BC%96%E8%AF%91%E5%99%A8-vs-%E5%8F%AA%E5%8C%85%E5%90%AB%E8%BF%90%E8%A1%8C%E6%97%B6)。它们之间的区别在于编译器是否需要能够在运行时编译`template`选项。由于运行时构建版本比完整版本的构建版本轻约30%，为了更好的性能和更少的代码尺寸，Weex用的是只包含运行时的方式构建Vue。 + +具体来说，差异如下： + ++ 定义组件时不支持[`template`](https://cn.vuejs.org/v2/api/#template)选项。 ++ 不支持使用[`x-templates`](https://cn.vuejs.org/v2/guide/components.html#X-Templates)。 ++ 不支持使用[`Vue.compile`](https://cn.vuejs.org/v2/api/#Vue-compile)。 + +## 平台的差异 + +Vue.js最初是为Web平台设计的。虽然可以基于Weex开发原生应用程序，但是仍然存在许多[Weex 与 Web 平台的差异](../wiki/platform-difference.html)。 + +与 Web 平台的主要差异是: 上下文、DOM、样式和事件。 + +### 上下文 +Weex 主要用于编写多页的应用程序，每一页相当于原生开发中的 *View* 或者 *Activity*，并且它有着自己的上下文。尤其`Vue`实例在每个页面都是不同的，甚至 Vue 的"全局"配置（`Vue.config.xxx`）也只会影响 Weex 上的单个页面。 + +在此基础上，一些 Vue 的 SPA （单页面应用）技术，如 [Vuex](https://vuex.vuejs.org/zh-cn/) 和 [vue-router](https://router.vuejs.org/zh-cn/) 也将单页内生效。更通俗地说，“页面”概念在 SPA 技术中是虚拟的，但在 Weex 上却是真实的。 + +无论如何，Vuex 和 vue-router 都是独立的库，它们都有自己的概念和使用场景，你仍然可以在 Weex 里[使用 Vuex 和 vue-router](./advanced/use-vuex-and-vue-router.html)。 + +### DOM + +因为在 Android 和 iOS 上没有 DOM（Document Object Model），如果你要手动操作和生成 DOM 元素的话可能会遇到一些兼容性问题。在你使用现代前端框架的情况下，操作数据与组件而不是生成的元素是一个比较好的做法。 + +一些与 DOM 相关的特性，比如 `v-html`，`vm.$el`，`template` 选项，在不同的平台上可能无法获得相同的反应。 + +准确来说，[`vm.$el`](https://cn.vuejs.org/v2/api/#vm-el)属性类型在web环境下是`HTMLElement`，但是在移动端并没有这个类型。实际上，它是一个由 *Weex 文档对象模型* 定义的特殊数据结构。 + +### 样式 + +样式表和 CSS 规则是由 Weex js 框架和原生渲染引擎管理的。要实现完整的 CSS 对象模型（CSSOM：CSS Object Model）并支持所有的 CSS 规则是非常困难的，而且没有这个必要。 + +出现性能考虑，**Weex 目前只支持单个类选择器，并且只支持 CSS 规则的子集**。详情请参阅 *[通用样式](../wiki/common-styles.html)* 与 *[文本样式](../wiki/text-styles.html)*。 + +在 Weex 里， 每一个 Vue 组件的样式都是 *[scoped](https://vue-loader.vuejs.org/zh-cn/features/scoped-css.html)*。 + +### 事件 + +目前在 Weex 里不支持事件冒泡和捕获，因此 Weex 原生组件不支持[事件修饰符](https://cn.vuejs.org/v2/guide/events.html#%E4%BA%8B%E4%BB%B6%E4%BF%AE%E9%A5%B0%E7%AC%A6)，例如`.prevent`，` .capture`，`.stop`，` .self` 。 + +此外，[按键修饰符](https://cn.vuejs.org/v2/guide/events.html#%E6%8C%89%E9%94%AE%E4%BF%AE%E9%A5%B0%E7%AC%A6)以及[系统修饰键](https://cn.vuejs.org/v2/guide/events.html#%E7%B3%BB%E7%BB%9F%E4%BF%AE%E9%A5%B0%E9%94%AE) 例如 `.enter`，`.tab`，`.ctrl`，`.shift` 在移动端基本没有意义，在 Weex 中也不支持。 + +## Web 渲染器 + +如果你想在网络上呈现你的页面，你需要 [weex-vue-render](https://github.com/weexteam/weex-vue-render) 来实现它。 + +`weex-vue-render`是 Vue DSL 的 Web 渲染器， 它在 Web 上实现了 Weex 的内置组件和内置模块。详情请参阅[这里](https://github.com/weexteam/weex-vue-render)。 + +## 单文件组件 + +Vue 中的[单文件组件](https://cn.vuejs.org/v2/guide/single-file-components.html)（即`*.vue`文件）是一种特殊的文件格式，扩展名为`.vue`。这个模板会在构建时便于到`render`函数里。 + +此外，所有的编辑器里都支持一个好的[语法高亮插件](https://github.com/vuejs/awesome-vue#source-code-editing)。 + +> 在 Weex 中使用单个文件组件语法是一种很好的做法。 + +### 编译目标 + +因为平台的差异以及为了提高网络性能，`*.vue`文件需要用两种不同的方式来编译： + ++ 对于 Web 平台来说，你可以用任何正式的方式来编译源文件，例如 使用 **[Webpack](https://webpack.js.org/) + [vue-loader](https://vue-loader.vuejs.org/en/)** 或者 **Browserify + vueify** 来编译`*.vue`文件。 ++ 对于安卓与 iOS 平台来说， 你需要使用 [weex-loader](https://github.com/weexteam/weex-loader) 来编译`*.vue`文件。 + +不同的平台使用不同的`bundles`，可以充分利用平台原有的特性，减少构建时的兼容性代码。但是源代码仍然是一样的，唯一的区别是编译它的方法。 + +### 使用weex-loader + +[weex-loader](https://github.com/weexteam/weex-loader) 是一个 webpack 的 [loader](https://webpack.js.org/concepts/loaders/#using-loaders)，它能把`*.vue`文件转化为简单的javascript 模块用于安卓以及 iOS 平台。所有的特性和配置都是跟 [vue-loader](https://vue-loader.vuejs.org/en/) 一样的。 + +需要注意的是，如果您的Webpack配置的*entry*选项是一个`*.vue`文件的话，你仍需要传递一个额外的`entry`参数。 + +```js +const webpackConfig = { + // Add the entry parameter for the .vue file + entry: './path/to/App.vue?entry=true' + + /* ... */ + + use: { + loaders: [{ + // matches the .vue file path which contains the entry parameter + test: /\.vue(\?^^]+)?$/, + loaders: ['weex-loader'] + }] + } +} +``` + +**如果你现在用的是`.js`文件做入口文件，你不需要写那些额外的参数。**推荐 webpack 配置的入口文件使用 javascript 文件。 + +```js +{ + entry: './path/to/entry.js' +} +``` + +## 支持的功能 + +### 全局配置 + +> Vue “全局”配置只会影响 Weex 上的单一页面，配置不会在不同的 Weex 页面之间共享。 + +| Vue 全局配置 | 是否支持 | 说明 | +| -------------- | --------- | ----- | +| [Vue.config.silent](https://cn.vuejs.org/v2/api/#silent) | <b class="tag-yes">支持</b> | - | +| [Vue.config.optionMergeStrategies](https://cn.vuejs.org/v2/api/#optionMergeStrategies) | <b class="tag-yes">支持</b> | - | +| [Vue.config.devtools](https://cn.vuejs.org/v2/api/#devtools) | <b class="tag-no">不支持</b> | 只在 Web 环境下支持 | +| [Vue.config.errorHandler](https://cn.vuejs.org/v2/api/#errorHandler) | <b class="tag-yes">支持</b> | - | +| [Vue.config.warnHandler](https://cn.vuejs.org/v2/api/#warnHandler) | <b class="tag-yes">支持</b> | - | +| [Vue.config.ignoredElements](https://cn.vuejs.org/v2/api/#ignoredElements) | <b class="tag-yes">支持</b> | 不推荐 | +| [Vue.config.keyCodes](https://cn.vuejs.org/v2/api/#keyCodes) | <b class="tag-no">不支持</b> | 在移动端无用 | +| [Vue.config.performance](https://cn.vuejs.org/v2/api/#performance) | <b class="tag-no">不支持</b> | 与 *devtools* 一样 | +| [Vue.config.productionTip](https://cn.vuejs.org/v2/api/#productionTip) | <b class="tag-yes">支持</b> | - | + +### 全局 API + +| Vue 全局 API | 是否支持 | 说明 | +| -------------- | --------- | ----- | +| [Vue.extend](https://cn.vuejs.org/v2/api/#Vue-extend) | <b class="tag-yes">支持</b> | - | +| [Vue.nextTick](https://cn.vuejs.org/v2/api/#Vue-nextTick) | <b class="tag-yes">支持</b> | - | +| [Vue.set](https://cn.vuejs.org/v2/api/#Vue-set) | <b class="tag-yes">支持</b> | - | +| [Vue.delete](https://cn.vuejs.org/v2/api/#Vue-delete) | <b class="tag-yes">支持</b> | - | +| [Vue.directive](https://cn.vuejs.org/v2/api/#Vue-directive) | <b class="tag-yes">支持</b> | - | +| [Vue.filter](https://cn.vuejs.org/v2/api/#Vue-filter) | <b class="tag-yes">支持</b> | - | +| [Vue.component](https://cn.vuejs.org/v2/api/#Vue-component) | <b class="tag-yes">支持</b> | - | +| [Vue.use](https://cn.vuejs.org/v2/api/#Vue-use) | <b class="tag-yes">支持</b> | - | +| [Vue.mixin](https://cn.vuejs.org/v2/api/#Vue-mixin) | <b class="tag-yes">支持</b> | - | +| [Vue.version](https://cn.vuejs.org/v2/api/#Vue-version) | <b class="tag-yes">支持</b> | - | +| [Vue.compile](https://cn.vuejs.org/v2/api/#Vue-compile) | <b class="tag-no">不支持</b> | Weex 用的是 [只包含运行时构建](https://cn.vuejs.org/v2/guide/installation.html#%E8%BF%90%E8%A1%8C%E6%97%B6-%E7%BC%96%E8%AF%91%E5%99%A8-vs-%E5%8F%AA%E5%8C%85%E5%90%AB%E8%BF%90%E8%A1%8C%E6%97%B6) | + +### 选项 + +| Vue 选项 | 是否支持 | 说明 | +| ---------- | --------- | ----- | +| [data](https://cn.vuejs.org/v2/api/#data) | <b class="tag-yes">支持</b> | - | +| [props](https://cn.vuejs.org/v2/api/#props) | <b class="tag-yes">支持</b> | - | +| [propsData](https://cn.vuejs.org/v2/api/#propsData) | <b class="tag-yes">支持</b> | - | +| [computed](https://cn.vuejs.org/v2/api/#computed) | <b class="tag-yes">支持</b> | - | +| [methods](https://cn.vuejs.org/v2/api/#methods) | <b class="tag-yes">支持</b> | - | +| [watch](https://cn.vuejs.org/v2/api/#watch) | <b class="tag-yes">支持</b> | - | +| [el](https://cn.vuejs.org/v2/api/#el) | <b class="tag-yes">支持</b> | 在移动端`el`的值是无意义的 | +| [template](https://cn.vuejs.org/v2/api/#template) | <b class="tag-no">不支持</b> | Weex 用的是 [只包含运行时构建](https://cn.vuejs.org/v2/guide/installation.html#%E8%BF%90%E8%A1%8C%E6%97%B6-%E7%BC%96%E8%AF%91%E5%99%A8-vs-%E5%8F%AA%E5%8C%85%E5%90%AB%E8%BF%90%E8%A1%8C%E6%97%B6) | +| [render](https://cn.vuejs.org/v2/api/#render) | <b class="tag-yes">支持</b> | 不推荐| +| [renderError](https://cn.vuejs.org/v2/api/#renderError) | <b class="tag-yes">支持</b> | - | +| [directives](https://cn.vuejs.org/v2/api/#directives) | <b class="tag-yes">支持</b> | - | +| [filters](https://cn.vuejs.org/v2/api/#filters) | <b class="tag-yes">支持</b> | - | +| [components](https://cn.vuejs.org/v2/api/#components) | <b class="tag-yes">支持</b> | - | +| [parent](https://cn.vuejs.org/v2/api/#parent) | <b class="tag-yes">支持</b> | 不推荐 | +| [mixins](https://cn.vuejs.org/v2/api/#mixins) | <b class="tag-yes">支持</b> | - | +| [extends](https://cn.vuejs.org/v2/api/#extends) | <b class="tag-yes">支持</b> | - | +| [provide/inject](https://cn.vuejs.org/v2/api/#provide-inject) | <b class="tag-yes">支持</b> | 不推荐 | +| [name](https://cn.vuejs.org/v2/api/#name) | <b class="tag-yes">支持</b> | - | +| [delimiters](https://cn.vuejs.org/v2/api/#delimiters) | <b class="tag-yes">支持</b> | 不推荐 | +| [functional](https://cn.vuejs.org/v2/api/#functional) | <b class="tag-yes">支持</b> | - | +| [model](https://cn.vuejs.org/v2/api/#model) | <b class="tag-yes">支持</b> | - | +| [inheritAttrs](https://cn.vuejs.org/v2/api/#inheritAttrs) | <b class="tag-yes">支持</b> | - | +| [comments](https://cn.vuejs.org/v2/api/#comments) | <b class="tag-no">不支持</b> | - | + +### 生命周期钩子 + +Vue 组件的实例生命周期钩子将在特定的阶段发出，详情请参考 Vue 组件的[生命周期图示](https://cn.vuejs.org/v2/guide/instance.html#%E7%94%9F%E5%91%BD%E5%91%A8%E6%9C%9F%E5%9B%BE%E7%A4%BA)。 + +| Vue 生命周期钩子 | 是否支持 | 说明 | +| ------------------ | --------- | ----- | +| [beforeCreate](https://cn.vuejs.org/v2/api/#beforeCreate) | <b class="tag-yes">支持</b> | - | +| [created](https://cn.vuejs.org/v2/api/#created) | <b class="tag-yes">支持</b> | - | +| [beforeMount](https://cn.vuejs.org/v2/api/#beforeMount) | <b class="tag-yes">支持</b> | - | +| [mounted](https://cn.vuejs.org/v2/api/#mounted) | <b class="tag-yes">支持</b> | 和 Web 端不完全一样（Weex 里并没有真实 DOM） | +| [beforeUpdate](https://cn.vuejs.org/v2/api/#beforeUpdate) | <b class="tag-yes">支持</b> | - | +| [updated](https://cn.vuejs.org/v2/api/#updated) | <b class="tag-yes">支持</b> | - | +| [activated](https://cn.vuejs.org/v2/api/#activated) | <b class="tag-no">不支持</b> | 不支持`<keep-alive>` | +| [deactivated](https://cn.vuejs.org/v2/api/#deactivated) | <b class="tag-no">不支持</b> | 不支持`<keep-alive>` | +| [beforeDestroy](https://cn.vuejs.org/v2/api/#beforeDestroy) | <b class="tag-yes">支持</b> | - | +| [destroyed](https://cn.vuejs.org/v2/api/#destroyed) | <b class="tag-yes">支持</b> | - | +| [errorCaptured](https://cn.vuejs.org/v2/api/#errorCaptured) | <b class="tag-yes">支持</b> | 在 Vue 2.5.0+， Weex SDK 0.18+ 中新增 | + +### 实例属性 + +| Vue 实例属性 | 是否支持 | 说明 | +| --------------------- | --------- | ----- | +| [vm.$data](https://cn.vuejs.org/v2/api/#vm-data) | <b class="tag-yes">支持</b> | - | +| [vm.$props](https://cn.vuejs.org/v2/api/#vm-props) | <b class="tag-yes">支持</b> | - | +| [vm.$el](https://cn.vuejs.org/v2/api/#vm-el) | <b class="tag-yes">支持</b> | 移动端没有`HTMLElement` | +| [vm.$options](https://cn.vuejs.org/v2/api/#vm-options) | <b class="tag-yes">支持</b> | - | +| [vm.$parent](https://cn.vuejs.org/v2/api/#vm-parent) | <b class="tag-yes">支持</b> | - | +| [vm.$root](https://cn.vuejs.org/v2/api/#vm-root) | <b class="tag-yes">支持</b> | - | +| [vm.$children](https://cn.vuejs.org/v2/api/#vm-children) | <b class="tag-yes">支持</b> | - | +| [vm.$slots](https://cn.vuejs.org/v2/api/#vm-slots) | <b class="tag-yes">支持</b> | - | +| [vm.$scopedSlots](https://cn.vuejs.org/v2/api/#vm-scopedSlots) | <b class="tag-yes">支持</b> | - | +| [vm.$refs](https://cn.vuejs.org/v2/api/#vm-refs) | <b class="tag-yes">支持</b> | - | +| [vm.$isServer](https://cn.vuejs.org/v2/api/#vm-isServer) | <b class="tag-yes">支持</b> | 永远是`false`| +| [vm.$attrs](https://cn.vuejs.org/v2/api/#vm-attrs) | <b class="tag-yes">支持</b> | - | +| [vm.$listeners](https://cn.vuejs.org/v2/api/#vm-listeners) | <b class="tag-yes">支持</b> | - | + +### 实例方法 + +| Vue 实例方法 | 是否支持 | 说明 | +| ------------------- | --------- | ----- | +| [vm.$watch()](https://cn.vuejs.org/v2/api/#vm-watch) | <b class="tag-yes">支持</b> | - | +| [vm.$set()](https://cn.vuejs.org/v2/api/#vm-set) | <b class="tag-yes">支持</b> | - | +| [vm.$delete()](https://cn.vuejs.org/v2/api/#vm-delete) | <b class="tag-yes">支持</b> | - | +| [vm.$on()](https://cn.vuejs.org/v2/api/#vm-on) | <b class="tag-yes">支持</b> | - | +| [vm.$once()](https://cn.vuejs.org/v2/api/#vm-once) | <b class="tag-yes">支持</b> | - | +| [vm.$off()](https://cn.vuejs.org/v2/api/#vm-off) | <b class="tag-yes">支持</b> | - | +| [vm.$emit()](https://cn.vuejs.org/v2/api/#vm-emit) | <b class="tag-yes">支持</b> | - | +| [vm.$mount()](https://cn.vuejs.org/v2/api/#vm-mount) | <b class="tag-no">不支持</b> | 你不需要手动安装 Vue 实例 | +| [vm.$forceUpdate()](https://cn.vuejs.org/v2/api/#vm-forceUpdate) | <b class="tag-yes">支持</b> | - | +| [vm.$nextTick()](https://cn.vuejs.org/v2/api/#vm-nextTick) | <b class="tag-yes">支持</b> | - | +| [vm.$destroy()](https://cn.vuejs.org/v2/api/#vm-destroy) | <b class="tag-yes">支持</b> | - | + +### 模板指令 + +| Vue 指令 | 是否支持 | 说明 | +| ------------- | --------- | ----- | +| [v-text](https://cn.vuejs.org/v2/api/#v-text) | <b class="tag-yes">支持</b> | - | +| [v-html](https://cn.vuejs.org/v2/api/#v-html) | <b class="tag-no">不支持</b> | Weex 中没有 HTML 解析器，这不是很好的实现 | +| [v-show](https://cn.vuejs.org/v2/api/#v-show) | <b class="tag-no">不支持</b> | 不支持 `display: none;` | +| [v-if](https://cn.vuejs.org/v2/api/#v-if) | <b class="tag-yes">支持</b> | - | +| [v-else](https://cn.vuejs.org/v2/api/#v-else) | <b class="tag-yes">支持</b> | - | +| [v-else-if](https://cn.vuejs.org/v2/api/#v-else-if) | <b class="tag-yes">支持</b> | - | +| [v-for](https://cn.vuejs.org/v2/api/#v-for) | <b class="tag-yes">支持</b> | - | +| [v-on](https://cn.vuejs.org/v2/api/#v-on) | <b class="tag-yes">支持</b> | 不支持[事件修饰符](https://cn.vuejs.org/v2/guide/events.html#%E4%BA%8B%E4%BB%B6%E4%BF%AE%E9%A5%B0%E7%AC%A6) | +| [v-bind](https://cn.vuejs.org/v2/api/#v-bind) | <b class="tag-yes">支持</b> | - | +| [v-model](https://cn.vuejs.org/v2/api/#v-model) | <b class="tag-yes">支持</b> | - | +| [v-pre](https://cn.vuejs.org/v2/api/#v-pre) | <b class="tag-yes">支持</b> | - | +| [v-cloak](https://cn.vuejs.org/v2/api/#v-cloak) | <b class="tag-no">不支持</b> | 只支持单类名选择器 | +| [v-once](https://cn.vuejs.org/v2/api/#v-once) | <b class="tag-yes">支持</b> | - | + +### 特殊属性 + +| Vue 特殊属性 | 是否支持 | 说明 | +| --------------------- | --------- | ----- | +| [key](https://cn.vuejs.org/v2/api/#key) | <b class="tag-yes">支持</b> | - | +| [ref](https://cn.vuejs.org/v2/api/#ref) | <b class="tag-yes">支持</b> | - | +| [slot](https://cn.vuejs.org/v2/api/#slot) | <b class="tag-yes">支持</b> | - | +| [slot-scope](https://cn.vuejs.org/v2/api/#slot-scope) | <b class="tag-yes">支持</b> | 在 Vue 2.5.0+， Weex SDK 0.18+ 中新增 | +| [scope](https://cn.vuejs.org/v2/api/#scope) | <b class="tag-yes">支持</b> | 不推荐 | +| [is](https://cn.vuejs.org/v2/api/#is) | <b class="tag-yes">支持</b> | - | + +### 内置组件 + +| Vue 内置组件 | 是否支持 | 说明 | +| ---------------------- | --------- | ----- | +| [component](https://cn.vuejs.org/v2/api/#component) | <b class="tag-yes">支持</b> | - | +| [transition](https://cn.vuejs.org/v2/api/#transition) | <b class="tag-no">不支持</b> | 在移动端 *enter* 与 *leave* 的概念可能有点不同， 并且 Weex 不支持`display: none;` | +| [transition-group](https://cn.vuejs.org/v2/api/#transition-group) | <b class="tag-no">不支持</b> | 跟 *transition* 一样 | +| [keep-alive](https://cn.vuejs.org/v2/api/#keep-alive) | <b class="tag-no">不支持</b> | 移动端的原生组件不能被前端缓存 | +| [slot](https://cn.vuejs.org/v2/api/#slot) | <b class="tag-yes">支持</b> | - | ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
