[GitHub] incubator-weex-site pull request #4: [WEEX-86][doc] Update image component's...

Wed, 25 Oct 2017 21:06:09 -0700 

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 
标准一致。
    +![image resize 
property](../../../references/images/image-resize-property.png)
     
    -  可选值为：
    +- `contain`: 缩放图片以完全装å…
¥`<image>`区域，可能背景区部分空白。 
([示例](http://dotwe.org/vue/89be94dcd1fec73b77246ec46c678914))
     
    -  - `stretch`：默认值，指定图片按ç…
§å®¹å™¨æ‹‰ä¼¸ï¼Œæœ‰å¯èƒ½ä½¿å›¾ç‰‡äº§ç”Ÿå½¢å˜ã€‚
    -  - `cover`：指定图片可以被调整到容器，以使图片完å…
¨è¦†ç›–背景区域，图片有可能被剪裁。
    -  - 
`contain`：指定可以不用考虑容器的大小，把图像扩展至最大尺寸，以使å
…¶å®½åº¦å’Œé«˜åº¦å®Œå…¨é€‚应内容区域。
    +- `cover`: 缩放图片以完å…
¨è¦†ç›–`<image>`区域，可能图片部分看不见。 
([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
     
    -  例子：
    +- `stretch`: `默认值`. 按ç…
§`<image>`区域的宽高比例缩放图片。([示例](http://dotwe.org/vue/f38e311d2e6b2af87f0a65a8f37d9490))
     
    -  ![mobile_preview](../images/image_1.jpg)
    +  参见: 
[`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size).
     
    -- `placeholder`: <span class="api-version">v0.9+</span> &lt;string&gt; 
当源图片下载中时显示一张占位图。
    +### `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.


---

Reply via email to