diff --git a/docs/components/viewContainer/scroll-view.md b/docs/components/viewContainer/scroll-view.md
index d594a2bfa620..7e5fef98d8d2 100755
--- a/docs/components/viewContainer/scroll-view.md
+++ b/docs/components/viewContainer/scroll-view.md
@@ -3,48 +3,23 @@ title: ScrollView
sidebar_label: ScrollView
---
-##### 可滚动视图区域
-> 属性
+可滚动视图区域。使用竖向滚动时，需要给scroll-view一个固定高度，通过 WXSS 设置 height。组件属性的长度单位默认为 px
-| 属性名 | 类型 | 默认值 | 说明 |
-| :- | :- | :- | :- |
-| scrollX | Boolean | false | 允许横向滚动 |
-| scrollY | Boolean | false | 允许纵向滚动 |
-| upperThreshold | Number | 50 | 距顶部/左边多远时（单位 px），触发 scrolltoupper 事件 |
-| lowerThreshold | Number | 50 | 距底部/右边多远时（单位 px），触发 scrolltolower 事件 |
-| scrollTop | Number | | 设置竖向滚动条位置 |
-| scrollLeft | Number | | 设置横向滚动条位置 |
-| scrollIntoView | String | | 值应为某子元素 id（id 不能以数字开头）。设置哪个方向可滚动，则在哪个方向滚动到该元素 |
-| scrollWithAnimation | Boolean | false | 在设置滚动条位置时使用动画过渡 |
-| enableBackToTop | Boolean | false | iOS 点击顶部状态栏、安卓双击标题栏时，滚动条返回顶部，只支持竖向 |
-| onScrollToUpper | EventHandle | | 滚动到顶部/左边，会触发 scrolltoupper 事件 |
-| onScrollToLower | EventHandle | | 滚动到底部/右边，会触发 scrolltolower 事件 |
-| onScroll | EventHandle | | 滚动时触发，event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY} |
+Tips:
+H5 中 ScrollView 组件是通过一个高度（或宽度）固定的容器内部滚动来实现的，因此务必正确的设置容器的高度。例如: 如果 ScrollView 的高度将 body 撑开，就会同时存在两个滚动条（body 下的滚动条，以及 ScrollView 的滚动条）。
+微信小程序 中 ScrollView 组件如果设置 scrollX 横向滚动时，并且子元素为多个时（单个子元素时设置固定宽度则可以正常横向滚动），需要通过 WXSS 设置 `white-space: nowrap` 来保证元素不换行，并对 ScrollView 内部元素设置 `display: inline-block` 来使其能够横向滚动。
->各端支持度
+> [参考文档](https://developers.weixin.qq.com/miniprogram/dev/component/scroll-view.html)
-| 属性 | 微信小程序 | H5 | ReactNative | 百度小程序 | 支付宝小程序 | 字节跳动小程序 |
-| :-: | :-: | :-: | :- | :- | :- | :- |
-| scrollX | ✔ | ✔ | 二选一 | ✔ | ✔ | ✔ |
-| scrollY | ✔ | ✔ | 二选一 | ✔ | ✔ | ✔ |
-| upperThreshold | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
-| lowerThreshold | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
-| scrollTop | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
-| scrollLeft | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
-| scrollIntoView | ✔ | ✔ | x | ✔ | ✔ | ✔ |
-| scrollWithAnimation| ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
-| enableBackToTop | ✔ | | ✔ | | ✔ | |
-| onScrollToUpper | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
-| onScrollToLower | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
-| onScroll | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
+## 类型
-使用竖向滚动时，需要给 `` 一个固定高度，通过 WXSS 设置 height。
+```tsx
+ComponentType
+```
-###### 示例：
-```jsx
-import Taro, { Component } from '@tarojs/taro'
-import { ScrollView, View } from '@tarojs/components'
+## 示例代码
+```tsx
export default class PageView extends Component {
constructor() {
super(...arguments)
@@ -99,6 +74,58 @@ export default class PageView extends Component {
}
```
-###### Tips:
-* H5 中 ScrollView 组件是通过一个高度（或宽度）固定的容器内部滚动来实现的，因此务必正确的设置容器的高度。例如: 如果 ScrollView 的高度将 body 撑开，就会同时存在两个滚动条（body 下的滚动条，以及 ScrollView 的滚动条）。
-* 微信小程序 中 ScrollView 组件如果设置 scrollX 横向滚动时，并且子元素为多个时（单个子元素时设置固定宽度则可以正常横向滚动），需要通过 WXSS 设置 white-space 为 nowrap 来保证元素不换行，并对 ScrollView 内部元素设置 display 为 inline-block 来使其能够横向滚动。
+## ScrollViewProps
+
+| 参数 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | :---: | :---: | --- |
+| scrollX | `boolean` | `fasle` | 否 | 允许横向滚动 |
+| scrollY | `boolean` | `fasle` | 否 | 允许纵向滚动 |
+| upperThreshold | `number` | `50` | 否 | 距顶部/左边多远时（单位px），触发 scrolltoupper 事件 |
+| lowerThreshold | `number` | `50` | 否 | 距底部/右边多远时（单位px），触发 scrolltolower 事件 |
+| scrollTop | `number` | | 否 | 设置竖向滚动条位置 |
+| scrollLeft | `number` | | 否 | 设置横向滚动条位置 |
+| scrollIntoView | `string` | | 否 | 值应为某子元素id（id不能以数字开头）。设置哪个方向可滚动，则在哪个方向滚动到该元素 |
+| scrollWithAnimation | `boolean` | `fasle` | 否 | 在设置滚动条位置时使用动画过渡 |
+| enableBackToTop | `boolean` | `fasle` | 否 | iOS 点击顶部状态栏、安卓双击标题栏时，滚动条返回顶部，只支持竖向 |
+| enableFlex | `boolean` | `fasle` | 否 | 启用 flexbox 布局。开启后，当前节点声明了 `display: flex` 就会成为 flex container，并作用于其孩子节点。 |
+| scrollAnchoring | `boolean` | `fasle` | 否 | 开启 scroll anchoring 特性，即控制滚动位置不随内容变化而抖动，仅在 iOS 下生效，安卓下可参考 CSS `overflow-anchor` 属性。 |
+| refresherEnabled | `boolean` | `fasle` | 否 | 开启自定义下拉刷新 |
+| refresherThreshold | `number` | `45` | 否 | 设置自定义下拉刷新阈值 |
+| refresherDefaultStyle | `string` | `'black'` | 否 | 设置自定义下拉刷新默认样式，支持设置 `black | white | none`， none 表示不使用默认样式 |
+| refresherBackground | `string` | `'#FFF'` | 否 | 设置自定义下拉刷新区域背景颜色 |
+| refresherTriggered | `boolean` | `fasle` | 否 | 设置当前下拉刷新状态，true 表示下拉刷新已经被触发，false 表示下拉刷新未被触发 |
+| onScrollToUpper | `(event: BaseEventOrigFunction) => any` | | 否 | 滚动到顶部/左边，会触发 scrolltoupper 事件 |
+| onScrollToLower | `(event: BaseEventOrigFunction) => any` | | 否 | 滚动到底部/右边，会触发 scrolltolower 事件 |
+| onScroll | `(event: BaseEventOrigFunction) => any` | | 否 | 滚动时触发
`event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY}` |
+| onRefresherPulling | `(event: BaseEventOrigFunction) => any` | | 否 | 自定义下拉刷新控件被下拉 |
+| onRefresherRefresh | `(event: BaseEventOrigFunction) => any` | | 否 | 自定义下拉刷新被触发 |
+| onRefresherRestore | `(event: BaseEventOrigFunction) => any` | | 否 | 自定义下拉刷新被复位 |
+| onRefresherAbort | `(event: BaseEventOrigFunction) => any` | | 否 | 自定义下拉刷新被中止 |
+
+### API 支持度
+
+| API | 微信小程序 | 百度小程序 | 支付宝小程序 | 字节跳动小程序 | QQ 小程序 | H5 | React Native | 快应用 |
+| :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
+| ScrollViewProps.scrollX | ✔️ | ✔️ | ✔️ | ✔️ | | ✔️ | ✔️(二选一) | |
+| ScrollViewProps.scrollY | ✔️ | ✔️ | ✔️ | ✔️ | | ✔️ | ✔️(二选一) | |
+| ScrollViewProps.upperThreshold | ✔️ | ✔️ | ✔️ | ✔️ | | ✔️ | ✔️ | |
+| ScrollViewProps.lowerThreshold | ✔️ | ✔️ | ✔️ | ✔️ | | ✔️ | ✔️ | |
+| ScrollViewProps.scrollTop | ✔️ | ✔️ | ✔️ | ✔️ | | ✔️ | ✔️ | |
+| ScrollViewProps.scrollLeft | ✔️ | ✔️ | ✔️ | ✔️ | | ✔️ | ✔️ | |
+| ScrollViewProps.scrollIntoView | ✔️ | ✔️ | ✔️ | ✔️ | | ✔️ | | |
+| ScrollViewProps.scrollWithAnimation | ✔️ | ✔️ | ✔️ | ✔️ | | ✔️ | ✔️ | |
+| ScrollViewProps.enableBackToTop | ✔️ | | ✔️ | | | | ✔️ | |
+| ScrollViewProps.enableFlex | ✔️ | | | | | | | |
+| ScrollViewProps.scrollAnchoring | ✔️ | | | | | | | |
+| ScrollViewProps.refresherEnabled | ✔️ | | | | | | | |
+| ScrollViewProps.refresherThreshold | ✔️ | | | | | | | |
+| ScrollViewProps.refresherDefaultStyle | ✔️ | | | | | | | |
+| ScrollViewProps.refresherBackground | ✔️ | | | | | | | |
+| ScrollViewProps.refresherTriggered | ✔️ | | | | | | | |
+| ScrollViewProps.onScrollToUpper | ✔️ | ✔️ | ✔️ | ✔️ | | ✔️ | ✔️ | |
+| ScrollViewProps.onScrollToLower | ✔️ | ✔️ | ✔️ | ✔️ | | ✔️ | ✔️ | |
+| ScrollViewProps.onScroll | ✔️ | ✔️ | ✔️ | ✔️ | | ✔️ | ✔️ | |
+| ScrollViewProps.onRefresherPulling | ✔️ | | | | | | | |
+| ScrollViewProps.onRefresherRefresh | ✔️ | | | | | | | |
+| ScrollViewProps.onRefresherRestore | ✔️ | | | | | | | |
+| ScrollViewProps.onRefresherAbort | ✔️ | | | | | | | |
diff --git a/packages/taro-components/types/ScrollView.d.ts b/packages/taro-components/types/ScrollView.d.ts
index 90be515fff65..30dd49975769 100644
--- a/packages/taro-components/types/ScrollView.d.ts
+++ b/packages/taro-components/types/ScrollView.d.ts
@@ -2,84 +2,201 @@ import { ComponentType } from 'react'
import { StandardProps, CommonEventFunction } from './common'
export interface ScrollViewProps extends StandardProps {
+ /** 允许横向滚动
+ * @default fasle
+ * @supported weapp, swan, alipay, tt, h5, rn
+ * @rn 二选一
+ */
+ scrollX?: boolean
- /**
- * 允许横向滚动
- *
- * 默认值：`fasle`
+ /** 允许纵向滚动
+ * @default fasle
+ * @supported weapp, swan, alipay, tt, h5, rn
+ * @rn 二选一
*/
- scrollX?: boolean,
+ scrollY?: boolean
- /**
- * 允许纵向滚动
- *
- * 默认值：`false`
+ /** 距顶部/左边多远时（单位px），触发 scrolltoupper 事件
+ * @default 50
+ * @supported weapp, swan, alipay, tt, h5, rn
*/
- scrollY?: boolean,
+ upperThreshold?: number
- /**
- * 距顶部/左边多远时（单位px），触发 scrolltoupper 事件
- *
- * 默认值：`50`
+ /** 距底部/右边多远时（单位px），触发 scrolltolower 事件
+ * @default 50
+ * @supported weapp, swan, alipay, tt, h5, rn
*/
- upperThreshold?: number,
+ lowerThreshold?: number
- /**
- * 距底部/右边多远时（单位px），触发 scrolltolower 事件
- *
- * 默认值：`50`
+ /** 设置竖向滚动条位置
+ * @supported weapp, swan, alipay, tt, h5, rn
*/
- lowerThreshold?: number,
+ scrollTop?: number
- /**
- * 设置竖向滚动条位置
+ /** 设置横向滚动条位置
+ * @supported weapp, swan, alipay, tt, h5, rn
*/
- scrollTop?: number,
+ scrollLeft?: number
- /**
- * 设置横向滚动条位置
+ /** 值应为某子元素id（id不能以数字开头）。设置哪个方向可滚动，则在哪个方向滚动到该元素
+ * @supported weapp, swan, alipay, tt, h5
*/
- scrollLeft?: number,
+ scrollIntoView?: string
- /**
- * 值应为某子元素id（id不能以数字开头）。设置哪个方向可滚动，则在哪个方向滚动到该元素
+ /** 在设置滚动条位置时使用动画过渡
+ * @supported weapp, swan, alipay, tt, h5, rn
+ * @default fasle
*/
- scrollIntoView?: string,
+ scrollWithAnimation?: boolean
- /**
- * iOS点击顶部状态栏、安卓双击标题栏时，滚动条返回顶部，只支持竖向
- *
- * 默认值：`false`
+ /** iOS 点击顶部状态栏、安卓双击标题栏时，滚动条返回顶部，只支持竖向
+ * @supported weapp, alipay, rn
+ * @default fasle
*/
- enableBackToTop?: boolean,
+ enableBackToTop?: boolean
- /**
- * 在设置滚动条位置时使用动画过渡
- *
- * 默认值：`fasle`
+ /** 启用 flexbox 布局。开启后，当前节点声明了 `display: flex` 就会成为 flex container，并作用于其孩子节点。
+ * @supported weapp
+ * @default fasle
*/
- scrollWithAnimation?: boolean,
+ enableFlex?: boolean
- /**
- * 滚动到顶部/左边，会触发 scrolltoupper 事件
+ /** 开启 scroll anchoring 特性，即控制滚动位置不随内容变化而抖动，仅在 iOS 下生效，安卓下可参考 CSS `overflow-anchor` 属性。
+ * @supported weapp
+ * @default fasle
+ */
+ scrollAnchoring?: boolean
+
+ /** 开启自定义下拉刷新
+ * @supported weapp
+ * @default fasle
+ */
+ refresherEnabled?: boolean
+
+ /** 设置自定义下拉刷新阈值
+ * @supported weapp
+ * @default 45
+ */
+ refresherThreshold?: number
+
+ /** 设置自定义下拉刷新默认样式，支持设置 `black | white | none`， none 表示不使用默认样式
+ * @supported weapp
+ * @default 'black'
+ */
+ refresherDefaultStyle?: string
+
+ /** 设置自定义下拉刷新区域背景颜色
+ * @supported weapp
+ * @default '#FFF'
+ */
+ refresherBackground?: string
+
+ /** 设置当前下拉刷新状态，true 表示下拉刷新已经被触发，false 表示下拉刷新未被触发
+ * @supported weapp
+ * @default fasle
+ */
+ refresherTriggered?: boolean
+
+ /** 滚动到顶部/左边，会触发 scrolltoupper 事件
+ * @supported weapp, swan, alipay, tt, h5, rn
*/
- onScrollToUpper?: (event: CommonEventFunction) => any,
+ onScrollToUpper?: (event: CommonEventFunction) => any
/**
* 滚动到底部/右边，会触发 scrolltolower 事件
+ * @supported weapp, swan, alipay, tt, h5, rn
*/
- onScrollToLower?: (event: CommonEventFunction) => any,
+ onScrollToLower?: (event: CommonEventFunction) => any
- /**
- * 滚动时触发
- *
+ /** 滚动时触发
* `event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY}`
+ * @supported weapp, swan, alipay, tt, h5, rn
*/
onScroll?: (event: CommonEventFunction) => any
+
+ /** 自定义下拉刷新控件被下拉
+ * @supported weapp
+ */
+ onRefresherPulling?: (event: CommonEventFunction) => any
+
+ /** 自定义下拉刷新被触发
+ * @supported weapp
+ */
+ onRefresherRefresh?: (event: CommonEventFunction) => any
+
+ /** 自定义下拉刷新被复位
+ * @supported weapp
+ */
+ onRefresherRestore?: (event: CommonEventFunction) => any
+
+ /** 自定义下拉刷新被中止
+ * @supported weapp
+ */
+ onRefresherAbort?: (event: CommonEventFunction) => any
}
-/**
+/** 可滚动视图区域。使用竖向滚动时，需要给scroll-view一个固定高度，通过 WXSS 设置 height。组件属性的长度单位默认为 px
+ *
+ * Tips:
+ * H5 中 ScrollView 组件是通过一个高度（或宽度）固定的容器内部滚动来实现的，因此务必正确的设置容器的高度。例如: 如果 ScrollView 的高度将 body 撑开，就会同时存在两个滚动条（body 下的滚动条，以及 ScrollView 的滚动条）。
+ * 微信小程序 中 ScrollView 组件如果设置 scrollX 横向滚动时，并且子元素为多个时（单个子元素时设置固定宽度则可以正常横向滚动），需要通过 WXSS 设置 `white-space: nowrap` 来保证元素不换行，并对 ScrollView 内部元素设置 `display: inline-block` 来使其能够横向滚动。
* @classification viewContainer
+ * @example
+ * ```tsx
+ * export default class PageView extends Component {
+ * constructor() {
+ * super(...arguments)
+ * }
+ *
+ * onScrollToUpper() {}
+ *
+ * // or 使用箭头函数
+ * // onScrollToUpper = () => {}
+ *
+ * onScroll(e){
+ * console.log(e.detail)
+ * }
+ *
+ * render() {
+ * const scrollStyle = {
+ * height: '150px'
+ * }
+ * const scrollTop = 0
+ * const Threshold = 20
+ * const vStyleA = {
+ * height: '150px',
+ * 'background-color': 'rgb(26, 173, 25)'
+ * }
+ * const vStyleB = {
+ * height: '150px',
+ * 'background-color': 'rgb(39,130,215)'
+ * }
+ * const vStyleC = {
+ * height: '150px',
+ * 'background-color': 'rgb(241,241,241)',
+ * color: '#333'
+ * }
+ * return (
+ *
+ * A
+ * B
+ * C
+ *
+ * )
+ * }
+ * }
+ * ```
+ * @see https://developers.weixin.qq.com/miniprogram/dev/component/scroll-view.html
*/
declare const ScrollView: ComponentType
diff --git a/scripts/docs-api.ts b/scripts/docs-api.ts
index 14a486c501a8..d97438b96ee8 100644
--- a/scripts/docs-api.ts
+++ b/scripts/docs-api.ts
@@ -58,7 +58,7 @@ const get = {
since: (data?: ts.JSDocTagInfo) => data ? splicing([`> 最低 Taro 版本: ${data.text || ''}`, '']) : undefined,
type: (data?: string, level = 0) => data && !isntShowType.includes(data) ?
splicing([level !== 0 ? `${'#'.repeat(level)} 类型\n` : undefined, '```tsx', data, '```', '']) : undefined,
- members: (data?: DocEntry[], title = '方法', level: number = 2, name = 'Taro') => {
+ members: (data?: DocEntry[], title = '方法', level: number = 2, name = 'Taro', isComp = false) => {
if (!data) return undefined
const methods: (string | undefined)[] = [level === 2 ? `## ${title}\n` : undefined]
const paramTabs: DocEntry[] = []
@@ -119,9 +119,11 @@ const get = {
if (arrs.name === 'see') {
return `
[参考地址](${arrs.text})`
} else if (arrs.name === 'supported') {
- return `
API 支持度: ${arrs.text}`
+ if (!isComp) return `
API 支持度: ${arrs.text}`
} else {
- return `
${arrs.name}: ${parseLineFeed(arrs.text)}`
+ if (!isComp || !Object.values(envMap).find(env => env.name === arrs.name)) {
+ return `
${arrs.name}: ${parseLineFeed(arrs.text)}`
+ }
}
}).join('')
}` : ''
@@ -131,6 +133,7 @@ const get = {
}),
'']))
}
+ const componentApis = {}
methods.push(...data.map(param => {
const tags = param.jsTags || []
@@ -178,15 +181,18 @@ const get = {
get.document(param.documentation),
get.see(tags.find(tag => tag.name === 'see')),
get.type(param.type),
- get.members(param.members, undefined, level + (level === 2 ? 2 : 1), param.name),
- get.members(declaration.parameters || param.exports, '参数', level + (level === 2 ? 2 : 1), param.name),
+ get.members(param.members, undefined, level + (level === 2 ? 2 : 1), param.name, isComp),
+ get.members(declaration.parameters || param.exports, '参数', level + (level === 2 ? 2 : 1), param.name, isComp),
get.example(tags, level + (level === 2 ? 2 : 1)),
get.api(apis, level + (level === 2 ? 2 : 1)),
])
- }/* else if (!isShowAPI(param.flags) && !isNotAPI(param.flags) && param.flags !== 1) {
+ } else if (isComp && isShowAPI(param.flags)) {
+ if (param.name && param.jsTags) componentApis[`${name}.${param.name}`] = param.jsTags || []
+ } /* else if (!isShowAPI(param.flags) && !isNotAPI(param.flags) && param.flags !== 1) {
console.log(param.name, param.flags)
} */
}))
+ isComp && methods.push(get.api(componentApis, level))
return splicing(methods) || undefined
},
@@ -336,6 +342,7 @@ export function writeApiDoc (routepath: string, doc: DocEntry[], withGeneral = f
}
export function writeDoc (routepath: string, doc: DocEntry[]) {
+ const isComp = true
const _p = path.parse(routepath)
const Component = childrenMerge(doc, []).find(e => e.name === _p.name) || {}
const ComponentTags = Component.jsTags || []
@@ -361,8 +368,8 @@ export function writeDoc (routepath: string, doc: DocEntry[]) {
get.document(Component.documentation),
get.see(ComponentTags.find(tag => tag.name === 'see')),
get.type(Component.type, 2),
- get.members(Component.members, undefined, 2, name),
- get.members(Component.exports || Component.parameters, '参数', 2, name),
+ get.members(Component.members, undefined, 2, name, isComp),
+ get.members(Component.exports || Component.parameters, '参数', 2, name, isComp),
get.example(ComponentTags),
...doc.map(e => {
const name = e.name || 'undefined'
@@ -380,8 +387,8 @@ export function writeDoc (routepath: string, doc: DocEntry[]) {
get.document(e.documentation),
get.see(tags.find(tag => tag.name === 'see')),
get.type(e.type, 3),
- get.members(e.members, undefined, 3, name),
- get.members(e.exports || e.parameters, '参数', 3, name),
+ get.members(e.members, undefined, 3, name, isComp),
+ get.members(e.exports || e.parameters, '参数', 3, name, isComp),
get.example(tags, 3),
)