This close #2146, support setting excel custom properties (properties in DocProps/custom.xml)

- support save some biz k:v data to excel custom properties to do such that save excel biz version etc.

Change-Id: I4a524b494f09fbfca321d515b5029f4f7361311f
Signed-off-by: mengzhongyuan <mengzhongyuan@bytedance.com>

Author: mengzhongyuan

docProps.go

@@ -16,6 +16,8 @@ import (
 	"encoding/xml"
 	"io"
 	"reflect"
+	"strconv"
+	"time"
 )
 
 // SetAppProps provides a function to set document application properties. The
@@ -206,6 +208,123 @@ func (f *File) SetDocProps(docProperties *DocProperties) error {
 	return err
 }
 
+// SetDocCustomProps provides a function to set excel custom properties, support string, bool, float64,
+// time.DateTime four types.
+func (f *File) SetDocCustomProps(name string, value interface{}) error {
+	customProps := new(xlsxCustomProperties)
+
+	// find existing custom properties
+	if err := f.xmlNewDecoder(bytes.NewReader(namespaceStrictToTransitional(f.readXML(defaultXMLPathDocPropsCustom)))).
+		Decode(customProps); err != nil && err != io.EOF {
+		return err
+	}
+
+	props := customProps.Props
+	existingPropertyMap := make(map[string]xlsxCustomProperty)
+	maxPID := 1 // pid from 2
+	for _, prop := range props {
+		pid, err := strconv.Atoi(prop.PID)
+		if err == nil && pid > maxPID {
+			maxPID = pid
+		}
+
+		existingPropertyMap[prop.Name] = prop
+	}
+
+	// different custom property value type setter function
+	var setValueFunc func(*xlsxCustomProperty) error
+	switch v := value.(type) {
+	case float64:
+		setValueFunc = func(property *xlsxCustomProperty) error {
+			property.Number = &NumberValue{Number: v}
+			return nil
+		}
+	case bool:
+		setValueFunc = func(property *xlsxCustomProperty) error {
+			property.Bool = &BoolValue{Bool: v}
+			return nil
+		}
+	case string:
+		setValueFunc = func(property *xlsxCustomProperty) error {
+			property.Text = &TextValue{Text: v}
+			return nil
+		}
+	case time.Time:
+		setValueFunc = func(property *xlsxCustomProperty) error {
+			property.DateTime = &FileTimeValue{
+				DateTime: v.Format(time.RFC3339),
+			}
+			return nil
+		}
+	default:
+		setValueFunc = func(_ *xlsxCustomProperty) error {
+			return ErrUnsupportedCustomPropertyDataType
+		}
+	}
+
+	// update existing custom properties
+	if existingProperty, ok := existingPropertyMap[name]; ok {
+		if err := setValueFunc(&existingProperty); err != nil {
+			return err
+		}
+	} else {
+		// add new custom property
+		newProperty := xlsxCustomProperty{
+			FmtID: CustomPropertiesFMTID,
+			PID:   strconv.FormatInt(int64(maxPID+1), 10), // max pid plus 1 to create a new unique pid
+			Name:  name,
+		}
+
+		if err := setValueFunc(&newProperty); err != nil {
+			return err
+		}
+
+		props = append(props, newProperty)
+	}
+
+	newCustomProps := &xlsxCustomProperties{
+		Vt:    NameSpaceDocumentPropertiesVariantTypes.Value,
+		Props: props,
+	}
+
+	output, err := xml.Marshal(newCustomProps)
+	f.saveFileList(defaultXMLPathDocPropsCustom, output)
+
+	// set custom properties if necessary
+	_ = f.addRels(defaultXMLRels, SourceRelationshipCustomProperties, defaultXMLPathDocPropsCustom, "")
+
+	// set content type if necessary
+	_ = f.setContentTypes("/"+defaultXMLPathDocPropsCustom, ContentTypeCustomProperties)
+
+	return err
+}
+
+// GetDocCustomProps provides a function to get document custom properties, supported string, bool, float64,
+// time.DateTime four types. If the custom property is not set, it will return an empty map, and if the custom property
+// value is invalid format, it returns as if the custom property does not exist.
+func (f *File) GetDocCustomProps() (kv map[string]interface{}, err error) {
+	custom := new(xlsxCustomProperties)
+
+	if err = f.xmlNewDecoder(bytes.NewReader(namespaceStrictToTransitional(f.readXML(defaultXMLPathDocPropsCustom)))).
+		Decode(custom); err != nil && err != io.EOF {
+		return
+	}
+
+	kv = make(map[string]interface{})
+	if custom == nil || len(custom.Props) == 0 {
+		return kv, nil
+	}
+
+	for _, prop := range custom.Props {
+		propertyValue := prop.getPropertyValue()
+		if propertyValue != nil {
+			kv[prop.Name] = propertyValue
+		}
+	}
+
+	return kv, nil
+}
+
 // GetDocProps provides a function to get document core properties.
 func (f *File) GetDocProps() (ret *DocProperties, err error) {
 	core := new(decodeCoreProperties)

docProps_test.go

@@ -14,6 +14,7 @@ package excelize
 import (
 	"path/filepath"
 	"testing"
+	"time"
 
 	"github.com/stretchr/testify/assert"
 )
@@ -97,6 +98,28 @@ func TestSetDocProps(t *testing.T) {
 	assert.EqualError(t, f.SetDocProps(&DocProperties{}), "XML syntax error on line 1: invalid UTF-8")
 }
 
+func TestSetDocCustomProps(t *testing.T) {
+	f, err := OpenFile(filepath.Join("test", "Book1.xlsx"))
+	if !assert.NoError(t, err) {
+		t.FailNow()
+	}
+
+	assert.NoError(t, f.SetDocCustomProps("string", "v1.0.0"))
+	assert.NoError(t, f.SetDocCustomProps("bool", true))
+	assert.EqualError(t, f.SetDocCustomProps("int64", int64(1)), ErrUnsupportedCustomPropertyDataType.Error())
+	assert.NoError(t, f.SetDocCustomProps("float64", 1.0))
+	assert.NoError(t, f.SetDocCustomProps("date", time.Now()))
+	assert.NoError(t, f.SaveAs(filepath.Join("test", "TestSetDocCustomProps.xlsx")))
+	f.Pkg.Store(defaultXMLPathDocPropsCustom, nil)
+	assert.NoError(t, f.SetDocCustomProps("version", ""))
+	assert.NoError(t, f.Close())
+
+	// Test unsupported charset
+	f = NewFile()
+	f.Pkg.Store(defaultXMLPathDocPropsCustom, MacintoshCyrillicCharset)
+	assert.EqualError(t, f.SetDocCustomProps("version", ""), "XML syntax error on line 1: invalid UTF-8")
+}
+
 func TestGetDocProps(t *testing.T) {
 	f, err := OpenFile(filepath.Join("test", "Book1.xlsx"))
 	if !assert.NoError(t, err) {
@@ -116,3 +139,34 @@ func TestGetDocProps(t *testing.T) {
 	_, err = f.GetDocProps()
 	assert.EqualError(t, err, "XML syntax error on line 1: invalid UTF-8")
 }
+
+func TestFile_GetDocCustomProps(t *testing.T) {
+	f, err := OpenFile(filepath.Join("test", "Book1.xlsx"))
+	if !assert.NoError(t, err) {
+		t.FailNow()
+	}
+
+	// now no custom properties in f
+	props, err := f.GetDocCustomProps()
+	assert.NoError(t, err)
+	assert.Empty(t, props)
+
+	assert.NoError(t, f.SetDocCustomProps("string", "v1.0.0"))
+	assert.NoError(t, f.SetDocCustomProps("bool", true))
+	assert.NoError(t, f.SetDocCustomProps("float64", 1.0))
+	dateValue := time.Date(2006, 01, 02, 15, 04, 05, 0, time.Local)
+	assert.NoError(t, f.SetDocCustomProps("date", dateValue))
+
+	props, err = f.GetDocCustomProps()
+	assert.NoError(t, err)
+	assert.Equal(t, "v1.0.0", props["string"])
+	assert.Equal(t, true, props["bool"])
+	assert.Equal(t, 1.0, props["float64"])
+	assert.Equal(t, dateValue, props["date"])
+
+	// Test get workbook properties with unsupported charset
+	f = NewFile()
+	f.Pkg.Store(defaultXMLPathDocPropsCustom, MacintoshCyrillicCharset)
+	_, err = f.GetDocCustomProps()
+	assert.EqualError(t, err, "XML syntax error on line 1: invalid UTF-8")
+}

errors.go

@@ -178,6 +178,8 @@ var (
 	// ErrWorkbookPassword defined the error message on receiving the incorrect
 	// workbook password.
 	ErrWorkbookPassword = errors.New("the supplied open workbook password is not correct")
+	// ErrUnsupportedCustomPropertyDataType defined the error message on unsupported custom property value data type.
+	ErrUnsupportedCustomPropertyDataType = errors.New("unsupported custom property value data type")
 )
 
 // ErrSheetNotExist defined an error of sheet that does not exist.

excelize.go

@@ -419,7 +419,8 @@ func (f *File) setRels(rID, relPath, relType, target, targetMode string) int {
 // relationship type, target and target mode.
 func (f *File) addRels(relPath, relType, target, targetMode string) int {
 	uniqPart := map[string]string{
-		SourceRelationshipSharedStrings: "/xl/sharedStrings.xml",
+		SourceRelationshipSharedStrings:    "/xl/sharedStrings.xml",
+		SourceRelationshipCustomProperties: "/docProps/custom.xml",
 	}
 	rels, _ := f.relsReader(relPath)
 	if rels == nil {

file.go

@@ -31,7 +31,7 @@ import (
 //	f := NewFile()
 func NewFile(opts ...Options) *File {
 	f := newFile()
-	f.Pkg.Store("_rels/.rels", []byte(xml.Header+templateRels))
+	f.Pkg.Store(defaultXMLRels, []byte(xml.Header+templateRels))
 	f.Pkg.Store(defaultXMLPathDocPropsApp, []byte(xml.Header+templateDocpropsApp))
 	f.Pkg.Store(defaultXMLPathDocPropsCore, []byte(xml.Header+templateDocpropsCore))
 	f.Pkg.Store(defaultXMLPathWorkbookRels, []byte(xml.Header+templateWorkbookRels))

sheet.go

@@ -239,6 +239,15 @@ func (f *File) setContentTypes(partName, contentType string) error {
 	}
 	content.mu.Lock()
 	defer content.mu.Unlock()
+
+	// if target partName exists, update it
+	for i, v := range content.Overrides {
+		if v.PartName == partName {
+			content.Overrides[i].ContentType = contentType
+			return nil
+		}
+	}
+
 	content.Overrides = append(content.Overrides, xlsxOverride{
 		PartName:    partName,
 		ContentType: contentType,

templates.go

@@ -59,6 +59,7 @@ const (
 	ContentTypeSpreadSheetMLWorksheet             = "application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"
 	ContentTypeTemplate                           = "application/vnd.openxmlformats-officedocument.spreadsheetml.template.main+xml"
 	ContentTypeTemplateMacro                      = "application/vnd.ms-excel.template.macroEnabled.main+xml"
+	ContentTypeCustomProperties                   = "application/vnd.openxmlformats-officedocument.custom-properties+xml"
 	ContentTypeVBA                                = "application/vnd.ms-office.vbaProject"
 	ContentTypeVML                                = "application/vnd.openxmlformats-officedocument.vmlDrawing"
 	NameSpaceDrawingMLMain                        = "http://schemas.openxmlformats.org/drawingml/2006/main"
@@ -86,6 +87,7 @@ const (
 	SourceRelationshipTable                       = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/table"
 	SourceRelationshipVBAProject                  = "http://schemas.microsoft.com/office/2006/relationships/vbaProject"
 	SourceRelationshipWorkSheet                   = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet"
+	SourceRelationshipCustomProperties            = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/custom-properties"
 	StrictNameSpaceDocumentPropertiesVariantTypes = "http://purl.oclc.org/ooxml/officeDocument/docPropsVTypes"
 	StrictNameSpaceDrawingMLMain                  = "http://purl.oclc.org/ooxml/drawingml/main"
 	StrictNameSpaceExtendedProperties             = "http://purl.oclc.org/ooxml/officeDocument/extendedProperties"
@@ -132,6 +134,9 @@ const (
 	ExtURIWebExtensions                  = "{F7C9EE02-42E1-4005-9D12-6889AFFD525C}"
 	ExtURIWorkbookPrX14                  = "{79F54976-1DA5-4618-B147-ACDE4B953A38}"
 	ExtURIWorkbookPrX15                  = "{140A7094-0E35-4892-8432-C4D2E57EDEB5}"
+
+	// CustomPropertiesFMTID is the format ID for custom properties items.
+	CustomPropertiesFMTID = "{D5CDD505-2E9C-101B-9397-08002B2CF9AE}"
 )
 
 // workbookExtURIPriority is the priority of URI in the workbook extension lists.
@@ -270,13 +275,15 @@ var supportedChartDataLabelsPosition = map[ChartType][]ChartDataLabelPositionTyp
 }
 
 const (
+	defaultXMLRels                        = "_rels/.rels"
 	defaultTempFileSST                    = "sharedStrings"
 	defaultXMLMetadata                    = "xl/metadata.xml"
 	defaultXMLPathCalcChain               = "xl/calcChain.xml"
 	defaultXMLPathCellImages              = "xl/cellimages.xml"
 	defaultXMLPathCellImagesRels          = "xl/_rels/cellimages.xml.rels"
 	defaultXMLPathContentTypes            = "[Content_Types].xml"
 	defaultXMLPathDocPropsApp             = "docProps/app.xml"
+	defaultXMLPathDocPropsCustom          = "docProps/custom.xml"
 	defaultXMLPathDocPropsCore            = "docProps/core.xml"
 	defaultXMLPathSharedStrings           = "xl/sharedStrings.xml"
 	defaultXMLPathStyles                  = "xl/styles.xml"

xmlCustom.go

@@ -0,0 +1,62 @@
+package excelize
+
+import (
+	"encoding/xml"
+	"time"
+)
+
+// xlsxCustomProperties is the root element of the Custom File Properties part
+type xlsxCustomProperties struct {
+	XMLName xml.Name             `xml:"http://schemas.openxmlformats.org/officeDocument/2006/custom-properties Properties"`
+	Vt      string               `xml:"xmlns:vt,attr"`
+	Props   []xlsxCustomProperty `xml:"property"`
+}
+
+type xlsxCustomProperty struct {
+	FmtID    string         `xml:"fmtid,attr"`
+	PID      string         `xml:"pid,attr"`
+	Name     string         `xml:"name,attr"`
+	Text     *TextValue     `xml:"http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes lpwstr,omitempty"`
+	Bool     *BoolValue     `xml:"http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes bool,omitempty"`
+	Number   *NumberValue   `xml:"http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes r8,omitempty"`
+	DateTime *FileTimeValue `xml:"http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes filetime,omitempty"`
+}
+
+func (p *xlsxCustomProperty) getPropertyValue() interface{} {
+	if p.Text != nil {
+		return p.Text.Text
+	}
+	if p.Bool != nil {
+		return p.Bool.Bool
+	}
+	if p.Number != nil {
+		return p.Number.Number
+	}
+	if p.DateTime != nil {
+		// parse date time raw str to time.Time
+		timeStr := p.DateTime.DateTime
+		parsedTime, err := time.Parse(time.RFC3339, timeStr)
+		if err != nil {
+			return nil
+		}
+		return parsedTime
+	}
+
+	return nil
+}
+
+type TextValue struct {
+	Text string `xml:",chardata"`
+}
+
+type BoolValue struct {
+	Bool bool `xml:",chardata"`
+}
+
+type NumberValue struct {
+	Number float64 `xml:",chardata"`
+}
+
+type FileTimeValue struct {
+	DateTime string `xml:",chardata"`
+}