diff --git a/docs/compatibility.md b/docs/compatibility.md index 2ed24ad..3b99c77 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -54,6 +54,7 @@ The latest `calamine 0.36` and `rust_xlsxwriter 0.97` require Rust 1.88. The MVP | Typed export | `save_as_serialized()` | Uses Serde mapping internally | | Multi-sheet export | `save_as_sheets()` / `save_as_serialized_sheets()` | Preserves input sheet order and returns data-row counts | | `InsertSheet` append/replace | `insert()` / `insert_with_schema()` / `insert_serialized()` / borrowed reader-to-writer variants | Path APIs are atomic; separate borrowed streams require an empty sink and preserve package behavior without atomic commit | +| Deferred cell font-color edits | `MiniExcel::edit_sheet()` / `WorkbookEditor::set_font_color()` / `save()` | Rust-only path API; existing cells in one worksheet, RGB colors, bounded-memory XML rewrite, and atomic commit | | Async Insert producer | `insert_with_schema_async*()` | Optional `async` feature; bounded producer channel with blocking XLSX work on a dedicated thread | | Async path query | `query_async*()` / `query_as_async*()` | Optional `async` feature; bounded dynamic/Serde streams, cooperative cancellation, blocking XLSX workers | | Async dynamic/Serde export | `save_as_with_schema_async*()` / `save_as_serialized_async*()` | Optional `async` feature; explicit or first-row-inferred schema, bounded producer, atomic destination, cooperative cancellation, data-cell progress | @@ -74,7 +75,7 @@ The latest `calamine 0.36` and `rust_xlsxwriter 0.97` require Rust 1.88. The MVP | Caller-owned XLSX input | `visit_*_from_reader()` / metadata `*_from_reader()` | Borrowed `Read + Seek`; synchronous visitor model | | Caller-owned XLSX output | `save_as*_to_writer()` | Borrowed `Write + Send`; dynamic, schema, typed, and multi-sheet | -`MiniExcel` is the only public behavior entry point. Reader, writer, parser, and concrete iterator types are crate-internal. Public supporting types are limited to row/cell values, structured provenance rows, options, errors/results, and Serde date/time helpers. +`MiniExcel` is the primary public behavior entry point. Reader, writer, parser, and concrete iterator types are crate-internal. `WorkbookEditor` is returned only by `MiniExcel::edit_sheet()` and exposes deferred worksheet edits. Other public supporting types are limited to row/cell values, structured provenance rows, options, errors/results, and Serde date/time helpers. ## Compatibility Defaults @@ -125,7 +126,7 @@ Path RAG exports retain parser state, repeated header context, and one output ch The backend makes two sequential, bounded-memory passes over the selected worksheet entry. The first records the used extent and compact merged-cell rectangles. This is required for MiniExcel-compatible stable dynamic schemas when legal files omit ``, to preserve style-only row elements like the .NET reader, and to support opt-in merged-cell filling without expanding ranges into an address map. The second pass emits rows and retains only anchor values for currently active merged ranges. Worksheet XML and prior rows are never retained; memory consists primarily of in-memory or disk-indexed shared strings, styles, merge metadata, parser buffers, the current row, and the bounded channel. -The internal writer assembles a new ZIP package with one or more worksheets. Path saves refuse existing files by default and can explicitly replace them. Path Insert APIs append or replace a worksheet through a validated package rewrite and atomic sibling-file replacement; unchanged ZIP entries and existing worksheet identities are preserved. Separate borrowed Insert APIs accept `Read + Seek` input and an empty `Write + Seek` output, leave both open, and preserve the same package behavior without atomic commit, rollback, or post-write validation. Fallible explicit-schema producers are consumed once through a disk spool and a constant-memory worksheet writer. Generated donor worksheet XML, shared-string conversion, style-ID rebasing, and ZIP insertion use temporary-file streams, so worksheet memory is independent of row count. Path Insert also uses advisory locking and a pre-commit source fingerprint to prevent lost concurrent updates. Template fills rewrite worksheet XML within a copied package; worksheet styles and unrelated ZIP parts are retained. Array expansion shifts row and cell addresses and updates the worksheet dimension. Formula expressions are preserved but not recalculated, and version 1 does not adjust formula references, merged ranges, tables, drawings, or defined names after inserted rows. +The internal writer assembles a new ZIP package with one or more worksheets. Path saves refuse existing files by default and can explicitly replace them. Path Insert APIs append or replace a worksheet through a validated package rewrite and atomic sibling-file replacement; unchanged ZIP entries and existing worksheet identities are preserved. Separate borrowed Insert APIs accept `Read + Seek` input and an empty `Write + Seek` output, leave both open, and preserve the same package behavior without atomic commit, rollback, or post-write validation. Fallible explicit-schema producers are consumed once through a disk spool and a constant-memory worksheet writer. Generated donor worksheet XML, shared-string conversion, style-ID rebasing, and ZIP insertion use temporary-file streams, so worksheet memory is independent of row count. Path Insert also uses advisory locking and a pre-commit source fingerprint to prevent lost concurrent updates. `WorkbookEditor` defers font-color operations until `save()`, then sorts them by cell coordinate, lets the last operation for a cell win, scans the selected worksheet for existing style IDs, deduplicates cloned font/XF records, streams the worksheet rewrite through a temporary file, validates the package, and commits atomically. It currently edits only cells already represented in worksheet XML. Template fills rewrite worksheet XML within a copied package; worksheet styles and unrelated ZIP parts are retained. Array expansion shifts row and cell addresses and updates the worksheet dimension. Formula expressions are preserved but not recalculated, and version 1 does not adjust formula references, merged ranges, tables, drawings, or defined names after inserted rows. ## Test Sources diff --git a/docs/compatibility.zh-CN.md b/docs/compatibility.zh-CN.md index f765eaf..8014410 100644 --- a/docs/compatibility.zh-CN.md +++ b/docs/compatibility.zh-CN.md @@ -54,6 +54,7 @@ Rust MVP 在统一的 `MiniExcel` facade 后实现最小但实用的 MiniExcel | 类型化导出 | `save_as_serialized()` | 内部使用 Serde 映射 | | 多工作表导出 | `save_as_sheets()` / `save_as_serialized_sheets()` | 保留输入工作表顺序并返回数据行数 | | `InsertSheet` append/replace | `insert()` / `insert_with_schema()` / `insert_serialized()` / borrowed reader-to-writer variants | Path API 为原子操作；独立 borrowed stream 要求空 sink，并在无原子 commit 的情况下保持相同 package 行为 | +| 延迟 cell 字体颜色编辑 | `MiniExcel::edit_sheet()` / `WorkbookEditor::set_font_color()` / `save()` | Rust-only path API；支持单个 worksheet 中已有 cell、RGB color、有界内存 XML rewrite 与原子 commit | | Async Insert producer | `insert_with_schema_async*()` | 可选 `async` feature；bounded producer channel，XLSX 工作在专用 blocking thread | | Async path query | `query_async*()` / `query_as_async*()` | 可选 `async` feature；bounded 动态/Serde stream、协作式 cancellation、blocking XLSX worker | | Async dynamic/Serde export | `save_as_with_schema_async*()` / `save_as_serialized_async*()` | 可选 `async` feature；显式或首行推断 schema、bounded producer、原子 destination、协作式 cancellation、data-cell progress | @@ -74,7 +75,7 @@ Rust MVP 在统一的 `MiniExcel` facade 后实现最小但实用的 MiniExcel | 调用方持有的 XLSX input | `visit_*_from_reader()` / metadata `*_from_reader()` | 借用 `Read + Seek`；同步 visitor 模型 | | 调用方持有的 XLSX output | `save_as*_to_writer()` | 借用 `Write + Send`；动态、schema、类型化和多工作表 | -`MiniExcel` 是唯一公共行为入口。Reader、writer、parser 和具体迭代器类型均为 crate 内部实现。公共支持类型仅限 row/cell value、结构化 provenance row、option、error/result 和 Serde date/time helper。 +`MiniExcel` 是主要公共行为入口。Reader、writer、parser 和具体迭代器类型均为 crate 内部实现。`WorkbookEditor` 仅由 `MiniExcel::edit_sheet()` 返回，用于延迟 worksheet 编辑。其他公共支持类型仅限 row/cell value、结构化 provenance row、option、error/result 和 Serde date/time helper。 ## 兼容性默认值 @@ -125,7 +126,7 @@ Rust MVP 在统一的 `MiniExcel` facade 后实现最小但实用的 MiniExcel backend 对所选 worksheet entry 执行两次顺序、有界内存扫描。第一次记录使用范围和紧凑 merged-cell 矩形。这是为了在合法文件省略 `` 时保持 MiniExcel 兼容的稳定动态 schema、像 .NET reader 一样保留仅含 style 的 row element，并在不展开地址 map 的情况下支持按需 merged-cell 填充。第二次扫描输出 row，只保留当前活动 merge range 的锚点值。Worksheet XML 和先前 row 永远不会保留；内存主要由内存或磁盘索引的 shared string、style、merge metadata、parser buffer、当前 row 和有界 channel 构成。 -内部 writer 组装包含一个或多个工作表的新 ZIP package。路径保存默认拒绝已有文件，也可显式替换。Path Insert API 通过验证后的 package rewrite 与同目录临时文件原子替换来追加或替换 worksheet；未修改的 ZIP entry 和现有 worksheet identity 会保留。独立 borrowed Insert API 接受 `Read + Seek` input 与空的 `Write + Seek` output，调用后两者保持 open，并在不提供 atomic commit、rollback 或写后验证的情况下保持相同 package 行为。可返回错误的显式 schema producer 只消费一次，经磁盘 spool 与 constant-memory worksheet writer 处理。生成的 donor worksheet XML、shared-string conversion、style-ID rebase 与 ZIP insertion 均使用临时文件 stream，因此 worksheet memory 与 row count 无关。Path Insert 还通过 advisory lock 与 commit 前 source fingerprint 防止并发更新丢失。模板填充会在复制的 package 中重写 worksheet XML；worksheet 样式和无关 ZIP part 会保留。数组展开会移动 row/cell 地址并更新 worksheet dimension。公式表达式会保留但不会重算；版本 1 不会在插行后调整公式引用、merge range、table、drawing 或 defined name。 +内部 writer 组装包含一个或多个工作表的新 ZIP package。路径保存默认拒绝已有文件，也可显式替换。Path Insert API 通过验证后的 package rewrite 与同目录临时文件原子替换来追加或替换 worksheet；未修改的 ZIP entry 和现有 worksheet identity 会保留。独立 borrowed Insert API 接受 `Read + Seek` input 与空的 `Write + Seek` output，调用后两者保持 open，并在不提供 atomic commit、rollback 或写后验证的情况下保持相同 package 行为。可返回错误的显式 schema producer 只消费一次，经磁盘 spool 与 constant-memory worksheet writer 处理。生成的 donor worksheet XML、shared-string conversion、style-ID rebase 与 ZIP insertion 均使用临时文件 stream，因此 worksheet memory 与 row count 无关。Path Insert 还通过 advisory lock 与 commit 前 source fingerprint 防止并发更新丢失。`WorkbookEditor` 会把字体颜色操作延迟到 `save()`，届时按 cell 坐标排序，同一 cell 以最后登记的操作为准；随后扫描所选 worksheet 的已有 style ID、去重克隆 font/XF record、经临时文件流式重写 worksheet、验证 package 并原子提交。当前只编辑 worksheet XML 中已经存在的 cell。模板填充会在复制的 package 中重写 worksheet XML；worksheet 样式和无关 ZIP part 会保留。数组展开会移动 row/cell 地址并更新 worksheet dimension。公式表达式会保留但不会重算；版本 1 不会在插行后调整公式引用、merge range、table、drawing 或 defined name。 ## 测试来源 diff --git a/miniexcel/src/cell.rs b/miniexcel/src/cell.rs index e9d27e3..fdb5ee3 100644 --- a/miniexcel/src/cell.rs +++ b/miniexcel/src/cell.rs @@ -141,7 +141,7 @@ impl StructuredRow { } } -#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)] +#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] pub struct CellReference { row: usize, column: usize, diff --git a/miniexcel/src/facade.rs b/miniexcel/src/facade.rs index bc76e75..c55a276 100644 --- a/miniexcel/src/facade.rs +++ b/miniexcel/src/facade.rs @@ -29,6 +29,18 @@ use crate::{ExistingSheetPolicy, InsertOptions, SheetVisibility, TargetRelations pub struct MiniExcel; impl MiniExcel { + /// Starts a deferred, fluent edit for one worksheet in an existing XLSX workbook. + /// + /// Operations are normalized and ordered only when [`crate::WorkbookEditor::save`] is called. + #[cfg(not(target_arch = "wasm32"))] + #[must_use] + pub fn edit_sheet( + path: impl AsRef, + sheet_name: impl Into, + ) -> crate::WorkbookEditor { + crate::WorkbookEditor::new(path.as_ref().to_owned(), sheet_name.into()) + } + /// Returns worksheet names in workbook order. pub fn get_sheet_names(path: impl AsRef) -> Result> { crate::streaming::sheet_names(path) diff --git a/miniexcel/src/insert/atomic.rs b/miniexcel/src/insert/atomic.rs index 7b1a384..f2afa46 100644 --- a/miniexcel/src/insert/atomic.rs +++ b/miniexcel/src/insert/atomic.rs @@ -13,10 +13,14 @@ use super::package::PackageInventory; use super::rewrite::{ PackageRewriteStage, ReplacementPlan, append_worksheet_to_writer_with_hook, mutate_worksheet_metadata_to_writer_with_hook, plan_replacement, remap_sheet_index, - reorder_worksheet_to_writer_with_hook, replace_worksheet_to_writer_with_hook, + reorder_worksheet_to_writer_with_hook, replace_worksheet_to_writer_with_hook, styles_path, + update_font_colors_to_writer_with_hook, }; use crate::writer::validate_sheet_name; -use crate::{Error, ExistingSheetPolicy, Result, SheetVisibility, TargetRelationshipPolicy}; +use crate::{ + CellReference, Error, ExistingSheetPolicy, Result, RgbColor, SheetVisibility, + TargetRelationshipPolicy, +}; const WORKSHEET_CONTENT_TYPE: &str = "application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"; @@ -513,6 +517,62 @@ pub(crate) fn reorder_sheet_to_path( reorder_sheet_to_path_with_hook(path.as_ref(), sheet_name, new_sheet_index, |_| Ok(())) } +pub(crate) fn update_font_colors_to_path( + path: &Path, + sheet_name: &str, + colors: &std::collections::BTreeMap, +) -> Result<()> { + validate_sheet_name(sheet_name, &std::collections::HashSet::new())?; + if colors.is_empty() { + return Ok(()); + } + let _guard = PathMutationGuard::acquire(path, "worksheet style update")?; + let source_fingerprint = SourceFingerprint::read(path)?; + let source_metadata = fs::metadata(path)?; + let mut source = File::open(path)?; + let inventory = PackageInventory::inspect(&mut source)?; + let target = inventory + .find_sheet(sheet_name) + .cloned() + .ok_or_else(|| Error::sheet_not_found(sheet_name))?; + let styles_path = styles_path(&inventory)?; + let parent = sibling_directory(path); + let mut temporary = + tempfile::Builder::new().prefix(".miniexcel-").suffix(".xlsx.tmp").tempfile_in(parent)?; + + source.rewind()?; + update_font_colors_to_writer_with_hook( + source, + temporary.as_file_mut(), + &target.target, + &styles_path, + colors, + |_| Ok(()), + )?; + temporary.as_file_mut().flush()?; + temporary.as_file().sync_all()?; + validate_rewritten_package(temporary.reopen()?, &target.name)?; + let rewritten = PackageInventory::inspect(temporary.reopen()?)?; + if rewritten.sheets != inventory.sheets + || rewritten.views != inventory.views + || rewritten.defined_names != inventory.defined_names + || rewritten.relationships != inventory.relationships + || rewritten.entry_names != inventory.entry_names + || rewritten.content_types != inventory.content_types + { + return Err(Error::atomic_commit( + "worksheet style update changed unrelated workbook metadata", + )); + } + if SourceFingerprint::read(path)? != source_fingerprint { + return Err(Error::atomic_commit(format!( + "source workbook '{}' changed during worksheet style update", + path.display(), + ))); + } + replace_temporary(temporary, path, source_metadata.permissions()) +} + fn reorder_sheet_to_path_with_hook( path: &Path, sheet_name: &str, diff --git a/miniexcel/src/insert/rewrite.rs b/miniexcel/src/insert/rewrite.rs index a434ed7..27f6fe6 100644 --- a/miniexcel/src/insert/rewrite.rs +++ b/miniexcel/src/insert/rewrite.rs @@ -8,8 +8,10 @@ use zip::{CompressionMethod, ZipArchive, ZipWriter}; use super::donor::DonorWorksheet; use super::package::{DefinedName, PackageInventory, WorkbookSheet, WorksheetAllocation}; -use super::style::rebase_styles; -use crate::{Error, Result, SheetVisibility, TargetRelationshipPolicy}; +use super::style::{ + collect_cell_styles, rebase_styles, rewrite_worksheet_font_colors, update_font_colors, +}; +use crate::{CellReference, Error, Result, RgbColor, SheetVisibility, TargetRelationshipPolicy}; const CONTENT_TYPES_PATH: &str = "[Content_Types].xml"; const WORKBOOK_PATH: &str = "xl/workbook.xml"; @@ -462,6 +464,68 @@ where ) } +pub(super) fn update_font_colors_to_writer_with_hook( + mut source: R, + destination: W, + worksheet_path: &str, + styles_path: &str, + colors: &BTreeMap, + mut checkpoint: F, +) -> Result +where + R: Read + Seek, + W: Write + Seek, + F: FnMut(PackageRewriteStage) -> Result<()>, +{ + source.seek(SeekFrom::Start(0))?; + let (styles_xml, cell_styles) = { + let mut archive = ZipArchive::new(&mut source).map_err(|error| { + Error::insert_package(format!("cannot reopen source workbook: {error}")) + })?; + let styles_xml = read_part(&mut archive, styles_path)?; + let worksheet = archive.by_name(worksheet_path).map_err(|error| { + Error::insert_package(format!("cannot read worksheet '{worksheet_path}': {error}")) + })?; + let cells = colors.keys().copied().collect::>(); + let cell_styles = collect_cell_styles(BufReader::new(worksheet), &cells)?; + (styles_xml, cell_styles) + }; + let (styles_xml, rewritten_styles) = update_font_colors(&styles_xml, &cell_styles, colors)?; + + source.seek(SeekFrom::Start(0))?; + let mut worksheet_xml = tempfile::NamedTempFile::new()?; + { + let mut archive = ZipArchive::new(&mut source).map_err(|error| { + Error::insert_package(format!("cannot reopen source workbook: {error}")) + })?; + let worksheet = archive.by_name(worksheet_path).map_err(|error| { + Error::insert_package(format!("cannot read worksheet '{worksheet_path}': {error}")) + })?; + rewrite_worksheet_font_colors( + BufReader::new(worksheet), + worksheet_xml.as_file_mut(), + &rewritten_styles, + )?; + worksheet_xml.as_file_mut().flush()?; + } + + source.seek(SeekFrom::Start(0))?; + let archive = ZipArchive::new(source).map_err(|error| { + Error::insert_package(format!("cannot reopen source workbook: {error}")) + })?; + let replacements = BTreeMap::from([(styles_path.to_owned(), styles_xml)]); + let mut worksheet_reader = BufReader::new(worksheet_xml.reopen()?); + write_package( + archive, + destination, + &replacements, + &BTreeSet::new(), + Some((worksheet_path, &mut worksheet_reader)), + None, + &mut checkpoint, + ) +} + pub(super) const fn remap_sheet_index( index: usize, source_index: usize, @@ -969,7 +1033,7 @@ fn relationship_part_path(source: &str) -> Result { } } -fn styles_path(inventory: &PackageInventory) -> Result { +pub(super) fn styles_path(inventory: &PackageInventory) -> Result { let mut paths = inventory .relationships .iter() diff --git a/miniexcel/src/insert/style.rs b/miniexcel/src/insert/style.rs index 25d132a..1810cf4 100644 --- a/miniexcel/src/insert/style.rs +++ b/miniexcel/src/insert/style.rs @@ -1,11 +1,11 @@ -use std::collections::{BTreeMap, HashMap}; +use std::collections::{BTreeMap, BTreeSet, HashMap}; use std::io::{BufRead, BufReader, Cursor, Read, Write}; use quick_xml::events::{BytesEnd, BytesStart, Event}; use quick_xml::{Reader, Writer}; use super::donor::DonorWorksheet; -use crate::{Error, Result}; +use crate::{CellReference, Error, Result, RgbColor}; const FIRST_CUSTOM_NUM_FMT_ID: u32 = 164; const MAX_NUM_FMT_ID: u32 = u16::MAX as u32; @@ -41,6 +41,152 @@ pub(crate) fn rebase_styles( rebase_style_reader(target_styles_xml, &donor.styles.xml, donor.worksheet_reader()?) } +pub(crate) fn collect_cell_styles( + xml: R, + cells: &BTreeSet, +) -> Result> +where + R: BufRead, +{ + let mut reader = Reader::from_reader(xml); + let mut buffer = Vec::new(); + let mut styles = BTreeMap::new(); + loop { + let event = reader + .read_event_into(&mut buffer) + .map_err(|error| Error::insert_package(format!("invalid worksheet XML: {error}")))?; + match event { + Event::Start(cell) | Event::Empty(cell) if local_name(cell.name().as_ref()) == b"c" => { + if let Some(address) = attribute(&cell, b"r")? { + let reference = address.parse::()?; + if cells.contains(&reference) { + styles.insert(reference, numeric_attribute(&cell, b"s")?.unwrap_or(0)); + } + } + } + Event::Eof => break, + _ => {} + } + buffer.clear(); + } + if let Some(cell) = cells.iter().find(|cell| !styles.contains_key(cell)) { + return Err(Error::insert_package(format!("cell '{cell}' does not exist"))); + } + Ok(styles) +} + +pub(crate) fn update_font_colors( + styles_xml: &[u8], + cell_styles: &BTreeMap, + colors: &BTreeMap, +) -> Result<(Vec, BTreeMap)> { + let document = StyleDocument::parse(styles_xml)?; + let fonts = document.nodes(StyleSection::Fonts)?; + let cell_xfs = document.nodes(StyleSection::CellXfs)?; + let mut font_indexes = fonts + .iter() + .enumerate() + .map(|(index, node)| Ok((node.key()?, index as u32))) + .collect::>>()?; + let mut xf_indexes = cell_xfs + .iter() + .enumerate() + .map(|(index, node)| Ok((node.key()?, index as u32))) + .collect::>>()?; + let mut appended_fonts = Vec::new(); + let mut appended_xfs = Vec::new(); + let mut rewritten_cells = BTreeMap::new(); + + for (cell, color) in colors { + let old_xf_id = *cell_styles + .get(cell) + .ok_or_else(|| Error::insert_package(format!("cell '{cell}' has no style")))?; + let old_xf = cell_xfs.get(old_xf_id as usize).ok_or_else(|| { + Error::insert_package(format!("cell '{cell}' references missing style {old_xf_id}")) + })?; + let old_font_id = numeric_attribute(old_xf.root()?, b"fontId")?.unwrap_or(0); + let old_font = fonts.get(old_font_id as usize).ok_or_else(|| { + Error::insert_package(format!( + "style {old_xf_id} references missing font {old_font_id}" + )) + })?; + let new_font = old_font.with_font_color(*color)?; + let font_key = new_font.key()?; + let new_font_id = if let Some(index) = font_indexes.get(&font_key) { + *index + } else { + let index = (fonts.len() + appended_fonts.len()) as u32; + font_indexes.insert(font_key, index); + appended_fonts.push(new_font); + index + }; + let new_xf = old_xf.with_attributes(&[ + (b"fontId", new_font_id.to_string()), + (b"applyFont", "1".to_owned()), + ])?; + let xf_key = new_xf.key()?; + let new_xf_id = if let Some(index) = xf_indexes.get(&xf_key) { + *index + } else { + let index = (cell_xfs.len() + appended_xfs.len()) as u32; + xf_indexes.insert(xf_key, index); + appended_xfs.push(new_xf); + index + }; + rewritten_cells.insert(*cell, new_xf_id); + } + + validate_limits( + document.nodes(StyleSection::NumFmts)?.len(), + fonts.len() + appended_fonts.len(), + document.nodes(StyleSection::Fills)?.len(), + document.nodes(StyleSection::Borders)?.len(), + document.nodes(StyleSection::CellStyleXfs)?.len(), + cell_xfs.len() + appended_xfs.len(), + )?; + let appended = BTreeMap::from([ + (StyleSection::NumFmts, Vec::new()), + (StyleSection::Fonts, appended_fonts), + (StyleSection::Fills, Vec::new()), + (StyleSection::Borders, Vec::new()), + (StyleSection::CellStyleXfs, Vec::new()), + (StyleSection::CellXfs, appended_xfs), + ]); + Ok((document.render(&appended)?, rewritten_cells)) +} + +pub(crate) fn rewrite_worksheet_font_colors( + xml: R, + output: W, + styles: &BTreeMap, +) -> Result<()> +where + R: BufRead, + W: Write, +{ + let mut reader = Reader::from_reader(xml); + reader.config_mut().trim_text(false); + let mut writer = Writer::new(output); + let mut buffer = Vec::new(); + loop { + let event = reader + .read_event_into(&mut buffer) + .map_err(|error| Error::insert_package(format!("invalid worksheet XML: {error}")))?; + match event { + Event::Start(cell) if local_name(cell.name().as_ref()) == b"c" => { + write_event(&mut writer, Event::Start(rewrite_selected_cell(&cell, styles)?))?; + } + Event::Empty(cell) if local_name(cell.name().as_ref()) == b"c" => { + write_event(&mut writer, Event::Empty(rewrite_selected_cell(&cell, styles)?))?; + } + Event::Eof => break, + event => write_event(&mut writer, event.into_owned())?, + } + buffer.clear(); + } + Ok(()) +} + fn rebase_style_xml( target_styles_xml: &[u8], donor_styles_xml: &[u8], @@ -205,6 +351,45 @@ impl XmlNode { }; Ok(Self { events }) } + + fn with_font_color(&self, color: RgbColor) -> Result { + let mut events = self.events.clone(); + let mut color_event = BytesStart::new("color"); + let rgb = format!("FF{:06X}", color.value()); + color_event.push_attribute(("rgb", rgb.as_str())); + let replacement = Event::Empty(color_event.into_owned()); + if events.len() == 1 && matches!(events.first(), Some(Event::Empty(_))) { + let root = self.root()?; + let qualified_name = root.name(); + let name = std::str::from_utf8(qualified_name.as_ref()) + .map_err(|_| Error::insert_package("font element name is not UTF-8"))?; + return Ok(Self { + events: vec![ + Event::Start(clone_start(root)?), + replacement, + Event::End(BytesEnd::new(name.to_owned())), + ], + }); + } + let mut index = 1; + while index + 1 < events.len() { + match &events[index] { + Event::Start(start) if local_name(start.name().as_ref()) == b"color" => { + let end = element_end(&events, index)?; + events.splice(index..=end, [replacement]); + return Ok(Self { events }); + } + Event::Empty(empty) if local_name(empty.name().as_ref()) == b"color" => { + events[index] = replacement; + return Ok(Self { events }); + } + _ => index += 1, + } + } + let insertion = events.len().saturating_sub(1); + events.insert(insertion, replacement); + Ok(Self { events }) + } } #[derive(Debug)] @@ -742,6 +927,20 @@ fn replace_attributes( Ok(output) } +fn rewrite_selected_cell( + cell: &BytesStart<'_>, + styles: &BTreeMap, +) -> Result> { + let Some(address) = attribute(cell, b"r")? else { + return clone_start(cell); + }; + let reference = address.parse::()?; + match styles.get(&reference) { + Some(style) => replace_attributes(cell, &[(b"s", style.to_string())]), + None => clone_start(cell), + } +} + fn clone_start(event: &BytesStart<'_>) -> Result> { replace_attributes(event, &[]) } diff --git a/miniexcel/src/lib.rs b/miniexcel/src/lib.rs index be05500..e6d69bc 100644 --- a/miniexcel/src/lib.rs +++ b/miniexcel/src/lib.rs @@ -21,6 +21,8 @@ pub mod serde_helpers; mod sheet; mod streaming; mod template; +#[cfg(not(target_arch = "wasm32"))] +mod workbook_edit; mod writer; pub use analytics::{ @@ -52,3 +54,5 @@ pub use rag::{ }; pub use sheet::{SheetInfo, SheetType, SheetVisibility}; pub use streaming::{ByteQuerySummary, QuerySummary}; +#[cfg(not(target_arch = "wasm32"))] +pub use workbook_edit::WorkbookEditor; diff --git a/miniexcel/src/workbook_edit.rs b/miniexcel/src/workbook_edit.rs new file mode 100644 index 0000000..559ffa9 --- /dev/null +++ b/miniexcel/src/workbook_edit.rs @@ -0,0 +1,38 @@ +use std::collections::BTreeMap; +use std::path::PathBuf; + +use crate::{CellReference, Result, RgbColor}; + +/// A deferred set of edits for one worksheet in an existing XLSX workbook. +#[derive(Debug)] +pub struct WorkbookEditor { + path: PathBuf, + sheet_name: String, + font_colors: Vec<(CellReference, RgbColor)>, +} + +impl WorkbookEditor { + pub(crate) fn new(path: PathBuf, sheet_name: String) -> Self { + Self { path, sheet_name, font_colors: Vec::new() } + } + + /// Sets a cell's font color while preserving its other style properties. + #[must_use] + pub fn set_font_color(mut self, cell: CellReference, color: RgbColor) -> Self { + self.font_colors.push((cell, color)); + self + } + + /// Orders, deduplicates, and atomically applies all deferred edits. + pub fn save(self) -> Result<()> { + let mut font_colors = BTreeMap::new(); + for (cell, color) in self.font_colors { + font_colors.insert(cell, color); + } + crate::insert::atomic::update_font_colors_to_path( + &self.path, + &self.sheet_name, + &font_colors, + ) + } +} diff --git a/miniexcel/tests/insert.rs b/miniexcel/tests/insert.rs index 30bc7ef..41ff149 100644 --- a/miniexcel/tests/insert.rs +++ b/miniexcel/tests/insert.rs @@ -7,9 +7,9 @@ use chrono::{Duration, NaiveDate, NaiveDateTime, NaiveTime}; #[cfg(feature = "async")] use futures_util::StreamExt; use miniexcel::{ - CellValue, DynamicRow, ExistingSheetPolicy, HeaderMode, HeaderStyle, HorizontalAlignment, - InsertOptions, MiniExcel, ReadOptions, RgbColor, SheetVisibility, TableStyle, - TargetRelationshipPolicy, VerticalAlignment, WriteOptions, + CellReference, CellValue, DynamicRow, ExistingSheetPolicy, HeaderMode, HeaderStyle, + HorizontalAlignment, InsertOptions, MiniExcel, ReadOptions, RgbColor, SheetVisibility, + TableStyle, TargetRelationshipPolicy, VerticalAlignment, WriteOptions, }; use quick_xml::Reader; use quick_xml::events::{BytesStart, Event}; @@ -827,6 +827,122 @@ fn write_options_matrix_repeated_inserts_preserve_and_deduplicate_styles() { assert_eq!(final_inventory.sheets.len(), 11); } +#[test] +fn workbook_edit_applies_reverse_ordered_font_colors_when_saved() { + let directory = tempfile::tempdir().unwrap(); + let path = directory.path().join("style-edit.xlsx"); + let schema = (1..=24).map(|column| format!("Column{column}")).collect::>(); + let rows = (1..=100).map(|row| { + let mut values = DynamicRow::new(); + for (index, name) in schema.iter().enumerate() { + values.insert(name.clone(), CellValue::Int((row * 100 + index) as i64)); + } + Ok(values) + }); + MiniExcel::insert_with_schema( + &path, + &schema, + rows, + &InsertOptions::new().with_sheet_name("Data"), + ) + .unwrap(); + + let initial_bytes = std::fs::read(&path).unwrap(); + let initial_inventory = package_inventory(&initial_bytes); + let initial_data = initial_inventory.sheets.iter().find(|sheet| sheet.name == "Data").unwrap(); + let initial_worksheet = entry_text(&initial_bytes, &format!("xl/{}", initial_data.target)); + let initial_styles = read_entry(&initial_bytes, "xl/styles.xml"); + let initial_a1 = cell_xf(&initial_styles, cell_style_index(&initial_worksheet, "A1")); + + MiniExcel::edit_sheet(&path, "Data") + .set_font_color("A1".parse::().unwrap(), RgbColor::new(0, 255, 0)) + .set_font_color("X100".parse::().unwrap(), RgbColor::new(0, 0, 255)) + .set_font_color("A1".parse::().unwrap(), RgbColor::new(255, 0, 0)) + .save() + .unwrap(); + + let bytes = std::fs::read(&path).unwrap(); + let inventory = package_inventory(&bytes); + let data = inventory.sheets.iter().find(|sheet| sheet.name == "Data").unwrap(); + let worksheet = entry_text(&bytes, &format!("xl/{}", data.target)); + let styles = read_entry(&bytes, "xl/styles.xml"); + let a1_font = cell_xf(&styles, cell_style_index(&worksheet, "A1")).font_id; + let x100_font = cell_xf(&styles, cell_style_index(&worksheet, "X100")).font_id; + assert_eq!(font_rgb(&styles, a1_font).as_deref(), Some("FFFF0000")); + assert_eq!(font_rgb(&styles, x100_font).as_deref(), Some("FF0000FF")); + let mut expected_a1 = initial_a1; + expected_a1.font_id = a1_font; + assert_eq!(cell_xf(&styles, cell_style_index(&worksheet, "A1")), expected_a1); + + let counts = parse_styles(&styles); + MiniExcel::edit_sheet(&path, "Data") + .set_font_color("X100".parse::().unwrap(), RgbColor::new(0, 0, 255)) + .set_font_color("A1".parse::().unwrap(), RgbColor::new(255, 0, 0)) + .save() + .unwrap(); + assert_eq!(parse_styles(&read_entry(&std::fs::read(&path).unwrap(), "xl/styles.xml")), counts); + + let before_failure = std::fs::read(&path).unwrap(); + assert!( + MiniExcel::edit_sheet(&path, "Data") + .set_font_color("XFD1048576".parse::().unwrap(), RgbColor::new(1, 2, 3),) + .save() + .is_err() + ); + assert_eq!(std::fs::read(&path).unwrap(), before_failure); +} + +#[test] +fn workbook_edit_without_operations_leaves_the_file_unchanged() { + let directory = tempfile::tempdir().unwrap(); + let path = directory.path().join("style-edit-noop.xlsx"); + MiniExcel::insert( + &path, + &[dynamic_insert_row("No-op", 1)], + &InsertOptions::new().with_sheet_name("Data"), + ) + .unwrap(); + let before = std::fs::read(&path).unwrap(); + + MiniExcel::edit_sheet(&path, "Data").save().unwrap(); + + assert_eq!(std::fs::read(&path).unwrap(), before); +} + +#[test] +fn workbook_edit_reuses_font_and_xf_for_matching_source_styles() { + let directory = tempfile::tempdir().unwrap(); + let path = directory.path().join("style-edit-dedup.xlsx"); + MiniExcel::insert( + &path, + &[dynamic_insert_row("First", 1), dynamic_insert_row("Second", 2)], + &InsertOptions::new().with_sheet_name("Data"), + ) + .unwrap(); + let before = std::fs::read(&path).unwrap(); + let before_counts = parse_styles(&read_entry(&before, "xl/styles.xml")); + + MiniExcel::edit_sheet(&path, "dAtA") + .set_font_color("A2".parse::().unwrap(), RgbColor::new(0x12, 0x34, 0x56)) + .set_font_color("A3".parse::().unwrap(), RgbColor::new(0x12, 0x34, 0x56)) + .save() + .unwrap(); + + let bytes = std::fs::read(&path).unwrap(); + let inventory = package_inventory(&bytes); + let data = inventory.sheets.iter().find(|sheet| sheet.name == "Data").unwrap(); + let worksheet = entry_text(&bytes, &format!("xl/{}", data.target)); + let styles = read_entry(&bytes, "xl/styles.xml"); + let after_counts = parse_styles(&styles); + let a2_style = cell_style_index(&worksheet, "A2"); + let a3_style = cell_style_index(&worksheet, "A3"); + + assert_eq!(a2_style, a3_style); + assert_eq!(after_counts.fonts, before_counts.fonts + 1); + assert_eq!(after_counts.cell_xfs, before_counts.cell_xfs + 1); + assert_eq!(font_rgb(&styles, cell_xf(&styles, a2_style).font_id).as_deref(), Some("FF123456")); +} + #[test] fn write_options_matrix_hundred_insert_stress_has_unique_ids_and_bounded_growth() { let directory = tempfile::tempdir().unwrap(); @@ -2500,6 +2616,38 @@ fn cell_xf_signatures(styles_xml: &[u8]) -> Vec { (0..count).map(|index| cell_xf(styles_xml, index)).collect() } +fn font_rgb(styles_xml: &[u8], font_index: usize) -> Option { + let mut reader = Reader::from_reader(styles_xml); + let mut in_fonts = false; + let mut current_font = None; + let mut next_font = 0; + loop { + match reader.read_event().expect("parse styles XML") { + Event::Start(event) if local_name(event.name().as_ref()) == b"fonts" => { + in_fonts = true; + } + Event::End(event) if local_name(event.name().as_ref()) == b"fonts" => { + return None; + } + Event::Start(event) if in_fonts && local_name(event.name().as_ref()) == b"font" => { + current_font = Some(next_font); + next_font += 1; + } + Event::End(event) if in_fonts && local_name(event.name().as_ref()) == b"font" => { + current_font = None; + } + Event::Start(event) | Event::Empty(event) + if current_font == Some(font_index) + && local_name(event.name().as_ref()) == b"color" => + { + return attribute(&event, b"rgb"); + } + Event::Eof => return None, + _ => {} + } + } +} + fn attribute(event: &BytesStart<'_>, key: &[u8]) -> Option { event .attributes()