Weex provide the ability of loading custom through DOM.addRule. Developers can load iconfont and custom font by specifying the font-family.
Developers may use the following code snippet to load their font:
``` html
``` html
<template>
<template>
<view>
<view>
...
@@ -57,31 +59,31 @@
...
@@ -57,31 +59,31 @@
**addRule(type, contentObject)**
**addRule(type, contentObject)**
- @fontFace 协议名称，不可修改。
- @fontFace You should not change this as this is the name of the font rule
- @fontFamily ```font-family```的名称。
- @fontFamily You should provide the name of your font-family there, the valid name should be a string.
- @src 字体地址，url('') 是保留字段，其参数如下:
- @src The src of your custom font, and url('') is reserved for protocol reason, the supported parameters are listed below:
-http. 从HTTP请求加载, e.g. ```url('http://at.alicdn.com/t/font_1469606063_76593.ttf')```
-`http`. Read from http, e.g. `url('http://at.alicdn.com/t/font_1469606063_76593.ttf')`
- https. 从HTTPS请求加载, e.g. ```url('https://at.alicdn.com/t/font_1469606063_76593.ttf')```
-`https`. Read from https, e.g. `url('https://at.alicdn.com/t/font_1469606063_76593.ttf')`
- local, Android ONLY. 从assets目录读取, e.g. url('local://foo.ttf'), foo.ttf 是文件名在你的assets目录中.
-`local`, *Android ONLY*. Read from assets directory e.g. `url('local://foo.ttf')`, the **foo.ttf** is in your android assets directory.
- file. 从本地文件读取, e.g. ```url('file://storage/emulated/0/Android/data/com.alibaba.weex/cache/http:__at.alicdn.com_t_font_1469606063_76593.ttf')```
-`file`. Read from a local file, e.g. `url('file://storage/emulated/0/Android/data/com.alibaba.weex/cache/http:__at.alicdncom_t_font_1469606063_76593.ttf')`
- data. 从base64读取, e.g. ```url('data:font/truetype;charset=utf-8;base64,AAEAAAALAIAAAwAwR1NVQrD+....')```, 上述data字段不全。
-`data`. Read from a base64 data source, e.g. `url('data:font/truetype;charset=utf-8;base64,AAEAAAALAIAAAwAwR1NVQrD+....')`, the above data field is only a part of the actual data.
> You can name `fontFamily` in `addRule` as you wish in your page, any string is OK. But this is not the real font-family name of the font file. The real name or system name for the font is stored in binrary data of ttf file. You must ensure that the real font-family name of font file is unique. Or your font may not be successfully registered to device and your text may display as a '?'.
> Specially, if you are using http://www.iconfont.cn/ to build your iconfont. Make sure that you set a unique enough font-family name for your font in project settings.
> 调用addRule 在 beforeCreate 中是被推荐的。
> Calling `addRule` in `beforeCreate` is recommended.
让页面滚动到 ref 对应的组件，这个 API 只能用于可滚动组件的子节点，例如 ```<scroller>```，```<list>```, ```<waterfall>``` 等可滚动组件中。
Scroll the scrollable component to the referenced component. This API should only be used in the children components of a scrollable component, such as in a `<scroller>` or `<list>` component.
**scrollToElement(ref, options)**
**scrollToElement(ref, options)**
- @ref，要滚动到的那个节点。
- @ref, the referenced component who is meant to scroll into the view.
- @options
- @options,
-offset，一个到其可见位置的偏移距离，默认是 0。
-`offset`, an space on top of the ref component, which is also scrolling down to the visual viewport. Default is `0`.
-animated，是否需要附带滚动动画，默认是 true。
-`animated`, a boolean indicates whether a scroll animation should be played. If set to false, the ref component will jump into the view without any transition animation. Default is true.
``` html
``` html
<template>
<template>
...
@@ -175,13 +177,13 @@
...
@@ -175,13 +177,13 @@
### getComponentRect
### getComponentRect
获取某个元素 View 的外框。
You can get the bounding rect of the referenced component using this API.
**getComponentRect(ref, callback)**
**getComponentRect(ref, callback)**
- @ref，要获取外框的那个节点。
- @ref, the referenced component.
- @callback，异步方法，通过回调返回信息。
- @callback, the callback function after executing this action.
> If you want to get the bounding rect of outside viewport of the weex container, you can specify the `ref` as a literal string `'viewport'`, like `getComponentRect('viewport', callback)`.
The `animation` module is used to perform animation on components.
JS-Animation can perform a series of simple transformations (position, size, rotation, background color, and opacity) on the component with Javascript.
- @ref, the element that will be animated. For example, if the value of `ref` for an element is `test`, you can start an animation with `this.$refs.test`.
- @options，动画参数。
- @options, animation properties such as keys, duration.
下表列出了options所有合法的参数：
下表列出了options所有合法的参数：
|可选值 |描述 |
|Property |Describe |
|-- |-- |
|-- |-- |
|styles |设置不同样式过渡效果的键值对|
|styles |specifies the names and values of styles to which a transition effect should be applied.|
|timingFunction |describes how the intermediate values are calculated for the CSS properties being affected by the animation effect. default value is `linear` |
- @callback, callback is a function called after the completion of animation. In iOS platform, you can use function to get information of animation execution.
-On iOS platform you can get animation's message about completion, there are two types of parameters with `result`, is `Success`and `Fail`, Android can not support until now.
#### The supported styles is listed below, and some component may support custom style, which you can check in the component's doc. Except for this, other styles are not supported.
The term "box model" is used when talking about design and layout. The box model is essentially a box that wraps around every HTML element. It consists of margins, borders, paddings, and the actual content.
`padding` specifies the space between element content and the element border. One can use shorthand for four edges or specify the padding for one edge:
|可选值 |描述 |
|Property |Describe |
|-- |-- |
|-- |-- |
|padding {length} |上、右、下、左四边内边距，默认值 0 |
|padding {length} |padding for four edges, default value 0 |
|padding-left {length} |左内边距，默认值 0 |
|padding-left {length} |default value 0 |
|padding-right {length} |右内边距，默认值 0 |
|padding-right {length} |default value 0 |
|padding-top {length} |上内边距，默认值 0 |
|padding-top {length} |default value 0 |
|padding-bottom {length}|下内边距，默认值 0 |
|padding-bottom {length}|default value 0 |
##### 边框
##### border
```border-style``` 设定边框样式，如果四个方向的边框样式不同，可分别设置：
The `border-style` CSS property is a shorthand property that sets the line style for all four sides of an element's border. One can use shorthand for four edges or specify the style for one edge:
The border-width shorthand CSS property sets the widths of all four sides of an element's border. One can use shorthand for four edges or specify the width for one edge:
|可选值 |描述 |
|Property |Describe |
|-- |-- |
|-- |-- |
|border-width {length} |非负值, 默认值 0 |
|border-width {length} |non-negative, default value 0 |
|border-left-width {length} |非负值, 默认值 0 |
|border-left-width {length} |non-negative, default value 0 |
|border-top-width {length} |非负值, 默认值 0 |
|border-top-width {length} |non-negative, default value 0 |
|border-right-width {length} |非负值, 默认值 0 |
|border-right-width {length} |non-negative, default value 0 |
|border-bottom-width {length} |非负值, 默认值 0 |
|border-bottom-width {length} |non-negative, default value 0 |
The border-color shorthand CSS property sets the color of all sides of an element's border. One can use shorthand for four edges or specify the color for one edge:
|可选值 |描述 |
|Property |Describe |
|-- |-- |
|-- |-- |
|border-color {color} |默认值 ```#000000``` |
|border-color {color} |default value #000000 |
|border-left-color {color} |默认值 ```#000000``` |
|border-left-color {color} |default value #000000 |
|border-top-color {color} |默认值 ```#000000``` |
|border-top-color {color} |default value #000000 |
|border-right-color {color} |默认值 ```#000000``` |
|border-right-color {color} |default value #000000 |
|border-bottom-color {color}|默认值 ```#000000``` |
|border-bottom-color {color}|default value #000000 |
border-radius property rounds the corners of an element's outer border edge. One can use shorthand for four corners or specify the radius for one corner:
|可选值 |描述 |
|Property |Describe |
|-- |-- |
|-- |-- |
|border-radius {length} |非负值, 默认值 0 |
|border-radius {length} |default value 0 which means the corner is a right angle. |
|border-bottom-left-radius {length} |非负值, 默认值 0 |
|border-bottom-left-radius {length} |non-negative, default value 0 |
|border-bottom-right-radius {length}|非负值, 默认值 0 |
|border-bottom-right-radius {length}|non-negative, default value 0 |
|border-top-left-radius {length} |非负值, 默认值 0 |
|border-top-left-radius {length} |non-negative, default value 0 |
|border-top-right-radius {length} |非负值, 默认值 0 |
|border-top-right-radius {length} |non-negative, default value 0 |
> `border-radius` defines the radius of a quarter ellipse that defines the shape of the corner of the outer border edge by definition, but weex may not render as expected if you need a smooth transition between different `border-radius` or `border-width` on adjoining sides.
Although `overflow:hidden` is default on Android, a view will not clip its children according to `border-radius` unless all the following conditions meet.
Weex box style model based on the CSS flexbox, ensures that elements behave predictably and the page layout can accommodates to different screen sizes and different display devices.
|column-reverse |Behaves the same as column but the main-start and main-end are permuted.|
|row |横排，从左到右排布 |
|row |The flex container's main-axis is horizontal and defined to be the same as direction. The main-start and main-end points are the same as the direction. |
|row-reverse |Behaves the same as row but the main-start and main-end points are permuted |
### flex-wrap
### flex-wrap
决定了 flex 成员项在一行还是多行分布，默认值为```nowrap```
The flex-wrap CSS property sets whether flex items are forced onto one line or can wrap onto multiple lines. The default value is nowrap
|可选值 |描述 |
|Property |Describe |
|-- |-- |
|-- |-- |
|nowrap | 不换行，flex 成员项在一行排布，排布的开始位置由direction指定 |
|nowrap | The flex items are laid out in a single line which may cause the flex container to overflow. The cross-start is either equivalent to start or before depending flex-direction value. This is the default value. |
|wrap | The flex items break into multiple lines. The cross-start is either equivalent to start or before depending flex-direction value and the cross-end is the opposite of the specified cross-start. |
The CSS justify-content property defines how Weex distributes space between and around content items along the main-axis of a flex container. The default value is `flex-start`.
|可选值 |描述 |
|Property |Describe |
|-- |-- |
|-- |-- |
|flex-start |左对齐，所有的 flex 成员项都排列在容器的前部 |
|flex-start |The items are packed flush to each other toward the edge of the alignment container depending on the flex container's main-start side. |
|flex-end |右对齐，则意味着成员项排列在容器的后部 |
|flex-end |The items are packed flush to each other toward the edge of the alignment container depending on the flex container's main-end side. |
|center |居中，即中间对齐，成员项排列在容器中间、两边留白 |
|center |The items are packed flush to each other toward the center of the alignment container along the main axis. |
|space-between |两端对齐，空白均匀地填充到 flex 成员项之间 |
|space-between |The items are evenly distributed within the alignment container along the main axis. The spacing between each pair of adjacent items is the same. The first item is flush with the main-start edge, and the last item is flush with the main-end edge. |
The CSS align-items property sets the align-self value on all direct children as a group. It controls the alignment of items on the cross Axis. The default value is `stretch`.
|可选值 |描述 |
|Property |Describe |
|-- |-- |
|-- |-- |
|stretch |即拉伸高度至 flex 容器的大小 |
|stretch |Flex items are stretched such that the cross-size of the item's margin box is the same as the line while respecting width and height constraints. |
|flex-start |上对齐，所有的成员项排列在容器顶部 |
|flex-start |The cross-start margin edges of the flex items are flushed with the cross-start edge of the line. |
|flex-end |下对齐，所有的成员项排列在容器底部 |
|flex-end |The cross-end margin edges of the flex items are flushed with the cross-end edge of the line. |
|center |中间对齐，所有成员项都垂直地居中显示 |
|center |The flex items' margin boxes are centered within the line on the cross-axis. |
If all of the flex items set flex: 1, they will have equal width or height on direction of flex container's flex-direction. If there are two flex items, with one setting flex: 1, and the other setting flex: 2, the first one will take 1/3 container space, and the second one will take 2/3 container space. If all of flex items don't set flex, they will be aligned depending on the container's justify-content property.
The following code snippet show three div with the same height
If your component is bigger than its parent, it will be partial invisible as Weex on Android only supports `overflow:hidden`.
## Transition
## Transition
```transition```允许 CSS 的属性值在一定的时间区间内平滑地过渡。
Now you can use the transition attribute in CSS to enhance the interactivity and visual experience of your application. The transition includes the layout animation, that is, LayoutAnimation, which now changes the layout and uses the fluent animation of the transition. Transition allows the CSS attribute values to transition smoothly over a certain time interval.
Allows the name of the transitional animation to set the value of the different styles transition effect, the default value is empty, that does not perform any transition, the following table lists all the legitimate parameters of the property:
|参数名 |描述 |
|Property |Describe |
|-- |-- |
|-- |-- |
|width |宽度参与过渡动画 |
|width |The transition is performed when the width of the component is involved in the animation |
|height |高度参与过渡动画 |
|height |The transition is performed when the height of the component is involved in the animation |
|top |顶部距离参与过渡动画 |
|top |The transition is performed when the top of the component is involved in the animation |
|bottom |底部距离参与过渡动画 |
|bottom |The transition is performed when the bottom of the component is involved in the animation |
|left |左侧距离参与过渡动画 |
|left |The transition is performed when the left of the component is involved in the animation |
|right |右侧距离参与过渡动画 |
|right |The transition is performed when the right of the component is involved in the animation |
|background-color |背景颜色参与过渡动画 |
|background-color |The transition is performed when the backgroundColor of the component is involved in the animation |
|opacity |不透明度参与过渡动画 |
|opacity |The transition is performed when the opacity of the component is involved in the animation |
|transform |变换类型参与过渡动画 |
|transform |The transition is performed when the transform of the component is involved in the animation |
#### transition-duration
#### transition-duration
指定过渡的持续时间 (单位是毫秒)，默认值是 0，表示没有动画效果。
Specifies the duration of the transition transition (in milliseconds). The default value is 0, indicating that there is no animation.
Specifies the time interval (in milliseconds or seconds) between the request transition transition and the transition transition. The default value is 0, indicating that there is no delay, and the transition transition is performed immediately after the request.
Describes the velocity curve of the transition transition, which is used to make the transition transition smoother. The default is ease. The following table lists all the valid attributes:
|参数名 |描述 |
|Property |Describe |
|-- |-- |
|-- |-- |
|ease |transition 过渡逐渐变慢的过渡效果 |
|ease |The transition gradually slow down the transition effect |
|ease-in |transition 过渡慢速开始，然后变快的过渡效果 |
|ease-in |The transition starts slowly and then becomes faster for the transition effect |
|ease-out |transition 过渡快速开始，然后变慢的过渡效果 |
|ease-out |The transition starts quickly and then slows the transition effect|
|cubic-bezier(x1, y1, x2, y2) |Using the custom transition in the third-order Bessel function, the parameter values of the function must be between 0 and 1. For more information on three times Bessel, see [cubic-bezier](http://cubic-bezier.com/) and [Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve). |
Weex support linear-gradient background, You can see [W3C description of the gradient](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Images/Using_CSS_gradients).
你可以通过 ``` background-image ```属性创建线性渐变。
You can use linear gradient by `background-image` property.
`text-decoration`: <enum>`none` | `underline` | `line-through`. This property is used to set the text formatting to underline or line-through. The default value is `none`.
|可选值 |描述 |
|Property |Describe |
|-- |-- |
|-- |-- |
|none |默认。定义标准的文本 |
|none |默认。定义标准的文本 |
|underline |定义文本下的一条线 |
|underline |定义文本下的一条线 |
|line-through |定义穿过文本下的一条线 |
|line-through |定义穿过文本下的一条线 |
> 只支持 ```text``` 和 ```ricthext```
> Only support for `<text>` and `<ricthext>`
>
>
> 不支持 ```text-decoration:overline```
> 不支持 ```text-decoration:overline```
### text-align
### text-align
```text-align {string}```：对齐方式。默认值为 ```left```。
`text-align`: <enum>`left` | `center` | `right`. This property describes how inline content like text is aligned in its parent component. The default value is `left`.
`font-family`:<string> this property set the font-family of the text. This property **doesn't guarantee** the given font will always be set to the text. If the specified font cannot be found at the device, a typeface fallback will occur and the default typeface will be load. The fallback mechanism may vary in different devices. If you want load your own font-family, ref [dom.addRule](/nvue-api?id=addrule) instead.
`text-overflow`:<enum>`clip` | `ellipsis`. This property determines how overflowed content that is not displayed is signaled to users. It can be clipped, display an ellipsis.
`lines`: <number> positive number. This is the max lines of text that would be displayed, the default value is 0 which means there is no restriction on text lines. If the text is not enough, the actual number of line may be shorter than the specified value.
### line-height
### line-height
line-height {length}: 正整数，每行文字高度。```line-height```是 top 至 bottom的距离。
`line-height`: <length> The line height of every line in the text. `line-height` is the space between top and bottom.`line-height` There is no relationship between `line-height` and `font-size`, as `line-height` is restricted by top and bottom, `font-size` is interpreted by glyph. Usually but not always, `line-height` and `font-size` with the same value will cause the text clipped.
```line-height```与```font-size```没有关系，因为```line-height```被 top 和 bottom 所限制，
`word-wrap`:<string>`break-word` | `normal` | `anywhere`. This property determins word wrap mode. For Weex, `anywhere` means clipping at character boundaries, other values or by default we break at word boundaries.
Weex provide the ability to let events trigger action, like starting a JavaScript when a user click on a component. Below are the common event attributes that can be added to weex components to define event actions.
下面列出了可被添加到 ```Weex``` 组件上以定义事件动作的属性：
### 事件穿透
### Event penetration
> Android和iOS下原生事件传递机制不同，这里仅针对iOS
> The principle of native event delivery under Android and iOS is different, only for iOS here.
When a parent view has multiple peer views, iOS will select the highest level View to respond to the event, and the underlying view event will never be responded.
Weex add attribute `eventPenetrationEnabled` to `<div>` component. When the value is `true`(default would be `false`), the view's children views still respond to the event normally, while the view itself will not respond to the event, but pass the event to the lower level View.
Weex add attribute `userInteractionEnabled` to `<div>` component. When the value is `false`(default would be `true`), neither the view nor its children views respond to the event. The event is passed to the lower layer View.
**longpress**
**longpress**
如果一个组件被绑定了 longpress 事件，那么当用户长按这个组件时，该事件将会被触发。
If a `longpress` event is bound to a component, the event will be triggered when user long press on it.
**事件对象**
**event object**
|key |value |备注 |
|key |value |备注 |
|-- |-- |-- |
|-- |-- |-- |
|type |longpress| |
|type |longpress| |
|target | |触发长按事件的目标组件 |
|target | |The target component where the event is triggered |
If a `disappear` event is bound to a component inside a scrollable container, the event will be triggered when the component scrolls out of viewport and disappears from your sight.
**事件对象**
**event object**
|key |value |备注 |
|key |value |备注 |
|-- |-- |-- |
|-- |-- |-- |
|type |disappear | |
|type |disappear | |
|target | |触发 Disappear 事件的组件对象 |
|target | |The target component where the event is triggered |
|timestamp| |事件被触发时的时间戳(不支持 H5)|
|timestamp| |Timestamp when event is triggered|
|direction| ```up```或 ```down``` |触发事件时屏幕的滚动方向 |
|direction| ```up```or ```down``` |The direction in which the scroller is scrolling. Could be `up` or `down` |
