2022-03-04

目录

1. Web颜色

   • HTML4
   • CSS1
   • CSS2
   • CSS3
   • HTML5

2. 介绍

3. 安装

4. 导入

5. 规范

   • 对于十六进制值指定的颜色
   • 对于整数和百分数rgb()三元组
   • 对于颜色名称

6. 内容

   • 数据类型

     • webcolors.IntegerRGB(red, green, blue)
     • webcolors.PercentRGB(red, green, blue)
     • webcolors.HTML5SimpleColor(red, green, blue)

   • 常量

     • 规格标识符

       webcolors.CSS2 == "css2"

       webcolors.CSS21 == "css21"

       webcolors.CSS3 == "css3"

       webcolors.HTML4 == "html4"

     • 从名称到十六进制值的映射

       webcolors.HTML4_NAMES_TO_HEX

       webcolors.CSS2_NAMES_TO_HEX

       webcolors.CSS21_NAMES_TO_HEX

       webcolors.CSS3_NAMES_TO_HEX

     • 从十六进制值到名称的映射

       webcolors.HTML4_HEX_TO_NAMES

       webcolors.CSS2_HEX_TO_NAMES

       webcolors.CSS21_HEX_TO_NAMES

       webcolors.CSS3_HEX_TO_NAMES

   • 归一化函数

     • webcolors.normalize_hex(hex_value)
     • webcolors.normalize_integer_triplet(rgb_triplet)
     • webcolors.normalize_percent_triplet(rgb_triplet)

   • 颜色名称 —— 十六进制、整数rgb三元组、百分数rgb三元组

     • webcolors.name_to_hex(name, spec=CSS3)
     • webcolors.name_to_rgb(name, spec=CSS3)
     • webcolors.name_to_rgb_percent(name, spec=CSS3)

   • 十六进制字符串 —— 颜色名称、整数rgb三元组、百分数rgb三元组

     • webcolors.hex_to_name(hex_value, spec=CSS3)
     • webcolors.hex_to_rgb(hex_value)
     • webcolors.hex_to_rgb_percent(hex_value)

   • 整数rgb三元组 —— 颜色名称、十六进制、百分数rgb三元组

     • webcolors.rgb_to_name(rgb_triplet, spec=CSS3)
     • webcolors.rgb_to_hex(rgb_triplet)
     • webcolors.rgb_to_rgb_percent(rgb_triplet)

   • 百分数rgb三元组 —— 颜色名称、十六进制、整数rgb三元组

     • webcolors.rgb_percent_to_name(rgb_percent_triplet, spec=CSS3)
     • webcolors.rgb_percent_to_hex(rgb_percent_triplet)
     • webcolors.rgb_percent_to_rgb(rgb_percent_triplet)

   • HTML5 颜色算法

     • webcolors.html5_parse_simple_color(input)
     • webcolors.html5_parse_legacy_color(input)
     • webcolors.html5_serialize_simple_color(simple_color)

Web颜色

web上的颜色通常在RGB颜色空间中指定，每种颜色由红色分量、绿色分量和蓝色分量组成，这三者映射到计算机显示器像素的红色分量、绿色分量和蓝色分量，以及人眼的三种视锥细胞。Web颜色的每个分量由8位二进制组成，所以一种颜色是3 * 8 = 24位。一共有2^8 * 2^8 * 2^8 = 256 * 256 * 256 = 16,777,216 中颜色。

1. HTML4

   • “#”后跟三对十六进制数字，按顺序指定红、绿、蓝三个分量的值。如“#0099cc”。

   • 一组预定义的颜色名称，对应于特定的十六进制值。HTML4定义了16种，如“blue”。

     "aqua": "#00ffff",
     "black": "#000000",
     "blue": "#0000ff",
     "fuchsia": "#ff00ff",
     "green": "#008000",
     "gray": "#808080",
     ......
     

2. CSS1

   • “#”后跟三个十六进制数字，通过重复每个数字来扩展为三个十六进制对。如“#09c” == “#0099cc”。

   • 字符串“rgb”后跟三个范围在（0~255）的十进制整数，分别被视为红、绿、蓝的分量值。如“rgb(0, 153, 204)”.

   • 同上，但以百分数取而代之。如“rgb(0%, 60%, 50%)”。

     CSS1还建议一组16种颜色名称。这些名称与HTML 4中定义的集合相同，但是CSS1没有提供它们的值的定义，并声明它们取自“Windows VGA调色板”。

3. CSS2

   在颜色部分中，CSS2允许使用与CSS1相同的方法来指定颜色，并为16种命名的颜色定义和提供值，与HTML 4中的集合相同。

   CSS2还指定了系统颜色的名称列表。它们没有固定的颜色值，但会从操作系统或其他用户界面获取值，并允许元素使用与周围用户界面相同的颜色进行样式化。这些名称在CSS3中已被弃用。

   "aqua": "#00ffff",
   "black": "#000000",
   "blue": "#0000ff",
   "fuchsia": "#ff00ff",
   ......
   

   CSS2.1版本没有添加任何指定RGB颜色的新方法，但定义了一个额外的名为颜色:“orange”。

   "aqua": "#00ffff",
   "black": "#000000",
   "blue": "#0000ff",
   "fuchsia": "#ff00ff",
   "green": "#008000",
   "gray": "#808080",
   "lime": "#00ff00",
   ......  
   

4. CSS3

   CSS3颜色模块增加了一种指定颜色的新方法:

   一个色调-饱和度-亮度三元组(HSL)，使用构造hsl(h, s, l)。
   CSS3还增加了对颜色不透明度的支持，通过rgba(r, g, b, a)和hsla(h, s, l, a)构造允许alpha通道信息的规范。它们的使用类似于rgb()和hsl()构造，只是提供了第四个值，表示不透明度级别从0.0(完全透明)到1.0(完全不透明)。虽然从技术上来说不是一种颜色，但关键字transparent也可用来代替颜色值，并对应于rgba(0,0,0,0)。

   CSS3还新定义了一组147个颜色名称。该集合直接取自为SVG (Scalable Vector Graphics)标记定义的命名颜色，是CSS2.1中定义的命名颜色的超集。

   1. "aliceblue": "#f0f8ff",
      "antiquewhite": "#faebd7",
      "aqua": "#00ffff",
      "aquamarine": "#7fffd4",
      "azure": "#f0ffff",
      "beige": "#f5f5dc",
      "bisque": "#ffe4c4",
      "black": "#000000",
      "blanchedalmond": "#ffebcd",
      ......
      

5. HTML5

   HTML5没有引入任何指定颜色的新方法，但简化了对颜色的描述，并引入了有用的术语。

   • 简单颜色

     一组三个八位数代表RGB颜色的红、绿、蓝分量。

   • 有效简单颜色

     以“#”开头紧跟六个ASCII十六进制数字的七个字符字符串。如“#A-Fa-f0-9”。

   • 有效小写简单颜色

     仅使用小写ASCII十六进制数字表示的有效简单颜色。如“#a-f0-9”。

介绍

这个模块提供了实用函数，用于处理HTML和CSS规范定义的颜色名称和颜色值格式，以便在web文档中使用。

webcolors模块支持以下方法来指定RGB颜色，以及它们之间的转换:：

1. HTML4、CSS2、CSS2.1和CSS3的已定义命名颜色
2. 六位十六进制
3. 三位十六进制
4. 整数rgb(r, g, b)三元组
5. 百分数rgb(r, g, b)三元组

webcolors模块不支持：

1. CSS1命名的没有定义值的颜色
2. CSS2没有固定值的系统颜色
3. 指示颜色的有效缺失的透明关键字
4. 通过rgba()构造指定的Opacity/alpha-channel信息
5. 通过HSL()或hsla()构造在HSL颜色空间中指定的颜色

安装

pip install webcolors

导入

import webcolors

规范

webcolors中的函数的字符串参数必须传入str类型，不能是bytes类型。

1. 对于十六进制值指定的颜色

   • 输入

     • 字符#后面跟着三个十六进制数字，其中数字A-F可以是大写或小写。如“#AF0”或“#af0”。

     • 字符#后面跟着六个十六进制数字，其中数字A-F可以是大写或小写。如“#AAFF00”或“#aaff00”。

       （当所有数字都是大写时，HTML5指定一个“有效的简单颜色”，当所有数字都是小写时，指定一个“有效的小写简单颜色”)

   • 输出

     • 字符#后面跟着6个十六进制数字，数字a - f被强制变成小写(这是HTML5指定的“有效的小写简单颜色”)。即“#aaff00”

   如果需要，可以使用函数normalize_hex()手动执行这种归一化。

2. 对于整数和百分数rgb()三元组

   使用整型rgb()三元组的函数接受它们为Python的int三元组。

   使用percentage rgb()三元组的函数接受它们为Python的字符串三元组。

   所有处理整数或百分比rgb()三元组的函数都接受纯元组，但也提供了三种类型的namedtuple()来表示这些值:IntegerRGB表示整数三元组，PercentRGB表示百分比三元组，HTML5SimpleColor表示HTML5简单颜色。返回整数或百分比rgb()三元组或HTML5简单颜色的函数将返回这些类型的值。

   在内部，Python float用于与三元组表示的某些转换;对于每个函数，其结果的精度可能受此影响，在文档中提供了说明。

   对于通过rgb()三元组指定的颜色，包含在三元组中的值将按照CSS裁剪规则被规范化:

   • 小于0的整数值将被规范化为0，小于0%的百分比值将被规范化为0%。
   • 大于255的整数值将被规范化为255，大于100%的百分比值将被规范化为100%。
   • --0和-0%将分别归一化为0和0%。

   如果需要，可以使用函数normalize_integer_triplet()和normalize_percent_triplet()手动执行这种标准化。

3. 对于颜色名称

   对于通过预定义名称指定的颜色，webcolors将接受包含名称 大小写不敏感 的字符串，只要它们不包含空格或非字母字符。因此，例如，' AliceBlue '和' aliceblue '都被接受，并且都将指向相同的颜色:rgb(240,248,255)。

   对于由颜色名称组成的输出，以及在返回另一种格式的结果之前执行中间转换到预定义名称的函数，webcolors总是将这些值规范化为完全小写。

   HTML 4、CSS1和CSS2都定义了一种名为"gray"的颜色。在CSS3中，这个颜色可以命名为"gray"或"grey"，其他几个相关的颜色值在CSS3中各有两个名称:"darkgray/darkgrey", "darkslategray/darkslategrey", "dimgray/dimgrey", "lightgray/lightgrey", "lightslategray/lightslategrey", "slategray/slategrey"。

   从十六进制值、整数元组或百分比元组反转到这些颜色的名称，需要选择一种拼写，而webcolors选择灰色"gray"拼写，以与HTML 4、CSS1和CSS2保持一致。

内容

1. 数据类型

   • webcolors.IntegerRGB(red, green, blue)

     参数

     • red: int （0~255）。
     • green: int（0~255）。
     • blue: int（0~255）。

     返回

     创建一个IntegerRGB对象。

• webcolors.PercentRGB(red, green, blue)

  参数

  • red: str （%0~100%）。
  • green: str （%0~100%）。
  • blue: str （%0~100%）。

  返回

  创建一个PercentRGB对象。

• webcolors.HTML5SimpleColor(red, green, blue)

  参数

  • red: int （0~255）。
  • green: int（0~255）。
  • blue: int（0~255）。

  返回

  创建一个HTML5SimpleColor对象。

2. 常量

   • 规格标识符

   webcolors.CSS2 == "css2"
   
   webcolors.CSS21 == "css21"
   
   webcolors.CSS3 == "css3"
   
   webcolors.HTML4 == "html4"
   

   • 从名称到十六进制值的映射

    webcolors.HTML4_NAMES_TO_HEX == {'aqua': '#00ffff', 'black': '#000000', 'blue': '#0000ff', ...}
     
    webcolors.CSS2_NAMES_TO_HEX == {'aqua': '#00ffff', 'black': '#000000', 'blue': '#0000ff', ...}
     
    webcolors.CSS21_NAMES_TO_HEX == {'orange': '#ffa500', 'aqua': '#00ffff', ...}
     
    webcolors.CSS3_NAMES_TO_HEX == {'aliceblue': '#f0f8ff', 'antiquewhite': '#faebd7', ...}
   

• 从十六进制值到名称的映射

webcolors.HTML4_HEX_TO_NAMES == {'#00ffff': 'aqua', '#000000': 'black', '#0000ff': 'blue', ...}

webcolors.CSS2_HEX_TO_NAMES == {'#00ffff': 'aqua', '#000000': 'black', '#0000ff': 'blue', ...}

webcolors.CSS21_HEX_TO_NAMES == {'#ffa500': 'orange', '#00ffff': 'aqua', '#000000': 'black', ...}

webcolors.CSS3_HEX_TO_NAMES == {'#f0f8ff': 'aliceblue', '#faebd7': 'antiquewhite', ...}

3. 归一化函数

   • webcolors.normalize_hex(hex_value)

     将16进制颜色值归一化为一个字符串，由字符#后跟6个小写16进制数字组成(HTML5称之为“有效的小写简单颜色”)。

     参数

     • hex_value: str。要归一化的十六进制颜色值。

     返回

     str。归一化后的十六进制颜色值。

     示例

     # 标准则正常输出
     webcolors.normalize_hex('#0099cc') --> '#0099cc'    
     
     # 全部小写化
     webcolors.normalize_hex('#0099CC') --> '#0099cc'    
     
     # 三位转六位
     webcolors.normalize_hex('#09c')     --> '#0099cc'    
     
     # 三位转六位并全部小写化
     webcolors.normalize_hex('#09C')    --> '#0099cc'    
     

• webcolors.normalize_integer_triplet(rgb_triplet)

  归一化一个整数rgb()三元组，使所有值都在（0~255）范围内。

  参数

  • rgb_triplet: tuple。要归一化的整数rgb()三元组或IntegerRGB对象。

  返回

  归一化后的IntegerRGB对象。

  示例

  # 标准则正常输出
  webcolors.normalize_integer_triplet((128, 128, 128)) --> IntegerRGB(red=128, green=128, blue=128)
  
  # >255的值化为255，<0的值化为0，-0化为0
  webcolors.normalize_integer_triplet((270, -20, -0)) --> IntegerRGB(red=255, green=0, blue=0)
  webcolors.normalize_integer_triplet(webcolors.IntegerRGB(270, -20, -0)) --> IntegerRGB(red=255, green=0, blue=0)
  

• webcolors.normalize_percent_triplet(rgb_triplet)

  归一化一个百分数rgb()三元组，使所有值都在（0%~100%）范围内。

  参数

  • rgb_triplet: tuple。要归一化的百分数rgb()三元组或PercentRGB对象。

  返回

  归一化后的PercentRGB对象。

  示例

  # 标准则正常输出
  webcolors.normalize_percent_triplet(('50%', '50%', '50%')) --> PercentRGB(red='50%', green='50%', blue='50%')
  
  # >100%的值化为100%，<0%的值化为0%，-0%化为0%
  webcolors.normalize_percent_triplet(('-10%', '-0%', '500%')) --> PercentRGB(red='0%', green='0%', blue='100%')
  webcolors.normalize_percent_triplet(webcolors.PercentRGB('-10%', '-0%', '500%')) --> PercentRGB(red='0%', green='0%', blue='100%')
  

4. 颜色名称 —— 十六进制、整数rgb三元组、百分数rgb三元组

   • webcolors.name_to_hex(name, spec=CSS3)

     参数

     • name:str。颜色名称。
     • spec: [webcolors.CSS3, webcolors.HTML4, webcolors.CSS2, webcolors.CSS21], 默认webcolors.CSS3。指定转换标准。指定颜色名称必须在该规范中定义了值。

     返回

     str。六位十六进制字符串。

     示例

     webcolors.name_to_hex("red") --> "#ff0000"
     

• webcolors.name_to_rgb(name, spec=CSS3)

  参数

  • name:str。颜色名称。
  • spec: [webcolors.CSS3, webcolors.HTML4, webcolors.CSS2, webcolors.CSS21], 默认webcolors.CSS3。指定转换标准。指定颜色名称必须在该规范中定义了值。

  返回

  IntegerRGB对象。

  示例

  webcolors.name_to_rgb("red") --> IntegerRGB(red=255, green=0, blue=0)
  

• webcolors.name_to_rgb_percent(name, spec=CSS3)

  参数

  • name:str。颜色名称。
  • spec: [webcolors.CSS3, webcolors.HTML4, webcolors.CSS2, webcolors.CSS21], 默认webcolors.CSS3。指定转换标准。指定颜色名称必须在该规范中定义了值。

  返回

  PercentRGB对象。

  示例

  webcolors.name_to_rgb_percent("red") --> PercentRGB(red='100%', green='0%', blue='0%')
  

5. 十六进制 —— 颜色名称、整数rgb三元组、百分数rgb三元组

   • webcolors.hex_to_name(hex_value, spec=CSS3)

     参数

     • hex_value:str。三位十六进制字符串或六位十六进制字符串。
     • spec: [webcolors.CSS3, webcolors.HTML4, webcolors.CSS2, webcolors.CSS21], 默认webcolors.CSS3。指定转换标准。指定颜色名称必须在该规范中定义了值。

     返回

     str。颜色名称。

     示例

     webcolors.hex_to_name("#fff") --> "white"
     
     webcolors.hex_to_name("#ffffff") --> "white"
     

• webcolors.hex_to_rgb(hex_value)

  参数

  • hex_value:str。三位十六进制字符串或六位十六进制字符串。

  返回

  IntegerRGB对象。

  示例

  webcolors.hex_to_rgb("#fff") --> IntegerRGB(red=255, green=255, blue=255)
  
  webcolors.hex_to_rgb("#ffffff") --> IntegerRGB(red=255, green=255, blue=255)
  

• webcolors.hex_to_rgb_percent(hex_value)

  参数

  • hex_value:str。三位十六进制字符串或六位十六进制字符串。

  返回

  PercentRGB对象。

  示例

  webcolors.hex_to_rgb_percent("#fff") --> PercentRGB(red='100%', green='100%', blue='100%')
  
  webcolors.hex_to_rgb_percent("#ffffff") --> PercentRGB(red='100%', green='100%', blue='100%')
  

6. 整数rgb三元组 —— 颜色名称、十六进制、百分数rgb三元组

   • webcolors.rgb_to_name(rgb_triplet, spec=CSS3)

     参数

     • rgb_triplet:整数三元组或IntegerRGB对象。
     • spec: [webcolors.CSS3, webcolors.HTML4, webcolors.CSS2, webcolors.CSS21], 默认webcolors.CSS3。指定转换标准。指定颜色名称必须在该规范中定义了值。

     返回

     str。颜色名称。

     示例

     webcolors.rgb_to_name((255, 0, 0)) --> "red"
     
     webcolors.rgb_to_name(webcolors.IntegerRGB(255, 0, 0)) --> "red"
     

• webcolors.rgb_to_hex(rgb_triplet)

  参数

  • rgb_triplet:整数三元组或IntegerRGB对象。

  返回

  str。六位十六进制颜色字符串。

  示例

  webcolors.rgb_to_hex((255, 0, 0)) --> "#ff0000"
  
  webcolors.rgb_to_hex(webcolors.IntegerRGB(255, 0, 0)) --> "#ff0000"
  

• webcolors.rgb_to_rgb_percent(rgb_triplet)

  参数

  • rgb_triplet:整数三元组或IntegerRGB对象。

  返回

     `PercentRGB`对象。
  

  示例

  webcolors.rgb_to_rgb_percent((255, 0, 0)) --> PercentRGB(red='100%', green='0%', blue='0%')
  
  webcolors.rgb_to_rgb_percent(webcolors.IntegerRGB(255, 0, 0)) --> PercentRGB(red='100%', green='0%', blue='0%')
  

7. 百分数rgb三元组 —— 颜色名称、十六进制、整数rgb三元组

   • webcolors.rgb_percent_to_name(rgb_percent_triplet, spec=CSS3)

     参数

     • rgb_percent_triplet:百分数三元组或 PercentRGB对象。
     • spec: [webcolors.CSS3, webcolors.HTML4, webcolors.CSS2, webcolors.CSS21], 默认webcolors.CSS3。指定转换标准。指定颜色名称必须在该规范中定义了值。

     返回

     str。颜色名称。

     示例

     webcolors.rgb_percent_to_name(("100%", "0%", "0%")) --> "red"
     
     webcolors.rgb_percent_to_name(webcolors.PercentRGB("100%", "0%", "0%")) --> "red"
     

• webcolors.rgb_percent_to_hex(rgb_percent_triplet)

  参数

  • rgb_percent_triplet:百分数三元组或 PercentRGB对象。

  返回

  str。六位十六进制字符串。

  示例

  webcolors.rgb_percent_to_hex(("100%", "0%", "0%")) --> "#ff0000"
  
  webcolors.rgb_percent_to_hex(webcolors.PercentRGB("100%", "0%", "0%")) --> "#ff0000"
  

• webcolors.rgb_percent_to_rgb(rgb_percent_triplet)

  参数

  • rgb_percent_triplet:百分数三元组或 PercentRGB对象。

  返回

  IntegerRGB对象。

  示例

  webcolors.rgb_percent_to_rgb(("100%", "0%", "0%")) --> IntegerRGB(red=255, green=0, blue=0)
  
  webcolors.rgb_percent_to_rgb(webcolors.PercentRGB("100%", "0%", "0%")) --> IntegerRGB(red=255, green=0, blue=0)
  

8. HTML5 颜色算法

• webcolors.html5_parse_simple_color(input)

  应用HTML5简单的颜色解析算法。

  参数

  • input: str。必须是六位十六进制字符串。

  返回

  HTML5SimpleColor对象。

  示例

  webcolors.html5_parse_simple_color("#ff00cc") --> HTML5SimpleColor(red=255, green=0, blue=204)
  

• webcolors.html5_parse_legacy_color(input)

  应用HTML5传统的颜色解析算法。

  参数

  • input: str。颜色名称、三位十六进制或六位十六进制。不能是“transparent"。

  返回

  HTML5SimpleColor对象。

  示例

  webcolors.html5_parse_legacy_color("red") --> HTML5SimpleColor(red=255, green=0, blue=0)
  
  webcolors.html5_parse_legacy_color("#fca") --> HTML5SimpleColor(red=255, green=204, blue=170)
  
  webcolors.html5_parse_legacy_color("#ffccaa") --> HTML5SimpleColor(red=255, green=204, blue=170)
  

• webcolors.html5_serialize_simple_color(simple_color)

  应用HTML5简单的颜色序列化算法。

  参数

  • simple_color: tuple。必须是整数三元组。

  返回

  str。六位十六进制颜色字符串。

  示例

  webcolors.html5_serialize_simple_color((255,134,233)) --> "#ff86e9"