This closes #2176, support set transparency for chart and shape

xuri · xuri · commit dd07139785fe · 2025-07-17T08:07:17.000+08:00
- Add Transparency field in the Fill data type
- Add a new exported error variable ErrTransparency
- Update error message for more clear
- Update unit tests
diff --git a/chart_test.go b/chart_test.go
@@ -177,7 +177,7 @@ func TestAddChart(t *testing.T) {
 	series2 := []ChartSeries{
 		{
 			Name: "Sheet1!$A$30", Categories: "Sheet1!$B$29:$D$29", Values: "Sheet1!$B$30:$D$30",
-			Fill:   Fill{Type: "pattern", Color: []string{"000000"}, Pattern: 1},
+			Fill:   Fill{Type: "pattern", Color: []string{"000000"}, Pattern: 1, Transparency: 60},
 			Marker: ChartMarker{Symbol: "none", Size: 10},
 		},
 		{Name: "Sheet1!$A$31", Categories: "Sheet1!$B$29:$D$29", Values: "Sheet1!$B$31:$D$31"},
diff --git a/drawing.go b/drawing.go
@@ -788,7 +788,11 @@ func (f *File) drawShapeFill(fill Fill, spPr *cSpPr) *cSpPr {
 			spPr = &cSpPr{}
 		}
 		if len(fill.Color) == 1 {
-			spPr.SolidFill = &aSolidFill{SrgbClr: &attrValString{Val: stringPtr(strings.TrimPrefix(fill.Color[0], "#"))}}
+			spPr.SolidFill = &aSolidFill{SrgbClr: &aSrgbClr{Val: stringPtr(strings.TrimPrefix(fill.Color[0], "#"))}}
+			if fill.Transparency > 0 {
+				val := (100 - fill.Transparency) * 1000
+				spPr.SolidFill.SrgbClr.Alpha = &attrValInt{Val: &val}
+			}
 			return spPr
 		}
 		spPr.SolidFill = nil
@@ -1186,7 +1190,7 @@ func drawChartFont(fnt *Font, r *aRPr) {
 			r.SolidFill = &aSolidFill{}
 		}
 		r.SolidFill.SchemeClr = nil
-		r.SolidFill.SrgbClr = &attrValString{Val: stringPtr(strings.ReplaceAll(strings.ToUpper(fnt.Color), "#", ""))}
+		r.SolidFill.SrgbClr = &aSrgbClr{Val: stringPtr(strings.ReplaceAll(strings.ToUpper(fnt.Color), "#", ""))}
 	}
 	if fnt.Family != "" {
 		if r.Latin == nil {
diff --git a/errors.go b/errors.go
@@ -60,10 +60,10 @@ var (
 	// family name overflow.
 	ErrFontLength = fmt.Errorf("the length of the font family name must be less than or equal to %d", MaxFontFamilyLength)
 	// ErrFontSize defined the error message on the size of the font is invalid.
-	ErrFontSize = fmt.Errorf("font size must be between %d and %d points", MinFontSize, MaxFontSize)
+	ErrFontSize = fmt.Errorf("font size must be an integer from %d to %d points", MinFontSize, MaxFontSize)
 	// ErrFormControlValue defined the error message for receiving a scroll
 	// value exceeds limit.
-	ErrFormControlValue = fmt.Errorf("scroll value must be between 0 and %d", MaxFormControlValue)
+	ErrFormControlValue = fmt.Errorf("scroll value must be an integer from 0 to %d", MaxFormControlValue)
 	// ErrGroupSheets defined the error message on group sheets.
 	ErrGroupSheets = errors.New("group worksheet must contain an active worksheet")
 	// ErrImgExt defined the error message on receive an unsupported image
@@ -91,7 +91,7 @@ var (
 	ErrOutlineLevel = errors.New("invalid outline level")
 	// ErrPageSetupAdjustTo defined the error message for receiving a page setup
 	// adjust to value exceeds limit.
-	ErrPageSetupAdjustTo = errors.New("adjust to value must be between 10 and 400")
+	ErrPageSetupAdjustTo = errors.New("adjust to value must be an integer from 0 to 400")
 	// ErrParameterInvalid defined the error message on receive the invalid
 	// parameter.
 	ErrParameterInvalid = errors.New("parameter is invalid")
@@ -132,10 +132,10 @@ var (
 	ErrSparklineRange = errors.New("parameter 'Range' is required")
 	// ErrSparklineStyle defined the error message on receive the invalid
 	// sparkline Style parameters.
-	ErrSparklineStyle = errors.New("parameter 'Style' must between 0-35")
+	ErrSparklineStyle = errors.New("parameter 'Style' value must be an integer from 0 to 35")
 	// ErrSparklineType defined the error message on receive the invalid
 	// sparkline Type parameters.
-	ErrSparklineType = errors.New("parameter 'Type' must be 'line', 'column' or 'win_loss'")
+	ErrSparklineType = errors.New("parameter 'Type' value must be one of 'line', 'column' or 'win_loss'")
 	// ErrStreamSetColStyle defined the error message on set column style in
 	// stream writing mode.
 	ErrStreamSetColStyle = errors.New("must call the SetColStyle function before the SetRow function")
@@ -148,6 +148,9 @@ var (
 	// ErrTotalSheetHyperlinks defined the error message on hyperlinks count
 	// overflow.
 	ErrTotalSheetHyperlinks = errors.New("over maximum limit hyperlinks in a worksheet")
+	// ErrTransparency defined the error message for receiving a transparency
+	// value exceeds limit.
+	ErrTransparency = errors.New("transparency value must be an integer from 0 to 100")
 	// ErrUnknownEncryptMechanism defined the error message on unsupported
 	// encryption mechanism.
 	ErrUnknownEncryptMechanism = errors.New("unknown encryption mechanism")
diff --git a/shape.go b/shape.go
@@ -46,6 +46,9 @@ func parseShapeOptions(opts *Shape) (*Shape, error) {
 	if opts.Line.Width == nil {
 		opts.Line.Width = float64Ptr(defaultShapeLineWidth)
 	}
+	if opts.Fill.Transparency < 0 || 100 < opts.Fill.Transparency {
+		return opts, ErrTransparency
+	}
 	return opts, nil
 }
 
@@ -363,7 +366,7 @@ func (f *File) addDrawingShape(sheet, drawingXML, cell string, opts *Shape) erro
 	}
 	var solidColor string
 	if len(opts.Fill.Color) == 1 {
-		solidColor = opts.Fill.Color[0]
+		solidColor = strings.ReplaceAll(strings.ToUpper(opts.Fill.Color[0]), "#", "")
 	}
 	shape := xdrSp{
 		Macro: opts.Macro,
@@ -407,6 +410,13 @@ func (f *File) addDrawingShape(sheet, drawingXML, cell string, opts *Shape) erro
 			W: f.ptToEMUs(*opts.Line.Width),
 		}
 	}
+	if opts.Fill.Transparency > 0 {
+		val := (100 - opts.Fill.Transparency) * 1000
+		shape.SpPr.SolidFill = &aSolidFill{SrgbClr: &aSrgbClr{
+			Val:   stringPtr(solidColor),
+			Alpha: &attrValInt{Val: &val},
+		}}
+	}
 	defaultFont, err := f.GetDefaultFont()
 	if err != nil {
 		return err
@@ -459,7 +469,7 @@ func (f *File) addDrawingShape(sheet, drawingXML, cell string, opts *Shape) erro
 		srgbClr := strings.ReplaceAll(strings.ToUpper(font.Color), "#", "")
 		if len(srgbClr) == 6 {
 			paragraph.R.RPr.SolidFill = &aSolidFill{
-				SrgbClr: &attrValString{
+				SrgbClr: &aSrgbClr{
 					Val: stringPtr(srgbClr),
 				},
 			}
diff --git a/shape_test.go b/shape_test.go
@@ -62,7 +62,7 @@ func TestAddShape(t *testing.T) {
 			Cell: "A1",
 			Type: "ellipseRibbon",
 			Line: ShapeLine{Color: "4286F4", Width: &lineWidth},
-			Fill: Fill{Color: []string{"8EB9FF"}},
+			Fill: Fill{Color: []string{"8EB9FF"}, Transparency: 60},
 			Paragraph: []RichTextRun{
 				{
 					Font: &Font{
@@ -87,6 +87,8 @@ func TestAddShape(t *testing.T) {
 			{Text: "Shape", Font: &Font{Bold: true, Color: "2980B9"}},
 		},
 	}))
+	// Test add shape with transparency value exceeds limit
+	assert.Equal(t, ErrTransparency, f.AddShape("Sheet1", &Shape{Cell: "B30", Type: "rect", Fill: Fill{Color: []string{"8EB9FF"}, Transparency: 110}}))
 	// Test add shape with unsupported charset style sheet
 	f.Styles = nil
 	f.Pkg.Store(defaultXMLPathStyles, MacintoshCyrillicCharset)
diff --git a/sheet_test.go b/sheet_test.go
@@ -219,11 +219,11 @@ func TestSetPageLayout(t *testing.T) {
 	// Test set page layout on not exists worksheet
 	assert.EqualError(t, f.SetPageLayout("SheetN", nil), "sheet SheetN does not exist")
 	// Test set page layout with invalid sheet name
-	assert.EqualError(t, f.SetPageLayout("Sheet:1", nil), ErrSheetNameInvalid.Error())
+	assert.Equal(t, ErrSheetNameInvalid, f.SetPageLayout("Sheet:1", nil))
 	// Test set page layout with invalid parameters
-	assert.EqualError(t, f.SetPageLayout("Sheet1", &PageLayoutOptions{
+	assert.Equal(t, ErrPageSetupAdjustTo, f.SetPageLayout("Sheet1", &PageLayoutOptions{
 		AdjustTo: uintPtr(5),
-	}), "adjust to value must be between 10 and 400")
+	}))
 	assert.EqualError(t, f.SetPageLayout("Sheet1", &PageLayoutOptions{
 		Orientation: stringPtr("x"),
 	}), "invalid Orientation value \"x\", acceptable value should be one of portrait, landscape")
diff --git a/slicer.go b/slicer.go
@@ -633,7 +633,7 @@ func (f *File) addDrawingSlicer(sheet, slicerName string, ns xml.Attr, opts *Sli
 		},
 		SpPr: &xlsxSpPr{
 			Xfrm:      xlsxXfrm{Off: xlsxOff{X: 2914650, Y: 152400}, Ext: xlsxPositiveSize2D{Cx: 1828800, Cy: 2238375}},
-			SolidFill: &xlsxInnerXML{Content: "<a:prstClr val=\"white\"/>"},
+			SolidFill: &aSolidFill{SrgbClr: &aSrgbClr{Val: stringPtr("FFFFFF")}},
 			PrstGeom: xlsxPrstGeom{
 				Prst: "rect",
 			},
diff --git a/sparkline.go b/sparkline.go
@@ -461,7 +461,7 @@ func (f *File) parseFormatAddSparklineSet(sheet string, opts *SparklineOptions)
 	if len(opts.Location) != len(opts.Range) {
 		return ws, ErrSparkline
 	}
-	if opts.Style < 0 || opts.Style > 35 {
+	if opts.Style < 0 || 35 < opts.Style {
 		return ws, ErrSparklineStyle
 	}
 	if ws.ExtLst == nil {
diff --git a/styles.go b/styles.go
@@ -216,6 +216,11 @@ func parseFormatStyleSet(style *Style) (*Style, error) {
 //	 8     | darkUp          | 18    | gray0625
 //	 9     | darkGrid        |       |
 //
+// The 'Fill.Transparency' only use to set transparency for chart and shape, not
+// used for cell. The value of 'Fill.Transparency' should be a number from 0 to
+// 100, which represents 0% to 100%, The default value is 0, representing full
+// opaque (not transparent).
+//
 // The 'Alignment.Indent' is an integer value, where an increment of 1
 // represents 3 spaces. Indicates the number of spaces (of the normal style
 // font) of indentation for text in a cell. The number of spaces to indent is
diff --git a/xmlChart.go b/xmlChart.go
@@ -119,12 +119,47 @@ type aPPr struct {
 	DefRPr aRPr `xml:"a:defRPr"`
 }
 
+// aSrgbClr (RGB Color Model - Hex Variant) specifies a color using the red,
+// green, blue RGB color model. Red, green, and blue is expressed as sequence of
+// hex digits, RRGGBB. A perceptual gamma of 2.2 is used.
+type aSrgbClr struct {
+	Val      *string     `xml:"val,attr"`
+	Tint     *attrValInt `xml:"a:tint"`
+	Shade    *attrValInt `xml:"a:shade"`
+	Comp     *attrValInt `xml:"a:comp"`
+	Inv      *attrValInt `xml:"a:inv"`
+	Gray     *attrValInt `xml:"a:gray"`
+	Alpha    *attrValInt `xml:"a:alpha"`
+	AlphaOff *attrValInt `xml:"a:alphaOff"`
+	AlphaMod *attrValInt `xml:"a:alphaMod"`
+	Hue      *attrValInt `xml:"a:hue"`
+	HueOff   *attrValInt `xml:"a:hueOff"`
+	HueMod   *attrValInt `xml:"a:hueMod"`
+	Sat      *attrValInt `xml:"a:sat"`
+	SatOff   *attrValInt `xml:"a:satOff"`
+	SatMod   *attrValInt `xml:"a:satMod"`
+	Lum      *attrValInt `xml:"a:lum"`
+	LumOff   *attrValInt `xml:"a:lumOff"`
+	LumMod   *attrValInt `xml:"a:lumMod"`
+	Red      *attrValInt `xml:"a:red"`
+	RedOff   *attrValInt `xml:"a:redOff"`
+	RedMod   *attrValInt `xml:"a:redMod"`
+	Green    *attrValInt `xml:"a:green"`
+	GreenOff *attrValInt `xml:"a:greenOff"`
+	GreenMod *attrValInt `xml:"a:greenMod"`
+	Blue     *attrValInt `xml:"a:blue"`
+	BlueOff  *attrValInt `xml:"a:blueOff"`
+	BlueMod  *attrValInt `xml:"a:blueMod"`
+	Gamma    *attrValInt `xml:"a:gamma"`
+	InvGamma *attrValInt `xml:"a:invGamma"`
+}
+
 // aSolidFill (Solid Fill) directly maps the solidFill element. This element
 // specifies a solid color fill. The shape is filled entirely with the specified
 // color.
 type aSolidFill struct {
-	SchemeClr *aSchemeClr    `xml:"a:schemeClr"`
-	SrgbClr   *attrValString `xml:"a:srgbClr"`
+	SchemeClr *aSchemeClr `xml:"a:schemeClr"`
+	SrgbClr   *aSrgbClr   `xml:"a:srgbClr"`
 }
 
 // aSchemeClr (Scheme Color) directly maps the a:schemeClr element. This
diff --git a/xmlDrawing.go b/xmlDrawing.go
@@ -173,7 +173,7 @@ type xlsxLineProperties struct {
 type xlsxSpPr struct {
 	Xfrm      xlsxXfrm           `xml:"a:xfrm"`
 	PrstGeom  xlsxPrstGeom       `xml:"a:prstGeom"`
-	SolidFill *xlsxInnerXML      `xml:"a:solidFill"`
+	SolidFill *aSolidFill        `xml:"a:solidFill"`
 	Ln        xlsxLineProperties `xml:"a:ln"`
 }
 
diff --git a/xmlStyles.go b/xmlStyles.go
@@ -356,10 +356,11 @@ type Font struct {
 
 // Fill directly maps the fill settings of the cells.
 type Fill struct {
-	Type    string
-	Pattern int
-	Color   []string
-	Shading int
+	Type         string
+	Pattern      int
+	Color        []string
+	Shading      int
+	Transparency int
 }
 
 // Protection directly maps the protection settings of the cells.

Original file line number	Diff line number	Diff line change
`@@ -177,7 +177,7 @@ func TestAddChart(t *testing.T) {`
`177`	`177`	`series2 := []ChartSeries{`
`178`	`178`	`{`
`179`	`179`	`Name: "Sheet1!$A$30", Categories: "Sheet1!$B$29:$D$29", Values: "Sheet1!$B$30:$D$30",`
`180`		`- Fill: Fill{Type: "pattern", Color: []string{"000000"}, Pattern: 1},`
	`180`	`+ Fill: Fill{Type: "pattern", Color: []string{"000000"}, Pattern: 1, Transparency: 60},`
`181`	`181`	`Marker: ChartMarker{Symbol: "none", Size: 10},`
`182`	`182`	`},`
`183`	`183`	`{Name: "Sheet1!$A$31", Categories: "Sheet1!$B$29:$D$29", Values: "Sheet1!$B$31:$D$31"},`
Original file line number	Diff line number	Diff line change
`@@ -788,7 +788,11 @@ func (f File) drawShapeFill(fill Fill, spPr cSpPr) *cSpPr {`
`788`	`788`	`spPr = &cSpPr{}`
`789`	`789`	`}`
`790`	`790`	`if len(fill.Color) == 1 {`
`791`		`- spPr.SolidFill = &aSolidFill{SrgbClr: &attrValString{Val: stringPtr(strings.TrimPrefix(fill.Color[0], "#"))}}`
	`791`	`+ spPr.SolidFill = &aSolidFill{SrgbClr: &aSrgbClr{Val: stringPtr(strings.TrimPrefix(fill.Color[0], "#"))}}`
	`792`	`+ if fill.Transparency > 0 {`
	`793`	`+ val := (100 - fill.Transparency) * 1000`
	`794`	`+ spPr.SolidFill.SrgbClr.Alpha = &attrValInt{Val: &val}`
	`795`	`+ }`
`792`	`796`	`return spPr`
`793`	`797`	`}`
`794`	`798`	`spPr.SolidFill = nil`
`@@ -1186,7 +1190,7 @@ func drawChartFont(fnt Font, r aRPr) {`
`1186`	`1190`	`r.SolidFill = &aSolidFill{}`
`1187`	`1191`	`}`
`1188`	`1192`	`r.SolidFill.SchemeClr = nil`
`1189`		`- r.SolidFill.SrgbClr = &attrValString{Val: stringPtr(strings.ReplaceAll(strings.ToUpper(fnt.Color), "#", ""))}`
	`1193`	`+ r.SolidFill.SrgbClr = &aSrgbClr{Val: stringPtr(strings.ReplaceAll(strings.ToUpper(fnt.Color), "#", ""))}`
`1190`	`1194`	`}`
`1191`	`1195`	`if fnt.Family != "" {`
`1192`	`1196`	`if r.Latin == nil {`
Original file line number	Diff line number	Diff line change
`@@ -46,6 +46,9 @@ func parseShapeOptions(opts Shape) (Shape, error) {`
`46`	`46`	`if opts.Line.Width == nil {`
`47`	`47`	`opts.Line.Width = float64Ptr(defaultShapeLineWidth)`
`48`	`48`	`}`
	`49`	`+ if opts.Fill.Transparency < 0 \|\| 100 < opts.Fill.Transparency {`
	`50`	`+ return opts, ErrTransparency`
	`51`	`+ }`
`49`	`52`	`return opts, nil`
`50`	`53`	`}`
`51`	`54`
`@@ -363,7 +366,7 @@ func (f File) addDrawingShape(sheet, drawingXML, cell string, opts Shape) erro`
`363`	`366`	`}`
`364`	`367`	`var solidColor string`
`365`	`368`	`if len(opts.Fill.Color) == 1 {`
`366`		`- solidColor = opts.Fill.Color[0]`
	`369`	`+ solidColor = strings.ReplaceAll(strings.ToUpper(opts.Fill.Color[0]), "#", "")`
`367`	`370`	`}`
`368`	`371`	`shape := xdrSp{`
`369`	`372`	`Macro: opts.Macro,`
`@@ -407,6 +410,13 @@ func (f File) addDrawingShape(sheet, drawingXML, cell string, opts Shape) erro`
`407`	`410`	`W: f.ptToEMUs(*opts.Line.Width),`
`408`	`411`	`}`
`409`	`412`	`}`
	`413`	`+ if opts.Fill.Transparency > 0 {`
	`414`	`+ val := (100 - opts.Fill.Transparency) * 1000`
	`415`	`+ shape.SpPr.SolidFill = &aSolidFill{SrgbClr: &aSrgbClr{`
	`416`	`+ Val: stringPtr(solidColor),`
	`417`	`+ Alpha: &attrValInt{Val: &val},`
	`418`	`+ }}`
	`419`	`+ }`
`410`	`420`	`defaultFont, err := f.GetDefaultFont()`
`411`	`421`	`if err != nil {`
`412`	`422`	`return err`
`@@ -459,7 +469,7 @@ func (f File) addDrawingShape(sheet, drawingXML, cell string, opts Shape) erro`
`459`	`469`	`srgbClr := strings.ReplaceAll(strings.ToUpper(font.Color), "#", "")`
`460`	`470`	`if len(srgbClr) == 6 {`
`461`	`471`	`paragraph.R.RPr.SolidFill = &aSolidFill{`
`462`		`- SrgbClr: &attrValString{`
	`472`	`+ SrgbClr: &aSrgbClr{`
`463`	`473`	`Val: stringPtr(srgbClr),`
`464`	`474`	`},`
`465`	`475`	`}`
Original file line number	Diff line number	Diff line change
`@@ -461,7 +461,7 @@ func (f File) parseFormatAddSparklineSet(sheet string, opts SparklineOptions)`
`461`	`461`	`if len(opts.Location) != len(opts.Range) {`
`462`	`462`	`return ws, ErrSparkline`
`463`	`463`	`}`
`464`		`- if opts.Style < 0 \|\| opts.Style > 35 {`
	`464`	`+ if opts.Style < 0 \|\| 35 < opts.Style {`
`465`	`465`	`return ws, ErrSparklineStyle`
`466`	`466`	`}`
`467`	`467`	`if ws.ExtLst == nil {`