# named-color

**Repository Path**: nodets/named-color

## Basic Information

- **Project Name**: named-color
- **Description**: 一个功能完善的命名颜色库，支持148种CSS标准命名色，提供直接访问、中英文查询及多格式转换功能。支持ESM、CJS和IIFE多种模块格式，适用于浏览器和Node.js环境。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-27
- **Last Updated**: 2025-10-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# named-color

A comprehensive named color library that supports 148 CSS standard named colors, providing direct access, multi-language querying, and multi-format conversion. It supports ESM, CJS, and IIFE module formats, suitable for both browser and Node.js environments.


## Features
- Includes complete information for 148 CSS standard named colors (English/Chinese names, HEX, RGB, HSL)
- Direct access via English color names (e.g., `namedColor.red`)
- Flexible query capabilities: supports English/Chinese names, HEX values, RGB objects, and keyword fuzzy search
- Built-in format conversion: HEX → RGB and RGB → HSL
- Multi-module support: available in ESM, CJS, and IIFE formats for versatile use cases


## Installation
```bash
npm install named-color
# Or
yarn add named-color
```


## Module Support
### 1. ESM (Recommended for Modern Projects)
```javascript
import { namedColor, queryColor, getAllColors } from 'named-color';
```

### 2. CJS (For Node.js Legacy Projects)
```javascript
const { namedColor, queryColor, getAllColors } = require('named-color');
```

### 3. IIFE (For Browser Global Usage)
Import via `<script>` tag, which exposes the global variable `namedcolor` (lowercase):
```html
<script src="https://unpkg.com/named-color/dist/index.global.js"></script>
<script>
  // Use the global variable "namedcolor"
  console.log(namedcolor.namedColor.red.hex); // "#ff0000"
</script>
```


## Type Definitions
The library includes TypeScript type definitions for full autocompletion support.
```typescript
// RGB color component type
interface RGB {
  r: number; // 0-255
  g: number; // 0-255
  b: number; // 0-255
  a?: number; // 0-1 Optional opacity
}

// HSL color component type
interface HSL {
  h: number; // 0-360 Hue
  s: number; // 0-100 Saturation (percentage)
  l: number; // 0-100 Lightness (percentage)
  a?: number; // 0-1 Optional opacity
}

// Complete color information type
interface ColorInfo {
  name: string; // English name (e.g., "red")
  chinese: string; // Chinese name (e.g., "红色")
  hex: string; // HEX value (e.g., "#ff0000")
  rgb: RGB; // RGB color object
  hsl: HSL; // HSL color object
}
```


## Usage Examples

### 1. Direct Color Access
Get complete color information directly via English names:
```javascript
import { namedColor } from 'named-color';

// Get full information for "red"
console.log(namedColor.red);
// Output:
// {
//   name: 'red',
//   chinese: '红色',
//   hex: '#ff0000',
//   rgb: { r: 255, g: 0, b: 0 },
//   hsl: { h: 0, s: 100, l: 50 }
// }

// Get HEX value of "blue"
console.log(namedColor.blue.hex); // "#0000ff"

// Get RGB value of "green"
console.log(namedColor.green.rgb); // { r: 0, g: 128, b: 0 }
```

### 2. Color Query
Use the `queryColor` function for flexible searches:
```javascript
import { queryColor } from 'named-color';

// 1. Query by Chinese name
const result1 = queryColor('红色');
console.log(result1[0].hex); // "#ff0000"

// 2. Query by English name
const result2 = queryColor('blue');
console.log(result2[0].chinese); // "蓝色"

// 3. Query by HEX value (with or without "#")
const result3 = queryColor('#ffff00');
console.log(result3[0].name); // "yellow"

// 4. Query by RGB object (fuzzy match, default tolerance: 10)
const result4 = queryColor({ r: 250, g: 0, b: 0 }, 10);
console.log(result4[0].name); // "red" (difference between 250 and 255 is within tolerance)

// 5. Fuzzy query by keyword
const result5 = queryColor('light');
console.log(result5.map(c => c.name)); // All colors with "light" in their English name
```

### 3. Get All Colors
Retrieve the full list of 148 named colors:
```javascript
import { getAllColors } from 'named-color';

const allColors = getAllColors();
console.log(allColors.length); // 148
```


## Browser Usage (IIFE)
```html
<script src="https://unpkg.com/named-color/dist/index.global.js"></script>
<script>
  // Access via the global "namedcolor" variable
  console.log(namedcolor.namedColor.pink.hex); // "#ffc0cb"
  
  // Query colors containing "green" in Chinese
  const greenColors = namedcolor.queryColor('绿');
  console.log(greenColors.map(c => c.name)); // English names of all green-related colors
</script>
```


## License
MIT