master-utils-lib 1.0.1

package/DEVELOPMENT.md

@@ -0,0 +1,274 @@
+# 开发指南
+
+本指南将帮助你在安装 `h5-utils-lib` 后快速开始开发和扩展。
+
+## 📦 安装依赖
+
+安装包后，首先安装开发依赖：
+
+```bash
+npm install
+# 或
+yarn install
+# 或
+pnpm install
+```
+
+## 🏗️ 项目结构
+
+```
+h5-utils-lib/
+├── src/                    # 源代码目录
+│   ├── device/            # 设备检测相关
+│   ├── format/            # 格式化相关
+│   ├── storage/           # 存储相关
+│   ├── url/               # URL 处理相关
+│   ├── validate/          # 验证相关
+│   └── index.ts           # 入口文件
+├── tests/                 # 测试文件
+├── dist/                  # 构建输出（自动生成）
+├── rollup.config.js       # Rollup 构建配置
+├── tsconfig.json          # TypeScript 配置
+├── jest.config.js         # Jest 测试配置
+├── babel.config.js        # Babel 配置
+└── package.json           # 项目配置
+```
+
+## 🚀 开发命令
+
+### 构建项目
+
+```bash
+# 构建生产版本
+npm run build
+
+# 监听模式（开发时使用）
+npm run dev
+```
+
+构建完成后，会在 `dist/` 目录生成以下文件：
+- `index.js` - CommonJS 格式
+- `index.esm.js` - ES Module 格式
+- `index.min.js` - UMD 格式（浏览器直接使用）
+- `types/` - TypeScript 类型定义文件
+
+### 运行测试
+
+```bash
+# 运行所有测试
+npm test
+
+# 监听模式运行测试
+npm run test:watch
+
+# 生成覆盖率报告
+npm run test:coverage
+```
+
+## ✏️ 添加新功能
+
+### 1. 创建新的工具模块
+
+假设要添加一个 `cookie` 相关的工具模块：
+
+```typescript
+// src/cookie/index.ts
+export const setCookie = (name: string, value: string, days?: number): void => {
+  // 实现代码
+};
+
+export const getCookie = (name: string): string | null => {
+  // 实现代码
+};
+
+export const removeCookie = (name: string): void => {
+  // 实现代码
+};
+```
+
+### 2. 在入口文件中导出
+
+```typescript
+// src/index.ts
+export * from './device';
+export * from './url';
+export * from './storage';
+export * from './validate';
+export * from './format';
+export * from './cookie'; // 新增
+```
+
+### 3. 编写测试
+
+```typescript
+// tests/cookie.test.ts
+import { setCookie, getCookie, removeCookie } from '../src/cookie';
+
+describe('Cookie Utils', () => {
+  beforeEach(() => {
+    // 清理 cookies
+    document.cookie.split(";").forEach((c) => {
+      document.cookie = c.replace(/^ +/, "").replace(/=.*/, "=;expires=" + new Date().toUTCString() + ";path=/");
+    });
+  });
+
+  test('setCookie and getCookie', () => {
+    setCookie('test', 'value');
+    expect(getCookie('test')).toBe('value');
+  });
+
+  test('removeCookie', () => {
+    setCookie('test', 'value');
+    removeCookie('test');
+    expect(getCookie('test')).toBeNull();
+  });
+});
+```
+
+### 4. 构建和测试
+
+```bash
+npm run build
+npm test
+```
+
+## 📝 代码规范
+
+### TypeScript 规范
+
+- 使用 TypeScript 严格模式
+- 所有函数都需要类型注解
+- 使用接口定义复杂类型
+- 导出函数需要添加 JSDoc 注释
+
+示例：
+
+```typescript
+/**
+ * 设置 Cookie
+ * @param name Cookie 名称
+ * @param value Cookie 值
+ * @param days 过期天数（可选）
+ */
+export const setCookie = (name: string, value: string, days?: number): void => {
+  // 实现
+};
+```
+
+### 测试规范
+
+- 每个模块都应该有对应的测试文件
+- 测试覆盖率应该保持在 80% 以上
+- 使用描述性的测试用例名称
+
+## 🔧 配置说明
+
+### TypeScript 配置 (`tsconfig.json`)
+
+- `target: "es5"` - 编译目标为 ES5，兼容低版本浏览器
+- `strict: true` - 启用严格模式
+- `declaration: true` - 生成类型定义文件
+
+### Rollup 配置 (`rollup.config.js`)
+
+构建输出三种格式：
+- **CommonJS** (`dist/index.js`) - 用于 Node.js 和传统构建工具
+- **ES Module** (`dist/index.esm.js`) - 用于现代构建工具，支持 Tree Shaking
+- **UMD** (`dist/index.min.js`) - 用于浏览器直接引入
+
+### Babel 配置 (`babel.config.js`)
+
+兼容性目标：
+- IE 11+
+- iOS 9+
+- Android 4.4+
+
+## 📦 发布新版本
+
+### 1. 更新版本号
+
+```bash
+# 补丁版本（1.0.0 -> 1.0.1）
+npm version patch
+
+# 次要版本（1.0.0 -> 1.1.0）
+npm version minor
+
+# 主要版本（1.0.0 -> 2.0.0）
+npm version major
+```
+
+### 2. 构建项目
+
+```bash
+npm run build
+```
+
+### 3. 发布到 npm
+
+```bash
+# 发布到公共 npm
+npm publish
+
+# 发布到私有 npm registry（需要先配置）
+npm publish --registry=https://your-registry.com
+```
+
+### 4. 配置私有 npm registry
+
+如果使用公司私有 npm registry，需要配置：
+
+```bash
+# 设置 registry
+npm config set registry https://your-registry.com
+
+# 或者使用 .npmrc 文件
+echo "registry=https://your-registry.com" > .npmrc
+```
+
+## 🐛 常见问题
+
+### Q: 构建失败怎么办？
+
+A: 检查以下几点：
+1. 确保所有依赖已安装：`npm install`
+2. 检查 TypeScript 类型错误：`npx tsc --noEmit`
+3. 查看 Rollup 错误信息
+
+### Q: 测试失败怎么办？
+
+A: 
+1. 确保测试环境正确配置
+2. 检查测试文件语法
+3. 运行 `npm run test:watch` 查看详细错误
+
+### Q: 如何添加新的构建格式？
+
+A: 编辑 `rollup.config.js`，在 `output` 数组中添加新的配置：
+
+```javascript
+{
+  file: 'dist/index.cjs.js',
+  format: 'cjs',
+  sourcemap: true,
+}
+```
+
+## 📚 相关文档
+
+- [使用示例](./USAGE_EXAMPLES.md) - 详细的使用示例
+- [README](./README.md) - 项目介绍和 API 文档
+- [设计文档](./docs/DESIGN.md) - 架构设计说明
+
+## 🤝 贡献指南
+
+1. Fork 项目
+2. 创建功能分支：`git checkout -b feature/new-feature`
+3. 提交更改：`git commit -am 'Add new feature'`
+4. 推送分支：`git push origin feature/new-feature`
+5. 提交 Pull Request
+
+## 📄 License
+
+ISC
+

package/PUBLISH.md

@@ -0,0 +1,248 @@
+# 发布指南
+
+本指南将帮助你将 `h5-utils-lib` 发布到 npm（公共或私有 registry）。
+
+## 📋 发布前检查清单
+
+- [ ] 确保所有测试通过：`npm test`
+- [ ] 确保代码已构建：`npm run build`
+- [ ] 检查 `package.json` 中的版本号
+- [ ] 更新 `CHANGELOG.md`（如果有）
+- [ ] 确保 `.npmignore` 配置正确
+- [ ] 检查 `files` 字段包含所有需要发布的文件
+
+## 🚀 发布步骤
+
+### 1. 登录 npm
+
+```bash
+# 登录公共 npm
+npm login
+
+# 或登录私有 registry
+npm login --registry=https://your-registry.com
+```
+
+### 2. 更新版本号
+
+使用语义化版本控制（SemVer）：
+
+```bash
+# 补丁版本：修复 bug（1.0.0 -> 1.0.1）
+npm version patch
+
+# 次要版本：新功能，向后兼容（1.0.0 -> 1.1.0）
+npm version minor
+
+# 主要版本：破坏性变更（1.0.0 -> 2.0.0）
+npm version major
+```
+
+或者手动编辑 `package.json` 中的 `version` 字段。
+
+### 3. 构建项目
+
+```bash
+npm run build
+```
+
+这会自动执行 `prepublishOnly` 脚本，确保发布前构建最新代码。
+
+### 4. 发布到 npm
+
+#### 发布到公共 npm
+
+```bash
+npm publish
+```
+
+#### 发布到私有 npm registry
+
+```bash
+# 方式1：使用 --registry 参数
+npm publish --registry=https://your-registry.com
+
+# 方式2：配置 .npmrc 文件
+echo "registry=https://your-registry.com" > .npmrc
+npm publish
+```
+
+#### 发布到 scoped package（推荐用于公司内部）
+
+如果包名是 `@company/h5-utils-lib`：
+
+```bash
+# 发布为公开包
+npm publish --access public
+
+# 发布为私有包（需要 npm 付费账户）
+npm publish --access restricted
+```
+
+### 5. 验证发布
+
+```bash
+# 查看包信息
+npm view h5-utils-lib
+
+# 或安装测试
+npm install h5-utils-lib@latest
+```
+
+## 🔐 配置私有 npm Registry
+
+### 方式1：使用 .npmrc 文件
+
+在项目根目录创建 `.npmrc` 文件：
+
+```
+registry=https://your-registry.com
+```
+
+### 方式2：使用 npm config
+
+```bash
+# 设置全局 registry
+npm config set registry https://your-registry.com
+
+# 或仅针对当前项目
+npm config set registry https://your-registry.com --location=project
+```
+
+### 方式3：使用 .npmrc 配置认证
+
+如果需要认证：
+
+```
+registry=https://your-registry.com
+//your-registry.com/:_authToken=your-token-here
+```
+
+## 📦 发布内容检查
+
+发布前，可以使用以下命令检查将要发布的内容：
+
+```bash
+# 查看将要发布的文件列表
+npm pack --dry-run
+
+# 打包但不发布（生成 .tgz 文件）
+npm pack
+```
+
+## 🏷️ 发布标签
+
+### 发布 beta 版本
+
+```bash
+npm version 1.0.1-beta.1
+npm publish --tag beta
+```
+
+安装时使用：
+```bash
+npm install h5-utils-lib@beta
+```
+
+### 发布 rc 版本
+
+```bash
+npm version 1.0.1-rc.1
+npm publish --tag rc
+```
+
+### 发布正式版本
+
+```bash
+npm publish --tag latest
+# 或直接
+npm publish
+```
+
+## 🔄 更新已发布的版本
+
+### 更新补丁版本
+
+```bash
+npm version patch
+npm publish
+```
+
+### 更新次要版本
+
+```bash
+npm version minor
+npm publish
+```
+
+### 更新主要版本
+
+```bash
+npm version major
+npm publish
+```
+
+## 🗑️ 撤销发布
+
+### 撤销单个版本（24小时内）
+
+```bash
+npm unpublish h5-utils-lib@1.0.1
+```
+
+### 撤销整个包（72小时内）
+
+```bash
+npm unpublish h5-utils-lib --force
+```
+
+⚠️ **注意**：撤销发布有严格的时间限制，请谨慎操作。
+
+## 📝 常见问题
+
+### Q: 发布时提示 "You do not have permission"
+
+A: 
+1. 检查是否已登录：`npm whoami`
+2. 检查包名是否已被占用
+3. 如果是 scoped package，检查 `--access` 参数
+
+### Q: 如何发布到公司私有 registry？
+
+A: 
+1. 配置 `.npmrc` 文件指向私有 registry
+2. 在私有 registry 中创建账户
+3. 使用 `npm login --registry=...` 登录
+4. 使用 `npm publish --registry=...` 发布
+
+### Q: 发布后如何让团队使用？
+
+A: 
+```bash
+# 团队成员安装
+npm install h5-utils-lib --registry=https://your-registry.com
+
+# 或配置 .npmrc
+echo "registry=https://your-registry.com" > .npmrc
+npm install h5-utils-lib
+```
+
+### Q: 如何同时支持公共和私有 registry？
+
+A: 使用 scoped package：
+
+```json
+{
+  "name": "@company/h5-utils-lib",
+  "publishConfig": {
+    "registry": "https://your-registry.com"
+  }
+}
+```
+
+## 🔗 相关资源
+
+- [npm 发布文档](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry)
+- [语义化版本控制](https://semver.org/)
+- [npm 私有包](https://docs.npmjs.com/about-private-packages)
+

package/QUICK_START.md

@@ -0,0 +1,174 @@
+# 快速开始指南
+
+## 🎯 作为开发模板使用
+
+安装 `h5-utils-lib` 后，你可以直接基于此项目继续开发，无需重新搭建项目结构。
+
+### 1. 安装包
+
+```bash
+npm install h5-utils-lib
+```
+
+### 2. 进入项目目录
+
+```bash
+cd node_modules/h5-utils-lib
+```
+
+### 3. 安装开发依赖
+
+```bash
+npm install
+```
+
+### 4. 开始开发
+
+```bash
+# 开发模式（监听文件变化，自动构建）
+npm run dev
+
+# 或手动构建
+npm run build
+
+# 运行测试
+npm test
+```
+
+## 📝 添加新功能示例
+
+### 示例：添加 Cookie 工具函数
+
+1. **创建新模块文件**
+
+```typescript
+// src/cookie/index.ts
+export const setCookie = (name: string, value: string, days?: number): void => {
+  if (typeof document === 'undefined') return;
+  const expires = days 
+    ? `; expires=${new Date(Date.now() + days * 864e5).toUTCString()}` 
+    : '';
+  document.cookie = `${name}=${encodeURIComponent(value)}${expires}; path=/`;
+};
+
+export const getCookie = (name: string): string | null => {
+  if (typeof document === 'undefined') return null;
+  const nameEQ = name + '=';
+  const ca = document.cookie.split(';');
+  for (let i = 0; i < ca.length; i++) {
+    let c = ca[i];
+    while (c.charAt(0) === ' ') c = c.substring(1, c.length);
+    if (c.indexOf(nameEQ) === 0) {
+      return decodeURIComponent(c.substring(nameEQ.length, c.length));
+    }
+  }
+  return null;
+};
+
+export const removeCookie = (name: string): void => {
+  setCookie(name, '', -1);
+};
+```
+
+2. **在入口文件中导出**
+
+```typescript
+// src/index.ts
+export * from './device';
+export * from './url';
+export * from './storage';
+export * from './validate';
+export * from './format';
+export * from './cookie'; // 新增
+```
+
+3. **编写测试**
+
+```typescript
+// tests/cookie.test.ts
+import { setCookie, getCookie, removeCookie } from '../src/cookie';
+
+describe('Cookie Utils', () => {
+  beforeEach(() => {
+    // 清理所有 cookies
+    document.cookie.split(';').forEach((c) => {
+      const eqPos = c.indexOf('=');
+      const name = eqPos > -1 ? c.substr(0, eqPos) : c;
+      document.cookie = `${name}=;expires=Thu, 01 Jan 1970 00:00:00 GMT;path=/`;
+    });
+  });
+
+  test('setCookie and getCookie', () => {
+    setCookie('test', 'value');
+    expect(getCookie('test')).toBe('value');
+  });
+
+  test('setCookie with expiration', () => {
+    setCookie('test', 'value', 7);
+    expect(getCookie('test')).toBe('value');
+  });
+
+  test('removeCookie', () => {
+    setCookie('test', 'value');
+    removeCookie('test');
+    expect(getCookie('test')).toBeNull();
+  });
+});
+```
+
+4. **构建和测试**
+
+```bash
+npm run build
+npm test
+```
+
+## 🚀 发布新版本
+
+### 快速发布
+
+```bash
+# 发布补丁版本（1.0.0 -> 1.0.1）
+npm run publish:patch
+
+# 发布次要版本（1.0.0 -> 1.1.0）
+npm run publish:minor
+
+# 发布主要版本（1.0.0 -> 2.0.0）
+npm run publish:major
+```
+
+### 手动发布
+
+```bash
+# 1. 更新版本号
+npm version patch  # 或 minor, major
+
+# 2. 构建（会自动执行）
+npm run build
+
+# 3. 发布
+npm publish
+
+# 或发布到私有 registry
+npm publish --registry=https://your-registry.com
+```
+
+## 📚 更多文档
+
+- [开发指南](./DEVELOPMENT.md) - 详细的开发文档
+- [使用示例](./USAGE_EXAMPLES.md) - 完整的使用示例
+- [发布指南](./PUBLISH.md) - 详细的发布说明
+- [README](./README.md) - 项目介绍和 API 文档
+
+## 💡 提示
+
+1. **开发时使用监听模式**：`npm run dev` 会自动监听文件变化并重新构建
+2. **测试驱动开发**：先写测试，再实现功能
+3. **保持代码风格一致**：参考现有代码的风格和结构
+4. **及时更新文档**：添加新功能后记得更新 README 和示例文档
+
+## 🆘 遇到问题？
+
+查看 [开发指南](./DEVELOPMENT.md) 中的"常见问题"部分，或查看相关文档。
+