Hướng dẫn python docx font color

Color, as a topic, extends beyond the Font object; font color is just the first place it’s come up. Accordingly, it bears a little deeper thought than usual since we’ll want to reuse the same objects and protocol to specify color in the other contexts; it makes sense to craft a general solution that will bear the expected reuse.

There are three historical sources to draw from for this API.

1. The w:rPr/w:color element. This is used by default when applying color directly to text or when setting the text color of a style. This corresponds to the Font.Color property [undocumented, unfortunately]. This element supports RGB colors, theme colors, and a tint or shade of a theme color.
2. The w:rPr/w14:textFill element. This is used by Word for fancy text like gradient and shadow effects. This corresponds to the Font.Fill property.
3. The PowerPoint font color UI. This seems like a reasonable compromise between the prior two, allowing direct-ish access to common color options while holding the door open for the Font.fill operations to be added later if required.

Candidate Protocol¶

docx.text.run.Run has a font property:

>>> from docx import Document
>>> from docx.text.run import Font, Run
>>> run = Document[].add_paragraph[].add_run[]
>>> isinstance[run, Run]
True
>>> font = run.font
>>> isinstance[font, Font]
True

docx.text.run.Font has a read-only color property, returning a docx.dml.color.ColorFormat object:

>>> from docx.dml.color import ColorFormat
>>> color = font.color
>>> isinstance[font.color, ColorFormat]
True
>>> font.color = 'anything'
AttributeError: can't set attribute

docx.dml.color.ColorFormat has a read-only type property and read/write rgb, theme_color, and brightness properties.

ColorFormat.type returns one of MSO_COLOR_TYPE.RGB, MSO_COLOR_TYPE.THEME, MSO_COLOR_TYPE.AUTO, or None, the latter indicating font has no directly-applied color:

ColorFormat.rgb returns an RGBColor object when type is MSO_COLOR_TYPE.RGB. It may also report an RGBColor value when type is MSO_COLOR_TYPE.THEME, since an RGB color may also be present in that case. According to the spec, the RGB color value is ignored when a theme color is specified, but Word writes the current RGB value of the theme color along with the theme color name [e.g. ‘accent1’] when assigning a theme color; perhaps as a convenient value for a file browser to use. The value of .type must be consulted to determine whether the RGB value is operative or a “best-guess”:

>>> font.color.type
RGB [1]
>>> font.color.rgb
RGBColor[0x3f, 0x2c, 0x36]

Assigning an RGBColor value to ColorFormat.rgb causes ColorFormat.type to become MSO_COLOR_TYPE.RGB:

>>> font.color.type
None
>>> font.color.rgb = RGBColor[0x3f, 0x2c, 0x36]
>>> font.color.type
RGB [1]
>>> font.color.rgb
RGBColor[0x3f, 0x2c, 0x36]

ColorFormat.theme_color returns a member of MSO_THEME_COLOR_INDEX when type is MSO_COLOR_TYPE.THEME:

>>> font.color.type
THEME [2]
>>> font.color.theme_color
ACCENT_1 [5]

Assigning a member of MSO_THEME_COLOR_INDEX to ColorFormat.theme_color causes ColorFormat.type to become MSO_COLOR_TYPE.THEME:

>>> font.color.type
RGB [1]
>>> font.color.theme_color = MSO_THEME_COLOR.ACCENT_2
>>> font.color.type
THEME [2]
>>> font.color.theme_color
ACCENT_2 [6]

The ColorFormat.brightness attribute can be used to select a tint or shade of a theme color. Assigning the value 0.1 produces a color 10% brighter [a tint]; assigning -0.1 produces a color 10% darker [a shade]:

>>> font.color.type
None
>>> font.color.brightness
0.0
>>> font.color.brightness = 0.4
ValueError: not a theme color

>>> font.color.theme_color = MSO_THEME_COLOR.TEXT_1
>>> font.color.brightness = 0.4
>>> font.color.brightness
0.4

Specimen XML¶

Baseline paragraph with no font color:

  
    Text with no color.
  

Paragraph with directly-applied RGB color:

  
    
      
    
  
  
    
      
    
    Directly-applied color Blue.
  

Run with directly-applied theme color:

  
    
  
  Theme color Accent 1.

Run with 40% tint of Text 2 theme color:

  
    
  
  Theme color with 40% tint.

Run with 25% shade of Accent 2 theme color:

  
    
  
  Theme color with 25% shade.

Schema excerpt¶