Files
craft-libs/crates/docx
Dylan M. TaylorandAndy Ching 046a7229af fix(docx): integrate VML fallbacks without breaking linked text-box stories (#1864)
* craft-docx: write Word 2010 shapes inside mc:AlternateContent with a VML fallback

A shape was written as a bare `wps:wsp` in `w:drawing`. Word 2007, and
Word 2000-2003 with the Office Compatibility Pack, don't know `wps` and
refuse the whole file. Word writes such shapes in `mc:AlternateContent`.

`write_shape` now guards the drawing with `mc:Choice Requires="wps"` and,
for rectangles, text boxes, rounded rectangles and ellipses, adds an
`mc:Fallback` with the shape as VML: size, position, z-order, wrapping,
fill, outline and the text box's text (copied from the choice's output,
so the story isn't written twice). Other kinds get no fallback; an old
reader skips that shape and still opens the file.

Refs storytold/wordcraft#6849

* craft-docx: guard a shape only when it gets a VML fallback; keep more in the fallback

A shape guarded by `mc:AlternateContent` with no fallback is skipped by
a reader that doesn't know `wps`, and dropped on that reader's next save:
worse than refusing the file. Such shapes are written bare again; only
shapes with a VML form are guarded.

The VML fallback also keeps the shape's own stacking order (a floating
object in its text box moved `self.z` on), its wrap distances, its hidden
flag and its text box's text direction.

* craft-docx: keep behind-text shapes' order in the VML fallback

A behind-text shape's fallback `z-index` was the negated `z`, which
reverses the order of overlapping behind-text shapes. It is now `z`
shifted below zero within signed 32-bit range, so a higher `z` still
stacks higher; other shapes' `z-index` is capped at `i32::MAX`.

* fix(docx): preserve linked text boxes without an incomplete VML fallback

---------

Co-authored-by: Andy Ching <53651198+andyching168@users.noreply.github.com>
2026-11-16 08:16:40 -05:00
..
…

craft-docx

DOCX (ECMA-376 / ISO/IEC 29500 WordprocessingML) read and written, on the craft-wordmodel document model. Also Word XML Documents (Flat OPC, one .xml file holding the whole package) and Word 2003 XML, password-protected packages and Restrict Editing password hashes.

It is WordCraft's DOCX crate, moved onto the shared crates: craft-opc for the package, craft-xml for parsing, craft-offcrypto for encryption, craft-wordmodel for the model.

use craft_wordmodel::Document;

let doc = Document::from_text("Hello\nWorld");
let bytes = craft_docx::write(&doc).unwrap();
let back = craft_docx::read(&bytes).unwrap();
assert_eq!(back.plain_text(craft_wordmodel::StoryRef::Body), doc.plain_text(craft_wordmodel::StoryRef::Body));

Reading

  • read(bytes), read_with(bytes, &ReadOptions { password, chunks }), read_with_password.
  • read_xml(bytes): a Word XML Document or a Word 2003 XML Document, told apart by its root.
  • package_title(reader, max_part): the title in docProps/core.xml, inflating only that part.

The reader is lenient (unknown markup is skipped, bad numbers fall back to defaults) and bounded:

Limit Value
ZIP entries 20,000 (checked before the archive is indexed)
One part 256 MiB
All parts 512 MiB, counting entries that fail their checksum
XML nesting 256 open elements
XML elements 8,000,000 in one part
Attributes 1,024 on one element
Word XML file 1 GiB

Markup the model does not hold is kept in Document::passthrough and the kept markup, and written back as it was read.

Writing

write(doc), write_as(doc, Flavor) for .docx, .docm, .dotx and .dotm; write_flat and write_wordml2003 for the XML forms; encrypt for a password.

Equations (OMML) are read and written by craft_math::omml.

Not here yet

  • DrawingML (a:) shape fills, lines, custom geometry and colours are still read with this crate's own code; they move to craft-drawingml.