From ad902f6cec0067dbc03a43902304571eff87bcfd Mon Sep 17 00:00:00 2001 From: ZakaryCode Date: Mon, 27 Jan 2020 14:45:22 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20=E8=A1=A5=E5=85=A8=E7=BB=84=E4=BB=B6?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E8=84=9A=E6=9C=AC=E7=94=9F=E6=88=90=20fix=20?= =?UTF-8?q?#4908?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/components/viewContainer/scroll-view.md | 105 +++++---- .../taro-components/types/ScrollView.d.ts | 211 ++++++++++++++---- scripts/docs-api.ts | 27 ++- 3 files changed, 247 insertions(+), 96 deletions(-) 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), )