Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147041159
--- Diff: source/references/components/image.md ---
@@ -6,122 +6,146 @@ order: 8.02
version: 2.1
---
-# <image>
+`<image>` is used to display a single image in your interface.
-### Summary
+> **Note:** `<img>` element which is usually used in HTML is not
supported in Weex, you should use `<image>` instead.
-`image` tag is used to render a specified picture, and it shouldn't
contain any child component. `<img>` is not supported currently.
+> **Note:** Weex doesn't have built-in image downloader, as relevant
download, cache, decompression mechanisms are very complicated and some open
sourced tools such as [SDWebImage](https://github.com/rs/SDWebImage) have
handled well, 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).
-**Notes:** the styles of `width` and `height` should be specified,
otherwise it won't work.
+## Basic Usage
+> **Note:** the styles of `width` and `height` must be specified,
otherwise it won't work.
-### Child Components
+```html
+<image style="width:500px;height:500px"
src="https://vuejs.org/images/logo.png";></image>
+```
+
+See the [example](http://dotwe.org/vue/00f4b68b3a86360df1f38728fd0b4a1f).
+
+ ## Attributes
+
+| Attribute | Type | Value | Default Value |
+| ------------- | ------ | -------------------------- | ------------- |
+| `placeholder` | String | {URL / Base64} | - |
+| `resize` | String | conver / contain / stretch | stretch |
+| `src` | String | {URL / Base64 } | - |
+
+ > **Note:** you can specify a URL which is relative to bundle URL for
`src` and `placeholder`, rel ative URL will be rewritten to the real
resource URL (local or remote). See also:
[Path](../../guide/advanced/path.html).
+
+ ### `placeholder`
+
+ A URL value for image placeholder. It will be displayed when the image
view is empty and will be removed when the image represented by `src` is
loaded. [(Example)](http://dotwe.org/vue/712ef102fc5e073b6c7e3b701545681c)
+
+ ### `resize`
+
+
-This component supports no child components.
+- `contain`: Scales the image as large as possible without cropping or
stretching the image. Any remaining area of bounds is transparent
([Example](http://dotwe.org/vue/89be94dcd1fec73b77246ec46c678914))
+- `cover`: Scales the image as large as possible without stretching the
image. 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 itself
by changing the aspect ratio of the image content if necessary.
([Example](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
-### Attributes
+ See also:
[`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size).
-- `src`: <string> image source url
-- `resize`: <span class="api-version">v0.5+</span> <string> the
'ScaleType' of the component. The default value is ``stretch``, if this
attribute is not specified. Possible values are ``cover``, ``contain``, each of
which has the same meaning with w3c standard.
-- `placeholder`: <span class="api-version">v0.9+</span> <string>
image to display while the network image src is loading.
+### `src`
-### Styles
+The URL of the image to display. This attribute is mandatory for the
`<image>` component.
-- `width`: <length> the width of the component. This style should be
specified.
-- `height`: <length> the height of the component. This style should
be specifed.
+#### Supported Image Formats
-**common styles**: check out the [common styles](../common-style.html)
+Weex doesn't give a list of image formats that must be supported, it
mainly rely 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 and
so on.
-- support flexbox related styles
-- support box model related styles
-- support ``position`` related styles
-- support ``opacity``, ``background-color`` etc.
+## Component Methods
-### Events
+### `save` <span class="api-version">v0.16.0+</span>
-**common events**: check out the [common events](../common-event.html)
+Save `<image>` content to local device or photo album, this operation may
require device permission.
-- support `click` event. Check out [common events](../common-event.html)
-- support `appear` / `disappear` event. Check out [common
events](../common-event.html)
-- `load`<sup class="api-version">v0.8+</sup> event. The `load` event fires
on an image has been loaded. Only Android and iOS are supported currently.
[example](http://dotwe.org/vue/e291159ac60b35dcd4994638a78d54ad)
- - event object
- - `success` : `true` if the image was loaded successfully, otherwise
`false`
- - `size` : the original size of image, contains two parameters:
`naturalWidth` representing the original width of image in pixels,
`naturalHeight` representing the original height of image in pixels. default
value. The default value for both parameters is `0`.
+**Parameters**:
-**component method**
+* `callback`: {Function} A function which is called after the image has
been written to the local device or photo album.
+ * `success`: {Boolean} A flag indicating whether the image has been
written completed.
+ * `errorDesc`: {String} A string containing the description of the error
if image is not written successfully.
-- support save <sup class="api-version">v0.16.0+</sup> image to local
device or photo album.
- - you should specify a callback function to receive the saving result.
- ```
- var image = this.$refs.imageRef; // image
æ¯ä¹åå·²ç»å®ä¹è¿çref
- Â image.save(function(result) {
- Â console.log(JSON.stringify(result))
- });
- ```
- and the result can be the following format
- ```
- {
-  "success" : true/false, // ä¿åæåæ失败
-  "errorDesc": "errordesc" // å¨success 为falseçæ
åµä¼è¿å
-Â }
-Â ```
-Â - note
-Â you must add `NSPhotoLibraryAddUsageDescription` and
`NSPhotoLibraryAddUsageDescription `(iOS 11) privacy to access photo album for
iOS, [see more
privacy](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html)
-Â
-Â [try it for saving
image](http://dotwe.org/vue/fadcd44a7031943ff0feaaf1895df414)
+**Return value**: null
-### Examples
+> **Note**: You must add `NSPhotoLibraryAddUsageDescription` and
`NSPhotoLibraryAddUsageDescription` (iOS 11) privacy to access photo album for
iOS. See also: [Cocoa
Keys](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html)
+
+#### Use `save` Method
+
+Add `ref` attribute (Vue.js *[Child Component
Refs](https://vuejs.org/v2/guide/components.html#Child-Component-Refs)*) on
`<image>`:
--- End diff --
in <image>
---
![https://vuejs.org/images/logo.png"](https://vuejs.org/images/logo.png"){kind=link}