You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@weex.apache.org by zs...@apache.org on 2018/12/14 05:54:35 UTC
[incubator-weex-site] branch draft updated: Update image.md
This is an automated email from the ASF dual-hosted git repository.
zshshr pushed a commit to branch draft
in repository https://gitbox.apache.org/repos/asf/incubator-weex-site.git
The following commit(s) were added to refs/heads/draft by this push:
new 5a2be4c Update image.md
5a2be4c is described below
commit 5a2be4cda047396a9b7183cb7b2b6bb4759c479d
Author: zshshr <zh...@gmail.com>
AuthorDate: Fri Dec 14 13:54:32 2018 +0800
Update image.md
---
docs/docs/components/image.md | 214 ++++++++++++++++++++++++++----------------
1 file changed, 135 insertions(+), 79 deletions(-)
diff --git a/docs/docs/components/image.md b/docs/docs/components/image.md
index d38d23d..7b688ab 100644
--- a/docs/docs/components/image.md
+++ b/docs/docs/components/image.md
@@ -1,74 +1,90 @@
-# <image>
+---
+title: <image>
+type: references
+group: Build-in Components
+order: 8.04
+version: 2.1
+---
-`<image>` 用于在界面中显示单个图片。
+`<image>` is used to display a single image in your interface.
-``` vue
+> **Note:** `<img>` element which is usually used in HTML is not supported in Weex, you should use `<image>` instead.
+
+> **Note:** Weex doesn't have built-in image downloader, as download, cache, decompression features are complicated and some open source tools like [SDWebImage](https://github.com/rs/SDWebImage) handles it well, so please add native image adapter/handler before using `<image>`.
+>
+> See also: [Android adapter](../android-apis.html#Adapter) and [iOS handler](../ios-apis.html#Handler-like-Android-Adapter).
+
+## Basic Usage
+
+> **Note:** the style attributes of `width` and `height` must be specified, otherwise it won't work.
+
+```html
<image style="width:500px;height:500px" src="https://vuejs.org/images/logo.png"></image>
```
-::: warning 注意
-* 必须指定样式中的宽度和高度，否则无法工作。
-* 不支持内嵌子组件。
-* 图片地址，建议以CDN的形式引入，但是也可以指定为一个相对路径，参考: [资源路径](http://weex.apache.org/cn/guide/advanced/path.html) 。
-* Weex 没有内置的图片下载器，因为相关的下载、缓存、解码机制非常复杂，一些开源的图片库已经处理得很好， 所以在使用 `<image>` 之前，请在客户端先接入相应的图片处理工具，参考: [Android](http://weex.apache.org/cn/references/android-apis.html#Adapter) 和 [iOS](http://weex.apache.org/cn/references/ios-apis.html#Handler-like-Android-Adapter)。
-* 支持的图片格式——Weex 没有提供必须支持的图片格式列表，主要依赖于你正在使用的图片处理工具。
-:::
-
-## 属性
-<table>
- <thead><tr><th>属性名</th><th style="width: 40%">说明</th><th>类型</th><th style="width: 33%">值</th><th style="width: 10%">默认值</th></tr></thead>
- <tbody>
- <tr><td>src</td><td>要显示图片的 URL</td><td>string</td><td>{ URL / Base64 }</td><td>-</td></tr>
- <tr><td>placeholder</td><td>占位图的 URL，当由 <code>src</code> 表示的图片下载完成并展示后将被删除</td><td>string</td><td>{ URL / Base64 }</td><td>-</td></tr>
- <tr><td>resize</td><td>说明见下文</td><td>string</td><td>cover / contain / stretch</td><td>stretch</td></tr>
- </tbody>
-</table>
-
-### resize
-
-<div style="text-align: center"><img src="https://img.alicdn.com/tfs/TB1Lik8nVzqK1RjSZFCXXbbxVXa-1620-538.png" width="700"></div>
-
-- contain：缩放图片以完全装入 `<image>` 区域，可能背景区部分空白。 ([示例](http://dotwe.org/vue/89be94dcd1fec73b77246ec46c678914))
-- cover：缩放图片以完全覆盖 `<image>` 区域，可能图片部分看不见。 ([示例](http://dotwe.org/vue/bcc12eb2321c1416fee518735646e059))
-- stretch：`默认值`，按照 `<image>` 区域的宽高比例缩放图片。([示例](http://dotwe.org/vue/dcf82a112bd49139685753ba20909a20))
-
-## 事件
-`<image>` 组件除了支持 [通用事件](/guide/common-events.html)外，还支持 `load事件`：当加载完 `src` 指定的图片时，`load` 事件将被触发。
-
-`load` 事件参数 `event`：
-* success：`{ Boolean }`，标记图片是否成功加载
-* size：`{ Object }`，加载的图片大小对象
- * naturalWidth: `{ Number }` 图片宽度，如果图片加载失败则为0
- * naturalHeight: `{ Number }` 图片高度，如果图片加载失败则为0
-```vue
-<template>
- <div>
- <image @load="onload" style="width:300px;height:300px;" src="https://gw.alicdn.com/tps/TB1bEMYKXXXXXaLaXXXXXXXXXXX-360-388.png"></image>
- </div>
-</template>
-<script>
- module.exports = {
- methods : {
- onload : function(e) {
- if (e.success) {
- console.log(e.size)
- }
- }
- }
- }
-</script>
-```
-[参考示例](http://dotwe.org/vue/4996b4d1e055168e0cb5cbf817b42249)
-<IPhoneImg imgSrc="https://img.alicdn.com/tfs/TB1lRQ4n9zqK1RjSZFLXXcn2XXa-544-960.gif" />
-## 组件方法
-**`save`** <Badge text="0.16.0+" type="warn" vertical="middle"/>
-保存图片内容到本地文件或相册，此操作可能需要设备相关权限。
+See the [example](http://dotwe.org/vue/00f4b68b3a86360df1f38728fd0b4a1f).
+
+ ## Attributes
+
+| Attribute | Type | Value | Default Value |
+| ------------- | ------ | -------------------------- | ------------- |
+| `placeholder` | String | {URL / Base64} | - |
+| `resize` | String | cover / contain / stretch | stretch |
+| `src` | String | {URL / Base64 } | - |
+
+ > **Note:** you can specify a relative URL for `src` and `placeholder`, relative URL will be rewritten to the to the actual resource URL (local or remote). See also: [Path](../../guide/advanced/path.html).
+
+ ### `placeholder`
+
+A URL value for placeholder image. It will be displayed when the image view is empty and will be replaced as soon as the 'src' image gets loaded.[(Example)](http://dotwe.org/vue/712ef102fc5e073b6c7e3b701545681c)
+
+ ### `resize`
+
+
+
+- `contain`: Scales the image as large as possible without cropping or stretching it. Remaining area within bounds is transparent ([Example](http://dotwe.org/vue/89be94dcd1fec73b77246ec46c678914))
+
+
+- `cover`: Scales the image as large as possible without stretching it. If the proportions of the image differ from the element, it is cropped either vertically or horizontally so that no empty space remains. ([Example](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
+
+- `stretch`: `Default value`. Scales the content to fit the size of the element itself by changing the aspect ratio of the image if necessary. ([Example](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
+
+See also: [`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size).
+
+### `src`
+
+The URL of the image to display. This attribute is mandatory for the `<image>` component.
+
+#### Supported Image Formats
+
+Weex doesn't give a list of image formats that must be supported, it mainly relies on the image adapter/handler you are using. For example, if you are using [SDWebImage](https://github.com/rs/SDWebImage#supported-image-formats) as the image adapter on iOS, you can use image formats like JPEG, PNG, GIF, WebP, etc.
+
+## Component Methods
+
+### `save` <span class="api-version">v0.16.0+</span>
+
+Save `<image>` content to the local device or photo album, this operation may require device permission.
+
+**Parameters**:
+
+* `callback`: {Function} A function which is called after the image has been saved to the local device or photo album. Callback parameters:
+ * `result`: {Object} Callback result whose properties are:
+ * `success`: {Boolean} A flag indicating whether the image has been saved completed.
+ * `errorDesc`: {String} A string containing the description of the error if image is not written successfully.
-使用方法：在 `<image>` 标签上增加 `ref` 属性 (Vue.js [Child Component Refs](https://vuejs.org/v2/guide/docss-edge-cases.html#Accessing-Child-Component-Instances-amp-Child-Elements))
-```vue
+**Return value**: null
+
+> **Note**: You must add `NSPhotoLibraryAddUsageDescription` and `NSPhotoLibraryAddUsageDescription` (iOS 11) to enable the access permission of the iOS photo album. See also: [Cocoa Keys](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html).
+
+#### Use `save` Method
+
+Add `ref` attribute (Vue.js *[Child Component Refs](https://vuejs.org/v2/guide/components.html#Child-Component-Refs)*) on `<image>`:
+
+```html
<image ref="poster" src="path/to/image.png"></image>
```
-获取组件引用并使用 `save` 方法，查看 [完整示例](http://dotwe.org/vue/204cafec46aa8e23485a94cfb2c39cfa):
+
+Get the component reference and use the `save` method:
```js
const $image = this.$refs.poster
@@ -82,19 +98,59 @@ $image.save(result => {
})
```
-参数说明：
-* callback: `{ Function }` 在图片被写入到本地文件或相册后的回调，回调参数
- * result: `{ Object }` 回调结果对象，属性列表
- * success: `{ Boolean }` 标记图片是否已写入完成
- * errorDesc: `{ String }` 如果图像没有成功写入，该字符串包含了详细的错误描述
-
-::: warning 注意
-必须加入 NSPhotoLibraryAddUsageDescription (iOS 11) 以获得访问 iOS 系统相册权限。参考：[Cocoa Keys](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html)。
-:::
-
-## Demo
-[图片 `contain` 属性](http://dotwe.org/vue/11da331116b74515a4d74ae9707f85a9)
-[图片 `cover` 属性](http://dotwe.org/vue/bcc12eb2321c1416fee518735646e059)
-[图片 `stretch` 属性](http://dotwe.org/vue/dcf82a112bd49139685753ba20909a20)
-[组件方法 `save` 示例](http://dotwe.org/vue/204cafec46aa8e23485a94cfb2c39cfa)
-[`load` 事件示例](http://dotwe.org/vue/213ef53ec275cbd550d9ebea9f81acf0)
+Complete example goes [here](http://dotwe.org/vue/fadcd44a7031943ff0feaaf1895df414).
+
+## Events
+
+Support **[common events](../../wiki/common-events.html)**.
+
+### `load`
+
+`load` event handler will be called when the image is loaded.
+
+**Event object**:
+
+- `success`: {Boolean} It shows that whether the image is loaded successfully.
+- `size`: {Object} The loaded image size whose properties are:
+ - `naturalWidth`: {Number} The intrinsic width of image displayed on device, it will be zero if the specified image cannot be loaded correctly.
+ - `naturalHeight`: {Number} the intrinsic height of image displayed on device, it will be zero if the specified image cannot be loaded correctly.
+
+#### Handle `load` Event
+
+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) {
+ // Do something to hanlde success
+ }
+ }
+ }
+}
+```
+
+Complete example goes [here](http://dotwe.org/vue/94de9307517240dec066d2ea57fe54a0).
+
+## Styles
+
+Support **[common styles](../../wiki/common-styles.html)**.
+
+## Usage Notes
+
+- Add image adapter/handler before using `<image>`
+- The `width` and `height` in the styles of `<image>` must be specified.
+- `<image>` can not have any nested child component.
+
+## Examples
+
+- [Base64 example](http://dotwe.org/vue/ba477790c85ea12bbf7ad3a5f0885b5c)
+- [Multi-layer images example](http://dotwe.org/vue/c44359c0f200abc1f66504b88587e4f6)
+- [Lazy load image example](http://dotwe.org/vue/b0b146e4e6fa4890f800e18cb950f803)