diff --git a/document/components/docs/en-US/scroll.md b/document/components/docs/en-US/scroll.md index 70ac67df754e0ee39fb7d0ed26eb3b3b090332a9..9cbec7613064e32c98c76cfe61ac5b8b39a054ce 100644 --- a/document/components/docs/en-US/scroll.md +++ b/document/components/docs/en-US/scroll.md @@ -11,11 +11,14 @@ So for the Scroll component, The length of `.cube-scroll-content`, the scroll-co 2）Scrolling horizontally: **The width of the content element must be greater than the container element.** Since the child element's width does not exceed the container element by default, the Scroll component's `.cube-scroll-content` element needs to be set to a width greater than the `.cube-scroll-wrapper`. +> Note: If there is any situation where scrolling is not possible, you should first check if the height/width of the content element `.cube-scroll-content` is greater than the height/width of the container element `.cube-scroll-wrapper`. This is a prerequisite for content to scroll. **If there is images in the content, the scrolling should be not normal. The reason is images may not be downloaded when the DOM element is rendered, so the height of the content element is less than expected. At this point you should manually call the Scroll component's `refresh()` method after the image has been loaded, such as calling in the onload event callback, which will recalculate the scroll distance.** + + ### Example Five sample code to quickly understand how to use the Scroll component. -- **Basic usage - Default** +- **1. Basic usage - Default** By setting the data property to an array, you can generate an elegantly scrolling list. The complete sample code is [here](https://github.com/didi/cube-ui/blob/master/example/pages/scroll/default.vue). @@ -36,9 +39,9 @@ Five sample code to quickly understand how to use the Scroll component. > **Note**: As the scrolling principle above, it is necessary to provide a fixed height to the scroll container, and scroll only when the height of the scroll content is greater than the height of the container. - In the prop `options`, you are able to control the scroll bar seen or not via `scrollbar`, and configure the initial position by `startX/startY`. + In the prop `options`, you are able to control the scrollbar seen or not via `scrollbar`, and configure the initial position by `startX/startY`. - Scroll component provide a `scrollTo()` method that allows you to manually control the list scroll position. + Scroll component provides a `scrollTo()` method that allows you to manually control the list scroll position. ```javascript scrollTo() { @@ -53,36 +56,41 @@ Five sample code to quickly understand how to use the Scroll component. In fact, this is a very useful method, such as when we want to achieve "click different anchor, list scroll to the corresponding position to show different content", you can use the `scrollTo ()` method. -- **Scrolling horizontally - Horizontal** +- **2. Scrolling horizontally - Horizontal** - Scroll component support horizontal scrolling by specifying `direction = 'horizental'`. The complete sample code is [here](https://github.com/didi/cube-ui/blob/master/example/pages/scroll/horizontal.vue) + Scroll component supports horizontal scrolling. All you need to do is specifying `direction = 'horizontal'` and giving some styles. The complete sample code is [here](https://github.com/didi/cube-ui/blob/master/example/pages/scroll/horizontal.vue) ```html -
- - - -
+ + + ``` ```stylus - .cube-scroll-content - display: inline-block + .horizontal-scroll-list-wrap + border: 1px solid rgba(0, 0, 0, 0.1) + border-radius: 5px + .cube-scroll-content + display: inline-block .list-wrapper padding: 0 10px line-height: 60px white-space: nowrap - .list-item - display: inline-block + .list-item + display: inline-block ``` - > **Note**：As the scrolling principle above, the CSS style setting here is required, and scrolling is possible only when the scrolling content is wider than the container width. + > **Note**：1. As the scrolling principle above, the CSS style setting here is required, and scrolling is possible only when the scrolling content is wider than the container width. 2. Sometimes we want to use the `Scroll` component to simulate the horizontal scroll, vertically retaining the browser's native scrolling, or vice versa. At this point you need to pass the better-scroll configuration item [eventPassthrough](http://ustbhuangyi.github.io/better-scroll/doc/en/options.html#eventpassthrough) + + Here giving a brief explanation of the style settings. `list-item` items with `display: inline-block` lead to all `list-item` elements showing on one line. `list-wrapper` adds `white-space: nowrap` hope `list-item` also showing on one line when reaching the outer element boundary. And the most important is setting `cube-scroll-content` with `display: inline-block`， which make the width of `cube-scroll-content` bigger enough so that `cube-scroll-content` can wrap descendants elements. Styles with the same properties are floating elements and absolutely positioned elements. When no specific width is set, the width is the minimum width of the wrapped descendant element. -- **Custom content - Customized** +- **3. Custom content - Customized** The Scroll component supports the customization of list content through default slot. The complete sample code is [here](https://github.com/didi/cube-ui/blob/master/example/pages/scroll/config.vue). @@ -90,6 +98,7 @@ Five sample code to quickly understand how to use the Scroll component.
@@ -98,7 +107,7 @@ Five sample code to quickly understand how to use the Scroll component.
``` - Scroll components also support **pull-down refresh** and **pull-up load** capabilities. By default, there is no pulldown refresh/pullup load. You can enable corresponding functions by `pullDownRefresh` and `pullUpLoad`. After opening, when pulling down, the Scroll component will show the default pulldown animation and dispatch pulldown events. You can monitor the `pull-down` event to update the data. Similarly, after the pull-up load is enabled, the data can be updated by the `pull-up` event. + Scroll components also support **pull-down refresh** and **pull-up load** capabilities. By default, there is no pulldown refresh/pull-up load. You can enable corresponding functions by `pullDownRefresh` and `pullUpLoad`. After opening, when pulling down, the Scroll component will show the default pulldown animation and dispatch pulldown events. You can monitor the `pull-down` event to update the data. Similarly, after the pull-up load is enabled, the data can be updated by the `pull-up` event. `pullDownRefresh`'s related configurations include: drop threshold (threshold), rebound position (stop), update successful copy (txt) and copy display time (stopTime). See the [Props configuration](#/en-US/docs/scroll#cube-Propsconfiguration-anchor) for all the configuration items and meanings of the `pullDownRefresh` and `pullUpLoad` objects. @@ -144,9 +153,9 @@ Five sample code to quickly understand how to use the Scroll component. } ``` - > **Note**: If a pulldown refresh has no data update, you must manually call the Scroll component's `forceUpdate()` method to end the pulldown refresh so that Scroll will restart listening for the next pulldown refresh operation. When the data is updated, the Scroll component will invoke `forceUpate()` method internally. + > **Note**: If a pulldown-refresh/pullup-loading has no data update, you must manually call the Scroll component's `forceUpdate()` method to end the pulldown-refresh/pullup-loading so that Scroll will restart listening for the next pulldown-refresh/pullup-loading operation. In the above example, when the data is updated, we did not invoke the `forceUpdate()` method. The reason is: ** If you pass the `data` attribute to the `Scroll` component, then when the `Scroll` component listens to the `data` update, the `forceUpate(true)` method will be called automatically. ** so it is recommended to pass the `data` attribute. -- **Custom pull-down refresh animation - Fake JD App** +- **4. Custom pull-down refresh animation - Fake JD App** If you don't like the built-in pull-down refresh and pull-up loading animations, you can also use the scope slots for custom animations. The variables exposed by [the scoped slots](https://vuejs.org/v2/guide/components-slots.html#Scoped-Slots) of the Scroll component are perfect to meet the needs of custom pull-down/pull-up animations in most scenarios. The following example imitates the pull-down refresh animation of Jingdong App's homepage. The complete sample code is [here](https://github.com/didi/cube-ui/blob/master/example/pages/scroll/jd.vue). @@ -232,12 +241,12 @@ Five sample code to quickly understand how to use the Scroll component. | - | - | - | - | | 1. Untrigger pull-down refresh | true | - | Show pattern guide user continues to pull down | | 2. Trigger pull-down refresh | false | true | Asynchronous request data，show loading | - | 3. Request data success | false | false | invoke `forceUpdate()`, show success copy | - | 4. A pull-down refresh complete | true | - | after invoke `forceUpdate()`, delay stopTime to step 4 | + | 3. Request data success | false | false | invoke `forceUpdate(true)`, show success copy. And delay 'stopTime' into step 4 | + | 4. A pull-down refresh complete | true | - | - | -- **Advanced usage - Fake TouTiao App** +- **5. Advanced usage - Fake TouTiao App** -Scroll components can meet the scrolling needs of most mobile applications. In this example, using two Scroll components, one vertical and one horizontal, to imitates the Toutiao App's home page. The complete sample code is [here](https://github.com/didi/cube-ui/blob/master/example/pages/scroll/toutiao.vue). +Scroll components can meet the scrolling needs of most mobile applications. In this example, using two Scroll components, one vertical and one horizontal, to imitates the Toutiao App's home page. The complete sample code is [here](https://github.com/didi/cube-ui/blob/master/example/pages/scroll/toutiao.vue). ```html
@@ -319,10 +328,10 @@ In `options`, there are three frequently-used options, `scrollbar`、`pullDownRe | Attribute | Description | Type | Accepted Values | Default | | - | - | - | - | - | -| threshold | the threshold of distance that pulling down for refreshing | Number | - | 90 | +| threshold | the threshold of distance that pulling down for refreshing | Number | - | 90 | | stop | the position where rebounding stays | Number | - | Scroll component will calculate the height of pulldown element as default `stop` value | -| stopTime | the time that keep showing the text of refreshing success | Number | - | 600 | -| txt | the text shown when refreshing successfully | String | - | 'Refresh success' | +| stopTime | the time that keeps showing the text of refreshing success | Number | - | 600 | +| txt | the text is shown when refreshing successfully | String | - | 'Refresh success' | - `pullUpLoad` sub configuration @@ -356,8 +365,8 @@ In `options`, there are three frequently-used options, `scrollbar`、`pullDownRe | Method Name | Description | Parameters | | - | - | - | | scrollTo | Scroll to specific position. | x: horizontal position
y: vertical position
time: transition time
ease: easing function | +| forceUpdate | Mark the end of pull-up or pull-down, and force recalculation of scrollable distance | dirty: whether there is data updating, when "true" indicate data updated so recalculate scrollable distance, when false no data update and no need to recalculate | | disable | Disable scroll. | - | | enable | Enable scroll. It's enabled by default | - | -| forceUpdate | If a pulldown/pullup refresh has no data update, you should call `forceUpdate()` method to force update pullUp/pullDown state | - | | resetPullUpTxt | Reset pull up txt when pull up state changed from no data to data updated | - | -| refresh | Refresh, computed height and called BetterScroll instance's refresh | - | +| refresh | Refresh, computed height and called BetterScroll instance's refresh | - | \ No newline at end of file diff --git a/document/components/docs/zh-CN/scroll.md b/document/components/docs/zh-CN/scroll.md index d5cdfa7cef1ca1bb2420738c8ba112c094fc635a..3fb325d6ab36a7c708a31824282fd494a937eefe 100644 --- a/document/components/docs/zh-CN/scroll.md +++ b/document/components/docs/zh-CN/scroll.md @@ -12,11 +12,13 @@ 2）横向滚动：**内容元素的宽度必须大于容器元素**。由于在默认情况下，子元素的宽度不会超过容器元素，所以需要给 Scroll 组件的 `.cube-scroll-content` 元素设置大于 `.cube-scroll-wrapper` 的宽度。 + > 注意：任何时候如果出现无法滚动的情况，都应该首先查看内容元素`.cube-scroll-content`的元素高度/宽度是否大于容器元素`.cube-scroll-wrapper`的高度/宽度。这是内容能够滚动的前提条件。**如果内容存在图片的情况，可能会出现 DOM 元素渲染时图片还未下载，因此内容元素的高度小于预期，出现滚动不正常的情况。此时你应该在图片加载完成后，比如 onload 事件回调中，手动调用 Scroll 组件的 `refresh()` 方法，它会重新计算滚动距离。** + ### 示例 5 个示例代码快速了解如何使用 Scroll 组件。 -- **基本使用 - Default** +- **1. 基本使用 - Default** 通过设置 `data` 属性为一个数组，即可生成能够在容器内优雅滚动的列表。完整示例代码在[这里](https://github.com/didi/cube-ui/blob/master/example/pages/scroll/default.vue)。 @@ -54,36 +56,41 @@ 实际上这是一个非常有用的方法，如当我们想要实现“点击不同锚点，列表滚动到相应位置展现不同内容”时，可以使用`scrollTo()`方法。 -- **横向滚动 - Horizontal** +- **2. 横向滚动 - Horizontal** - Scroll 组件支持横向滚动，只需指定`direction="horizontal"`即可。完整示例代码在[这里](https://github.com/didi/cube-ui/blob/master/example/pages/scroll/horizontal.vue)。 + Scroll 组件支持横向滚动，只需指定`direction="horizontal"`，同时需要添加相应样式如下。完整示例代码在[这里](https://github.com/didi/cube-ui/blob/master/example/pages/scroll/horizontal.vue)。 ```html -
- -
    -
  • {{ item }}
    • -
- -
+ + + ``` ```stylus - .cube-scroll-content - display: inline-block + .horizontal-scroll-list-wrap + border: 1px solid rgba(0, 0, 0, 0.1) + border-radius: 5px + .cube-scroll-content + display: inline-block .list-wrapper padding: 0 10px line-height: 60px white-space: nowrap - .list-item - display: inline-block + .list-item + display: inline-block ``` - > **注意**：由上面的滚动原理可知，这里的 CSS 样式设置是必须的，同时只有在滚动内容的宽度大于容器宽度时才可滚动。 + > **注意**：1. 由上面的滚动原理可知，这里的 CSS 样式设置是必须的，只有在滚动内容的宽度大于容器宽度时才可滚动。2. 有时候我们希望横向滚动使用`Scroll`组件来模拟，纵向保留浏览器原生滚动，或者相反的情况。这时你需要传递 better-scroll 配置项 [eventPassthrough](http://ustbhuangyi.github.io/better-scroll/doc/zh-hans/options.html#eventpassthrough)。 + + 这里对样式的设定做简要的解释，为`list-item`元素添加`display: inline-block`是希望元素能够不换行，单行显示。`list-wrapper`添加`white-space: nowrap`是希望遇到父元素边界，依然不换行。另外，关键是`cube-scroll-content`元素添加`display: inline-block`样式，此时`cube-scroll-content`元素的宽度为能够包裹子孙元素的最小宽度，即为连续内联`list-item`元素的宽度之和子元素的最大宽度。具有同样性质的样式还有，浮动元素和绝对定位元素，在不设置具体宽度时，其宽度为包裹子孙元素的最小宽度。 -- **自定义内容和上拉刷新下拉加载 - Customized** +- **3. 自定义内容和上拉刷新下拉加载 - Customized** `Scroll`组件支持通过插槽自定义列表内容和样式。完整示例代码在[这里](https://github.com/didi/cube-ui/blob/master/example/pages/scroll/config.vue)。 @@ -91,6 +98,7 @@
@@ -99,9 +107,9 @@
``` - Scroll 组件还支持下拉刷新和上拉加载的能力。默认无下拉刷新/上拉加载，可通过`options`传递配置项`pullDownRefresh`和`pullUpLoad`开启相应功能。开启后，下拉时，Scroll 组件会展示默认下拉动画以及派发`pulling-down`事件，你可以监听`pulling-down`事件更新数据。同理，开启上拉加载后，可通过`pulling-up`事件更新数据。 + Scroll 组件还支持下拉刷新和上拉加载的能力。默认无下拉刷新/上拉加载，可通过`options`传递配置项`pullDownRefresh`和`pullUpLoad`开启相应功能。开启后，下拉时，Scroll 组件会展示默认下拉动画以及派发`pulling-down`事件，你可以监听`pulling-down`事件更新数据。同理，开启上拉加载后，可通过`pulling-up`事件更新数据。 - `pullDownRefresh`的相关配置有：下拉阈值（threshold）, 回弹位置（stop）, 更新成功文案（txt）和文案显示时间（stopTime）。`pullDownRefresh`和`pullUpLoad`对象的所有配置项和含义见 [Props 配置](#/zh-CN/docs/scroll#cube-Props配置-anchor) + `pullDownRefresh`的相关配置有：下拉阈值（threshold）, 回弹位置（stop）, 更新成功文案（txt）和文案显示时间（stopTime）。`pullDownRefresh`和`pullUpLoad`对象的所有配置项和含义见 [Props 配置](#/zh-CN/docs/scroll#cube-Props配置-anchor) ```javascript ... // 省略非核心代码 @@ -145,11 +153,11 @@ } ``` - > **注意**：如果请求结果没有数据更新，则必须调用 Scroll 组件的`forceUpdate()`方法结束此次下拉刷新，这样 Scroll 组件才会开始监听下一次下拉刷新操作。当有数据更新时，Scroll 组件内部会自行调用`forceUpate()`方法 + > **注意**：如果请求结果没有数据更新，则必须调用 Scroll 组件的`forceUpdate()`方法结束此次下拉刷新/上拉加载，这样 Scroll 组件才会开始监听下一次下拉刷新/上拉加载操作。在上例中数据更新时，没有调用`forceUpdate()`方法，原因为：**如果你向`Scroll`组件传递了`data`属性，那么当`Scroll`组件监听到`data`有更新时会自行调用`forceUpate(true)`方法**，因此推荐传递`data`属性。 -- **自定义下拉刷新动画 - 仿京东 App 首页** +- **4. 自定义下拉刷新动画 - 仿京东 App 首页** - 如果你不喜欢内置的下拉刷新和上拉加载动画，还可以用[作用域插槽](https://cn.vuejs.org/v2/guide/components.html#作用域插槽)做自定义动画。Scroll 组件的作用域插槽暴露出的变量非常完善，可以满足绝大多数场景下自定义下拉/上拉动画的需求。下面的例子模仿了京东 App 首页的下拉刷新动画。完整示例代码在[这里](https://github.com/didi/cube-ui/blob/master/example/pages/scroll/jd.vue)。 + 如果你不喜欢内置的下拉刷新和上拉加载动画，还可以用[作用域插槽](https://cn.vuejs.org/v2/guide/components.html#作用域插槽)做自定义动画。Scroll 组件的作用域插槽暴露出的变量非常完善，可以满足绝大多数场景下自定义下拉/上拉动画的需求。下面的例子模仿了京东 App 首页的下拉刷新动画。完整示例代码在[这里](https://github.com/didi/cube-ui/blob/master/example/pages/scroll/jd.vue)。 ```html @@ -291,11 +299,11 @@ 和“仿京东 APP”示例不同的是，在下拉刷新的自定义动画中，使用了`pulldown`作用域插槽中的`pullDownStyle`和`bubbleY`更方便的实现下拉动画。 - `pullDownStyle`用来控制下拉内容的位置，值为字符串`top: n px`（n 代表数值）。Scroll 组件是通过绝对定位的`top`值来控制下拉内容位置的。初始状态`top`值为负值，大小刚好为下拉内容的高度，因此下拉内容被隐藏到滚动区域上方，当下拉过程中，Scroll 组件会逐渐增大`top`值，实时更新下拉内容的位置。`top`最大值为0，即当下拉内容完全显示后`top`值不再增加。即 `pullY - height <= top <= 0`。（pullY 为下拉距离，height 为下拉内容高度） + `pullDownStyle`用来控制下拉内容的位置，值为字符串`top: n px`（n 代表数值）。Scroll 组件是通过绝对定位的`top`值来控制下拉内容位置的。初始状态`top`值为负值，大小刚好为下拉内容的高度，因此下拉内容被隐藏到滚动区域上方，当下拉过程中，Scroll 组件会逐渐增大`top`值，实时更新下拉内容的位置。`top`最大值为0，即当下拉内容完全显示后`top`值不再增加。即 `pullY - height <= top <= 0`。（pullY 为下拉距离，height 为下拉内容高度） - `bubbleY`用来辅助实现自定义动画。在默认动画中，`bubbleY`用来控制气泡尾巴长度；在头条例子中，用来控制箭头的`padding-top`值，间接控制箭头位置。`bubbleY`的最小值为 0，下拉过程中，当下拉距离大于下拉内容高度后，`bubbleY`开始增大。即`0 <= bubbleY <= pullY - height`。 + `bubbleY`用来辅助实现自定义动画。在默认动画中，`bubbleY`用来控制气泡尾巴长度；在头条例子中，用来控制箭头的`padding-top`值，间接控制箭头位置。`bubbleY`的最小值为 0，下拉过程中，当下拉距离大于下拉内容高度后，`bubbleY`开始增大。即 `0 <= bubbleY <= pullY - height`。 - > 在本例中，`pullDownRefresh`配置项没有传入`stop`值，但是下拉后依然能够回弹到正确位置，原因是 Scroll 组件初始化时会将 `beforePullDown === false && isPullingDown === true` 时下拉内容高度作为 `stop` 默认值。 + > 在本例中，`pullDownRefresh`配置项没有传入`stop`值，但是下拉后依然能够回弹到正确位置，原因是 Scroll 组件初始化时会将 `beforePullDown === false && isPullingDown === true` 时下拉内容高度作为 `stop` 默认值。 ### Props 配置 @@ -357,8 +365,14 @@ | 方法名 | 说明 | 参数 | | - | - | - | | scrollTo | 滚动到指定位置 | x: 横向位置
y: 纵向位置
time: 过渡动画时间
ease: 动画曲线 | +| forceUpdate | 标记上拉下拉结束，强制重新计算可滚动距离 | dirty: 是否有数据更新，默认为 false。true 表示有数据更新重新计算可滚动距离，上拉文案显示`pullUpLoad.text.more`值，false 表示没有数据更新，无需重新计算, 上拉文案显示`pullUpLoad.text.nomore`值 | | disable | 禁用滚动 | - | -| enable | 启用滚动，默认是开启滚动的 | - | -| forceUpdate | 强制更新状态，用于上拉或者下拉无数据的情况 | - | +| enable | 启用滚动，默认是开启滚动的。 | - | | resetPullUpTxt | 当从无更多切换到有更多时，重置上拉文本内容 | - | | refresh | 刷新，重新计算高度且刷新 BetterScroll 实例 | - | + +### 内部属性 + +| 属性名 | 说明 | +| - | - | +| scroll | 可以通过该属性获得内部实现滚动核心的 BScoll 实例，从而获得更多 BScoll 的底层能力，如监听`touchEnd`事件，获得滚动中的中间状态等，具体可查看[ better-scroll 文档](http://ustbhuangyi.github.io/better-scroll/doc/zh-hans/) | \ No newline at end of file