@weitutech/by-components 1.1.18 → 1.1.19

package/README.md

@@ -52,6 +52,20 @@ npm publish --access public
 项目中运行 npm link @weitutech/by-components
 ```
 
+> **💡 提示**  
+> 本地link调试时，需要把组件库的package.json中的main字段改为src/index.js（"main": "src/index.js"）  
+> 调试完成后，切记改回 "main": "lib/by-components.umd.js",
+
+### 组件文档构建
+
+```
+npm run docs:dev
+npm run docs:build
+文档部署到Github Pages: npm run docs:deploy
+```
+
+[组件文档·Github Pages](https://heqican.github.io/by-frontend-components-docs/)
+
 ### 关于新组件开发
 
 1. 采用 by 为前缀命名方式

package/deploy.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env sh
+
+# 脚本作用：将组件文档 部署到GitHub Pages
+
+# 确保脚本抛出遇到的错误
+set -e
+
+# 生成静态文件
+npm run docs:build
+
+# 进入生成的文件夹
+cd docs/.vuepress/dist
+
+# 如果是发布到自定义域名
+# echo 'www.example.com' > CNAME
+
+git init
+git add -A
+git commit -m 'deploy docs'
+
+# 部署到GitHub Pages
+git branch -M gh-pages
+git push -f https://github.com/heqican/by-frontend-components-docs gh-pages
+
+cd - 

package/docs-setup-guide.md

@@ -0,0 +1,338 @@
+# By Components 文档搭建指南
+
+本指南介绍了如何为 Vue2 组件库搭建 VuePress 文档网站的完整过程。
+
+## 📁 文档结构
+
+```
+docs/
+├── .vuepress/                    # VuePress 配置目录
+│   ├── config.js                 # 主配置文件
+│   ├── enhanceApp.js             # 应用增强配置
+│   └── public/                   # 静态资源
+│       ├── favicon.ico           # 网站图标
+│       └── logo.png              # 网站 Logo
+├── guide/                        # 指南文档
+│   ├── README.md                 # 指南首页
+│   ├── installation.md          # 安装指南
+│   └── quick-start.md            # 快速上手
+├── components/                   # 组件文档
+│   ├── README.md                 # 组件总览
+│   ├── form.md                   # 表单组件
+│   ├── table.md                  # 表格组件
+│   ├── pager.md                  # 分页组件
+│   ├── page-search.md            # 页面搜索组件
+│   ├── fold-search.md            # 折叠搜索组件
+│   ├── select.md                 # 选择器组件
+│   └── date-picker-range.md      # 日期范围选择器
+└── README.md                     # 文档首页
+```
+
+## 🚀 快速开始
+
+### 1. 安装依赖
+
+```bash
+npm install --save-dev vuepress@1.9.10 @vuepress/plugin-back-to-top @vuepress/plugin-medium-zoom
+```
+
+### 2. 添加构建脚本
+
+在 `package.json` 中添加：
+
+```json
+{
+  "scripts": {
+    "docs:dev": "vuepress dev docs",
+    "docs:build": "vuepress build docs"
+  }
+}
+```
+
+### 3. 启动开发服务器
+
+```bash
+npm run docs:dev
+```
+
+### 4. 构建生产版本
+
+```bash
+npm run docs:build
+```
+
+## ⚙️ 配置说明
+
+### VuePress 配置 (docs/.vuepress/config.js)
+
+```javascript
+const path = require('path')
+
+module.exports = {
+  title: 'By Components',
+  description: '基于 Vue2 + Element UI 的业务组件库',
+  base: '/',
+
+  themeConfig: {
+    nav: [
+      { text: '指南', link: '/guide/' },
+      { text: '组件', link: '/components/' }
+    ],
+    sidebar: {
+      '/guide/': [
+        /* 指南侧边栏 */
+      ],
+      '/components/': [
+        /* 组件侧边栏 */
+      ]
+    }
+  },
+
+  plugins: ['@vuepress/back-to-top', '@vuepress/medium-zoom']
+}
+```
+
+### 应用增强配置 (docs/.vuepress/enhanceApp.js)
+
+```javascript
+import Vue from 'vue'
+import ElementUI from 'element-ui'
+import 'element-ui/lib/theme-chalk/index.css'
+import ByComponents from '../../src/index.js'
+import '../../src/style/index.scss'
+
+Vue.use(ElementUI)
+Vue.use(ByComponents)
+```
+
+## 📝 编写文档
+
+### 组件文档模板
+
+每个组件文档应包含以下部分：
+
+1. **组件介绍** - 简述组件功能和用途
+2. **基础用法** - 展示最简单的使用方式
+3. **高级用法** - 展示复杂场景的使用方式
+4. **API 文档** - 详细的属性、事件、方法说明
+
+### 示例代码
+
+```markdown
+# 组件名称
+
+组件简介...
+
+## 基础用法
+
+<template>
+  <component-name :prop="value" @event="handler" />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      value: 'example'
+    }
+  },
+  methods: {
+    handler() {
+      // 处理逻辑
+    }
+  }
+}
+</script>
+
+## API
+
+### Props
+
+| 参数 | 说明     | 类型   | 默认值 |
+| ---- | -------- | ------ | ------ |
+| prop | 属性说明 | string | ''     |
+
+### Events
+
+| 事件名 | 说明     | 参数    |
+| ------ | -------- | ------- |
+| event  | 事件说明 | (value) |
+```
+
+## 🎨 主题定制
+
+### 自定义样式
+
+可以在 `docs/.vuepress/styles/` 目录下添加自定义样式：
+
+```
+docs/.vuepress/styles/
+├── index.styl      # 全局样式
+├── palette.styl    # 主题色彩配置
+└── override.styl   # 样式覆盖
+```
+
+### 主题色彩配置
+
+```stylus
+// docs/.vuepress/styles/palette.styl
+$accentColor = #3eaf7c
+$textColor = #2c3e50
+$borderColor = #eaecef
+$codeBgColor = #282c34
+```
+
+## 🔧 常用插件
+
+### 推荐插件列表
+
+```bash
+# 返回顶部
+npm install @vuepress/plugin-back-to-top
+
+# 图片缩放
+npm install @vuepress/plugin-medium-zoom
+
+# 代码复制
+npm install vuepress-plugin-copy-code
+
+# 全文搜索
+npm install @vuepress/plugin-search
+
+# Google Analytics
+npm install @vuepress/plugin-google-analytics
+```
+
+### 插件配置
+
+```javascript
+module.exports = {
+  plugins: [
+    '@vuepress/back-to-top',
+    '@vuepress/medium-zoom',
+    [
+      'copy-code',
+      {
+        copySelector: ['div[class*="language-"] pre', 'div[class*="aside-code"] aside']
+      }
+    ],
+    [
+      '@vuepress/search',
+      {
+        searchMaxSuggestions: 10
+      }
+    ]
+  ]
+}
+```
+
+## 🚀 部署
+
+### GitHub Pages
+
+1. 配置 `base` 路径：
+
+```javascript
+module.exports = {
+  base: '/your-repo-name/'
+  // ...
+}
+```
+
+2. 创建部署脚本：
+
+```bash
+#!/usr/bin/env sh
+
+# 确保脚本抛出遇到的错误
+set -e
+
+# 生成静态文件
+npm run docs:build
+
+# 进入生成的文件夹
+cd docs/.vuepress/dist
+
+git init
+git add -A
+git commit -m 'deploy'
+
+# 推送到 gh-pages 分支
+git push -f git@github.com:username/repo.git master:gh-pages
+
+cd -
+```
+
+### Netlify
+
+1. 连接 GitHub 仓库
+2. 设置构建命令：`npm run docs:build`
+3. 设置发布目录：`docs/.vuepress/dist`
+
+## 📊 性能优化
+
+### 1. 代码分割
+
+```javascript
+// 异步加载组件示例
+const ComponentDemo = () => import('./components/ComponentDemo.vue')
+```
+
+### 2. 图片优化
+
+- 使用 WebP 格式
+- 添加图片懒加载
+- 压缩图片资源
+
+### 3. 构建优化
+
+```javascript
+module.exports = {
+  chainWebpack: (config, isServer) => {
+    // 优化构建配置
+    config.optimization.splitChunks({
+      chunks: 'all'
+    })
+  }
+}
+```
+
+## 🛠️ 维护指南
+
+### 更新组件文档
+
+1. 当添加新组件时，在 `docs/components/` 目录下创建对应的 `.md` 文件
+2. 在 `docs/.vuepress/config.js` 的 `sidebar` 配置中添加新页面
+3. 更新组件总览页面 `docs/components/README.md`
+
+### 版本管理
+
+- 使用语义化版本控制
+- 维护 CHANGELOG.md
+- 及时更新文档内容
+
+### 内容审查
+
+- 定期检查文档的准确性
+- 确保示例代码可以正常运行
+- 保持文档风格一致
+
+## 📚 参考资源
+
+- [VuePress 官方文档](https://vuepress.vuejs.org/)
+- [Element UI 官方文档](https://element.eleme.cn/)
+- [Markdown 语法指南](https://www.markdownguide.org/)
+- [Vue.js 官方文档](https://cn.vuejs.org/)
+
+---
+
+## 🎉 完成！
+
+恭喜你已经成功搭建了 Vue2 组件库的文档网站！现在你可以：
+
+1. ✅ 访问 http://localhost:8080 查看文档
+2. ✅ 编写和更新组件文档
+3. ✅ 自定义主题和样式
+4. ✅ 部署到生产环境
+
+如有问题，请参考上述配置或查阅官方文档。