快速开始

本指南将帮助你快速上手 Shared Library，了解基本用法和核心概念。

第一个示例

让我们从一个简单的颜色转换示例开始：

// 导入单个函数 - 获得最佳的 tree-shaking 效果
import { convertColor } from 'zcw-shared/functions/color/convertColor'

// 将 HEX 颜色转换为 RGB
const rgbColor = convertColor('#ff0000', 'rgb')
console.log(rgbColor) // 输出: rgb(255, 0, 0)

// 将 RGB 颜色转换为 HSL
const hslColor = convertColor('rgb(255, 0, 0)', 'hsl')
console.log(hslColor) // 输出: hsl(0, 100%, 50%)

环境 API 注入

Shared Library 的核心特性是环境无关性。对于需要环境 API 的函数，你需要传入相应的环境对象：

浏览器环境

import { compressToTargetSize } from 'zcw-shared/functions/image/compressToTargetSize'

// 在浏览器中压缩图片
const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement
const file = fileInput.files?.[0]

if (file) {
  const compressedFile = await compressToTargetSize(
    file,
    { targetSize: 100 * 1024 }, // 100KB
    {
      Image: window.Image,
      File: window.File,
      createObjectURL: window.URL.createObjectURL.bind(window.URL),
      createElement: document.createElement.bind(document)
    }
  )
  console.log('压缩完成:', compressedFile)
}

Node.js 环境

import { JSDOM } from 'jsdom'
import { modifyManifest } from 'zcw-shared/functions/android/modifyManifest'
import fs from 'fs'
import xpath from 'xpath'

// 在 Node.js 中修改 Android Manifest
const dom = new JSDOM()
const manifestPath = 'AndroidManifest.xml'

const modifiedXml = modifyManifest(
  manifestPath,
  [{ xpath: '//manifest', action: 'setAttribute', attributeName: 'package', value: 'com.example.app' }],
  {
    existsSync: fs.existsSync,
    readFileSync: fs.readFileSync,
    writeFileSync: fs.writeFileSync,
    xmlParser: dom.window.DOMParser,
    xmlSerializer: dom.window.XMLSerializer,
    xpath
  }
)

错误处理

Shared Library 提供了完善的错误处理机制：

import { convertColor } from 'zcw-shared/functions/color/convertColor'
import { validateColor } from 'zcw-shared/functions/color/colorValidation'

try {
  const result = convertColor('invalid-color', 'rgb')
} catch (error) {
  console.error('颜色转换失败:', error.message)
}

// 或者使用验证函数
const color = 'invalid-color'
if (validateColor(color)) {
  const result = convertColor(color, 'rgb')
} else {
  console.error('无效的颜色格式')
}

类型支持

如果你使用 TypeScript，Shared Library 提供了完整的类型定义：

import type { ColorFormat, ConvertOptions } from 'zcw-shared/types/color'
import { convertColor } from 'zcw-shared/functions/color/convertColor'

const format: ColorFormat = 'rgb'
const options: ConvertOptions = {
  alpha: true,
  precision: 2
}

const result = convertColor('#ff0000', format, options)
// TypeScript 会提供完整的类型检查和自动补全

按需导入 - 库的核心优势

Shared Library 采用单函数导入设计，这是我们库的核心优势：

✨ 为什么这样设计？

• 极致的 Tree-Shaking - 只打包你实际使用的代码，零冗余
• 更小的包体积 - 每个函数独立，按需加载
• 更快的构建速度 - 减少打包器的解析负担
• 更清晰的依赖关系 - 一目了然地知道使用了哪些功能

导入方式

导入函数

// ✅ 导入单个函数
import { convertColor } from 'zcw-shared/functions/color/convertColor'
import { validateColor } from 'zcw-shared/functions/color/colorValidation'
import { compressToTargetSize } from 'zcw-shared/functions/image/compressToTargetSize'

导入 Hooks

// ✅ 导入 hooks
import { useCache } from 'zcw-shared/reactive/useCache'
import { useLocalStorage } from 'zcw-shared/reactive/useLocalStorage'

导入常量

// ✅ 导入常量
import { COLOR_PATTERNS } from 'zcw-shared/constants/colorPatterns'
import { NAMED_COLORS } from 'zcw-shared/constants/namedColors'

导入类型定义

// ✅ 导入类型
import type { ColorFormat } from 'zcw-shared/types/color'
import type { AndroidBuildOptions } from 'zcw-shared/types/android-build'

如何找到函数路径？

所有导出路径遵循统一规则：

• 函数：zcw-shared/functions/{分类}/{模块名}/{文件名}
• Vue Hooks：zcw-shared/vue-hooks/{hookName}
• 响应式（跨框架）：zcw-shared/reactive/{hookName}
• 常量：zcw-shared/constants/{constantName}
• 类型：zcw-shared/types/{typeName}

你可以在 API 文档 中查看每个函数的完整导入路径。

下一步

现在你已经了解了基本用法，可以：

• 查看 架构设计 了解实现原理
• 查看 API 参考 了解所有可用函数和使用示例