Complete XLSX insert WriteOptions support

Author: shps951023

docs/insert-existing-workbook-plan.md

@@ -317,17 +317,23 @@ Acceptance:
 
 Depends on Tasks 6-8.
 
-- [ ] Run inserted sheets through all current write options: headers, AutoFilter, panes, RTL, AutoWidth, fixed/hidden columns, body wrap/alignment, header style, `TableStyle`, number formats, sheet visibility, and case-insensitive names.
-- [ ] Add dynamic, explicit-schema, Serde, empty, header-only, and multi-insert sequences.
-- [ ] Verify that donor style rebasing does not change existing style IDs after repeated inserts.
-- [ ] Add a 100-insert stress test for ID/path collisions and package growth.
+- [x] Run inserted sheets through all current write options: headers, AutoFilter, panes, RTL, AutoWidth, fixed/hidden columns, body wrap/alignment, header style, `TableStyle`, number formats, sheet visibility, and case-insensitive names.
+- [x] Add dynamic, explicit-schema, Serde, empty, header-only, and multi-insert sequences.
+- [x] Verify that donor style rebasing does not change existing style IDs after repeated inserts.
+- [x] Add a 100-insert stress test for ID/path collisions and package growth.
 
 Acceptance:
 
 - Every supported new-workbook option has an Insert test.
 - Repeated inserts remain readable by Rust, LibreOffice, and the .NET Open XML SDK.
 - Focused command: `cargo +1.85.0 test -p miniexcel --test insert write_options_matrix --locked`.
 
+Completed on 2026-08-25. The focused matrix covers dynamic rows, explicit-schema
+iterators, Serde rows, empty/header-only sheets, append visibility, style stability, and a
+100-insert collision/growth run. The generated 101-sheet stress workbook was read by the Rust
+CLI, round-tripped by LibreOffice 26.2.1.2, and validated with zero Office 2019 schema errors by
+the .NET Open XML SDK 3.5.1 before and after the roundtrip.
+
 ### Task 10: Separate Reader/Writer Insert API
 
 Depends on Task 9.

docs/insert-existing-workbook-plan.zh-CN.md

@@ -317,17 +317,23 @@ Donor-workbook 方案复用经过测试的 `XlsxWriter`，避免重复实现 ser
 
 依赖 Task 6-8。
 
-- [ ] 插入 sheet 覆盖全部当前 write option：header、AutoFilter、pane、RTL、AutoWidth、固定/隐藏列、body wrap/alignment、header style、`TableStyle`、number format、sheet visibility 和大小写不敏感 name。
-- [ ] 增加 dynamic、显式 schema、Serde、empty、header-only 和连续多次 insert。
-- [ ] 验证 donor style rebase 在重复 insert 后不改变现有 style ID。
-- [ ] 增加 100 次 insert 的 ID/path collision 与 package growth stress test。
+- [x] 插入 sheet 覆盖全部当前 write option：header、AutoFilter、pane、RTL、AutoWidth、固定/隐藏列、body wrap/alignment、header style、`TableStyle`、number format、sheet visibility 和大小写不敏感 name。
+- [x] 增加 dynamic、显式 schema、Serde、empty、header-only 和连续多次 insert。
+- [x] 验证 donor style rebase 在重复 insert 后不改变现有 style ID。
+- [x] 增加 100 次 insert 的 ID/path collision 与 package growth stress test。
 
 验收：
 
 - 每个已支持 new-workbook option 都有 Insert test。
 - 重复 insert 后仍可被 Rust、LibreOffice 和 .NET Open XML SDK 读取。
 - 聚焦命令：`cargo +1.85.0 test -p miniexcel --test insert write_options_matrix --locked`。
 
+已于 2026-08-25 完成。聚焦矩阵覆盖 dynamic row、显式 schema iterator、Serde row、
+empty/header-only sheet、append visibility、style 稳定性，以及 100 次 insert 的
+collision/growth 压力测试。生成的 101-sheet 压力工作簿已由 Rust CLI 读取，经
+LibreOffice 26.2.1.2 roundtrip，并在 roundtrip 前后均通过 .NET Open XML SDK 3.5.1
+的 Office 2019 schema 验证，错误数为零。
+
 ### Task 10：分离 Reader/Writer Insert API
 
 依赖 Task 9。

miniexcel/src/facade.rs

@@ -7,7 +7,10 @@ use serde::de::DeserializeOwned;
 use crate::streaming::{StreamingRows, StreamingStructuredRows, StreamingTypedRows};
 use crate::writer::XlsxWriter;
 #[cfg(not(target_arch = "wasm32"))]
-use crate::writer::{validate_dimensions, validate_schema, validate_single_sheet_options};
+use crate::writer::{
+    validate_dimensions, validate_insert_sheet_options, validate_schema,
+    validate_single_sheet_options,
+};
 use crate::{
     AnalysisResult, ByteQuerySummary, DynamicRow, ExcelRange, QueryPlan, QuerySummary, RagChunk,
     RagExport, RagExportOptions, RagManifest, ReadOptions, Result, SheetInfo, StructuredRow,
@@ -607,5 +610,9 @@ fn validate_insert_options(path: &Path, options: &InsertOptions) -> Result<()> {
             "target relationship removal requires ExistingSheetPolicy::Replace",
         ));
     }
-    validate_single_sheet_options(options.write_options())
+    if path.exists() {
+        validate_insert_sheet_options(options.write_options())
+    } else {
+        validate_single_sheet_options(options.write_options())
+    }
 }

miniexcel/src/insert/donor.rs

@@ -11,7 +11,7 @@ use super::package::{DefinedName, PackageInventory};
 use crate::writer::XlsxWriter;
 #[cfg(not(target_arch = "wasm32"))]
 use crate::writer::validate_dimensions;
-use crate::{DynamicRow, Error, Result, WriteOptions};
+use crate::{DynamicRow, Error, Result, SheetVisibility, WriteOptions};
 
 const STYLES_PATH: &str = "xl/styles.xml";
 const SHARED_STRINGS_PATH: &str = "xl/sharedStrings.xml";
@@ -32,6 +32,7 @@ pub(crate) struct DonorStyleModel {
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub(crate) struct DonorWorksheet {
     pub(crate) sheet_name: String,
+    pub(crate) visibility: SheetVisibility,
     pub(crate) worksheet_xml: Vec<u8>,
     pub(crate) data_row_count: usize,
     pub(crate) styles: DonorStyleModel,
@@ -47,7 +48,11 @@ impl DonorBuilder {
     ) -> Result<DonorWorksheet> {
         let mut writer = XlsxWriter::new();
         writer.add_rows(rows, options)?;
-        extract_donor(writer.save_to_bytes()?, rows.len())
+        extract_donor(
+            writer.save_insert_donor_to_bytes()?,
+            rows.len(),
+            options.sheet_visibility(options.sheet_name()),
+        )
     }
 
     pub(crate) fn from_dynamic_with_schema(
@@ -57,7 +62,11 @@ impl DonorBuilder {
     ) -> Result<DonorWorksheet> {
         let mut writer = XlsxWriter::new();
         writer.add_rows_with_schema(schema, rows, options)?;
-        extract_donor(writer.save_to_bytes()?, rows.len())
+        extract_donor(
+            writer.save_insert_donor_to_bytes()?,
+            rows.len(),
+            options.sheet_visibility(options.sheet_name()),
+        )
     }
 
     pub(crate) fn from_serialized<T>(rows: &[T], options: &WriteOptions) -> Result<DonorWorksheet>
@@ -66,7 +75,11 @@ impl DonorBuilder {
     {
         let mut writer = XlsxWriter::new();
         writer.add_serialized(rows, options)?;
-        extract_donor(writer.save_to_bytes()?, rows.len())
+        extract_donor(
+            writer.save_insert_donor_to_bytes()?,
+            rows.len(),
+            options.sheet_visibility(options.sheet_name()),
+        )
     }
 
     #[cfg(not(target_arch = "wasm32"))]
@@ -98,8 +111,12 @@ where
     let mut writer = XlsxWriter::new();
     writer.add_rows_iter_with_schema(schema, rows, row_count, options)?;
     let mut package = tempfile::NamedTempFile::new()?;
-    writer.save_to_writer(package.as_file_mut())?;
-    extract_donor_from_reader(package.reopen()?, row_count)
+    writer.save_insert_donor_to_writer(package.as_file_mut())?;
+    extract_donor_from_reader(
+        package.reopen()?,
+        row_count,
+        options.sheet_visibility(options.sheet_name()),
+    )
 }
 
 #[cfg(not(target_arch = "wasm32"))]
@@ -166,11 +183,19 @@ fn spooled_rows(
         }))
 }
 
-pub(super) fn extract_donor(bytes: Vec<u8>, data_row_count: usize) -> Result<DonorWorksheet> {
-    extract_donor_from_reader(Cursor::new(bytes), data_row_count)
+pub(super) fn extract_donor(
+    bytes: Vec<u8>,
+    data_row_count: usize,
+    visibility: SheetVisibility,
+) -> Result<DonorWorksheet> {
+    extract_donor_from_reader(Cursor::new(bytes), data_row_count, visibility)
 }
 
-fn extract_donor_from_reader<R>(mut source: R, data_row_count: usize) -> Result<DonorWorksheet>
+fn extract_donor_from_reader<R>(
+    mut source: R,
+    data_row_count: usize,
+    visibility: SheetVisibility,
+) -> Result<DonorWorksheet>
 where
     R: Read + std::io::Seek,
 {
@@ -206,7 +231,14 @@ where
     };
     let worksheet_xml = inline_shared_strings(&worksheet_xml, &shared_strings)?;
 
-    Ok(DonorWorksheet { sheet_name, worksheet_xml, data_row_count, styles, local_defined_names })
+    Ok(DonorWorksheet {
+        sheet_name,
+        visibility,
+        worksheet_xml,
+        data_row_count,
+        styles,
+        local_defined_names,
+    })
 }
 
 fn read_part<R>(archive: &mut ZipArchive<R>, path: &str) -> Result<Vec<u8>>

miniexcel/src/insert/rewrite.rs

@@ -9,7 +9,7 @@ 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, TargetRelationshipPolicy};
+use crate::{Error, Result, SheetVisibility, TargetRelationshipPolicy};
 
 const CONTENT_TYPES_PATH: &str = "[Content_Types].xml";
 const WORKBOOK_PATH: &str = "xl/workbook.xml";
@@ -294,6 +294,7 @@ where
     let workbook_xml = append_workbook(
         &workbook_xml,
         &donor.sheet_name,
+        donor.visibility,
         &allocation,
         inventory.sheets.len(),
         &donor.local_defined_names,
@@ -533,6 +534,7 @@ fn styles_path(inventory: &PackageInventory) -> Result<String> {
 fn append_workbook(
     xml: &[u8],
     sheet_name: &str,
+    visibility: SheetVisibility,
     allocation: &WorksheetAllocation,
     local_sheet_id: usize,
     local_defined_names: &[DefinedName],
@@ -567,6 +569,7 @@ fn append_workbook(
                 write_new_sheet(
                     &mut writer,
                     sheet_name,
+                    visibility,
                     allocation,
                     &prefix,
                     &relationship_prefix,
@@ -1122,6 +1125,7 @@ where
 fn write_new_sheet(
     writer: &mut Writer<Vec<u8>>,
     sheet_name: &str,
+    visibility: SheetVisibility,
     allocation: &WorksheetAllocation,
     element_prefix: &str,
     relationship_prefix: &str,
@@ -1131,6 +1135,11 @@ fn write_new_sheet(
     let relationship_id_name = qualify(relationship_prefix, "id");
     sheet.push_attribute(("name", sheet_name));
     sheet.push_attribute(("sheetId", sheet_id.as_str()));
+    match visibility {
+        SheetVisibility::Visible => {}
+        SheetVisibility::Hidden => sheet.push_attribute(("state", "hidden")),
+        SheetVisibility::VeryHidden => sheet.push_attribute(("state", "veryHidden")),
+    }
     sheet.push_attribute((relationship_id_name.as_str(), allocation.relationship_id.as_str()));
     write_event(writer, Event::Empty(sheet))
 }
@@ -1692,8 +1701,15 @@ mod tests {
             formula: "'New Data'!$A$1:$A$2".to_owned(),
         };
         let workbook = br#"<workbook xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"><sheets><sheet name="A" sheetId="1" r:id="rId1"/></sheets><externalReferences><externalReference r:id="rId4"/></externalReferences><calcPr calcId="7"/></workbook>"#;
-        let patched =
-            append_workbook(workbook, "New Data", &allocation, 1, &[defined_name]).unwrap();
+        let patched = append_workbook(
+            workbook,
+            "New Data",
+            SheetVisibility::Visible,
+            &allocation,
+            1,
+            &[defined_name],
+        )
+        .unwrap();
         let text = String::from_utf8(patched).unwrap();
         assert!(text.contains("<definedNames><definedName"));
         assert!(text.find("</sheets>").unwrap() < text.find("<definedNames>").unwrap());
@@ -1705,7 +1721,15 @@ mod tests {
 
         let prefixed_workbook = br#"<x:workbook xmlns:x="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:q="http://schemas.openxmlformats.org/officeDocument/2006/relationships"><x:sheets><x:sheet name="A" sheetId="1" q:id="rId1"/></x:sheets><x:calcPr calcId="7"/></x:workbook>"#;
         let prefixed = String::from_utf8(
-            append_workbook(prefixed_workbook, "New Data", &allocation, 1, &[]).unwrap(),
+            append_workbook(
+                prefixed_workbook,
+                "New Data",
+                SheetVisibility::Visible,
+                &allocation,
+                1,
+                &[],
+            )
+            .unwrap(),
         )
         .unwrap();
         assert!(prefixed.contains("<x:sheet name=\"New Data\" sheetId=\"5\" q:id=\"rId8\"/>"));

miniexcel/src/insert/style.rs

@@ -746,7 +746,7 @@ mod tests {
     use super::*;
     use crate::insert::donor::{DonorBuilder, extract_donor};
     use crate::writer::XlsxWriter;
-    use crate::{CellValue, DynamicRow, MiniExcel, ReadOptions, WriteOptions};
+    use crate::{CellValue, DynamicRow, MiniExcel, ReadOptions, SheetVisibility, WriteOptions};
 
     #[derive(Serialize)]
     struct CustomFormatRow {
@@ -800,6 +800,7 @@ mod tests {
         let first = rebase_styles(target_styles().as_bytes(), &donor).unwrap();
         let donor_again = DonorWorksheet {
             sheet_name: donor.sheet_name.clone(),
+            visibility: donor.visibility,
             worksheet_xml: donor.worksheet_xml.clone(),
             data_row_count: donor.data_row_count,
             styles: super::super::donor::DonorStyleModel {
@@ -919,7 +920,7 @@ mod tests {
         let mut writer = XlsxWriter::new();
         writer.add_rows(&[row], &options).unwrap();
         let package = writer.save_to_bytes().unwrap();
-        let extracted = extract_donor(package.clone(), 1).unwrap();
+        let extracted = extract_donor(package.clone(), 1, SheetVisibility::Visible).unwrap();
         assert_eq!(donor, extracted);
         (donor, package)
     }

miniexcel/src/writer.rs

@@ -93,7 +93,7 @@ impl XlsxWriter {
     }
 
     pub(crate) fn save(&mut self, path: impl AsRef<Path>, overwrite_file: bool) -> Result<()> {
-        self.validate_workbook()?;
+        self.validate_workbook(true)?;
         let file = OpenOptions::new()
             .write(true)
             .create(true)
@@ -105,15 +105,30 @@ impl XlsxWriter {
     }
 
     pub(crate) fn save_to_bytes(&mut self) -> Result<Vec<u8>> {
-        self.validate_workbook()?;
+        self.validate_workbook(true)?;
+        Ok(self.workbook.save_to_buffer()?)
+    }
+
+    pub(crate) fn save_insert_donor_to_bytes(&mut self) -> Result<Vec<u8>> {
+        self.validate_workbook(false)?;
         Ok(self.workbook.save_to_buffer()?)
     }
 
     pub(crate) fn save_to_writer<W>(&mut self, writer: &mut W) -> Result<()>
     where
         W: Write + Send,
     {
-        self.validate_workbook()?;
+        self.validate_workbook(true)?;
+        self.workbook.save_to_writer(writer)?;
+        Ok(())
+    }
+
+    #[cfg(not(target_arch = "wasm32"))]
+    pub(crate) fn save_insert_donor_to_writer<W>(&mut self, writer: &mut W) -> Result<()>
+    where
+        W: Write + Send,
+    {
+        self.validate_workbook(false)?;
         self.workbook.save_to_writer(writer)?;
         Ok(())
     }
@@ -193,13 +208,13 @@ impl XlsxWriter {
         self.sheet_names.insert(normalized_name);
     }
 
-    fn validate_workbook(&self) -> Result<()> {
+    fn validate_workbook(&self, require_visible_worksheet: bool) -> Result<()> {
         if let Some(name) =
             self.requested_visibilities.difference(&self.matched_visibilities).next()
         {
             return Err(Error::unknown_sheet_visibility(name));
         }
-        if self.visible_worksheets == 0 {
+        if require_visible_worksheet && self.visible_worksheets == 0 {
             return Err(Error::no_visible_worksheets());
         }
         Ok(())
@@ -381,6 +396,15 @@ fn validate_auto_width_options(options: &WriteOptions) -> Result<()> {
 
 #[cfg(not(target_arch = "wasm32"))]
 pub(crate) fn validate_single_sheet_options(options: &WriteOptions) -> Result<()> {
+    validate_insert_sheet_options(options)?;
+    if options.sheet_visibility(options.sheet_name()) != SheetVisibility::Visible {
+        return Err(Error::no_visible_worksheets());
+    }
+    Ok(())
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+pub(crate) fn validate_insert_sheet_options(options: &WriteOptions) -> Result<()> {
     validate_sheet_name(options.sheet_name(), &HashSet::new())?;
     validate_auto_width_options(options)?;
     validate_column_widths(options)?;
@@ -391,9 +415,6 @@ pub(crate) fn validate_single_sheet_options(options: &WriteOptions) -> Result<()
     {
         return Err(Error::unknown_sheet_visibility(name));
     }
-    if options.sheet_visibility(options.sheet_name()) != SheetVisibility::Visible {
-        return Err(Error::no_visible_worksheets());
-    }
     Ok(())
 }