{"id":16324059,"url":"https://github.com/lionad-morotar/use-scrollbar","last_synced_at":"2025-03-22T21:32:49.612Z","repository":{"id":65557036,"uuid":"590370638","full_name":"Lionad-Morotar/use-scrollbar","owner":"Lionad-Morotar","description":"Use-Scrollbar enables a component relies on a native scrollbar to replace its native scrollbar with a virtual scrollbar instead, NOT virtual scroll.","archived":false,"fork":false,"pushed_at":"2024-02-16T14:40:37.000Z","size":849,"stargazers_count":12,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"dev","last_synced_at":"2025-03-18T15:16:13.017Z","etag":null,"topics":["directive","hook","scroll","scrollbar","virtual","vue","vue3"],"latest_commit_sha":null,"homepage":"","language":"Vue","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Lionad-Morotar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-18T09:00:59.000Z","updated_at":"2025-02-19T06:51:42.000Z","dependencies_parsed_at":"2023-12-14T16:50:40.436Z","dependency_job_id":"e3b821c3-73a7-448e-90e3-d56f04031c38","html_url":"https://github.com/Lionad-Morotar/use-scrollbar","commit_stats":{"total_commits":84,"total_committers":1,"mean_commits":84.0,"dds":0.0,"last_synced_commit":"76970680910bd917d4b89afa2bf653c7c3a5f6aa"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lionad-Morotar%2Fuse-scrollbar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lionad-Morotar%2Fuse-scrollbar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lionad-Morotar%2Fuse-scrollbar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lionad-Morotar%2Fuse-scrollbar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Lionad-Morotar","download_url":"https://codeload.github.com/Lionad-Morotar/use-scrollbar/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245023436,"owners_count":20548727,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["directive","hook","scroll","scrollbar","virtual","vue","vue3"],"created_at":"2024-10-10T22:56:28.398Z","updated_at":"2025-03-22T21:32:49.184Z","avatar_url":"https://github.com/Lionad-Morotar.png","language":"Vue","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg width=\"555\" alt=\"use-scrollbar\" src=\"./docs/assets/logo.png\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003c!-- npm version --\u003e\n  \u003ca href=\"https://github.com/Lionad-Morotar/use-scrollbar\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/use-scrollbars.svg\" alt=\"npm package\"\u003e\u003c/a\u003e\n  \u003c!-- ci status --\u003e\n  \u003ca href=\"https://github.com/Lionad-Morotar/use-scrollbar/actions/workflows/ci-on-release.yml\"\u003e\u003cimg src=\"https://github.com/Lionad-Morotar/use-scrollbar/actions/workflows/ci-on-release.yml/badge.svg?branch=release\" alt=\"build status\"\u003e\u003c/a\u003e\n  \u003c!-- license --\u003e\n  \u003ca href=\"https://github.com/Lionad-Morotar/use-scrollbar/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/Lionad-Morotar/use-scrollbar\" alt=\"LICENSE\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n# use-scrollbar\n\n`Use-Scrollbar` enables a component relies on a native scrollbar to replace its native scrollbar with a virtual scrollbar instead, NOT virtual scroll.\n\n\u003c/div\u003e\n\n## 🎇 Brief\n\nAssuming a 400px height div, you can easily get a div with beautiful virtual scrollbars by simply wrap the div with [ElementPlus Scrollbar](https://element-plus.gitee.io/zh-CN/component/scrollbar.html) scrollbars. But  none of the popular scrollbar components provide an interface for handling complex elements, that is to say, you cant wrap an complex component with [ElementPlus Scrollbar](https://element-plus.gitee.io/zh-CN/component/scrollbar.html) to have its internal native scrollbar replaced with beautiful virtual scrollbars. So you need `use-scrollbar`.\n\n* [vxe-table example](./play/src/vxe-table.vue)\n* [antd-vue-table example](./play/src/ant-vue-table.vue)\n\n## ⚒️ Feature\n\n- [x] **Powerful API**, have ability to deal with complex components[^1], such as vxe-table、ant-vue-table\n- [x] **Customizable**, so that you can create your own scrollbar style, animation and user interaction\n- [x] **Theme**, integrated with these style configurations: ElementPlus, Steam, CSS-Tricks ...\n- [x] **Full Typed**, with the power of typescript\n- [ ] Support Vue3 \u0026 \u003cdel\u003eVue2\u003c/del\u003e\n- [ ] WIP \u003cdel\u003eVue Directives\u003c/del\u003e\n- [ ] WIP \u003cdel\u003eHeadless Component\u003c/del\u003e\n- [ ] WIP \u003cdel\u003eGithub pages for document and preview\u003c/del\u003e\n\n[^1]: which is not possible with other libraries\n\nand PRs are welcome\n\n## 📸 Preview\n\n\u003ch4\u003e1. Native Scrollbar \u003cstrong\u003eVS\u003c/strong\u003e Customized Scrollbar (theme: default)\u003c/h4\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"555\" alt=\"compare\" src=\"./docs/assets/compare-1.png\"\u003e\n\u003c/p\u003e\n\n\u003ch4\u003e2. Native Scrollbar \u003cstrong\u003eVS\u003c/strong\u003e Customized Scrollbar (theme: css-tricks)\u003c/h4\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"555\" alt=\"compare\" src=\"./docs/assets/compare-3.png\"\u003e\n\u003c/p\u003e\n\n## 🤹‍♀️ Usage\n\nSimple example\n\n```typescript\nimport { onMounted, ref } from 'vue'\nimport { useScrollbar } from 'use-scrollbars'\n\nconst componentOrElementRef = ref(null);\nconst barStates = useScrollbar(componentOrElementRef, {\n  // override default options\n});\n\n// dont forget to import style.css\n// in your main.ts (or entry.ts anyway)\nimport \"use-scrollbars/dist/style.css\"\n```\n\nAnother example\n\n```typescript\nimport { watchEffect, onMounted, ref } from 'vue'\nimport { useScrollbar } from 'use-scrollbars'\n\nconst componentOrElementRef = ref(null);\nconst barStates = useScrollbar(componentOrElementRef, {\n  // override default options\n});\n\nconst componentStates = ref('your-states');\nwatchEffect(() =\u003e {\n  if (componentStates.xxx === 'your-states') {\n    barStates.theme = 'steam'\n  } else {\n    barStates.destroy()\n  }\n})\n```\n\nMore example on `pnpm dev`\n\n## 📦 Install\n\n```bash\npnpm install use-scrollbars\n```\n\n## 🗂️ Document\n\n### 1. States\n\n#### 1.1. barStates.theme\n\n改变滚动条样式。\n\n```typescript\nconst theme = 'normal' // 'normal' | 'steam' | 'css-tricks'\nbarStates.theme = theme\n```\n\n#### 1.2. barStates.offset\n\n改变滚动条相对挂载元素的偏移量。\n\n```typescript\nbarStates.offset.y.top = 10 // px\nbarStates.offset.y.right = 10 // px\nbarStates.offset.x.left = 5 // px\nbarStates.offset.x.bottom = 5 // px\n```\n\n#### 1.3. barStates.scrollTop\n\n如果传入多个 wrapper，那么 scrollTop 属性等同于这几个 wrapper 对应 DOM 元素的最大的哪个 scrollTop 属性。如果需要滚动 wrapper 中的内容，可以给 scrollTop 设置值，也可以使用 [barStates.scrollTo](#barStates-scrollTo) 方法。\n\n#### 1.4. barStates.scrollLeft\n\n类似 [barStates.scrollTop](#barStates-scrollTop)。\n\n#### 1.5. barStates.isDragging\n\n判断当前滚动条是否出于拖动状态。\n\n```typescript\nconsole.log(barStates.isDragging.y)\n```\n\n#### 1.6. barStates.isScrolling\n\n获取当前滚动区域的滚动状态。\n\n```typescript\nconsole.log(barStates.isScrolling.x)\n```\n\n### 2. Actions\n\n#### 2.1. barStates.init\n\n如果不是通过显式初始化（即 `useScrollbar(elem)`）的方式自动初始化滚动条，那么需要使用 init 方法手动初始化。init 方法提供了对控制滚动区（甚至多个滚动区）所需要的更细致的参数。\n\n```typescript\nconst $parent = cmptRef.value.$el.parentElement;\nconst $wrapper = $parent.querySelector(\".content-wrapper\");\nconst $content = $parent.querySelector(\".content\");\n\n// 详细 API 见类型文档\nbarStates.init({\n  mount: cmptRef.value,\n  content: [$content],\n  // 可以不传，默认为 content 的 上一级父元素\n  wrapper: [$wrapper],\n  // 可以不传，默认为 wrapper 或 wrapper 的第一个元素\n  viewport: $wrapper,\n})\n```\n\n#### 2.2. barStates.visibleOnHover\n\n监听传入元素的鼠标事件，mouseenter 时显示滚动条，mouseleave 时隐藏滚动条。\n\n#### 2.3. barStates.setOffset\n\n根据传入元素的尺寸自动设置滚动条的偏移量。在某些场景非常有用，比如你想改变一个弹窗，其滚动区域为整个弹窗内容区域，但是内容区填充了一个 `position:sticky` 头部，此时，如果将滚动条直接挂载到弹窗的内容区域，那么 y 轴滚动条的上方偏移量应为头部的高度。你可以在 barStates.setOffset 中传入此头部元素或组件，动态跟踪其高度并自动设置偏移量。\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"555\" alt=\"use-scrollbar\" src=\"./docs/assets/setOffset-dialog-example.svg\"\u003e\n\u003c/p\u003e\n\n```typescript\nconst cmptOrElemRef = ref(null);\n\nbarStates.setOffset({\n  y: {\n    top: cmptOrElemRef,\n  }\n})\n```\n\n### 3. Hooks\n\n#### 3.1 useScrollbar\n\n等同于 useScrollbars，用于将一个已有的滚动系统的原生滚动条替换为虚拟滚动条，也是这个库最主要的功能。\n\n#### 3.2 useNativeScrollbar\n\n获取原生滚动条相关的一些信息，如宽度。\n\n```typescript\nconst nativeBar = useNativeScrollbar()\n\nconsole.log(nativeBar.thick) // usually 17px in Windows\n```\n\n## 🚩 Dev\n\n```bash\npnpm install\npnpm serve\n```\n\n近期开发路线：接下来会看一下性能方面的优化，以及如何在 Vue2/Vue3 中通用。\n\n## 📄 License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flionad-morotar%2Fuse-scrollbar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flionad-morotar%2Fuse-scrollbar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flionad-morotar%2Fuse-scrollbar/lists"}