You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@weex.apache.org by ky...@apache.org on 2018/12/26 04:03:54 UTC
[incubator-weex-site] branch draft updated: * Update doc for
animation, text, image and dom (#270)
This is an automated email from the ASF dual-hosted git repository.
kyork 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 50fdca9 * Update doc for animation, text, image and dom (#270)
50fdca9 is described below
commit 50fdca9fe0f06781de6c60c0b5645e5fabb7b772
Author: YorkShen <sh...@gmail.com>
AuthorDate: Wed Dec 26 12:03:51 2018 +0800
* Update doc for animation, text, image and dom (#270)
---
docs/docs/components/image.md | 61 +++++------
docs/docs/components/text.md | 61 +++++++----
docs/docs/modules/animation.md | 154 ++++++++++++++--------------
docs/docs/modules/dom.md | 201 +++++++++++++++++++++++++++++++++---
docs/zh/docs/components/image.md | 136 ++++++++++++-------------
docs/zh/docs/components/text.md | 132 ++++++++----------------
docs/zh/docs/modules/animation.md | 207 +++++++++++++++++---------------------
docs/zh/docs/modules/dom.md | 38 ++++---
8 files changed, 561 insertions(+), 429 deletions(-)
diff --git a/docs/docs/components/image.md b/docs/docs/components/image.md
index d072f09..1ff873c 100644
--- a/docs/docs/components/image.md
+++ b/docs/docs/components/image.md
@@ -1,16 +1,23 @@
-# Image Component
+---
+title: <image>
+type: references
+group: Build-in Components
+order: 8.04
+version: 2.1
+---
`<image>` is used to display a single image in your interface.
-> **Note:** `<img>` element which is usually used in HTML is not supported in Weex, you should use `<image>` instead.
+> **Note:** Always use `<image>` in your code, as `<img>` exists only for backward compatibility reasons and may removed in the future release.
-> **Note:** Weex doesn't have built-in image downloader, as download, cache, decompression features are complicated and some open source tools like [SDWebImage](https://github.com/rs/SDWebImage) handles it well, so please add native image adapter/handler before using `<image>`.
+> **Note:** Weex doesn't have built-in library for image downloading and caching, as there are some great open source library like [SDWebImage in iOS](https://github.com/rs/SDWebImage) and [Picasso in Android](https://github.com/square/picasso) handling these problem, so please add native image adapter/handler before using `<image>`.
>
-> See also: [Android adapter](../android-apis.html#Adapter) and [iOS handler](../ios-apis.html#Handler-like-Android-Adapter).
+> See also: [Android adapter](../api/android-apis.html) and [iOS handler](../api/ios-apis.html).
## Basic Usage
-> **Note:** the style attributes of `width` and `height` must be specified, otherwise it won't work.
+> **Note:** the style of `width`, `height` and `src` must be specified, otherwise it will load nothing.
+
```html
<image style="width:500px;height:500px" src="https://vuejs.org/images/logo.png"></image>
@@ -18,7 +25,14 @@
See the [example](http://dotwe.org/vue/00f4b68b3a86360df1f38728fd0b4a1f).
- ## Attributes
+## Child
+`<image>` doesn't support any child component.
+
+## Styles
+
+Support **[common styles](../styles/common-styles.html)**.
+
+## Attributes
| Attribute | Type | Value | Default Value |
| ------------- | ------ | -------------------------- | ------------- |
@@ -28,11 +42,11 @@ See the [example](http://dotwe.org/vue/00f4b68b3a86360df1f38728fd0b4a1f).
> **Note:** you can specify a relative URL for `src` and `placeholder`, relative URL will be rewritten to the to the actual resource URL (local or remote). See also: [Path](../../guide/advanced/asset-path.html).
- ### `placeholder`
+### placeholder
-A URL value for placeholder image. It will be displayed when the image view is empty and will be replaced as soon as the 'src' image gets loaded.[(Example)](http://dotwe.org/vue/712ef102fc5e073b6c7e3b701545681c)
+A URL value for placeholder image. It will be displayed during image downloading and replaced as soon as the image gets loaded.[(Example)](http://dotwe.org/vue/712ef102fc5e073b6c7e3b701545681c)
- ### `resize`
+### resize
@@ -43,9 +57,9 @@ A URL value for placeholder image. It will be displayed when the image view is e
- `stretch`: `Default value`. Scales the content to fit the size of the element itself by changing the aspect ratio of the image if necessary. ([Example](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
-See also: [`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size).
+`resize` property is similar to [`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size).
-### `src`
+### src
The URL of the image to display. This attribute is mandatory for the `<image>` component.
@@ -53,6 +67,8 @@ The URL of the image to display. This attribute is mandatory for the `<image>` c
Weex doesn't give a list of image formats that must be supported, it mainly relies on the image adapter/handler you are using. For example, if you are using [SDWebImage](https://github.com/rs/SDWebImage#supported-image-formats) as the image adapter on iOS, you can use image formats like JPEG, PNG, GIF, WebP, etc.
+> **Note:** The default image adapter on Android doesn't support gif.
+
## Component Methods
### `save` <span class="api-version">v0.16.0+</span>
@@ -84,10 +100,10 @@ Get the component reference and use the `save` method:
const $image = this.$refs.poster
$image.save(result => {
if (result.success) {
- // Do something to hanlde success
+ // Do something to handle success
} else {
console.log(result.errorDesc)
- // Do something to hanlde failure
+ // Do something to handle failure
}
})
```
@@ -96,8 +112,7 @@ Complete example goes [here](http://dotwe.org/vue/fadcd44a7031943ff0feaaf1895df4
## Events
-Support **[common events](../../wiki/common-events.html)**.
-
+Support **[common events](../events/common-events.html)**.
### `load`
`load` event handler will be called when the image is loaded.
@@ -133,18 +148,6 @@ export default {
Complete example goes [here](http://dotwe.org/vue/94de9307517240dec066d2ea57fe54a0).
-## Styles
-
-Support **[common styles](../../wiki/common-styles.html)**.
-
-## Usage Notes
-
-- Add image adapter/handler before using `<image>`
-- The `width` and `height` in the styles of `<image>` must be specified.
-- `<image>` can not have any nested child component.
-
## Examples
-
-- [Base64 example](http://dotwe.org/vue/ba477790c85ea12bbf7ad3a5f0885b5c)
-- [Multi-layer images example](http://dotwe.org/vue/c44359c0f200abc1f66504b88587e4f6)
-- [Lazy load image example](http://dotwe.org/vue/b0b146e4e6fa4890f800e18cb950f803)
+* [Base64 example](http://dotwe.org/vue/ba477790c85ea12bbf7ad3a5f0885b5c)
+* [Lazy load image example](http://dotwe.org/vue/b0b146e4e6fa4890f800e18cb950f803)
\ No newline at end of file
diff --git a/docs/docs/components/text.md b/docs/docs/components/text.md
index eebc172..3000cf0 100644
--- a/docs/docs/components/text.md
+++ b/docs/docs/components/text.md
@@ -1,35 +1,52 @@
# Text
-The weex builtin component 'text' is used to render text with specified style rule. `<text>` tag can contain text value only. You can use variable interpolation in the text content with the mark `{% raw %}{{}}{% endraw %}`.
+The weex builtin component 'text' is used to render text with specified style rule.
> **Note:** This component supports no child components.
-## Attributes
-* value(string): text value of this component. This is equal to the content of 'text'.
-
- var textComponent = this.$el("textid");
- this.text = textComponent.attr.value;
+> **Note:** The heading and trailing white space will be ignored. If this is not what you need, you can set text using the data-binding method above.
## Styles
-* Support [common styles for components](/wiki/common-styles.html)
-* lines: specify the text lines. Default value is `0` for unlimited.
-* Support [text styles](/wiki/text-styles.html)
- * support 'color' style.
- * support 'font-size' style. iOS: default vlaue `32`. Android: platform specify. HTML5: default value `32`.
- * support 'font-style' style.
- * support 'font-weight' style.
- * support 'text-align' style.
- * support 'text-decoration' style.
- * support 'text-overflow' style.
- * support 'line-height'(available from v0.6.1) style.
+* Support [common styles for components](../styles/common-styles.html)
+* Support [text style](../styles/text-styles.html)
-## Events
-Support [common events](/wiki/common-events.html)
+## Attributes
+Except for dynamic text, there is no other supported attributes for text.
+### dynamic text
+One can use the following code snippet to bind the content of text to a variable
+
+ <template>
+ <div>
+ <text >{{content}}</text>
+ </div>
+ </template>
+ <script>
+ module.exports = {
+ data: function(){
+ return {
+ content: "Weex is an cross-platform development solution that builds high-performance, scalable native applications with a Web development experience. Vue is a lightweight and powerful progressive front-end framework. "
+ }
+ }
+ }
+ </script>
-## Custom Typeface
+## Events
+Support [common events](../events/common-events.html)
+
+## Other
+### The magic of text height
+The rules for computed height of text component is complicated, basically but not always, text in weex obey the following rules in order:
+1. The CSS style of `max-height`/`min-height` on your text
+2. The CSS style of `flex` on your text if there is a `flex-direction:column` on the parent component of you text.
+3. The CSS style of `height` on your text
+4. The CSS style of `align-items:stretch` on your text if there is a `flex-direction:row` on the parent you text.
+5. The content of your text and [text style](../styles/text-styles.html) on your text.
+6. Other related CSS style not mentioned here.
+
+### Custom Typeface
`support:v0.12.0`
-support `ttf` and `woff` font format to custom your text, call [addRule](../modules/custom_font.html) in dom module to build your own `font-family`, we suggest that you call `addRule` in `beforeCreate`.
+support loading custom font of `ttf` and `woff` format. Call [addRule](../modules/custom_font.html) in dom module to build your own `font-family`, we suggest that you call `addRule` in `beforeCreate`.
## Examples
-* [Basic usage for `<text>`](http://dotwe.org/vue/9ac60ccb4d1aacbdbd608dd7107ad105).
+* [Basic usage for `<text>`](http://dotwe.org/vue/7d2bf6e112ea26984fd5930663f092e0).
diff --git a/docs/docs/modules/animation.md b/docs/docs/modules/animation.md
index c0a69f5..727bf65 100644
--- a/docs/docs/modules/animation.md
+++ b/docs/docs/modules/animation.md
@@ -1,90 +1,92 @@
----
-title: animation
-type: references
-order: 9.01
-version: 2.1
----
-
# Animation
-
-## Overview
-
The `animation` module is used to perform animation on components.
JS-Animation can perform a series of simple transformations (position, size, rotation, background color, and opacity) on the component with Javascript.
For example, if you have a `image` component, you can move, rotate, grow, or shrink it by animation.
-> **Note:** Now,Weex only support use animation in Javascript. CSS Animation is different from this,we will soon support CSS Animation.
+:::tip
+Ref [transition](../styles/common-styles.html#property) or [transform](../styles/common-styles.html#transform) if you prefer CSS animation.
+:::
## Basic Usage
+One can invoke `animation.transition(ref, options, callback)` to start animation. Ref the following code snippets.
-### animation.transition(el, options, callback)
+## Example
+* [animation demo](http://dotwe.org/vue/2d1b61bef061448c1a5a13eac9624410)
```javascript
-animation.transition(ref1, {
- styles: {
- backgroundColor: '#FF0000',
- transform: 'translate(250px, 100px)',
- },
- duration: 800, //ms
- timingFunction: 'ease',
- needLayout:false,
- delay: 0 //ms
- }, function () {
- modal.toast({ message: 'animation finished.' })
- })
+animation.transition(test, {
+ styles: {
+ backgroundColor: '#FF0000',
+ transform: 'translate(250px, 100px)',
+ },
+ duration: 800, //ms
+ timingFunction: 'ease',
+ needLayout:false,
+ delay: 0 //ms
+ }, function () {
+ modal.toast({ message: 'animation finished.' })
+ })
```
-## Attributes
-
-### ``el``
-
-An element that will be animated.
-
-For example , specify the `el` attribute for the element you want to animated as `element`, so you can get this element by calling `this.refs.element`.
-
-### ``options``
-
-- `styles` (object): Specify the names and values of styles to which a transition effect should be applied. The allowed attributes are listed in the following table:
-
-| name | description | value type | default value |
-| :-------------- | :--------------------------------------- | :-------------------- | :-------------- |
-| width | The width applied to the component after the animation finished. | length | none |
-| height | The height applied to the component after the animation finished. | length | none |
-| backgroundColor | The background color applied to the component after the animation finished. | string | none |
-| opacity | The opacity applied to the component after the animation finished. | number between 0 to 1 | `1` |
-| transformOrigin | The povit of transition. The possible values for `x-aris` are `left`/`center`/`right`/length or percent, and possible values of `y-axis` are `top`/`center`/`bottom`/ length or percent | `x-axis y-axis` | `center center` |
-| **transform** | Transform function to be applied to the element. The properties in the following table are supported | object | none |
-
-``transform`` also have many parameters,please see the table below.
-
-| name | description | value type | default value |
-| :--------------------------------------- | :--------------------------------------- | :--------------- | :---------------- |
-| translate/translateX/translateY | Specifies the location of which the element will be translated to. | pixel or percent | none |
-| rotate/rotateX <span class="api-version">v0.14+</span> /rotateY <span class="api-version">v0.14+</span> | Specifies the angle of which the element will be rotated, the unit is degree. | number | none |
-| perspective <span class="api-version">v0.16+</span> | The distance between the z=0 plane and the user in order to give to the 3D-positioned element some perspective. Supported for Android 4.1 and above. | number | positive infinity |
-| scale/scaleX/scaleY | Stretch or shrink the element. | number | none |
-
-- `duration` (number): Specifies the number of milliseconds of animation execution, the default value is `0`, means that no animation will occur.
-- `delay` (number): Specifies the amount of milliseconds to wait between a change being requested to a property that is to be transitioned and the start of the transition effect. The default value is `0`.
-- `needLayout`(boolean)：Whether or not the layout animation occurs when animation is executed，default value is `false`
-- `timingFunction` (string): Used to describe how the intermediate values of the styles being affected by a transition effect are calculated, default value is `linear`, the allowed attributes are listed in the following table:
-
-| name | description |
-| :----------------------------- | :--------------------------------------- |
-| `linear` | Specifies a transition effect with the same speed from start to end |
-| `ease` | Specifies a transition effect with a slower and slower speed |
-| `ease-in` | Specifies a transition effect with a slow start |
-| `ease-out` | Specifies a transition effect with a slow end |
-| `ease-in-out` | Specifies a transition effect with a slow start and end |
-| `cubic-bezier(x1, y1, x2, y2)` | Define your own values in the cubic-bezier function. Possible values are parameter values from 0 to 1. More information about cubic-bezier please visit [cubic-bezier](http://cubic-bezier.com/) and [Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve). |
-
-### ``callback``
-
-Callback which is a function called after the completion of animation. In iOS platform, you can use function to get animation processing's information.
-
->**Note: after WeexSDK0.16.0, in iOS platform can get animation's message about completion, there are two types of parameters with `result`, is `Success`and `Fail`, Android can not support until now.**
-
-### Example
-- [animation demo](http://dotwe.org/vue/2d1b61bef061448c1a5a13eac9624410)
+# Reference
+## ``ref``
+The element that will be animated.
+
+For example, if the value of `ref` for an element is `test`, you can start an animation with `this.$refs.test`.
+
+## ``options``
+### styles
+`styles` specifies the names and values of styles to which a transition effect should be applied. The supported styles are listed below:
+ * width
+ * height
+ * backgroundColor
+ * opacity
+ * transformOrigin
+ * transform
+ * translate/translateX/translateY
+ * rotate/rotateX/rotateY
+ * perspective
+ * scale/scaleX/scaleY
+#### width
+The `width` applied to the component after the animation finished. Set `needLayout` to true if you want the change to be persistence. The default value is `computed width`.
+#### height
+The `height` applied to the component after the animation finished. Set `needLayout` to true if you want the change to be persistence. The default value is `computed height`.
+#### backgroundColor
+The `backgroundColor` applied to the component after the animation finished. The default value is `computed backgroundColor`.
+#### opacity
+The `opacity` applied to the component after the animation finished. The default value is `computed opacity`.
+#### transformOrigin
+The `transformOrigin` indicate the pivot of the element being animated. The possible values for `x-axis` are `left`/`center`/`right`/length or percent, and possible values of `y-axis` are `top`/`center`/`bottom`/ length or percent. The default value is `center center`.
+#### transform
+Transform object, which may include `rotate`, `translate`, `scale` and etc. The detail of transform is illustrated below.
+ * `translate/translateX/translateY`: Specify the location which the element will be translated to.The unit is number or percent and the default value is 0.
+ * `rotate/rotateX/rotateY`**v0.14+**: Specify the angle of which the element will be rotated. The unit is **degree** and the default value is 0.
+ * `perspective`**v0.16+**: The distance between the z=0 plane and the user. Supported for **Android 4.1** and above. The unit is number and the default value is positive infinity.
+ * `scale/scaleX/scaleY`: Stretch or shrink the element. The unit is number and the default value is 1.
+### duration
+`duration` *number* specifies the duration of animation execution, the default value is `0`, meaning that the component get the desired property immediately.
+### delay
+`delay` *number* specifies the waiting time before the animation starts. The default value is `0`.
+### needLayout
+`needLayout` *boolean* Specifies whether the change to layout(width/height/etc..) is persistence and takes affect after the animation. Default value is `false`
+### timingFunction
+`timingFunction` *string* describes how the intermediate values are calculated for the CSS properties being affected by the animation effect. default value is `linear`, the supported values are listed in the following:
+ * `linear`: Specify a transition effect with the same speed from start to end.
+ * `ease-in`: Specify a transition effect with a slow start and fast end.
+ * `ease-out`: Specify a transition effect with a fast start and slow end.
+ * `ease-in-out`: Specify a transition effect with a slow start, fast intermediate and slow end.
+ * `cubic-bezier(x1, y1, x2, y2)`: Define your own values in the cubic-bezier function. Possible values are parameter values from 0 to 1. More information about cubic-bezier please visit [cubic-bezier](http://cubic-bezier.com/) and [Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve)
+
+## ``callback``
+
+Callback is a function called after the completion of animation. In iOS platform, you can use function to get information of animation execution.
+
+::: tip
+after WeexSDK0.16.0, in iOS platform can get animation's message about completion, there are two types of parameters with `result`, is `Success`and `Fail`, Android can not support until now.
+:::
+
+::: tip
+Android doesn't support the result parameter.
+:::
diff --git a/docs/docs/modules/dom.md b/docs/docs/modules/dom.md
index 11f2bc8..d4f1a32 100644
--- a/docs/docs/modules/dom.md
+++ b/docs/docs/modules/dom.md
@@ -1,16 +1,67 @@
----
-title: dom
-type: references
-group: Build-in Modules
-order: 9.03
-version: 2.1
----
-
-# Custom Font <span class="api-version">v0.12.0+</span>
-## OverView
-Weex provide the ability of loading custom through **DOM.addRule**. Developers can load *iconfont* and *custom font* by specifying the **font-family**.
+# Dom
+
+## Overview
+
+The `dom` module is used to manipulate the components in weex pages.
+
+You can use these APIs to get a component's bounding rect in the page, or scroll a list to some specific component, or add a font-face rule to the page and so on.
+
+> **Note:** The `addRule` method is currently used only with font-face supportability.
## API
+
+### scrollToElement(ref, options)
+
+Scroll the scrollable component to the referenced component. This API should only be used in the children components of a scrollable component, such as in a `<scroller>` or `<list>` component.
+
+> **NOTE:** You can use `weex.requireModule('dom')` to requrie the dom module, and use `weex.requireModule('dom').scrollToElement` to call this API.
+
+#### Arguments
+
+* `ref`*(Node)*: the referenced component who is meant to scroll into the view.
+* `options`*(object)*:
+ * `offset`*(number)*: An space on top of the ref component, which is also scrolling down to the visual viewport. Default is `0`.
+ * `animated` *(bool)*: <sup class="wx-v">0.10+</sup> Indicates whether a scroll animation should be played. If set to false, the ref component will jump into the view without any transition animation. Default is true.
+
+#### Example
+
+[Scroll To Floor](http://dotwe.org/vue/56e0d256cbb26facd958dbd6424f42b2)
+
+### getComponentRect(ref, callback) <span class="api-version">v0.9.4+</span>
+
+`support: >=0.9.4`
+
+You can get the bounding rect of the referenced component using this API.
+
+An example callback result should be like:
+
+```javascript
+{
+ result: true,
+ size: {
+ bottom: 60,
+ height: 15,
+ left: 0,
+ right: 353,
+ top: 45,
+ width: 353
+ }
+}
+```
+
+If you want to get the bounding rect of outside viewport of the weex container, you can specify the `ref` as a literal string `'viewport'`, like `getComponentRect('viewport', callback)`.
+
+#### Example
+
+[get box's rect](http://dotwe.org/vue/d69ec16302e06300096c7285baef538a)
+
+
+### addRule(type, contentObject) <span class="api-version">v0.12.0+</span>
+
+`support: >=0.12.0`
+
+Weex provide the ability of loading custom through **DOM.addRule**. Developers can load *iconfont* and *custom font* by specifying the **font-family**.
+
Developers may use the following code snippet to load their font:
const domModule = weex.requireModule('dom')
@@ -30,12 +81,136 @@ The parameter of **Add Rule** is illustrated as following:
* **file**. Read from a local file, e.g. `url('file://storage/emulated/0/Android/data/com.alibaba.weex/cache/http:__at.alicdn.com_t_font_1469606063_76593.ttf')`
* **data**. Read from a base64 data source, e.g. `url('data:font/truetype;charset=utf-8;base64,AAEAAAALAIAAAwAwR1NVQrD+....')`, the above data field is only a part of the actual data.
-## Note
+#### Note
> **Note:** You can name `fontFamily` in `addRule` as you wish in your page, any string is OK. But this is not the real font-family name of the font file. The real name or system name for the font is stored in binrary data of ttf file. You must ensure that the real font-family name of font file is unique. Or your font may not be successfully registered to device and your text may display as a '?'.
> **Note:** Specially, if you are using http://www.iconfont.cn/ to build your iconfont. Make sure that you set a unique enough font-family name for your font in project settings.
> **Note:** Calling `addRule` in `beforeCreate` is recommended.
-## Example
+#### Example
Check the custom font [example](http://dotwe.org/vue/7e328ee2ac9b7205c9ee37f4e509263d).
+
+## DEMO
+
+[<IPhoneImg imgSrc="https://img.alicdn.com/tfs/TB1hVg_n8LoK1RjSZFuXXXn0XXa-262-433.png" />](http://dotwe.org/vue/d8459936b12ed070ccf6bf5b953aa344)
+
+<!-- [](http://dotwe.org/vue/d8459936b12ed070ccf6bf5b953aa344) -->
+
+<details>
+ <summary>Code</summary>
+
+```vue
+ <template>
+ <div class="root">
+ <list class="list">
+ <cell v-for="item in items" v-bind:key="item.title">
+ <div :ref="`widget${item.title}`" class="widget">
+ <text>widget{{item.title}}</text>
+ <text>iconfont{{item.title}}</text>
+ <text :style="{fontFamily:`iconfont${item.title}`, fontSize: '50px'}"></text>
+ </div>
+ </cell>
+ </list>
+ <div class="btn-holder">
+ <text class="btn" @click="getComponentRect">getComponentRect of 10</text>
+ <text class="btn" @click="scrollToElement">scroll to 10</text>
+ <text class="btn" @click="addRule">addRule</text>
+ </div>
+ <div class="message">
+ <text>{{message}}</text>
+ </div>
+ </div>
+ </template>
+
+ <script>
+const dom = weex.requireModule('dom');
+const modal = weex.requireModule('modal');
+
+export default {
+ data() {
+ return {
+ targetIndex: 10,
+ items: [],
+ trigger: '',
+ message: ''
+ };
+ },
+ created() {
+ const targetIndex = this.targetIndex;
+ const items = [];
+ for (let i = 0; i < 30; i++) {
+ items.push({
+ title: i,
+ desc: i === targetIndex ? '' : ''
+ });
+ }
+ this.items = items;
+ },
+ methods: {
+ getStyle(i) {
+ return {};
+ },
+ addRule() {
+ const targetIndex = this.targetIndex;
+ modal.toast({
+ message: `addRule to iconfont${targetIndex}`
+ });
+ this.scrollToElement();
+ dom.addRule('fontFace', {
+ fontFamily: `iconfont${targetIndex}`,
+ src: "url('http://at.alicdn.com/t/font_zn5b3jswpofuhaor.ttf')"
+ });
+ },
+ scrollToElement() {
+ const element = this.$refs[`widget${this.targetIndex}`][0];
+ dom.scrollToElement(element);
+ },
+ getComponentRect() {
+ const element = this.$refs[`widget${this.targetIndex}`][0];
+ dom.getComponentRect(element, data => {
+ this.message = JSON.stringify(data);
+ });
+ }
+ }
+};
+</script>
+
+
+ <style scoped>
+.root {
+ width: 700px;
+ margin-left: 25px;
+}
+.list {
+ height: 600px;
+ width: 700px;
+}
+.widget {
+ height: 150px;
+ width: 700px;
+ border-width: 1px;
+}
+.btn-holder {
+ flex-direction: row;
+ margin-top: 10px;
+}
+.btn {
+ padding-left: 10px;
+ padding-right: 10px;
+ padding-top: 10px;
+ padding-bottom: 10px;
+ background-color: #00b4ff;
+ margin-right: 10px;
+ color: #fff;
+}
+.message {
+ margin-top: 10px;
+ border-width: 1px;
+ height: 300px;
+ width: 700px;
+}
+</style>
+```
+
+</details>
diff --git a/docs/zh/docs/components/image.md b/docs/zh/docs/components/image.md
index 7b688ab..2792d1a 100644
--- a/docs/zh/docs/components/image.md
+++ b/docs/zh/docs/components/image.md
@@ -1,90 +1,87 @@
----
-title: <image>
-type: references
-group: Build-in Components
-order: 8.04
-version: 2.1
----
+# Image
-`<image>` is used to display a single image in your interface.
+`<image>` 用于在界面中显示单个图片。
-> **Note:** `<img>` element which is usually used in HTML is not supported in Weex, you should use `<image>` instead.
+> **注意:** 在代码中请使用 `<image>` 标签, `<img>` 的存在只是因为兼容性原因，在将来的版本中可能删除。
-> **Note:** Weex doesn't have built-in image downloader, as download, cache, decompression features are complicated and some open source tools like [SDWebImage](https://github.com/rs/SDWebImage) handles it well, so please add native image adapter/handler before using `<image>`.
+> **注意：** Weex 没有内置的图片库，因为一些开源项目如 [SDWebImage](https://github.com/rs/SDWebImage) 和[Picasso](https://github.com/square/picasso)已经能很好的解决这个问题， 所以在使用 `<image>` 之前，请在 native 侧先接入相应的 adapter 或者 handler。
>
-> See also: [Android adapter](../android-apis.html#Adapter) and [iOS handler](../ios-apis.html#Handler-like-Android-Adapter).
+> 参见: [Android adapter](../api/android-apis.html) 和 [iOS handler](../api/ios-apis.html)。
-## Basic Usage
+## 基本用法
-> **Note:** the style attributes of `width` and `height` must be specified, otherwise it won't work.
+> **注意：** `width`, `height` 和 `src`必须被提供，否则图片无法渲染。
```html
<image style="width:500px;height:500px" src="https://vuejs.org/images/logo.png"></image>
```
-See the [example](http://dotwe.org/vue/00f4b68b3a86360df1f38728fd0b4a1f).
+参见[示例](http://dotwe.org/vue/00f4b68b3a86360df1f38728fd0b4a1f)。
- ## Attributes
+## 子组件
+`<image>`不支持子组件。
-| Attribute | Type | Value | Default Value |
-| ------------- | ------ | -------------------------- | ------------- |
-| `placeholder` | String | {URL / Base64} | - |
-| `resize` | String | cover / contain / stretch | stretch |
-| `src` | String | {URL / Base64 } | - |
+## 样式
+支持**[通用样式](../styles/common-styles.html)**。
- > **Note:** you can specify a relative URL for `src` and `placeholder`, relative URL will be rewritten to the to the actual resource URL (local or remote). See also: [Path](../../guide/advanced/path.html).
+## 属性
- ### `placeholder`
+| 属性名 | 类型 | 值 | 默认值 |
+| ------------- | ------ | -------------------------- | ------- |
+| `placeholder` | String | {URL / Base64} | - |
+| `resize` | String | cover / contain / stretch | stretch |
+| `src` | String | {URL / Base64 } | - |
-A URL value for placeholder image. It will be displayed when the image view is empty and will be replaced as soon as the 'src' image gets loaded.[(Example)](http://dotwe.org/vue/712ef102fc5e073b6c7e3b701545681c)
+> **注意：**您可以指定一个相对 bundle URL 的相对路径，相对路径将被重写为绝对资源路径(本地或远程)。参见: [资源路径](../../guide/advanced/asset-path.html)。
- ### `resize`
+### `placeholder`
-
+占位图的 URL，在图片下载过程中将展示占位图，图片下载完成后将显示`src`中指定的图片。 ([示例](http://dotwe.org/vue/712ef102fc5e073b6c7e3b701545681c))
-- `contain`: Scales the image as large as possible without cropping or stretching it. Remaining area within bounds is transparent ([Example](http://dotwe.org/vue/89be94dcd1fec73b77246ec46c678914))
+### `resize`
+- `contain`：缩放图片以完全装入`<image>`区域，可能背景区部分空白。 ([示例](http://dotwe.org/vue/89be94dcd1fec73b77246ec46c678914))
+- `cover`：缩放图片以完全覆盖`<image>`区域，可能图片部分看不见。 ([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
+- `stretch`：`默认值`. 按照`<image>`区域的宽高比例缩放图片。([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
-- `cover`: Scales the image as large as possible without stretching it. If the proportions of the image differ from the element, it is cropped either vertically or horizontally so that no empty space remains. ([Example](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
-
-- `stretch`: `Default value`. Scales the content to fit the size of the element itself by changing the aspect ratio of the image if necessary. ([Example](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
-
-See also: [`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size).
+resize属性和[`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size)的理念很相似。
### `src`
-The URL of the image to display. This attribute is mandatory for the `<image>` component.
+要显示图片的 URL，该属性是 `<image>` 组件的强制属性。
-#### Supported Image Formats
+#### 支持的图片格式
-Weex doesn't give a list of image formats that must be supported, it mainly relies on the image adapter/handler you are using. For example, if you are using [SDWebImage](https://github.com/rs/SDWebImage#supported-image-formats) as the image adapter on iOS, you can use image formats like JPEG, PNG, GIF, WebP, etc.
+Weex没有提供必须支持的图片格式列表，主要依赖于你正在使用的图片 adapter 或者 handler。例如，如果你使用 [SDWebImage](https://github.com/rs/SDWebImage#supported-image-formats) 作为iOS上的图片 handler，你可以使用像 JPEG、PNG、GIF、WebP 等图片格式。
-## Component Methods
+> **Note:** Android 默认的Image Adapter不支持 gif。
+
+## Component 方法
### `save` <span class="api-version">v0.16.0+</span>
-Save `<image>` content to the local device or photo album, this operation may require device permission.
+保存图片内容到本地文件或相册，此操作可能需要设备相关权限。
-**Parameters**:
+**参数**:
-* `callback`: {Function} A function which is called after the image has been saved to the local device or photo album. Callback parameters:
- * `result`: {Object} Callback result whose properties are:
- * `success`: {Boolean} A flag indicating whether the image has been saved completed.
- * `errorDesc`: {String} A string containing the description of the error if image is not written successfully.
+* `callback`：{Function} 在图片被写入到本地文件或相册后的回调，回调参数：
+ * `result`：{Object} 回调结果对象，属性列表：
+ * `success`：{Boolean} 标记图片是否已写入完成。
+ * `errorDesc`：{String} 如果图像没有成功写入，该字符串包含了详细的错误描述。
-**Return value**: null
+**返回值**: null
-> **Note**: You must add `NSPhotoLibraryAddUsageDescription` and `NSPhotoLibraryAddUsageDescription` (iOS 11) to enable the access permission of the iOS photo album. See also: [Cocoa Keys](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html).
+> **注意**: 你必须加入`NSPhotoLibraryAddUsageDescription` 和 `NSPhotoLibraryAddUsageDescription` (iOS 11) 以获得访问 iOS 系统相册权限. 参见: [Cocoa Keys](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html)
-#### Use `save` Method
+#### 使用 `save` 方法
-Add `ref` attribute (Vue.js *[Child Component Refs](https://vuejs.org/v2/guide/components.html#Child-Component-Refs)*) on `<image>`:
+在 `<image>`标签上增加 `ref` 属性 (Vue.js *[Child Component Refs](https://vuejs.org/v2/guide/components.html#Child-Component-Refs)*) ：
```html
<image ref="poster" src="path/to/image.png"></image>
```
-Get the component reference and use the `save` method:
+获取组件引用并使用 `save` 方法:
```js
const $image = this.$refs.poster
@@ -98,32 +95,34 @@ $image.save(result => {
})
```
-Complete example goes [here](http://dotwe.org/vue/fadcd44a7031943ff0feaaf1895df414).
+参见 [完整例子](http://dotwe.org/vue/fadcd44a7031943ff0feaaf1895df414).
-## Events
+## 事件
-Support **[common events](../../wiki/common-events.html)**.
+支持 **[通用事件](../events/common-events.html)**.
### `load`
-`load` event handler will be called when the image is loaded.
+当加载完成 `src` 指定的图片时，`load`事件将被触发。
+
+**事件对象**:
-**Event object**:
+- `success`: {Boolean} 标记图片是否成功加载。
-- `success`: {Boolean} It shows that whether the image is loaded successfully.
-- `size`: {Object} The loaded image size whose properties are:
- - `naturalWidth`: {Number} The intrinsic width of image displayed on device, it will be zero if the specified image cannot be loaded correctly.
- - `naturalHeight`: {Number} the intrinsic height of image displayed on device, it will be zero if the specified image cannot be loaded correctly.
-#### Handle `load` Event
+- `size`: {Object} 加载的图片大小对象，属性列表：
+ - `naturalWidth`: {Number} 图片宽度，如果图片加载失败则为0。
+ - `naturalHeight`: {Number} 图片高度，如果图片加载失败则为0。
-Bind `load` event on `<image>`:
+#### 处理 `load` 事件
+
+在 `<image>` 标签上绑定 `load` 事件：
```html
<image @load="onImageLoad" src="path/to/image.png"></image>
```
-Add event handler:
+增加事件处理函数：
```js
export default {
@@ -137,20 +136,15 @@ export default {
}
```
-Complete example goes [here](http://dotwe.org/vue/94de9307517240dec066d2ea57fe54a0).
-
-## Styles
-
-Support **[common styles](../../wiki/common-styles.html)**.
+参见[完整示例](http://dotwe.org/vue/94de9307517240dec066d2ea57fe54a0)。
-## Usage Notes
+## 使用说明
-- Add image adapter/handler before using `<image>`
-- The `width` and `height` in the styles of `<image>` must be specified.
-- `<image>` can not have any nested child component.
+- 在使用 `<image>` 之前，请在 native 侧先接入相应的 adapter 或者 handler。
+- `<image>` 必须指定样式中的宽度和高度。
+- `<image>` 不支持内嵌子组件。
-## Examples
+## 示例
-- [Base64 example](http://dotwe.org/vue/ba477790c85ea12bbf7ad3a5f0885b5c)
-- [Multi-layer images example](http://dotwe.org/vue/c44359c0f200abc1f66504b88587e4f6)
-- [Lazy load image example](http://dotwe.org/vue/b0b146e4e6fa4890f800e18cb950f803)
+* [Base64 示例](http://dotwe.org/vue/ba477790c85ea12bbf7ad3a5f0885b5c)
+* [Lazy load image 示例](http://dotwe.org/vue/b0b146e4e6fa4890f800e18cb950f803)
\ No newline at end of file
diff --git a/docs/zh/docs/components/text.md b/docs/zh/docs/components/text.md
index 3fb6109..9290661 100644
--- a/docs/zh/docs/components/text.md
+++ b/docs/zh/docs/components/text.md
@@ -1,103 +1,53 @@
-# <text>
+# Text
-`<text>` 用来将文本按照指定的样式渲染出来。**`<text>` 只能包含文本，不支持其他子组件**，和 Vue 一样，你可以使用“Mustache”语法 (双大括号) `{{}}` 进行文本插值，当数据改变时，插值处的内容会自动更新。
+`<text>` 是 Weex 内置的组件，用来将文本按照指定的样式渲染出来.
+> **注意：** `<text>` 里直接写文本头尾空白会被过滤，如果需要保留头尾空白，暂时只能通过数据绑定写头尾空格。
-::: warning 注意
-- 所有文本内容都必须放在 `<text>` 中，不能放在 `<div>` 等其他组件中。
-- `<text>` 里直接写文本头尾空白会被过滤，如果需要保留头尾空白，暂时只能通过数据绑定写头尾空格。
-:::
-
-```html
-<template>
- <div class="wrapper">
- <text class="text" >Weex 是一套简单易用的跨平台开发方案，能以 Web 的开发体验构建高性能、可扩展的原生应用。</text>
- <text class="text ellipsis">{{enText}}</text>
- </div>
-</template>
-
-<script>
- export default {
- data () {
- return {
- enText: 'Weex is an cross-platform development solution that builds high-performance, scalable native applications with a Web development experience. '
- }
- }
- }
-</script>
-```
-
-[示例](http://dotwe.org/vue/808aa57e344eb7a9b7012a8540efae9f)
-
-## 子组件
-
-`<text>` 不支持子组件。
-
-## 属性
-
-| 参数 | 说明 | 类型 | 默认值 |
-| ---------- | ------------- | ----- | ----- |
-| `value` | 文本内容，可直接将文本内容置于在 `<text>` 标签中 | string | - |
+> **注意：** `<text>`不支持子组件。
## 样式
+* 支持 **[通用样式](../styles/common-styles.html)。**
+* 支持 **[文本样式](../styles/text-styles.html)。**
-除通用的样式外，`<text>` 还支持文本样式，其表现与 CSS 文本样式相同相同：
-
-- 支持 `color` 样式。
-- 支持 `font-size` 样式，默认值为 32。
-- 支持 `font-style` 样式。
-- 支持 `font-weight` 样式。
-- 支持 `text-align` 样式。
-- 支持 `text-decoration` 样式。
-- 支持 `text-overflow` 样式。
-- 支持 `line-height` 样式。
-
-此外，`<text>` 还支持限制行数的样式 `lines`:
-
-`lines {number}`: 指定文本行数，默认值是 0，代表不限制行数。
-
-### 自定义字体
-
-在 Weex 0.12 以上版本支持 `ttf` 和 `woff` 字体格式的自定义字体, 可以通过调用 `dom.addRule()` 方法, 构建自定义的 `font-family` 使用, `dom.addRule()` 建议在 `beforeCreate` 或者更早时调用。
-
-```html
-<template>
- <div style='flex-direction:row;margin-top:50px'>
- <text style='font-family:iconfont;font-size:80;color:blue'></text>
- <text style='font-family:iconfont;font-size:80;color:green'></text>
- </div>
-</template>
-
-<script>
- const domModule = weex.requireModule('dom');
-
- export default {
- beforeCreate: function() {
- //目前支持ttf、woff文件，不支持svg、eot类型,moreItem at http://www.iconfont.cn/
- domModule.addRule('fontFace', {
- 'fontFamily': "iconfont",
- 'src': "url('http://at.alicdn.com/t/font_522989_pchx71aqjd.ttf')"
- });
- }
- }
-</script>
-```
-
-## Demo
-
-
-- [自定义字体](http://dotwe.org/vue/6062cf0121e0dae5d05c7033ee93a5dc)
-
- <IPhoneImg imgSrc="https://img.alicdn.com/tfs/TB1aQM4n3DqK1RjSZSyXXaxEVXa-750-1334.png" />
+## 属性
+除了动态文本，text组件不支持其他属性
+### dynamic text
+下列代码片段可以实现文字内容和JS变量的绑定。
+
+ <template>
+ <div>
+ <text >{{content}}</text>
+ </div>
+ </template>
+ <script>
+ module.exports = {
+ data: function(){
+ return {
+ content: "Weex is an cross-platform development solution that builds high-performance, scalable native applications with a Web development experience. Vue is a lightweight and powerful progressive front-end framework. "
+ }
+ }
+ }
+ </script>
-- [热门动画列表](http://dotwe.org/vue/892bd1c977b61762baca8e02a65b6d97)，常见的图文混排场景，限制行数，设置文本多种样式等效果。
+## 事件
+支持 **[通用事件](../events/common-events.html)**。
- <IPhoneImg imgSrc="https://img.alicdn.com/tfs/TB1.Bg6nZbpK1RjSZFyXXX_qFXa-750-1334.gif" />
+## 其他
+### 文字高度
+文字高度的计算规则比较复杂，但大致上遵循以下优先级进行计算，排在前面的优先级最高。
+1. 文字节点的`max-height`/`min-height`样式。
+2. 文字节点的`flex`属性且文字的父节点上有`flex-direction:column`样式。
+3. 文字节点的`height`样式。
+4. 文字节点的`align-items:stretch`如果文字父节点有 `flex-direction:row`样式。
+5. 文字内容和文字本身的[样式](../styles/text-styles.html)。
+6. 其他相关CSS属性。
-- [Ocean](http://dotwe.org/vue/bf65efdb828c1c4e5613a0e7a6f7ee57)，场景的文章详情页，使用 `<text>` 文本样式渲染文章标题和正文。
- <IPhoneImg imgSrc="https://img.alicdn.com/tfs/TB1YqM9n9zqK1RjSZFHXXb3CpXa-750-1334.gif" />
+### 自定义字体
+`支持版本:v0.12.0`
-- [聊天窗口](http://dotwe.org/vue/695ee4cba19d4d9c4dc845e113710dbc)，结合 `flex` 实现复杂的排版效果。
+支持ttf和woff字体格式的自定义字体, 可以通过调用 `dom` module 里面的 [addRule](../modules/dom.html)方法, 构建自定义的`font-family`使用, addRule 建议在 `beforeCreate` 或者更早时调用
- <IPhoneImg imgSrc="https://img.alicdn.com/tfs/TB11_g_n7voK1RjSZPfXXXPKFXa-264-439.gif" />
\ No newline at end of file
+## 示例
+* [`<text>`的基本用法](http://dotwe.org/vue/7d2bf6e112ea26984fd5930663f092e0)
\ No newline at end of file
diff --git a/docs/zh/docs/modules/animation.md b/docs/zh/docs/modules/animation.md
index 00a0630..ea21c53 100644
--- a/docs/zh/docs/modules/animation.md
+++ b/docs/zh/docs/modules/animation.md
@@ -1,119 +1,100 @@
-# animation
-
-`animation` 模块用来在组件上执行动画。可以对组件执行一系列简单的变换 (位置、大小、旋转角度、背景颜色和不透明度)。
-
-```vue
-<template>
- <div class="wrapper">
- <div ref="test" class="box"></div>
- </div>
-</template>
-<script>
- const animation = weex.requireModule('animation')
- export default {
- mounted() {
- animation.transition(this.$refs.test, {
- styles: {
- height: '100px'
- },
- duration: 800, //ms
- timingFunction: 'ease',
- delay: 100 //ms
- })
- }
- }
-</script>
-<style scoped>
- .box {
- width: 250px;
- height: 250px;
- background-color: #DDD;
- }
-</style>
-```
+# 动画
+``animation`` 模块可以用来在组件上执行动画。
+
+JS-Animation可以对组件执行一系列简单的变换 (位置、大小、旋转角度、背景颜色和不透明度)。
+
+举个例子，如果有一个 `<image>` 组件，通过动画你可以对其进行移动、旋转、拉伸或收缩等动作。
-::: warning 注意
-* 涉及动画的需求，建议使用 animation 模块方法。相比于 css 动画 animation 模块方法有更好的兼容性。
+:::tip
+如果需要使用CSS动画，参考 [transition](../styles/common-styles.html#property)或[transform](../styles/common-styles.html#transform) 。
:::
-## API
-
-### animation.transition(element, options, callback)
-
-**element**：`[必选]`将要执行动画的元素。
-
-```vue
-<template>
- <div class="wrapper">
- <div ref="test"></div>
- </div>
-</template>
-<script>
- export default {
- mounted() {
- // 例如指定动画的元素 element 属性为 test , 可以通过调用 this.$refs.test 来获取元素的引用。
- console.log(this.$refs.test);
- }
- }
-</script>
+
+## 基本用法
+
+```javascript
+animation.transition(ref1, {
+ styles: {
+ backgroundColor: '#FF0000',
+ transform: 'translate(250px, 100px)',
+ },
+ duration: 800, //ms
+ timingFunction: 'ease',
+ needLayout:false,
+ delay: 0 //ms
+ }, function () {
+ modal.toast({ message: 'animation finished.' })
+ })
```
-**options**：`[必选]`指定动画参数
-- styles(object):设置不同样式过渡效果的键值对，下表列出了所有合法的参数：
- | 参数 | 描述 | 值类型 | 默认值 |
- | ---------- | ------------- | ----- | ----- |
- | width|动画执行后应用到组件上的宽度值|number|无|
- | height|动画执行后应用到组件上的高度值|number|无|
- | backgroundColor|动画执行后应用到组件上的背景颜色|string|无|
- | opacity|动画执行后应用到组件上的不透明度值|number|1|
- | transformOrigin|定义变化过程的中心点. 参数 x-aris 可能的值为 left、center、right、长度值或百分比值, 参数 y-axis 可能的值为 top、center、bottom、长度值或百分比值|x-axis y-axis|center center|
- | transform|定义应用在元素上的变换类型，支持的属性请见下方附录部分|object|无|
-- duration(number)：指定动画的持续时间 (单位是毫秒)，默认值是 0，表示没有动画效果。
-- delay (number)：指定请求动画操作到执行动画之间的时间间隔 (单位是毫秒)，默认值是 0，表示没有延迟，在请求后立即执行动画。如下图，控制不同的间隔可实现特定效果。
-<div style="text-align: center"><img src="https://img.alicdn.com/tfs/TB15iA.nVzqK1RjSZSgXXcpAVXa-539-428.gif" width="300"></div>
-- needLayout (boolean)：节点动画执行时是否产生布局动画即LayoutAnimation，默认值是false。
- <div style="dispaly:flex;">
- <img src="https://img.alicdn.com/tfs/TB1x74XoirpK1RjSZFhXXXSdXXa-300-320.gif" width="300"/>
- <img src="https://img.alicdn.com/tfs/TB175RXomzqK1RjSZFHXXb3CpXa-300-320.gif" width="300"/>
- </div>
- 上图为会影响布局的元素 `height` 变化动画：左侧为浏览器动画，右侧为客户端动画。
-
- 在浏览器上执行动画当布局变化时，会自动将视图运动到它们新的位置上。但客户端 layout 都是独立的，
- 布局动画变化时，可能不会影响其他元素。当您的动画不符合您的预期时，可设置此参数，保障三端动画一致。
-
- 请用客户端扫描示例二维码[体验动画差异](http://dotwe.org/vue/45e8b954d93216510782b3b6c0889298)
-- timingFunction (string)：描述动画执行的速度曲线，用于使动画变化更为平滑。默认值是 linear，表示动画从开始到结束都拥有同样的速度。下表列出了所有合法的属性：
- | 参数 | 描述 |
- | ---------- | ------------- |
- |linear|动画从头到尾的速度是相同的|
- |ease|动画速度逐渐变慢|
- |ease-in|动画速度由慢到快|
- |ease-out|动画速度由快到慢|
- |ease-in-out|动画先加速到达中间点后减速到达终点|
- |cubic-bezier(x1, y1, x2, y2)|在三次贝塞尔函数中定义变化过程，函数的参数值必须处于 0 到 1 之间。更多关于三次贝塞尔的信息请参阅 cubic-bezier 和 Bézier curve.|
-
-**callback**：`[可选]`是动画执行完毕之后的回调函数。
-
-## Demo
-[体验示例](http://dotwe.org/vue/a0f4ed064a6b46a2b8f63ab3843d7aee)
-
-上述示例点击灰色方块后，便可看到操作动画。
-
-[循环动画](http://dotwe.org/vue/97e01e1b7f8992de287b0a690b54511c)
-
-目前 WEEX 没有提供可循环的属性，循环动画可像上述 Demo 在 callback 回调中执行下一次动画形成循环。
-
-### 附录
-WEEX transform 支持的对应属性，可以参见下表：
-
-```js
-// 注:如果想同时执行多个动画只需要用空格隔开，比如
-transform: 'translate(250px, 100px) scale(1.5)'
+## 示例
+[animation demo](http://dotwe.org/vue/a6c03edd4c5bbd6caea29cac688269a0)
+
+# 文档
+## `ref `：
+
+将要执行动画的元素。
+
+例如指定动画的元素 ``ref`` 属性为 ``test`` , 可以通过调用 `this.$refs.test` 来获取元素的引用。
+
+## `options`：
+### styles
+`styles`(object):设置不同样式过渡效果的键值对，下表列出了所有合法的参数：
+ * width
+ * height
+ * backgroundColor
+ * opacity
+ * transformOrigin
+ * transform
+ * translate/translateX/translateY
+ * rotate/rotateX/rotateY
+ * perspective
+ * scale/scaleX/scaleY
+#### width
+`width`表示动画执行后应用到组件上的宽度值。如果你需要影响布局，设置`needLayout`为`true`。默认值为`computed width`。
+#### height
+`height`表示动画执行后应用到组件上的高度值。如果你需要影响布局，设置设置为 `needLayout`为`true`。默认值为`computed width`。
+#### backgroundColor
+`backgroundColor`动画执行后应用到组件上的背景颜色，默认值为computed backgroundColor。
+#### opacity
+`opacity`表示动画执行后应用到组件上的不透明度值，默认值为computed opacity。
+#### transformOrigin
+`transformOrigin`定义变化过程的中心点，如`transformOrigin: x-axis y-axis` 参数 `x-axis` 可能的值为 `left`、`center`、`right`、长度值或百分比值, 参数 `y-axis` 可能的值为 `top`、`center`、`bottom`、长度值或百分比。默认值为`center center`。
+#### transform
+`transform`变换类型，可能包含rotate`, `translate`, `scale`及其他属性。默认值为空。
+ * `translate`/`translateX`/`translateY`指定元素要移动到的位置。单位是长度或百分比，默认值是0.
+ * `rotate`/`rotateX`/`rotateY`**v0.16+** 指定元素将被旋转的角度。单位是度 *角度度*，默认值是0
+ * `scale`/`scaleX`/`scaleY`按比例放大或缩小元素。单位是数字，默认值是1
+ * `perspective`**v0.16+** 观察者距离z=0平面的距离，在**Android 4.1**及以上有效。单位值数字，默认值为正无穷。
+:::tip
+如果想同时执行多个动画只需要用空格隔开，比如
+```
+ transform: 'translate(250px, 100px) scale(1.5)'
```
-| 参数 | 描述 | 值类型 | 默认值 |
-| ---------- | ------------- | ----- | ----- |
-|translate/translateX/translateY|指定元素要移动到的位置|像素值或百分比 |无|
-|rotate|指定元素将被旋转的角度，单位是度|number|无|
-|scale/scaleX/scaleY|按比例放大或缩小元素|number|无|
-|rotateX/rotateY 需要 WEEX v0.14+ |指定元素将被旋转的角度，单位是度|number|无|
-|perspective 需要 WEEX v0.16+ |观察者距离z=0平面的距离，在Android 4.1及以上有效|number|无|
\ No newline at end of file
+:::
+
+### duration
+`duration `(number)：指定动画的持续时间 (单位是毫秒)，默认值是 `0`，表示瞬间达到动画结束状态。
+### delay
+`delay ` (number)：指定请求动画操作到执行动画之间的时间间隔 (单位是毫秒)，默认值是 `0`，表示没有延迟，在请求后立即执行动画。
+### needLayout
+`needLayout` (boolean)：动画执行是否影响布局，默认值是false。
+### timingFunction
+`timingFunction ` (string)：描述动画执行的速度曲线，用于描述动画已消耗时间和动画完成进度间的映射关系。默认值是 `linear`，表示动画从开始到结束都拥有同样的速度。下表列出了所有合法的属性：
+ * `linear`:动画从头到尾的速度是相同的
+ * `ease-in`:动画速度由慢到快
+ * `ease-out`:动画速度由快到慢
+ * `ease-in-out`:动画先加速到达中间点后减速到达终点
+ * `cubic-bezier(x1, y1, x2, y2)`:在三次贝塞尔函数中定义变化过程，函数的参数值必须处于 0 到 1 之间。更多关于三次贝塞尔的信息请参阅 [cubic-bezier](http://cubic-bezier.com/) 和 [Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve)。
+
+## `callback `
+`callback`是动画执行完毕之后的回调函数。在iOS平台上，你可以获取动画执行是否成功的信息。
+
+:::tip
+在0.16.0+版本后，iOS上可以获取 animation 是否执行成功的信息，callback中的`result`参数会有两种，分别是是`Success`与`Fail`。**
+:::
+
+:::tip
+Android 的callback 函数不支持result参数**
+:::
+
diff --git a/docs/zh/docs/modules/dom.md b/docs/zh/docs/modules/dom.md
index 4ee8ec8..d19f5fb 100644
--- a/docs/zh/docs/modules/dom.md
+++ b/docs/zh/docs/modules/dom.md
@@ -87,26 +87,36 @@ dom.scrollToElement(element, { offset: 0 });
### addRule(type, contentObject)
`支持版本: >=0.12.0`
-addRule 是可以为 dom 添加一条规则，目前支持自定义字体 fontFace 规则，构建自定义的 font-family，可以在 text 使用
+Weex 提供 **DOM.addRule** 以加载自定义字体。开发者可以通过指定 **font-family**加载 *iconfont* 和 *custom font*。
-- fontFace
+开发者可以使用下面的代码加载自定义字体：
- ```javascript
- const domModule = weex.requireModule('dom');
- domModule.addRule('fontFace', {
- fontFamily: 'iconfont2',
- src: "url('http://at.alicdn.com/t/font_1469606063_76593.ttf')"
- });
- ```
+ const domModule = weex.requireModule('dom')
+ domModule.addRule('fontFace', {
+ 'fontFamily': "iconfont2",
+ 'src': "url('http://at.alicdn.com/t/font_1469606063_76593.ttf')"
+ });
- ::: tip
+参数含义如下:
- - addRule 目前仅支持添加 ‘font-face’
- - 字体只支持 ttf 和 woff
+* **fontFace** 协议名称，不可修改。
+* **fontFamily** font-family的名称。
+* **src** 字体地址，url('') 是保留字段，其参数如下:
+ * **http**. 从HTTP请求加载, e.g. `url('http://at.alicdn.com/t/font_1469606063_76593.ttf')`
+ * **https**. 从HTTPS请求加载, e.g. `url('https://at.alicdn.com/t/font_1469606063_76593.ttf')`
+ * **local**, *Android ONLY*. 从assets目录读取, e.g. `url('local://foo.ttf')`, **foo.ttf** 是文件名在你的assets目录中.
+ * **file**. 从本地文件读取, e.g. `url('file://storage/emulated/0/Android/data/com.alibaba.weex/cache/http:__at.alicdn.com_t_font_1469606063_76593.ttf')`
+ * **data**. 从base64读取, e.g. `url('data:font/truetype;charset=utf-8;base64,AAEAAAALAIAAAwAwR1NVQrD+....')`, 上述data字段不全。
- :::
+#### Note
+> **Note:** `addRule` 方法里的 `fontFamily` 可以随意取。这个名字不是字体真正的名字。字体真正的名字（font-family），也就是注册到系统中的名字是保存在字体二进制文件中的。你需要确保你使用的字体的真正名字（font-family）足够特殊，否则在向系统注册时可能发生冲突，导致注册失败，你的字符被显示为‘?’。
+
+> **Note:** 如果你使用 http://www.iconfont.cn/ 来构建你的 iconfont。确保在项目设置中，设置一个特殊的 font-family 名字。默认是 “iconfont”，但极大可能发生冲突。
+
+> **Note:** 调用`addRule` 在 `beforeCreate` 中是被推荐的。
-[add rule fontface](http://dotwe.org/vue/95b2c6716f37066d5f44c5c75c979394)
+#### Example
+[示例](http://dotwe.org/vue/7e328ee2ac9b7205c9ee37f4e509263d)。
## DEMO