{"_id":"@caohaitao/v-scroll-bar","name":"@caohaitao/v-scroll-bar","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@caohaitao/v-scroll-bar","version":"1.0.0","type":"module","main":"./dist/v-scroll.js","exports":{".":"./dist/v-scroll.js"},"scripts":{"dev":"vite","build":"./build.sh","preview":"vite preview"},"devDependencies":{"@biomejs/biome":"^2.4.6","lightningcss":"^1.24.0","vite":"^7.0.0"},"_id":"@caohaitao/v-scroll-bar@1.0.0","gitHead":"ad8b9df20215226973f9dd39038745b8c9e900c2","description":"一个基于 Web Components 的轻量级自定义滚动条组件。使用 **Vite 7** 构建，利用 **Shadow DOM** 封装内部结构，支持通过 **Import Map** 或构建工具别名灵活切换主题。","_nodeVersion":"20.17.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-SeTNKhTUPXua7eJAYCoDRKE3qAB1H8eMFzwbs/WPzgShhGXS68YPlSq9XBwsiWU7exQdLYM3rHig6UkKLlkcRQ==","shasum":"459f33f453bea0b0059911cc72267bff3c3e976e","tarball":"https://registry.npmjs.org/@caohaitao/v-scroll-bar/-/v-scroll-bar-1.0.0.tgz","fileCount":7,"unpackedSize":22362,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD3w0KMiw8TS/4fORcxBwt8Ys8XnzFLiFrUXExR65sKYAIgWjDbxDQ64ulPkqdpQCYKbUKU2lqP/PR2ZQuY7kkNZXU="}]},"_npmUser":{"name":"caohaitaocc","email":"caohaitaocc@126.com"},"directories":{},"maintainers":[{"name":"caohaitaocc","email":"caohaitaocc@126.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/v-scroll-bar_1.0.0_1773388513038_0.009467437463983597"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-13T07:55:12.981Z","1.0.0":"2026-03-13T07:55:13.172Z","modified":"2026-03-13T07:55:13.351Z"},"maintainers":[{"name":"caohaitaocc","email":"caohaitaocc@126.com"}],"description":"一个基于 Web Components 的轻量级自定义滚动条组件。使用 **Vite 7** 构建，利用 **Shadow DOM** 封装内部结构，支持通过 **Import Map** 或构建工具别名灵活切换主题。","readme":"\n# v-scroll\n\n一个基于 Web Components 的轻量级自定义滚动条组件。使用 **Vite 7** 构建，利用 **Shadow DOM** 封装内部结构，支持通过 **Import Map** 或构建工具别名灵活切换主题。\n\n## 特性\n\n- **原生规范**：基于 Web Components 标准，无框架依赖。\n- **Shadow DOM**：内部结构样式隔离，通过 `::part()` 暴露样式钩子。\n- **主题分离**：样式通过外部模块引入，支持运行时切换主题。\n- **高性能**：使用 `lightningcss` 压缩，利用 `ResizeObserver` 监听尺寸变化。\n\n---\n\n## 安装\n\n```bash\n# npm\nnpm install v-scroll\n\n# pnpm\npnpm add v-scroll\n\n# bun\nbun add v-scroll\n```\n\n---\n\n## 使用指南\n\n由于组件逻辑依赖外部样式模块（`$/v-scroll.js`），你需要根据项目类型选择对应的配置方式。\n\n### 方式一：构建工具项目 (Vite / Webpack / Rollup)\n\n推荐在构建配置中将样式模块指向实体文件。\n\n**1. 配置别名**\n\n组件代码中引用了 `$/v-scroll.js`，你需要在构建工具中将其别名指向真实的物理文件路径。\n\n```javascript\n// vite.config.js\nimport { defineConfig } from 'vite';\nimport path from 'path';\n\nexport default defineConfig({\n  resolve: {\n    alias: {\n      // 将虚拟模块 $/v-scroll.js 指向 node_modules 中的实际主题文件\n      '$/v-scroll.js': path.resolve(__dirname, 'node_modules/v-scroll/dist/theme/v-scroll.js')\n    }\n  }\n});\n```\n\n**2. 在代码中使用**\n\n```javascript\n// main.js\nimport 'v-scroll'; // 导入即注册自定义元素\n```\n\n```html\n<!-- HTML -->\n<v-scroll style=\"height: 300px;\">\n  <p>你的滚动内容...</p>\n</v-scroll>\n```\n\n---\n\n### 方式二：原生 HTML / CDN 引入\n\n在无构建工具的场景下，需要配合 `Import Map` 和 `node_modules` 路径映射。\n\n**1. 复制静态资源**\n\n将 `node_modules/v-scroll/dist` 目录复制到你的静态资源目录（假设为 `/public/lib/v-scroll/`）。\n\n**2. 配置 Import Map**\n\n```html\n<head>\n  <!-- 配置模块路径 -->\n  <script type=\"importmap\">\n  {\n    \"imports\": {\n      \"v-scroll\": \"./lib/v-scroll/v-scroll.js\",\n      \"$/\": \"./lib/v-scroll/theme/\"\n    }\n  }\n  </script>\n</head>\n<body>\n  <v-scroll style=\"height: 300px;\">\n    <p>内容...</p>\n  </v-scroll>\n\n  <script type=\"module\">\n    import 'v-scroll';\n  </script>\n</body>\n```\n\n---\n\n## 主题与样式定制\n\n组件样式默认注入到页面的 `<head>` 中（全局生效），通过 **CSS 变量** 和 **::part()** 伪类实现深度定制。\n\n### CSS 变量覆盖\n\n通过设置宿主元素的 CSS 变量即可修改外观：\n\n```css\nv-scroll {\n  --v-scroll-thumb-width: 6px;               /* 滑块宽度 */\n  --v-scroll-thumb-bg: rgba(0, 0, 0, 0.3);   /* 滑块默认颜色 */\n  --v-scroll-thumb-bg-hover: rgba(0, 0, 0, 0.5); /* 悬停颜色 */\n  --v-scroll-thumb-bg-active: rgba(0, 0, 0, 0.8); /* 拖拽颜色 */\n  --v-scroll-track-expanded-width: 12px;     /* 展开时轨道宽度 */\n}\n```\n\n### 结构化样式 (::part)\n\n组件内部结构通过 `part` 属性暴露，可直接控制布局：\n\n```css\n/* 滚动容器 */\nv-scroll::part(scroll) {\n  scrollbar-width: none; /* 隐藏原生滚动条 */\n}\n\n/* 滚动条轨道 */\nv-scroll::part(bar) {\n  background: transparent;\n}\n\n/* 滚动条滑块 */\nv-scroll::part(thumb) {\n  border-radius: 4px;\n  background: var(--v-scroll-thumb-bg);\n}\n\n/* 交互状态 */\nv-scroll[data-scrolling]::part(thumb) {\n  opacity: 1;\n}\n\nv-scroll[data-dragging]::part(thumb) {\n  background: var(--v-scroll-thumb-bg-active);\n}\n```\n\n---\n\n## 构建产物说明\n\n包发布后的 `dist` 目录结构如下：\n\n```text\ndist/\n├── v-scroll.js        # 组件主入口 (ES Module)\n└── theme/\n    └── v-scroll.js    # 主题模块\n```\n\n**注意**：\n1. 样式文件 (`v-scroll.css`) 已被转换为 JS 模块 (`theme/v-scroll.js`)，**不包含独立的 .css 文件**。\n2. 组件在加载时会自动执行 `import CSS from '$/v-scroll.js'` 并注入到文档中。\n\n---\n\n## 开发与构建\n\n```bash\n# 安装依赖\nbun install\n\n# 开发模式\nbun run dev\n\n# 构建生产包\nbun run build\n\n# 本地预览构建效果\nbun run preview\n```\n\n---\n\n## API 参考\n\n### 属性\n\n| 属性名 | 类型 | 说明 |\n|--------|------|------|\n| `theme` | String | (预留) 主题标识 |\n| `disabled` | Boolean | 禁用滚动 |\n\n### 方法\n\n| 方法名 | 参数 | 说明 |\n|--------|------|------|\n| `scrollTo` | `options` (Number or Object) | 滚动到指定位置，用法同 `Element.scrollTo` |\n| `refresh` | - | 手动刷新滚动条尺寸计算 |\n\n### CSS Parts\n\n| Part 名称 | 说明 |\n|-----------|------|\n| `scroll` | 内部滚动容器 (`overflow: auto`) |\n| `bar` | 滚动条轨道容器 |\n| `thumb` | 滚动条滑块 |\n\n## License\n\nMIT\n```","readmeFilename":"README.md","_rev":"1-2a1f3cb85de3c033f520cfe2bf2867d7"}