From 0472b1031045858898d9af1c5fe81c6c1b2092fd Mon Sep 17 00:00:00 2001 From: neverland Date: Sat, 19 Nov 2022 16:32:54 +0800 Subject: [PATCH] docs(BackTop): update demo and document (#11272) --- packages/vant/src/back-top/BackTop.tsx | 32 +++++--- packages/vant/src/back-top/README.md | 73 +++++++++++------ packages/vant/src/back-top/README.zh-CN.md | 79 +++++++++++++------ packages/vant/src/back-top/demo/index.vue | 35 +++++--- packages/vant/src/back-top/index.less | 8 +- .../test/__snapshots__/demo.spec.ts.snap | 21 ++++- 6 files changed, 172 insertions(+), 76 deletions(-) diff --git a/packages/vant/src/back-top/BackTop.tsx b/packages/vant/src/back-top/BackTop.tsx index 6e090cefa..89468fe05 100644 --- a/packages/vant/src/back-top/BackTop.tsx +++ b/packages/vant/src/back-top/BackTop.tsx @@ -45,18 +45,20 @@ export type BackTopProps = ExtractPropTypes; export default defineComponent({ name, + inheritAttrs: false, + props: backTopProps, emits: ['click'], - setup(props, { emit, slots }) { + setup(props, { emit, slots, attrs }) { const show = ref(false); const scrollParent = ref(); - const backTopEl = ref(null); + const root = ref(null); let target: Window | HTMLElement; - const backTopStyle = computed(() => ({ + const style = computed(() => ({ right: addUnit(props.right), bottom: addUnit(props.bottom), })); @@ -73,8 +75,6 @@ export default defineComponent({ show.value = getScrollTop(target) >= props.visibilityHeight; }; - const throttleScroll = throttle(scroll, 300); - const getTarget = () => { const { target } = props; @@ -86,19 +86,23 @@ export default defineComponent({ return el as HTMLElement; } - if (isObject(target)) return target; + if (isObject(target)) { + return target; + } + throw Error( '[Vant] BackTop: type of prop "target" should be a selector or an element object' ); }; - useEventListener('scroll', throttleScroll, { target: scrollParent }); + useEventListener('scroll', throttle(scroll, 300), { target: scrollParent }); + onMounted(() => { nextTick(() => { if (inBrowser) { target = props.target ? (getTarget() as typeof target) - : (getScrollParent(backTopEl.value!) as typeof target); + : (getScrollParent(root.value!) as typeof target); scrollParent.value = target; } }); @@ -107,14 +111,20 @@ export default defineComponent({ return () => { const Content = (
- {slots.default ? slots.default() : } + {slots.default ? ( + slots.default() + ) : ( + + )}
); + if (props.teleport) { return {Content}; } diff --git a/packages/vant/src/back-top/README.md b/packages/vant/src/back-top/README.md index 254eaf16f..b9ab37057 100644 --- a/packages/vant/src/back-top/README.md +++ b/packages/vant/src/back-top/README.md @@ -20,69 +20,90 @@ app.use(BackTop); ### Basic Usage -```html - +Please scroll the demo page to display the back top button. - +```html + ``` ```js export default { setup() { const list = [...Array(50).keys()]; + return { list }; + }, +}; +``` + +### Custom Position + +Using `right` and `bottom` props to set the position of BackTop component. + +```html + + +``` + +```js +export default { + setup() { + const list = [...Array(50).keys()]; + return { list }; }, }; ``` ### Custom Content +Using the default slot to custom content. + ```html - -
Custom Content
- +Back Top + + ``` ```js export default { setup() { const list = [...Array(50).keys()]; + return { list }; }, }; ``` -```css -.custom { - width: 200px; - line-height: 40px; - text-align: center; -} -``` - ### Set Scroll Target ```html
- +
+ + ``` ```js export default { setup() { const list = [...Array(50).keys()]; + return { list }; }, }; ``` -```css -.container { - height: 300px; - overflow: auto; -} -``` - ## API ### Props @@ -101,6 +122,14 @@ export default { | ------- | ------------------------- | | default | customize default content | +### Types + +The component exports the following type definitions: + +```ts +import type { BackTopProps, BackTopThemeVars } from 'vant'; +``` + ## Theming ### CSS Variables diff --git a/packages/vant/src/back-top/README.zh-CN.md b/packages/vant/src/back-top/README.zh-CN.md index 132f0a7d5..d130dbc08 100644 --- a/packages/vant/src/back-top/README.zh-CN.md +++ b/packages/vant/src/back-top/README.zh-CN.md @@ -20,80 +20,99 @@ app.use(BackTop); ### 基础用法 -通过滚动 Demo 页面查看右下角按钮。 +请滚动示例页面来查看右下角的返回顶部按钮。 ```html - - - + ``` ```js export default { setup() { const list = [...Array(50).keys()]; + return { list }; + }, +}; +``` + +### 自定义位置 + +通过 `right` 和 `bottom` 属性来设置组件距离右侧和底部的位置。 + +```html + + +``` + +```js +export default { + setup() { + const list = [...Array(50).keys()]; + return { list }; }, }; ``` ### 自定义内容 +使用默认插槽来自定义组件展示的内容。 + ```html - -
自定义内容
- +返回顶部 + + ``` ```js export default { setup() { const list = [...Array(50).keys()]; + return { list }; }, }; ``` -```css -.custom { - width: 200px; - line-height: 40px; - text-align: center; -} -``` +### 设置滚动目标 -### 设置监听目标 - -可以通过设置 `target` 控制监听哪个元素触发 Back Top。 +可以通过 `target` 属性来设置触发滚动的目标对象，支持传入选择器或 `HTMLElement`。 ```html
- +
+ + ``` ```js export default { setup() { const list = [...Array(50).keys()]; + return { list }; }, }; ``` -```css -.container { - height: 300px; - overflow: auto; -} -``` - ## API ### Props | 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | -| target | 触发滚动的目标对象，支持`selector`和`HTMLElement` | _string \| HTMLElement_ | - | +| target | 触发滚动的目标对象，支持传入选择器或 `HTMLElement` | _string \| HTMLElement_ | - | | right | 距离页面右侧的距离，默认单位为 `px` | _number \| string_ | `30` | | bottom | 距离页面底部的距离，默认单位为 `px` | _number \| string_ | `40` | | visibility-height | 滚动高度达到此参数值才显示 | _number_ | `200` | @@ -105,6 +124,14 @@ export default { | ------- | ------------------ | | default | 自定义按钮显示内容 | +### 类型定义 + +组件导出以下类型定义： + +```ts +import type { BackTopProps, BackTopThemeVars } from 'vant'; +``` + ## 主题定制 ### 样式变量 diff --git a/packages/vant/src/back-top/demo/index.vue b/packages/vant/src/back-top/demo/index.vue index f2f3770d6..5fdf66f40 100644 --- a/packages/vant/src/back-top/demo/index.vue +++ b/packages/vant/src/back-top/demo/index.vue @@ -8,50 +8,61 @@ import { useTranslate } from '../../../docs/site'; const t = useTranslate({ 'zh-CN': { + backTop: '返回顶部', customContent: '自定义内容', - setScrollTarget: '设置监听目标', + customPosition: '自定义位置', + setScrollTarget: '设置滚动目标', }, 'en-US': { + backTop: 'Back Top', customContent: 'Custom Content', + customPosition: 'Custom Position', setScrollTarget: 'Set Scroll Target', }, }); +const activeTab = ref(0); const list = [...Array(50).keys()]; const targetEl = ref(); diff --git a/packages/vant/src/back-top/index.less b/packages/vant/src/back-top/index.less index 3518f5484..ce4c1a0ea 100644 --- a/packages/vant/src/back-top/index.less +++ b/packages/vant/src/back-top/index.less @@ -10,8 +10,8 @@ display: flex; align-items: center; justify-content: center; - min-width: var(--van-back-top-size); - min-height: var(--van-back-top-size); + width: var(--van-back-top-size); + height: var(--van-back-top-size); cursor: pointer; color: var(--van-back-top-text-color); border-radius: var(--van-radius-max); @@ -21,14 +21,14 @@ background-color: var(--van-back-top-background); &:active { - opacity: 0.6; + opacity: var(--van-active-opacity); } &--active { transform: scale(1); } - .van-icon { + &__icon { font-size: var(--van-back-top-icon-size); font-weight: var(--van-font-bold); } diff --git a/packages/vant/src/back-top/test/__snapshots__/demo.spec.ts.snap b/packages/vant/src/back-top/test/__snapshots__/demo.spec.ts.snap index 68d17fbf3..e2c2e6458 100644 --- a/packages/vant/src/back-top/test/__snapshots__/demo.spec.ts.snap +++ b/packages/vant/src/back-top/test/__snapshots__/demo.spec.ts.snap @@ -26,7 +26,7 @@ exports[`should render demo and match snapshot 1`] = ` aria-controls="van-tab" > - Custom Content + Custom Position
+ + Custom Content + +
+ + `;