feat(xlsxgen): generate spreadsheets from a declarative spec and structured data
Maintainer thường phản hồi trong vòng 1 ngày
@sthanikan2000 đang làm issue này rồi.
Từ ngày 17/9/2026.
Đánh giá
Issue này chưa được đánh giá.
Mô tả
1. Problem
Core does not support generating spreadsheets. A single window system has to hand people tabular
output — a sales schedule, a line-item listing, a reconciliation — and there is no supported way to
produce a workbook from data the system already holds. archive/zip is used nowhere in the repo,
so this is greenfield.
Writing .xlsx by hand is not realistic. It is a ZIP of interdependent OOXML parts, and getting
the content types, relationships or cell encoding wrong produces a file Excel silently refuses to
open, usually with no useful diagnostic.
2. Proposed approach
A standalone module xlsxgen, stdlib-only (archive/zip + encoding/xml), mirroring
xmlgen's shape and dependency profile.
The template is a JSON spec, not a binary workbook. A spec describes the sheet, where the rows
come from, and how each column is headed and formatted:
{
"sheet": "Auction Report",
"rows": "sales.sheet",
"columns": [
{ "header": "Date of Sale", "from": "Sale_date" },
{ "header": "Garden Mark", "from": "Garden_mark" },
{ "header": "Rate per KG", "from": "Sale_rate", "type": "number", "format": "#,##0.00" },
{ "header": "Qty in KG", "from": "Sale_quantity", "type": "number" },
{ "header": "Total Value", "from": "Sale_value", "type": "number", "format": "#,##0.00" }
]
}
At its smallest the spec is two fields — a sheet name and where the rows are:
{ "sheet": "Sales Data", "rows": "sales.sheet" }
Two row shapes
Tabular data reaches a generator in one of two forms, and the spec has to serve both:
// a matrix — row 1 is already the header
[["Date", "Item", "Qty"], ["01/06/2026", "Widget A", 500]]
// records — one object per row
[{ "Date": "01/06/2026", "Item": "Widget A", "Qty": 500 }]
They are told apart by whether the first element is an array.
- Matrix, no
columnsgiven — written verbatim, header row included. This is the common case
and needs no column spec at all. - Records —
columnsis required, supplying both the order and the header text. Not optional
sugar: a decoded JSON object is a Go map, which has no iteration order, so without an explicit
list the column order would vary between runs. - Matrix with
columnsgiven — columns select and re-order by position ("index": 2) rather
than by field name, which also lets a caller drop or reorder columns of a matrix it does not own.
Interface
Deliberately the same shape as xmlgen, so the two read as siblings:
// Generate renders spec against data and returns the .xlsx bytes.
func Generate(ctx context.Context, spec []byte, data any, opts ...Option) ([]byte, error)
// GenerateTo is Generate writing to w. Like xmlgen's, it does not stream: a ZIP
// central directory can only be written once the whole archive is known, so w
// receives nothing unless the whole workbook is valid.
func GenerateTo(ctx context.Context, w io.Writer, spec []byte, data any, opts ...Option) error
// Validate checks a spec without data, for load-time and CI checks.
func Validate(spec []byte) error
func WithMaxOutputBytes(n int64) Option
func WithStrictKeys() Option // a column whose `from` is absent becomes an error
data accepts the same inputs as xmlgen: []byte/json.RawMessage decoded internally with
UseNumber, or an already-decoded map[string]any. Output is bytes, never a file — the caller
streams it to a download or hands it to storage.
What it emits
Six OOXML parts, the minimum for a workbook that opens everywhere:
[Content_Types].xml, _rels/.rels, xl/workbook.xml, xl/_rels/workbook.xml.rels,
xl/worksheets/sheet1.xml, and xl/styles.xml only when a column declares a format.
Three decisions inside that, each of which is a trap if taken the other way:
- Inline strings (
<c t="inlineStr"><is><t>…</t></is></c>) rather than a shared-strings table.
Marginally larger files, but it removes a whole part and its index-consistency failure mode. - Cell text is XML-escaped and control characters replaced, the same rule
xmlgenenforces — a
value containing&must not produce a workbook Excel refuses to open. archive/ziprecords modification times, which would make output non-reproducible. Zeroing
FileHeader.Modifiedkeeps byte-stability, the propertyxmlgenalready advertises so a
generated artefact can be hashed or signed.
Values, not formulas
Aggregates are written as computed numbers rather than as =SUM(...). Common spreadsheet parsers
read a formula cell's cached value rather than its formula text, so a workbook carrying formulas
without cached results reads back empty — and computing the cache correctly means reimplementing a
formula engine. The cost is that a recipient editing a row in Excel sees no recalculation, which is
acceptable for a document that is a record rather than a working model.
Properties the output must hold
Worth pinning with tests, because each is easy to get subtly wrong and hard to notice:
- one sheet, since many readers take the first and ignore the rest
- the header in row 1, so the table is addressable as
A1:… - blank cells omitted entirely rather than written as empty strings, so a reader can distinguish
"no value" from"" - numbers written as numbers, not as text that looks numeric
- the file unzips, every declared part exists, and the sheet XML parses
Not in scope
Styling beyond number formats, charts, images, merged cells, frozen panes, multiple sheets,
formulas, and .xlsm. Each of those is a reason to reach for github.com/xuri/excelize/v2 — which
would make xlsxgen the first pure-computation module in core carrying a large third-party
dependency, against the precedent of xmlgen, httputil and shared, all of which have none. If
a styled workbook is ever genuinely required, adding an excelize-backed path behind the same
interface is the follow-up, not a reason to start there.
3. Open decisions
- Aggregates. A table often arrives alongside computed totals. Should the spec place them — as
a trailing totals row, a separate block below the table, or left to the caller to fold into the
rows first? A trailing row is the obvious default but complicates the "rows come from one path"
model. - Dates. Write them as strings, or as real Excel date serials with a
numFmt? Serials are
what makes a date sortable and formattable in Excel; strings are simpler and survive any reader
unchanged. This changes what downstream code has to handle, so it is worth deciding once. - Transposed output. A "wide" table puts labels in column A and one record per subsequent
column. Worth supporting on the write side, or is row-per-record enough? - Where the spec lives.
artifact.Loaderreturns raw[]byte, so a spec could be a registry
artifact with its own adapter — the same follow-up pending for XML templates. - CSV. Is a CSV writer wanted from the same module, or is that a separate concern?
- Ngôn ngữ chính
- Go
- Star
- 6
- Fork
- 8
- Merge trung bình
- 21 giờ 36 phút
- Pull request đã merge (30 ngày)
- 42
Chuẩn bị môi trường
- Không có Dockerfile hay tệp Docker Compose
- Có mẫu pull request
- Đọc hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của OpenNSW/core
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 74/100
Maintainer thường phản hồi trong vòng 1 ngày
-
payment: test fixtures hardcode real gateway names (govpay/lankapay) instead of generic placeholdersĐang mở
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 88/100
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 72/100
Maintainer thường phản hồi trong vòng 1 ngày
-
nsw-sl cleanup Type/Improvement
Độ khó 3/5 1-2 ngày Mức phù hợp với người mới 48/100
Maintainer thường phản hồi trong vòng 1 ngày
-
remote: let the host inject a logger, and log with one consistent policyCó thể đã có người làm @mushrafmim đã nhận 5 ngày trước. Đang mởType/Improvement
Độ khó 4/5 3-5 ngày Mức phù hợp với người mới 22/100
Maintainer thường phản hồi trong vòng 1 ngày
Issue tương tự
-
agent-research-finding chore
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
jordansmall/spindrift#7370 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
☢️ Bug v3
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 82/100
Maintainer thường phản hồi trong vòng 1 ngày
-
The repo's gates check is clean and runs need no swapsCó thể đã có người làm @turbot-agent-fleet đã nhận hôm nay. Đang mởagent:ready
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 64/100
turbot/tailpipe#677 · 2 bình luận ·
Maintainer thường phản hồi trong vòng 1 ngày
-
needs-kind needs-triage
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 72/100
Maintainer thường phản hồi trong vòng 2 ngày
-
enhancement
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 70/100
crossplane-contrib/provider-keycloak#806 ·
Maintainer thường phản hồi trong vòng 1 ngày