You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@weex.apache.org by cxfeng1 <gi...@git.apache.org> on 2017/10/25 07:40:19 UTC
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
GitHub user cxfeng1 opened a pull request:
https://github.com/apache/incubator-weex-site/pull/4
[WEEX-86][doc] Update image component's document.
Add more examples(basic, placeholder, base64, resize, etc.) and add more details for usage notes.
issue: 86
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/cxfeng1/incubator-weex-site doc-image
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/incubator-weex-site/pull/4.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #4
----
commit ed1b823e91ada91b2d7ef1aac04de096ca64ed3c
Author: yinfeng <cx...@apache.org>
Date: 2017-10-25T07:29:48Z
[WEEX-86][doc] Update image component's document.
Add more examples(basic, placeholder, base64, resize, etc.) and add more details for usage notes.
issue: 86
----
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147028740
--- 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).
--- End diff --
unnecessary space.
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147040711
--- 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)
--- End diff --
Space
you must add ... (iOS 11) to enable the access permission of the iOS photo album.
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by cxfeng1 <gi...@git.apache.org>.
Github user cxfeng1 commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147076974
--- Diff: source/cn/references/components/image.md ---
@@ -6,181 +6,148 @@ order: 8.02
version: 2.1
---
-# <image>
+`<image>` 用于在界面中显示单个图片。
-`<image>` 组件用于渲染图片，并且它不能包含任何子组件。新版 Vue 2.0 中**不支持**用 `<img>` 作简写。
+> **注意：**在HTML中通常使用的 `<img>` 标签在 Weex 中不支持，你应该使用`<image>` 。
-需要注意的是，需要明确指定 `width` 和 `height`，否则图片无法显示。
+> **注意：** Weex 没有内置的图片下载器，因为相关的下载、缓存、解码机制非常复杂，一些开源的工具如 [SDWebImage](https://github.com/rs/SDWebImage) 已经处理得很好， 所以在使用 `<image>` 之前，请在 native 侧先接入相应的 adapter 或者 handler。
+>
+> 参见: [Android adapter](../android-apis.html#Adapter) 和 [iOS handler](../ios-apis.html#Handler-like-Android-Adapter)。
-简单例子：
+## 基本用法
+
+> **注意：** 必须指定样式中的宽度和高度，否则无法工作。
```html
-<template>
- <div>
- <image style="width: 560px;height: 560px;" src="https://img.alicdn.com/tps/TB1z.55OFXXXXcLXXXXXXXXXXXX-560-560.jpg"></image>
- </div>
-</template>
+<image style="width:500px;height:500px" src="https://vuejs.org/images/logo.png"></image>
```
-[体验一下](http://dotwe.org/vue/1d6145d98cbdb8c66c69b4d4dcd2744d)
+参见[示例](http://dotwe.org/vue/00f4b68b3a86360df1f38728fd0b4a1f)。
-## 子组件
+## 属性
-`<image>` 组件不支持任何子组件，因此不要尝试在 `<image>` 组件中添加任何组件。如果需要实现 `background-image` 的效果，可以使用 `<image>` 组件和 `position` 定位来现实，如下面代码。
+| 属性名 | 类型 | 值 | 默认值 |
+| ------------- | ------ | -------------------------- | ------- |
+| `placeholder` | String | {URL / Base64} | - |
+| `resize` | String | conver / contain / stretch | stretch |
+| `src` | String | {URL / Base64 } | - |
-```html
-<template>
- <div>
- <image style="width:750px; height:750px;" src="https://img.alicdn.com/tps/TB1z.55OFXXXXcLXXXXXXXXXXXX-560-560.jpg"></image>
- <div class="title">
- <text style="font-size:50px; color: #ff0000">你好，image</text>
- </div>
- </div>
-</template>
-<style>
- .title{
- position:absolute;
- top:50;
- left:10;
- }
-</style>
-```
+> **注意：**您可以指定一个相对 bundle URL 的相对路径，相对路径将被重写为绝对资源路径(本地或远程)。参见: [资源路径](../../guide/advanced/path.html)。
-[体验一下](http://dotwe.org/vue/0a81d27b5dbc68ea3bf5f9fd56c882e8)
+### `placeholder`
-## 特性
+占位图的 URL，当由 `src` 表示的图片下载完成并展示后将被删除。 ([示例](http://dotwe.org/vue/712ef102fc5e073b6c7e3b701545681c))
-`<image>` 组件，包含 `src` 和 `resize` 两个重要特性。
+### `resize`
-- `src {string}`：定义图片链接，目前图片暂不支持本地图片。
-- `resize {string}`：可以控制图片的拉伸状态，值行为和 W3C 标准一致。
+
- 可选值为：
+- `contain`: 缩放图片以完全装入`<image>`区域，可能背景区部分空白。 ([示例](http://dotwe.org/vue/89be94dcd1fec73b77246ec46c678914))
- - `stretch`：默认值，指定图片按照容器拉伸，有可能使图片产生形变。
- - `cover`：指定图片可以被调整到容器，以使图片完全覆盖背景区域，图片有可能被剪裁。
- - `contain`：指定可以不用考虑容器的大小，把图像扩展至最大尺寸，以使其宽度和高度完全适应内容区域。
+- `cover`: 缩放图片以完全覆盖`<image>`区域，可能图片部分看不见。 ([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
- 例子：
+- `stretch`: `默认值`. 按照`<image>`区域的宽高比例缩放图片。([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
- 
+ 参见: [`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size).
-- `placeholder`: <span class="api-version">v0.9+</span> <string> 当源图片下载中时显示一张占位图。
+### `src`
- [体验一下](http://dotwe.org/vue/18e71ab3484bb6751ad77ff7d5195404)
+要显示图片的 URL，该属性是 `<image>` 组件的强制属性。
-## 样式
+#### 支持的图片格式
-- 通用样式：支持所有通用样式
+Weex没有提供必须支持的图片格式列表，主要依赖于你正在使用的图片 adapter 或者 handler。例如，如果你使用 [SDWebImage](https://github.com/rs/SDWebImage#supported-image-formats) 作为iOS上的图片 handler，你可以使用像 JPEG、PNG、GIF、WebP 等图片格式。
- - 盒模型
- - `flexbox` 布局
- - `position`
- - `opacity`
- - `background-color`
+## Component 方法
- 查看 [组件通用样式](../common-style.html)
+### `save` <span class="api-version">v0.16.0+</span>
-## 事件
+保存图片内容到本地文件或相册，此操作可能需要设备相关权限。
+
+**参数**:
+
+- `callback`: {Function} 在图片被写入到本地文件或相册后调用的函数。
+ - `success`: {Boolean} 标记图片是否已写入完成。
--- End diff --
Actually, the spaces here is used to make a sub-list to identify that `success` and `errorDesc` are parameters of the `callback`.
@CYJB has given a good advice, to point out the parameters more clearly.
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147025826
--- Diff: source/cn/references/components/image.md ---
@@ -6,181 +6,148 @@ order: 8.02
version: 2.1
---
-# <image>
+`<image>` 用于在界面中显示单个图片。
-`<image>` 组件用于渲染图片，并且它不能包含任何子组件。新版 Vue 2.0 中**不支持**用 `<img>` 作简写。
+> **注意：**在HTML中通常使用的 `<img>` 标签在 Weex 中不支持，你应该使用`<image>` 。
-需要注意的是，需要明确指定 `width` 和 `height`，否则图片无法显示。
+> **注意：** Weex 没有内置的图片下载器，因为相关的下载、缓存、解码机制非常复杂，一些开源的工具如 [SDWebImage](https://github.com/rs/SDWebImage) 已经处理得很好， 所以在使用 `<image>` 之前，请在 native 侧先接入相应的 adapter 或者 handler。
+>
+> 参见: [Android adapter](../android-apis.html#Adapter) 和 [iOS handler](../ios-apis.html#Handler-like-Android-Adapter)。
-简单例子：
+## 基本用法
+
+> **注意：** 必须指定样式中的宽度和高度，否则无法工作。
```html
-<template>
- <div>
- <image style="width: 560px;height: 560px;" src="https://img.alicdn.com/tps/TB1z.55OFXXXXcLXXXXXXXXXXXX-560-560.jpg"></image>
- </div>
-</template>
+<image style="width:500px;height:500px" src="https://vuejs.org/images/logo.png"></image>
```
-[体验一下](http://dotwe.org/vue/1d6145d98cbdb8c66c69b4d4dcd2744d)
+参见[示例](http://dotwe.org/vue/00f4b68b3a86360df1f38728fd0b4a1f)。
-## 子组件
+## 属性
-`<image>` 组件不支持任何子组件，因此不要尝试在 `<image>` 组件中添加任何组件。如果需要实现 `background-image` 的效果，可以使用 `<image>` 组件和 `position` 定位来现实，如下面代码。
+| 属性名 | 类型 | 值 | 默认值 |
+| ------------- | ------ | -------------------------- | ------- |
+| `placeholder` | String | {URL / Base64} | - |
+| `resize` | String | conver / contain / stretch | stretch |
+| `src` | String | {URL / Base64 } | - |
-```html
-<template>
- <div>
- <image style="width:750px; height:750px;" src="https://img.alicdn.com/tps/TB1z.55OFXXXXcLXXXXXXXXXXXX-560-560.jpg"></image>
- <div class="title">
- <text style="font-size:50px; color: #ff0000">你好，image</text>
- </div>
- </div>
-</template>
-<style>
- .title{
- position:absolute;
- top:50;
- left:10;
- }
-</style>
-```
+> **注意：**您可以指定一个相对 bundle URL 的相对路径，相对路径将被重写为绝对资源路径(本地或远程)。参见: [资源路径](../../guide/advanced/path.html)。
-[体验一下](http://dotwe.org/vue/0a81d27b5dbc68ea3bf5f9fd56c882e8)
+### `placeholder`
-## 特性
+占位图的 URL，当由 `src` 表示的图片下载完成并展示后将被删除。 ([示例](http://dotwe.org/vue/712ef102fc5e073b6c7e3b701545681c))
-`<image>` 组件，包含 `src` 和 `resize` 两个重要特性。
+### `resize`
-- `src {string}`：定义图片链接，目前图片暂不支持本地图片。
-- `resize {string}`：可以控制图片的拉伸状态，值行为和 W3C 标准一致。
+
- 可选值为：
+- `contain`: 缩放图片以完全装入`<image>`区域，可能背景区部分空白。 ([示例](http://dotwe.org/vue/89be94dcd1fec73b77246ec46c678914))
- - `stretch`：默认值，指定图片按照容器拉伸，有可能使图片产生形变。
- - `cover`：指定图片可以被调整到容器，以使图片完全覆盖背景区域，图片有可能被剪裁。
- - `contain`：指定可以不用考虑容器的大小，把图像扩展至最大尺寸，以使其宽度和高度完全适应内容区域。
+- `cover`: 缩放图片以完全覆盖`<image>`区域，可能图片部分看不见。 ([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
- 例子：
+- `stretch`: `默认值`. 按照`<image>`区域的宽高比例缩放图片。([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
- 
+ 参见: [`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size).
-- `placeholder`: <span class="api-version">v0.9+</span> <string> 当源图片下载中时显示一张占位图。
+### `src`
- [体验一下](http://dotwe.org/vue/18e71ab3484bb6751ad77ff7d5195404)
+要显示图片的 URL，该属性是 `<image>` 组件的强制属性。
-## 样式
+#### 支持的图片格式
-- 通用样式：支持所有通用样式
+Weex没有提供必须支持的图片格式列表，主要依赖于你正在使用的图片 adapter 或者 handler。例如，如果你使用 [SDWebImage](https://github.com/rs/SDWebImage#supported-image-formats) 作为iOS上的图片 handler，你可以使用像 JPEG、PNG、GIF、WebP 等图片格式。
- - 盒模型
- - `flexbox` 布局
- - `position`
- - `opacity`
- - `background-color`
+## Component 方法
- 查看 [组件通用样式](../common-style.html)
+### `save` <span class="api-version">v0.16.0+</span>
-## 事件
+保存图片内容到本地文件或相册，此操作可能需要设备相关权限。
+
+**参数**:
+
+- `callback`: {Function} 在图片被写入到本地文件或相册后调用的函数。
+ - `success`: {Boolean} 标记图片是否已写入完成。
+ - `errorDesc`: {String} 如果图像没有成功写入，该字符串包含了详细的错误描述。
+
+**返回值**: null
-- `load`: <sup class="api-version">v0.8+</sup>：当图片加载完成时触发。目前在 Android、iOS 上支持，H5 暂不支持。[示例](http://dotwe.org/vue/e291159ac60b35dcd4994638a78d54ad)
+> **注意**: 你必须加入`NSPhotoLibraryAddUsageDescription` 和 `NSPhotoLibraryAddUsageDescription` (iOS 11) 以获得访问 iOS 系统相册权限. 参见: [Cocoa Keys](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html)
- - 事件对象
- - `success`: 当图片成功加载时为`true`，否则为`false`
- - `size`: 图片的原始尺寸，包含两个参数：`naturalWidth` 代表图片的原始宽度像素值，`naturalHeight` 代表图片的原始高度值。这两个参数的默认值都为`0`
+#### 使用 `save` 方法
-- 通用事件
+在 `<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>
+```
- - `click`
- - `longpress`
- - `appear`
- - `disappear`
+获取组件引用并使用 `save` 方法:
- 查看 [通用事件](../common-event.html)
+```js
+const $image = this.$refs.poster
+$image.save(result => {
+ if (result.success) {
+ // TODO
--- End diff --
I think I prefer using elaborated instruction here, like "Handle success" or something else, instead of TODO.
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147028708
--- 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))
--- End diff --
size of the element itself by changing the aspect ratio of the image if necessary.
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147027375
--- 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).
--- End diff --
relative URL ... to the actual resource URL.
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by CYJB <gi...@git.apache.org>.
Github user CYJB commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147050673
--- Diff: source/cn/references/components/image.md ---
@@ -6,181 +6,148 @@ order: 8.02
version: 2.1
---
-# <image>
+`<image>` 用于在界面中显示单个图片。
-`<image>` 组件用于渲染图片，并且它不能包含任何子组件。新版 Vue 2.0 中**不支持**用 `<img>` 作简写。
+> **注意：**在HTML中通常使用的 `<img>` 标签在 Weex 中不支持，你应该使用`<image>` 。
-需要注意的是，需要明确指定 `width` 和 `height`，否则图片无法显示。
+> **注意：** Weex 没有内置的图片下载器，因为相关的下载、缓存、解码机制非常复杂，一些开源的工具如 [SDWebImage](https://github.com/rs/SDWebImage) 已经处理得很好， 所以在使用 `<image>` 之前，请在 native 侧先接入相应的 adapter 或者 handler。
+>
+> 参见: [Android adapter](../android-apis.html#Adapter) 和 [iOS handler](../ios-apis.html#Handler-like-Android-Adapter)。
-简单例子：
+## 基本用法
+
+> **注意：** 必须指定样式中的宽度和高度，否则无法工作。
```html
-<template>
- <div>
- <image style="width: 560px;height: 560px;" src="https://img.alicdn.com/tps/TB1z.55OFXXXXcLXXXXXXXXXXXX-560-560.jpg"></image>
- </div>
-</template>
+<image style="width:500px;height:500px" src="https://vuejs.org/images/logo.png"></image>
```
-[体验一下](http://dotwe.org/vue/1d6145d98cbdb8c66c69b4d4dcd2744d)
+参见[示例](http://dotwe.org/vue/00f4b68b3a86360df1f38728fd0b4a1f)。
-## 子组件
+## 属性
-`<image>` 组件不支持任何子组件，因此不要尝试在 `<image>` 组件中添加任何组件。如果需要实现 `background-image` 的效果，可以使用 `<image>` 组件和 `position` 定位来现实，如下面代码。
+| 属性名 | 类型 | 值 | 默认值 |
+| ------------- | ------ | -------------------------- | ------- |
+| `placeholder` | String | {URL / Base64} | - |
+| `resize` | String | conver / contain / stretch | stretch |
+| `src` | String | {URL / Base64 } | - |
-```html
-<template>
- <div>
- <image style="width:750px; height:750px;" src="https://img.alicdn.com/tps/TB1z.55OFXXXXcLXXXXXXXXXXXX-560-560.jpg"></image>
- <div class="title">
- <text style="font-size:50px; color: #ff0000">你好，image</text>
- </div>
- </div>
-</template>
-<style>
- .title{
- position:absolute;
- top:50;
- left:10;
- }
-</style>
-```
+> **注意：**您可以指定一个相对 bundle URL 的相对路径，相对路径将被重写为绝对资源路径(本地或远程)。参见: [资源路径](../../guide/advanced/path.html)。
-[体验一下](http://dotwe.org/vue/0a81d27b5dbc68ea3bf5f9fd56c882e8)
+### `placeholder`
-## 特性
+占位图的 URL，当由 `src` 表示的图片下载完成并展示后将被删除。 ([示例](http://dotwe.org/vue/712ef102fc5e073b6c7e3b701545681c))
-`<image>` 组件，包含 `src` 和 `resize` 两个重要特性。
+### `resize`
-- `src {string}`：定义图片链接，目前图片暂不支持本地图片。
-- `resize {string}`：可以控制图片的拉伸状态，值行为和 W3C 标准一致。
+
- 可选值为：
+- `contain`: 缩放图片以完全装入`<image>`区域，可能背景区部分空白。 ([示例](http://dotwe.org/vue/89be94dcd1fec73b77246ec46c678914))
- - `stretch`：默认值，指定图片按照容器拉伸，有可能使图片产生形变。
- - `cover`：指定图片可以被调整到容器，以使图片完全覆盖背景区域，图片有可能被剪裁。
- - `contain`：指定可以不用考虑容器的大小，把图像扩展至最大尺寸，以使其宽度和高度完全适应内容区域。
+- `cover`: 缩放图片以完全覆盖`<image>`区域，可能图片部分看不见。 ([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
- 例子：
+- `stretch`: `默认值`. 按照`<image>`区域的宽高比例缩放图片。([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
- 
+ 参见: [`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size).
-- `placeholder`: <span class="api-version">v0.9+</span> <string> 当源图片下载中时显示一张占位图。
+### `src`
- [体验一下](http://dotwe.org/vue/18e71ab3484bb6751ad77ff7d5195404)
+要显示图片的 URL，该属性是 `<image>` 组件的强制属性。
-## 样式
+#### 支持的图片格式
-- 通用样式：支持所有通用样式
+Weex没有提供必须支持的图片格式列表，主要依赖于你正在使用的图片 adapter 或者 handler。例如，如果你使用 [SDWebImage](https://github.com/rs/SDWebImage#supported-image-formats) 作为iOS上的图片 handler，你可以使用像 JPEG、PNG、GIF、WebP 等图片格式。
- - 盒模型
- - `flexbox` 布局
- - `position`
- - `opacity`
- - `background-color`
+## Component 方法
- 查看 [组件通用样式](../common-style.html)
+### `save` <span class="api-version">v0.16.0+</span>
-## 事件
+保存图片内容到本地文件或相册，此操作可能需要设备相关权限。
+
+**参数**:
+
+- `callback`: {Function} 在图片被写入到本地文件或相册后调用的函数。
+ - `success`: {Boolean} 标记图片是否已写入完成。
+ - `errorDesc`: {String} 如果图像没有成功写入，该字符串包含了详细的错误描述。
--- End diff --
I think `success` and `errorDesc` means parameter of callback function? Indent by spaces can make sub-list in markdown.
It is better to point out `success` and `errorDesc` is parameter, and use ordered list
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147029096
--- 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.
--- End diff --
unnecessary spaces.
it mainly relies on...
WebP, etc.
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147041361
--- 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>`:
```html
-<template>
- <scroller class="wrapper" >
- <div class="page-head" >
- <image class="title-bg" resize="cover" src="https://img.alicdn.com/tps/TB1dX5NOFXXXXc6XFXXXXXXXXXX-750-202.png"></image>
- <div class="title-box">
- <text class="title">Alan Mathison Turing</text>
- </div>
- </div>
- <div class="article">
- <text class="paragraph">Alan Mathison Turing ( 23 June 1912 – 7 June 1954) was an English computer scientist, mathematician, logician, cryptanalyst and theoretical biologist. He was highly influential in the development of theoretical computer science, providing a formalisation of the concepts of algorithm and computation with the Turing machine, which can be considered a model of a general purpose computer.Turing is widely considered to be the father of theoretical computer science and artificial intelligence.</text>
- <text class="paragraph">During the Second World War, Turing worked for the Government Code and Cypher School (GC&CS) at Bletchley Park, Britain's codebreaking centre. For a time he led Hut 8, the section responsible for German naval cryptanalysis. He devised a number of techniques for speeding the breaking of German ciphers, including improvements to the pre-war Polish bombe method, an electromechanical machine that could find settings for the Enigma machine. Turing played a pivotal role in cracking intercepted coded messages that enabled the Allies to defeat the Nazis in many crucial engagements, including the Battle of the Atlantic; it has been estimated that this work shortened the war in Europe by more than two years and saved over fourteen million lives.</text>
- <text class="paragraph">After the war, he worked at the National Physical Laboratory, where he designed the ACE, among the first designs for a stored-program computer. In 1948 Turing joined Max Newman's Computing Machine Laboratory at the Victoria University of Manchester, where he helped develop the Manchester computers and became interested in mathematical biology. He wrote a paper on the chemical basis of morphogenesis, and predicted oscillating chemical reactions such as the Belousov–Zhabotinsky reaction, first observed in the 1960s.</text>
- <text class="paragraph">Turing was prosecuted in 1952 for homosexual acts, when by the Labouchere Amendment, "gross indecency" was still criminal in the UK. He accepted chemical castration treatment, with DES, as an alternative to prison. Turing died in 1954, 16 days before his 42nd birthday, from cyanide poisoning. An inquest determined his death as suicide, but it has been noted that the known evidence is also consistent with accidental poisoning. In 2009, following an Internet campaign, British Prime Minister Gordon Brown made an official public apology on behalf of the British government for "the appalling way he was treated." Queen Elizabeth II granted him a posthumous pardon in 2013.</text>
- </div>
- </scroller>
-</template>
-
-<style>
- .page-head {
- width: 750px;
- height: 200px;
- }
- .title-bg {
- width: 750px;
- height: 200px;
- }
- .title-box {
- width: 750px;
- height: 200px;
- justify-content: center;
- align-items: center;
- position: absolute;
- top: 0;
- right: 0;
- bottom: 0;
- left: 0;
- }
- .title {
- color: #ffffff;
- font-size: 32px;
- font-weight: bold;
- }
- .article {
- padding: 20px;
+<image ref="poster" src="path/to/image.png"></image>
+```
+
+Get the component reference and use the `save` method:
+
+```js
+const $image = this.$refs.poster
+$image.save(result => {
+ if (result.success) {
+ // TODO
+ } else {
+ console.log(result.errorDesc)
}
- .paragraph{
- margin-bottom: 15px;
+})
+```
+
+See the [complete example](http://dotwe.org/vue/fadcd44a7031943ff0feaaf1895df414).
+
+## Events
+
+Support **[common events](../../wiki/common-events.html)**.
+
+### `load`
+
+`load` event handler will be called when the image specified by `src` is loaded.
+
+**Event object**:
+
+- `success`: {Boolean} It shows that whether the image is loaded successfully.
+- `size`: {Object} The loaded image size
+ - `naturalWidth`: {Number} The intrinsic width of image displayed on device, it will be zero if the specified image cannot be loaded correctly.
--- End diff --
space
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147028176
--- 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))
--- End diff --
unnecessary spaces at the beginning.
without cropping or stretching it.
Remaining area within bounds is transparent.
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147025867
--- Diff: source/cn/references/components/image.md ---
@@ -6,181 +6,148 @@ order: 8.02
version: 2.1
---
-# <image>
+`<image>` 用于在界面中显示单个图片。
-`<image>` 组件用于渲染图片，并且它不能包含任何子组件。新版 Vue 2.0 中**不支持**用 `<img>` 作简写。
+> **注意：**在HTML中通常使用的 `<img>` 标签在 Weex 中不支持，你应该使用`<image>` 。
-需要注意的是，需要明确指定 `width` 和 `height`，否则图片无法显示。
+> **注意：** Weex 没有内置的图片下载器，因为相关的下载、缓存、解码机制非常复杂，一些开源的工具如 [SDWebImage](https://github.com/rs/SDWebImage) 已经处理得很好， 所以在使用 `<image>` 之前，请在 native 侧先接入相应的 adapter 或者 handler。
+>
+> 参见: [Android adapter](../android-apis.html#Adapter) 和 [iOS handler](../ios-apis.html#Handler-like-Android-Adapter)。
-简单例子：
+## 基本用法
+
+> **注意：** 必须指定样式中的宽度和高度，否则无法工作。
```html
-<template>
- <div>
- <image style="width: 560px;height: 560px;" src="https://img.alicdn.com/tps/TB1z.55OFXXXXcLXXXXXXXXXXXX-560-560.jpg"></image>
- </div>
-</template>
+<image style="width:500px;height:500px" src="https://vuejs.org/images/logo.png"></image>
```
-[体验一下](http://dotwe.org/vue/1d6145d98cbdb8c66c69b4d4dcd2744d)
+参见[示例](http://dotwe.org/vue/00f4b68b3a86360df1f38728fd0b4a1f)。
-## 子组件
+## 属性
-`<image>` 组件不支持任何子组件，因此不要尝试在 `<image>` 组件中添加任何组件。如果需要实现 `background-image` 的效果，可以使用 `<image>` 组件和 `position` 定位来现实，如下面代码。
+| 属性名 | 类型 | 值 | 默认值 |
+| ------------- | ------ | -------------------------- | ------- |
+| `placeholder` | String | {URL / Base64} | - |
+| `resize` | String | conver / contain / stretch | stretch |
+| `src` | String | {URL / Base64 } | - |
-```html
-<template>
- <div>
- <image style="width:750px; height:750px;" src="https://img.alicdn.com/tps/TB1z.55OFXXXXcLXXXXXXXXXXXX-560-560.jpg"></image>
- <div class="title">
- <text style="font-size:50px; color: #ff0000">你好，image</text>
- </div>
- </div>
-</template>
-<style>
- .title{
- position:absolute;
- top:50;
- left:10;
- }
-</style>
-```
+> **注意：**您可以指定一个相对 bundle URL 的相对路径，相对路径将被重写为绝对资源路径(本地或远程)。参见: [资源路径](../../guide/advanced/path.html)。
-[体验一下](http://dotwe.org/vue/0a81d27b5dbc68ea3bf5f9fd56c882e8)
+### `placeholder`
-## 特性
+占位图的 URL，当由 `src` 表示的图片下载完成并展示后将被删除。 ([示例](http://dotwe.org/vue/712ef102fc5e073b6c7e3b701545681c))
-`<image>` 组件，包含 `src` 和 `resize` 两个重要特性。
+### `resize`
-- `src {string}`：定义图片链接，目前图片暂不支持本地图片。
-- `resize {string}`：可以控制图片的拉伸状态，值行为和 W3C 标准一致。
+
- 可选值为：
+- `contain`: 缩放图片以完全装入`<image>`区域，可能背景区部分空白。 ([示例](http://dotwe.org/vue/89be94dcd1fec73b77246ec46c678914))
- - `stretch`：默认值，指定图片按照容器拉伸，有可能使图片产生形变。
- - `cover`：指定图片可以被调整到容器，以使图片完全覆盖背景区域，图片有可能被剪裁。
- - `contain`：指定可以不用考虑容器的大小，把图像扩展至最大尺寸，以使其宽度和高度完全适应内容区域。
+- `cover`: 缩放图片以完全覆盖`<image>`区域，可能图片部分看不见。 ([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
- 例子：
+- `stretch`: `默认值`. 按照`<image>`区域的宽高比例缩放图片。([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
- 
+ 参见: [`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size).
-- `placeholder`: <span class="api-version">v0.9+</span> <string> 当源图片下载中时显示一张占位图。
+### `src`
- [体验一下](http://dotwe.org/vue/18e71ab3484bb6751ad77ff7d5195404)
+要显示图片的 URL，该属性是 `<image>` 组件的强制属性。
-## 样式
+#### 支持的图片格式
-- 通用样式：支持所有通用样式
+Weex没有提供必须支持的图片格式列表，主要依赖于你正在使用的图片 adapter 或者 handler。例如，如果你使用 [SDWebImage](https://github.com/rs/SDWebImage#supported-image-formats) 作为iOS上的图片 handler，你可以使用像 JPEG、PNG、GIF、WebP 等图片格式。
- - 盒模型
- - `flexbox` 布局
- - `position`
- - `opacity`
- - `background-color`
+## Component 方法
- 查看 [组件通用样式](../common-style.html)
+### `save` <span class="api-version">v0.16.0+</span>
-## 事件
+保存图片内容到本地文件或相册，此操作可能需要设备相关权限。
+
+**参数**:
+
+- `callback`: {Function} 在图片被写入到本地文件或相册后调用的函数。
+ - `success`: {Boolean} 标记图片是否已写入完成。
+ - `errorDesc`: {String} 如果图像没有成功写入，该字符串包含了详细的错误描述。
+
+**返回值**: null
-- `load`: <sup class="api-version">v0.8+</sup>：当图片加载完成时触发。目前在 Android、iOS 上支持，H5 暂不支持。[示例](http://dotwe.org/vue/e291159ac60b35dcd4994638a78d54ad)
+> **注意**: 你必须加入`NSPhotoLibraryAddUsageDescription` 和 `NSPhotoLibraryAddUsageDescription` (iOS 11) 以获得访问 iOS 系统相册权限. 参见: [Cocoa Keys](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html)
- - 事件对象
- - `success`: 当图片成功加载时为`true`，否则为`false`
- - `size`: 图片的原始尺寸，包含两个参数：`naturalWidth` 代表图片的原始宽度像素值，`naturalHeight` 代表图片的原始高度值。这两个参数的默认值都为`0`
+#### 使用 `save` 方法
-- 通用事件
+在 `<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>
+```
- - `click`
- - `longpress`
- - `appear`
- - `disappear`
+获取组件引用并使用 `save` 方法:
- 查看 [通用事件](../common-event.html)
+```js
+const $image = this.$refs.poster
+$image.save(result => {
+ if (result.success) {
+ // TODO
+ } else {
+ console.log(result.errorDesc)
+ }
+})
+```
-## 组件方法
- <sup class="api-version">v0.16.0+</sup>
+参见 [完整例子](http://dotwe.org/vue/fadcd44a7031943ff0feaaf1895df414).
- - save：保存当前图片到本地
- - 参数
- 回调函数作为方法入参，接收保存结果.
- ```
- var image = this.$refs.imageRef; // image 是之前已经定义过的ref
- image.save(function(result) {
- console.log(JSON.stringify(result))
- });
- ```
- - 异步返回的数据描述
- ```
- {
- "success" : true/false, // 保存成功或失败
- "errorDesc": "errordesc" // 在success 为false的情况会返回
- }
- ```
- - 说明
- 对于 iOS 系统需要添加 `NSPhotoLibraryAddUsageDescription`相册访问权限, iOS 11 需要再添加一个`NSPhotoLibraryAddUsageDescription`权限, [查看更多iOS系统权限](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html)
-
- [试一试](http://dotwe.org/vue/fadcd44a7031943ff0feaaf1895df414)
+## 事件
-## 约束
+支持 **[通用事件](../../wiki/common-events.html)**.
-1. 需要指定宽高；
-2. 不支持子组件。
+### `load`
-## 示例
+当加载完成 `src` 指定的图片时，`load`事件将被触发。
+
+**事件对象**:
+
+- `success`: {Boolean} 标记图片是否成功加载。
+- `size`: {Object} 加载的图片大小。
+ - `naturalWidth`: {Number} 图片宽度，如果图片加载失败则为0。
--- End diff --
unnecessary space here.
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147025555
--- Diff: source/cn/references/components/image.md ---
@@ -6,181 +6,148 @@ order: 8.02
version: 2.1
---
-# <image>
+`<image>` 用于在界面中显示单个图片。
-`<image>` 组件用于渲染图片，并且它不能包含任何子组件。新版 Vue 2.0 中**不支持**用 `<img>` 作简写。
+> **注意：**在HTML中通常使用的 `<img>` 标签在 Weex 中不支持，你应该使用`<image>` 。
-需要注意的是，需要明确指定 `width` 和 `height`，否则图片无法显示。
+> **注意：** Weex 没有内置的图片下载器，因为相关的下载、缓存、解码机制非常复杂，一些开源的工具如 [SDWebImage](https://github.com/rs/SDWebImage) 已经处理得很好， 所以在使用 `<image>` 之前，请在 native 侧先接入相应的 adapter 或者 handler。
+>
+> 参见: [Android adapter](../android-apis.html#Adapter) 和 [iOS handler](../ios-apis.html#Handler-like-Android-Adapter)。
-简单例子：
+## 基本用法
+
+> **注意：** 必须指定样式中的宽度和高度，否则无法工作。
```html
-<template>
- <div>
- <image style="width: 560px;height: 560px;" src="https://img.alicdn.com/tps/TB1z.55OFXXXXcLXXXXXXXXXXXX-560-560.jpg"></image>
- </div>
-</template>
+<image style="width:500px;height:500px" src="https://vuejs.org/images/logo.png"></image>
```
-[体验一下](http://dotwe.org/vue/1d6145d98cbdb8c66c69b4d4dcd2744d)
+参见[示例](http://dotwe.org/vue/00f4b68b3a86360df1f38728fd0b4a1f)。
-## 子组件
+## 属性
-`<image>` 组件不支持任何子组件，因此不要尝试在 `<image>` 组件中添加任何组件。如果需要实现 `background-image` 的效果，可以使用 `<image>` 组件和 `position` 定位来现实，如下面代码。
+| 属性名 | 类型 | 值 | 默认值 |
+| ------------- | ------ | -------------------------- | ------- |
+| `placeholder` | String | {URL / Base64} | - |
+| `resize` | String | conver / contain / stretch | stretch |
+| `src` | String | {URL / Base64 } | - |
-```html
-<template>
- <div>
- <image style="width:750px; height:750px;" src="https://img.alicdn.com/tps/TB1z.55OFXXXXcLXXXXXXXXXXXX-560-560.jpg"></image>
- <div class="title">
- <text style="font-size:50px; color: #ff0000">你好，image</text>
- </div>
- </div>
-</template>
-<style>
- .title{
- position:absolute;
- top:50;
- left:10;
- }
-</style>
-```
+> **注意：**您可以指定一个相对 bundle URL 的相对路径，相对路径将被重写为绝对资源路径(本地或远程)。参见: [资源路径](../../guide/advanced/path.html)。
-[体验一下](http://dotwe.org/vue/0a81d27b5dbc68ea3bf5f9fd56c882e8)
+### `placeholder`
-## 特性
+占位图的 URL，当由 `src` 表示的图片下载完成并展示后将被删除。 ([示例](http://dotwe.org/vue/712ef102fc5e073b6c7e3b701545681c))
-`<image>` 组件，包含 `src` 和 `resize` 两个重要特性。
+### `resize`
-- `src {string}`：定义图片链接，目前图片暂不支持本地图片。
-- `resize {string}`：可以控制图片的拉伸状态，值行为和 W3C 标准一致。
+
- 可选值为：
+- `contain`: 缩放图片以完全装入`<image>`区域，可能背景区部分空白。 ([示例](http://dotwe.org/vue/89be94dcd1fec73b77246ec46c678914))
- - `stretch`：默认值，指定图片按照容器拉伸，有可能使图片产生形变。
- - `cover`：指定图片可以被调整到容器，以使图片完全覆盖背景区域，图片有可能被剪裁。
- - `contain`：指定可以不用考虑容器的大小，把图像扩展至最大尺寸，以使其宽度和高度完全适应内容区域。
+- `cover`: 缩放图片以完全覆盖`<image>`区域，可能图片部分看不见。 ([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
- 例子：
+- `stretch`: `默认值`. 按照`<image>`区域的宽高比例缩放图片。([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
- 
+ 参见: [`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size).
-- `placeholder`: <span class="api-version">v0.9+</span> <string> 当源图片下载中时显示一张占位图。
+### `src`
- [体验一下](http://dotwe.org/vue/18e71ab3484bb6751ad77ff7d5195404)
+要显示图片的 URL，该属性是 `<image>` 组件的强制属性。
-## 样式
+#### 支持的图片格式
-- 通用样式：支持所有通用样式
+Weex没有提供必须支持的图片格式列表，主要依赖于你正在使用的图片 adapter 或者 handler。例如，如果你使用 [SDWebImage](https://github.com/rs/SDWebImage#supported-image-formats) 作为iOS上的图片 handler，你可以使用像 JPEG、PNG、GIF、WebP 等图片格式。
- - 盒模型
- - `flexbox` 布局
- - `position`
- - `opacity`
- - `background-color`
+## Component 方法
- 查看 [组件通用样式](../common-style.html)
+### `save` <span class="api-version">v0.16.0+</span>
-## 事件
+保存图片内容到本地文件或相册，此操作可能需要设备相关权限。
+
+**参数**:
+
+- `callback`: {Function} 在图片被写入到本地文件或相册后调用的函数。
+ - `success`: {Boolean} 标记图片是否已写入完成。
--- End diff --
unnecessary space at the beginning of the line.
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by asfgit <gi...@git.apache.org>.
Github user asfgit closed the pull request at:
https://github.com/apache/incubator-weex-site/pull/4
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
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>
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147052566
--- Diff: source/cn/references/components/image.md ---
@@ -6,181 +6,148 @@ order: 8.02
version: 2.1
---
-# <image>
+`<image>` 用于在界面中显示单个图片。
-`<image>` 组件用于渲染图片，并且它不能包含任何子组件。新版 Vue 2.0 中**不支持**用 `<img>` 作简写。
+> **注意：**在HTML中通常使用的 `<img>` 标签在 Weex 中不支持，你应该使用`<image>` 。
-需要注意的是，需要明确指定 `width` 和 `height`，否则图片无法显示。
+> **注意：** Weex 没有内置的图片下载器，因为相关的下载、缓存、解码机制非常复杂，一些开源的工具如 [SDWebImage](https://github.com/rs/SDWebImage) 已经处理得很好， 所以在使用 `<image>` 之前，请在 native 侧先接入相应的 adapter 或者 handler。
+>
+> 参见: [Android adapter](../android-apis.html#Adapter) 和 [iOS handler](../ios-apis.html#Handler-like-Android-Adapter)。
-简单例子：
+## 基本用法
+
+> **注意：** 必须指定样式中的宽度和高度，否则无法工作。
```html
-<template>
- <div>
- <image style="width: 560px;height: 560px;" src="https://img.alicdn.com/tps/TB1z.55OFXXXXcLXXXXXXXXXXXX-560-560.jpg"></image>
- </div>
-</template>
+<image style="width:500px;height:500px" src="https://vuejs.org/images/logo.png"></image>
```
-[体验一下](http://dotwe.org/vue/1d6145d98cbdb8c66c69b4d4dcd2744d)
+参见[示例](http://dotwe.org/vue/00f4b68b3a86360df1f38728fd0b4a1f)。
-## 子组件
+## 属性
-`<image>` 组件不支持任何子组件，因此不要尝试在 `<image>` 组件中添加任何组件。如果需要实现 `background-image` 的效果，可以使用 `<image>` 组件和 `position` 定位来现实，如下面代码。
+| 属性名 | 类型 | 值 | 默认值 |
+| ------------- | ------ | -------------------------- | ------- |
+| `placeholder` | String | {URL / Base64} | - |
+| `resize` | String | conver / contain / stretch | stretch |
+| `src` | String | {URL / Base64 } | - |
-```html
-<template>
- <div>
- <image style="width:750px; height:750px;" src="https://img.alicdn.com/tps/TB1z.55OFXXXXcLXXXXXXXXXXXX-560-560.jpg"></image>
- <div class="title">
- <text style="font-size:50px; color: #ff0000">你好，image</text>
- </div>
- </div>
-</template>
-<style>
- .title{
- position:absolute;
- top:50;
- left:10;
- }
-</style>
-```
+> **注意：**您可以指定一个相对 bundle URL 的相对路径，相对路径将被重写为绝对资源路径(本地或远程)。参见: [资源路径](../../guide/advanced/path.html)。
-[体验一下](http://dotwe.org/vue/0a81d27b5dbc68ea3bf5f9fd56c882e8)
+### `placeholder`
-## 特性
+占位图的 URL，当由 `src` 表示的图片下载完成并展示后将被删除。 ([示例](http://dotwe.org/vue/712ef102fc5e073b6c7e3b701545681c))
-`<image>` 组件，包含 `src` 和 `resize` 两个重要特性。
+### `resize`
-- `src {string}`：定义图片链接，目前图片暂不支持本地图片。
-- `resize {string}`：可以控制图片的拉伸状态，值行为和 W3C 标准一致。
+
- 可选值为：
+- `contain`: 缩放图片以完全装入`<image>`区域，可能背景区部分空白。 ([示例](http://dotwe.org/vue/89be94dcd1fec73b77246ec46c678914))
- - `stretch`：默认值，指定图片按照容器拉伸，有可能使图片产生形变。
- - `cover`：指定图片可以被调整到容器，以使图片完全覆盖背景区域，图片有可能被剪裁。
- - `contain`：指定可以不用考虑容器的大小，把图像扩展至最大尺寸，以使其宽度和高度完全适应内容区域。
+- `cover`: 缩放图片以完全覆盖`<image>`区域，可能图片部分看不见。 ([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
- 例子：
+- `stretch`: `默认值`. 按照`<image>`区域的宽高比例缩放图片。([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
- 
+ 参见: [`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size).
-- `placeholder`: <span class="api-version">v0.9+</span> <string> 当源图片下载中时显示一张占位图。
+### `src`
- [体验一下](http://dotwe.org/vue/18e71ab3484bb6751ad77ff7d5195404)
+要显示图片的 URL，该属性是 `<image>` 组件的强制属性。
-## 样式
+#### 支持的图片格式
-- 通用样式：支持所有通用样式
+Weex没有提供必须支持的图片格式列表，主要依赖于你正在使用的图片 adapter 或者 handler。例如，如果你使用 [SDWebImage](https://github.com/rs/SDWebImage#supported-image-formats) 作为iOS上的图片 handler，你可以使用像 JPEG、PNG、GIF、WebP 等图片格式。
- - 盒模型
- - `flexbox` 布局
- - `position`
- - `opacity`
- - `background-color`
+## Component 方法
- 查看 [组件通用样式](../common-style.html)
+### `save` <span class="api-version">v0.16.0+</span>
-## 事件
+保存图片内容到本地文件或相册，此操作可能需要设备相关权限。
+
+**参数**:
+
+- `callback`: {Function} 在图片被写入到本地文件或相册后调用的函数。
+ - `success`: {Boolean} 标记图片是否已写入完成。
+ - `errorDesc`: {String} 如果图像没有成功写入，该字符串包含了详细的错误描述。
--- End diff --
ah, make sense. 👍
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147041602
--- 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>`:
```html
-<template>
- <scroller class="wrapper" >
- <div class="page-head" >
- <image class="title-bg" resize="cover" src="https://img.alicdn.com/tps/TB1dX5NOFXXXXc6XFXXXXXXXXXX-750-202.png"></image>
- <div class="title-box">
- <text class="title">Alan Mathison Turing</text>
- </div>
- </div>
- <div class="article">
- <text class="paragraph">Alan Mathison Turing ( 23 June 1912 – 7 June 1954) was an English computer scientist, mathematician, logician, cryptanalyst and theoretical biologist. He was highly influential in the development of theoretical computer science, providing a formalisation of the concepts of algorithm and computation with the Turing machine, which can be considered a model of a general purpose computer.Turing is widely considered to be the father of theoretical computer science and artificial intelligence.</text>
- <text class="paragraph">During the Second World War, Turing worked for the Government Code and Cypher School (GC&CS) at Bletchley Park, Britain's codebreaking centre. For a time he led Hut 8, the section responsible for German naval cryptanalysis. He devised a number of techniques for speeding the breaking of German ciphers, including improvements to the pre-war Polish bombe method, an electromechanical machine that could find settings for the Enigma machine. Turing played a pivotal role in cracking intercepted coded messages that enabled the Allies to defeat the Nazis in many crucial engagements, including the Battle of the Atlantic; it has been estimated that this work shortened the war in Europe by more than two years and saved over fourteen million lives.</text>
- <text class="paragraph">After the war, he worked at the National Physical Laboratory, where he designed the ACE, among the first designs for a stored-program computer. In 1948 Turing joined Max Newman's Computing Machine Laboratory at the Victoria University of Manchester, where he helped develop the Manchester computers and became interested in mathematical biology. He wrote a paper on the chemical basis of morphogenesis, and predicted oscillating chemical reactions such as the Belousov–Zhabotinsky reaction, first observed in the 1960s.</text>
- <text class="paragraph">Turing was prosecuted in 1952 for homosexual acts, when by the Labouchere Amendment, "gross indecency" was still criminal in the UK. He accepted chemical castration treatment, with DES, as an alternative to prison. Turing died in 1954, 16 days before his 42nd birthday, from cyanide poisoning. An inquest determined his death as suicide, but it has been noted that the known evidence is also consistent with accidental poisoning. In 2009, following an Internet campaign, British Prime Minister Gordon Brown made an official public apology on behalf of the British government for "the appalling way he was treated." Queen Elizabeth II granted him a posthumous pardon in 2013.</text>
- </div>
- </scroller>
-</template>
-
-<style>
- .page-head {
- width: 750px;
- height: 200px;
- }
- .title-bg {
- width: 750px;
- height: 200px;
- }
- .title-box {
- width: 750px;
- height: 200px;
- justify-content: center;
- align-items: center;
- position: absolute;
- top: 0;
- right: 0;
- bottom: 0;
- left: 0;
- }
- .title {
- color: #ffffff;
- font-size: 32px;
- font-weight: bold;
- }
- .article {
- padding: 20px;
+<image ref="poster" src="path/to/image.png"></image>
+```
+
+Get the component reference and use the `save` method:
+
+```js
+const $image = this.$refs.poster
+$image.save(result => {
+ if (result.success) {
+ // TODO
+ } else {
+ console.log(result.errorDesc)
}
- .paragraph{
- margin-bottom: 15px;
+})
+```
+
+See the [complete example](http://dotwe.org/vue/fadcd44a7031943ff0feaaf1895df414).
+
+## Events
+
+Support **[common events](../../wiki/common-events.html)**.
+
+### `load`
+
+`load` event handler will be called when the image specified by `src` is loaded.
+
+**Event object**:
+
+- `success`: {Boolean} It shows that whether the image is loaded successfully.
+- `size`: {Object} The loaded image size
+ - `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
+
+Bind `load` event on `<image>`:
+
+```html
+<image @load="onImageLoad" src="path/to/image.png"></image>
+```
+
+Add event handler:
+
+```js
+export default {
+ methods: {
+ onImageLoad (event) {
+ if (event.success) {
+ // TODO
+ }
+ }
}
-</style>
+}
```
-[try it](http://dotwe.org/vue/e2122bc245beafb0348d79bfd1274904)
+See the [complete example](http://dotwe.org/vue/94de9307517240dec066d2ea57fe54a0).
--- End diff --
Complete example goes [here](http://dotwe.org/vue/94de9307517240dec066d2ea57fe54a0)
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147025571
--- Diff: source/cn/references/components/image.md ---
@@ -6,181 +6,148 @@ order: 8.02
version: 2.1
---
-# <image>
+`<image>` 用于在界面中显示单个图片。
-`<image>` 组件用于渲染图片，并且它不能包含任何子组件。新版 Vue 2.0 中**不支持**用 `<img>` 作简写。
+> **注意：**在HTML中通常使用的 `<img>` 标签在 Weex 中不支持，你应该使用`<image>` 。
-需要注意的是，需要明确指定 `width` 和 `height`，否则图片无法显示。
+> **注意：** Weex 没有内置的图片下载器，因为相关的下载、缓存、解码机制非常复杂，一些开源的工具如 [SDWebImage](https://github.com/rs/SDWebImage) 已经处理得很好， 所以在使用 `<image>` 之前，请在 native 侧先接入相应的 adapter 或者 handler。
+>
+> 参见: [Android adapter](../android-apis.html#Adapter) 和 [iOS handler](../ios-apis.html#Handler-like-Android-Adapter)。
-简单例子：
+## 基本用法
+
+> **注意：** 必须指定样式中的宽度和高度，否则无法工作。
```html
-<template>
- <div>
- <image style="width: 560px;height: 560px;" src="https://img.alicdn.com/tps/TB1z.55OFXXXXcLXXXXXXXXXXXX-560-560.jpg"></image>
- </div>
-</template>
+<image style="width:500px;height:500px" src="https://vuejs.org/images/logo.png"></image>
```
-[体验一下](http://dotwe.org/vue/1d6145d98cbdb8c66c69b4d4dcd2744d)
+参见[示例](http://dotwe.org/vue/00f4b68b3a86360df1f38728fd0b4a1f)。
-## 子组件
+## 属性
-`<image>` 组件不支持任何子组件，因此不要尝试在 `<image>` 组件中添加任何组件。如果需要实现 `background-image` 的效果，可以使用 `<image>` 组件和 `position` 定位来现实，如下面代码。
+| 属性名 | 类型 | 值 | 默认值 |
+| ------------- | ------ | -------------------------- | ------- |
+| `placeholder` | String | {URL / Base64} | - |
+| `resize` | String | conver / contain / stretch | stretch |
+| `src` | String | {URL / Base64 } | - |
-```html
-<template>
- <div>
- <image style="width:750px; height:750px;" src="https://img.alicdn.com/tps/TB1z.55OFXXXXcLXXXXXXXXXXXX-560-560.jpg"></image>
- <div class="title">
- <text style="font-size:50px; color: #ff0000">你好，image</text>
- </div>
- </div>
-</template>
-<style>
- .title{
- position:absolute;
- top:50;
- left:10;
- }
-</style>
-```
+> **注意：**您可以指定一个相对 bundle URL 的相对路径，相对路径将被重写为绝对资源路径(本地或远程)。参见: [资源路径](../../guide/advanced/path.html)。
-[体验一下](http://dotwe.org/vue/0a81d27b5dbc68ea3bf5f9fd56c882e8)
+### `placeholder`
-## 特性
+占位图的 URL，当由 `src` 表示的图片下载完成并展示后将被删除。 ([示例](http://dotwe.org/vue/712ef102fc5e073b6c7e3b701545681c))
-`<image>` 组件，包含 `src` 和 `resize` 两个重要特性。
+### `resize`
-- `src {string}`：定义图片链接，目前图片暂不支持本地图片。
-- `resize {string}`：可以控制图片的拉伸状态，值行为和 W3C 标准一致。
+
- 可选值为：
+- `contain`: 缩放图片以完全装入`<image>`区域，可能背景区部分空白。 ([示例](http://dotwe.org/vue/89be94dcd1fec73b77246ec46c678914))
- - `stretch`：默认值，指定图片按照容器拉伸，有可能使图片产生形变。
- - `cover`：指定图片可以被调整到容器，以使图片完全覆盖背景区域，图片有可能被剪裁。
- - `contain`：指定可以不用考虑容器的大小，把图像扩展至最大尺寸，以使其宽度和高度完全适应内容区域。
+- `cover`: 缩放图片以完全覆盖`<image>`区域，可能图片部分看不见。 ([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
- 例子：
+- `stretch`: `默认值`. 按照`<image>`区域的宽高比例缩放图片。([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
- 
+ 参见: [`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size).
-- `placeholder`: <span class="api-version">v0.9+</span> <string> 当源图片下载中时显示一张占位图。
+### `src`
- [体验一下](http://dotwe.org/vue/18e71ab3484bb6751ad77ff7d5195404)
+要显示图片的 URL，该属性是 `<image>` 组件的强制属性。
-## 样式
+#### 支持的图片格式
-- 通用样式：支持所有通用样式
+Weex没有提供必须支持的图片格式列表，主要依赖于你正在使用的图片 adapter 或者 handler。例如，如果你使用 [SDWebImage](https://github.com/rs/SDWebImage#supported-image-formats) 作为iOS上的图片 handler，你可以使用像 JPEG、PNG、GIF、WebP 等图片格式。
- - 盒模型
- - `flexbox` 布局
- - `position`
- - `opacity`
- - `background-color`
+## Component 方法
- 查看 [组件通用样式](../common-style.html)
+### `save` <span class="api-version">v0.16.0+</span>
-## 事件
+保存图片内容到本地文件或相册，此操作可能需要设备相关权限。
+
+**参数**:
+
+- `callback`: {Function} 在图片被写入到本地文件或相册后调用的函数。
+ - `success`: {Boolean} 标记图片是否已写入完成。
+ - `errorDesc`: {String} 如果图像没有成功写入，该字符串包含了详细的错误描述。
--- End diff --
ditto
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147040772
--- 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.
--- End diff --
to the local device or photo album
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147026442
--- 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>`.
--- End diff --
as download, cache, decompression features are complicated and some open source tools like SDWebImage handles it well, ...
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147041308
--- 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>`:
```html
-<template>
- <scroller class="wrapper" >
- <div class="page-head" >
- <image class="title-bg" resize="cover" src="https://img.alicdn.com/tps/TB1dX5NOFXXXXc6XFXXXXXXXXXX-750-202.png"></image>
- <div class="title-box">
- <text class="title">Alan Mathison Turing</text>
- </div>
- </div>
- <div class="article">
- <text class="paragraph">Alan Mathison Turing ( 23 June 1912 – 7 June 1954) was an English computer scientist, mathematician, logician, cryptanalyst and theoretical biologist. He was highly influential in the development of theoretical computer science, providing a formalisation of the concepts of algorithm and computation with the Turing machine, which can be considered a model of a general purpose computer.Turing is widely considered to be the father of theoretical computer science and artificial intelligence.</text>
- <text class="paragraph">During the Second World War, Turing worked for the Government Code and Cypher School (GC&CS) at Bletchley Park, Britain's codebreaking centre. For a time he led Hut 8, the section responsible for German naval cryptanalysis. He devised a number of techniques for speeding the breaking of German ciphers, including improvements to the pre-war Polish bombe method, an electromechanical machine that could find settings for the Enigma machine. Turing played a pivotal role in cracking intercepted coded messages that enabled the Allies to defeat the Nazis in many crucial engagements, including the Battle of the Atlantic; it has been estimated that this work shortened the war in Europe by more than two years and saved over fourteen million lives.</text>
- <text class="paragraph">After the war, he worked at the National Physical Laboratory, where he designed the ACE, among the first designs for a stored-program computer. In 1948 Turing joined Max Newman's Computing Machine Laboratory at the Victoria University of Manchester, where he helped develop the Manchester computers and became interested in mathematical biology. He wrote a paper on the chemical basis of morphogenesis, and predicted oscillating chemical reactions such as the Belousov–Zhabotinsky reaction, first observed in the 1960s.</text>
- <text class="paragraph">Turing was prosecuted in 1952 for homosexual acts, when by the Labouchere Amendment, "gross indecency" was still criminal in the UK. He accepted chemical castration treatment, with DES, as an alternative to prison. Turing died in 1954, 16 days before his 42nd birthday, from cyanide poisoning. An inquest determined his death as suicide, but it has been noted that the known evidence is also consistent with accidental poisoning. In 2009, following an Internet campaign, British Prime Minister Gordon Brown made an official public apology on behalf of the British government for "the appalling way he was treated." Queen Elizabeth II granted him a posthumous pardon in 2013.</text>
- </div>
- </scroller>
-</template>
-
-<style>
- .page-head {
- width: 750px;
- height: 200px;
- }
- .title-bg {
- width: 750px;
- height: 200px;
- }
- .title-box {
- width: 750px;
- height: 200px;
- justify-content: center;
- align-items: center;
- position: absolute;
- top: 0;
- right: 0;
- bottom: 0;
- left: 0;
- }
- .title {
- color: #ffffff;
- font-size: 32px;
- font-weight: bold;
- }
- .article {
- padding: 20px;
+<image ref="poster" src="path/to/image.png"></image>
+```
+
+Get the component reference and use the `save` method:
+
+```js
+const $image = this.$refs.poster
+$image.save(result => {
+ if (result.success) {
+ // TODO
+ } else {
+ console.log(result.errorDesc)
}
- .paragraph{
- margin-bottom: 15px;
+})
+```
+
+See the [complete example](http://dotwe.org/vue/fadcd44a7031943ff0feaaf1895df414).
+
+## Events
+
+Support **[common events](../../wiki/common-events.html)**.
+
+### `load`
+
+`load` event handler will be called when the image specified by `src` is loaded.
--- End diff --
when the image is loaded.
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147040745
--- 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.
--- End diff --
has been saved
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by cxfeng1 <gi...@git.apache.org>.
Github user cxfeng1 commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147051068
--- Diff: source/cn/references/components/image.md ---
@@ -6,181 +6,148 @@ order: 8.02
version: 2.1
---
-# <image>
+`<image>` 用于在界面中显示单个图片。
-`<image>` 组件用于渲染图片，并且它不能包含任何子组件。新版 Vue 2.0 中**不支持**用 `<img>` 作简写。
+> **注意：**在HTML中通常使用的 `<img>` 标签在 Weex 中不支持，你应该使用`<image>` 。
-需要注意的是，需要明确指定 `width` 和 `height`，否则图片无法显示。
+> **注意：** Weex 没有内置的图片下载器，因为相关的下载、缓存、解码机制非常复杂，一些开源的工具如 [SDWebImage](https://github.com/rs/SDWebImage) 已经处理得很好， 所以在使用 `<image>` 之前，请在 native 侧先接入相应的 adapter 或者 handler。
+>
+> 参见: [Android adapter](../android-apis.html#Adapter) 和 [iOS handler](../ios-apis.html#Handler-like-Android-Adapter)。
-简单例子：
+## 基本用法
+
+> **注意：** 必须指定样式中的宽度和高度，否则无法工作。
```html
-<template>
- <div>
- <image style="width: 560px;height: 560px;" src="https://img.alicdn.com/tps/TB1z.55OFXXXXcLXXXXXXXXXXXX-560-560.jpg"></image>
- </div>
-</template>
+<image style="width:500px;height:500px" src="https://vuejs.org/images/logo.png"></image>
```
-[体验一下](http://dotwe.org/vue/1d6145d98cbdb8c66c69b4d4dcd2744d)
+参见[示例](http://dotwe.org/vue/00f4b68b3a86360df1f38728fd0b4a1f)。
-## 子组件
+## 属性
-`<image>` 组件不支持任何子组件，因此不要尝试在 `<image>` 组件中添加任何组件。如果需要实现 `background-image` 的效果，可以使用 `<image>` 组件和 `position` 定位来现实，如下面代码。
+| 属性名 | 类型 | 值 | 默认值 |
+| ------------- | ------ | -------------------------- | ------- |
+| `placeholder` | String | {URL / Base64} | - |
+| `resize` | String | conver / contain / stretch | stretch |
+| `src` | String | {URL / Base64 } | - |
-```html
-<template>
- <div>
- <image style="width:750px; height:750px;" src="https://img.alicdn.com/tps/TB1z.55OFXXXXcLXXXXXXXXXXXX-560-560.jpg"></image>
- <div class="title">
- <text style="font-size:50px; color: #ff0000">你好，image</text>
- </div>
- </div>
-</template>
-<style>
- .title{
- position:absolute;
- top:50;
- left:10;
- }
-</style>
-```
+> **注意：**您可以指定一个相对 bundle URL 的相对路径，相对路径将被重写为绝对资源路径(本地或远程)。参见: [资源路径](../../guide/advanced/path.html)。
-[体验一下](http://dotwe.org/vue/0a81d27b5dbc68ea3bf5f9fd56c882e8)
+### `placeholder`
-## 特性
+占位图的 URL，当由 `src` 表示的图片下载完成并展示后将被删除。 ([示例](http://dotwe.org/vue/712ef102fc5e073b6c7e3b701545681c))
-`<image>` 组件，包含 `src` 和 `resize` 两个重要特性。
+### `resize`
-- `src {string}`：定义图片链接，目前图片暂不支持本地图片。
-- `resize {string}`：可以控制图片的拉伸状态，值行为和 W3C 标准一致。
+
- 可选值为：
+- `contain`: 缩放图片以完全装入`<image>`区域，可能背景区部分空白。 ([示例](http://dotwe.org/vue/89be94dcd1fec73b77246ec46c678914))
- - `stretch`：默认值，指定图片按照容器拉伸，有可能使图片产生形变。
- - `cover`：指定图片可以被调整到容器，以使图片完全覆盖背景区域，图片有可能被剪裁。
- - `contain`：指定可以不用考虑容器的大小，把图像扩展至最大尺寸，以使其宽度和高度完全适应内容区域。
+- `cover`: 缩放图片以完全覆盖`<image>`区域，可能图片部分看不见。 ([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
- 例子：
+- `stretch`: `默认值`. 按照`<image>`区域的宽高比例缩放图片。([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
- 
+ 参见: [`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size).
-- `placeholder`: <span class="api-version">v0.9+</span> <string> 当源图片下载中时显示一张占位图。
+### `src`
- [体验一下](http://dotwe.org/vue/18e71ab3484bb6751ad77ff7d5195404)
+要显示图片的 URL，该属性是 `<image>` 组件的强制属性。
-## 样式
+#### 支持的图片格式
-- 通用样式：支持所有通用样式
+Weex没有提供必须支持的图片格式列表，主要依赖于你正在使用的图片 adapter 或者 handler。例如，如果你使用 [SDWebImage](https://github.com/rs/SDWebImage#supported-image-formats) 作为iOS上的图片 handler，你可以使用像 JPEG、PNG、GIF、WebP 等图片格式。
- - 盒模型
- - `flexbox` 布局
- - `position`
- - `opacity`
- - `background-color`
+## Component 方法
- 查看 [组件通用样式](../common-style.html)
+### `save` <span class="api-version">v0.16.0+</span>
-## 事件
+保存图片内容到本地文件或相册，此操作可能需要设备相关权限。
+
+**参数**:
+
+- `callback`: {Function} 在图片被写入到本地文件或相册后调用的函数。
+ - `success`: {Boolean} 标记图片是否已写入完成。
+ - `errorDesc`: {String} 如果图像没有成功写入，该字符串包含了详细的错误描述。
--- End diff --
@CYJB that's a good idea😆
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147040423
--- 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.
--- End diff --
spaces
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147041521
--- 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>`:
```html
-<template>
- <scroller class="wrapper" >
- <div class="page-head" >
- <image class="title-bg" resize="cover" src="https://img.alicdn.com/tps/TB1dX5NOFXXXXc6XFXXXXXXXXXX-750-202.png"></image>
- <div class="title-box">
- <text class="title">Alan Mathison Turing</text>
- </div>
- </div>
- <div class="article">
- <text class="paragraph">Alan Mathison Turing ( 23 June 1912 – 7 June 1954) was an English computer scientist, mathematician, logician, cryptanalyst and theoretical biologist. He was highly influential in the development of theoretical computer science, providing a formalisation of the concepts of algorithm and computation with the Turing machine, which can be considered a model of a general purpose computer.Turing is widely considered to be the father of theoretical computer science and artificial intelligence.</text>
- <text class="paragraph">During the Second World War, Turing worked for the Government Code and Cypher School (GC&CS) at Bletchley Park, Britain's codebreaking centre. For a time he led Hut 8, the section responsible for German naval cryptanalysis. He devised a number of techniques for speeding the breaking of German ciphers, including improvements to the pre-war Polish bombe method, an electromechanical machine that could find settings for the Enigma machine. Turing played a pivotal role in cracking intercepted coded messages that enabled the Allies to defeat the Nazis in many crucial engagements, including the Battle of the Atlantic; it has been estimated that this work shortened the war in Europe by more than two years and saved over fourteen million lives.</text>
- <text class="paragraph">After the war, he worked at the National Physical Laboratory, where he designed the ACE, among the first designs for a stored-program computer. In 1948 Turing joined Max Newman's Computing Machine Laboratory at the Victoria University of Manchester, where he helped develop the Manchester computers and became interested in mathematical biology. He wrote a paper on the chemical basis of morphogenesis, and predicted oscillating chemical reactions such as the Belousov–Zhabotinsky reaction, first observed in the 1960s.</text>
- <text class="paragraph">Turing was prosecuted in 1952 for homosexual acts, when by the Labouchere Amendment, "gross indecency" was still criminal in the UK. He accepted chemical castration treatment, with DES, as an alternative to prison. Turing died in 1954, 16 days before his 42nd birthday, from cyanide poisoning. An inquest determined his death as suicide, but it has been noted that the known evidence is also consistent with accidental poisoning. In 2009, following an Internet campaign, British Prime Minister Gordon Brown made an official public apology on behalf of the British government for "the appalling way he was treated." Queen Elizabeth II granted him a posthumous pardon in 2013.</text>
- </div>
- </scroller>
-</template>
-
-<style>
- .page-head {
- width: 750px;
- height: 200px;
- }
- .title-bg {
- width: 750px;
- height: 200px;
- }
- .title-box {
- width: 750px;
- height: 200px;
- justify-content: center;
- align-items: center;
- position: absolute;
- top: 0;
- right: 0;
- bottom: 0;
- left: 0;
- }
- .title {
- color: #ffffff;
- font-size: 32px;
- font-weight: bold;
- }
- .article {
- padding: 20px;
+<image ref="poster" src="path/to/image.png"></image>
+```
+
+Get the component reference and use the `save` method:
+
+```js
+const $image = this.$refs.poster
+$image.save(result => {
+ if (result.success) {
+ // TODO
+ } else {
+ console.log(result.errorDesc)
}
- .paragraph{
- margin-bottom: 15px;
+})
+```
+
+See the [complete example](http://dotwe.org/vue/fadcd44a7031943ff0feaaf1895df414).
--- End diff --
Complete example goes [here](http://dotwe.org/vue/fadcd44a7031943ff0feaaf1895df414).
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147027991
--- 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)
--- End diff --
placeholder image... and will be replaced as soon as the 'src' image gets loaded.
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147028591
--- 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))
--- End diff --
without stretching it.
---
[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...
Posted by jondong <gi...@git.apache.org>.
Github user jondong commented on a diff in the pull request:
https://github.com/apache/incubator-weex-site/pull/4#discussion_r147026535
--- 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.
--- End diff --
the style attributes of ...
---