Swiftpack.co - shinjukunian/DocX as Swift Package

Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.
See all packages published by shinjukunian.
shinjukunian/DocX v0.8.6.1
Convert NSAttributedString / AttributedString to .docx Word files on iOS and macOS
⭐️ 42
🕓 12 weeks ago
iOS macOS watchOS tvOS
.package(url: "https://github.com/shinjukunian/DocX.git", from: "v0.8.6.1")

DocX

Swift

A small framework that converts NSAttributedString to .docx Word files on iOS and macOS.

Motivation

On iOS, NSAttributedString.DocumentType supports only HTML and Rich Text, while on macOS .doc and .docx are available options. Even then the .docx exporter on macOS supports only a subset of the attributes of NSAttributedString.

This library is used in SimpleFurigana for macOS and SimpleFurigana for iOS, hence the focus on furigana annotation export.

Installation

Add

.package(name: "DocX", url: "https://github.com/shinjukunian/DocX.git", .branch("master"))

to dependencies in your Package.swift file. This requires Swift 5.3, which shipped with Xcode12. Alternatively, add DocX in Xcode via File->Swift Packages->Add Package Dependency, paste https://github.com/shinjukunian/DocX.git as URL and specify master as branch.

Usage

let string = NSAttributedString(string: "This is a string", attributes: [.font: UIFont.systemFont(ofSize: UIFont.systemFontSize), .backgroundColor: UIColor.blue])
let url = URL(fileURLWithPath:"myPath")
try? string.writeDocX(to: url)

Starting from iOS 15 / macOS 12, you can use the new AttributedString.

var att=AttributedString("Lorem ipsum dolor sit amet")
att.font = NSFont(name: "Helvetica", size: 12)
att[att.range(of: "Lorem")!].backgroundColor = .blue
let url = URL(fileURLWithPath:"myPath")
try att.writeDocX(to: url)

Naturally, this works for Markdown as well:

let mD="~~This~~ is a **Markdown** *string*."
let att=try AttributedString(markdown: mD)
try att.writeDocX(to: url)

DocXOptions allow the customization of DocX output.

  • you can optionally specify metadata using DocXOptions:
let font = NSFont(name: "Helvetica", size: 13)! //on macOS
let string = NSAttributedString(string: "The Foundation For Law and Government favours Helvetica.", attributes: [.font: font])

var options = DocXOptions()
options.author = "Michael Knight"
options.title = "Helvetica Document"

let url = URL(fileURLWithPath:"myPath")
try string.writeDocX(to: url, options:options)
  • you can specify character and paragraph styling based on a style document using the NSAttributedString.Key.characterStyleId and NSAttributedString.Key.paragraphStyleId attributes. Use DocXStyleConfiguration to specify the style document.

  • you can use DocXStyleConfiguration to specify that Word should use standard fonts instead of explicitly specified font names. This is useful for cross-platform compatibility when using Apple system fonts. Other font attributes (size, bold / italic) will be preserved if possible.

See the attached sample projects (for iOS and macOS) for usage and limitations. On iOS, DocX also includes a UIActivityItemProvider subclass (DocXActivityItemProvider) for exporting .docx files through UIActivityViewController.

NSAttributedString has no concept of pagination. For manual pagination, use

try DocXWriter.write(pages:[NSAttributedString], to url:URL)

to render each NSAttributedString as a separate page.

Screenshot macOS

A sample output on macOS opened in Word365.

Screenshot Lenna

A sample output on macOS with an embedded image (via NSTextAttachment). in the macOS sample application (which is a simple NSTextView), this can be achieved using drag&drop. Note that there is little control over the placement of the image, the image will be inline with text.

Screenshot iOS

A sample output on iOS opened in Word for iOS. Furigana annotations are preserved. The link is clickable. Please note that Quicklook (on both platforms) only supports a limited number of attributes.

Supported Attributes

  • most things in NSAttributedString.Key (fonts, colors, underline, indents etc.) except
    • NSAttributedString.Key.expansion
    • NSAttributedString.Key.kern
    • NSAttributedString.Key.ligature
    • NSAttributedString.Key.obliqueness
    • NSAttributedString.Key.superscript (macOS only, doesnt really work for most fonts anyway). Use NSAttributedString.Key.baselineOffset with a positive value for superscript and a negative value for subscript instead
    • NSAttributedString.Key.textEffect
  • CTRubyAnnotation for furigana (ruby) annotations in CoreText
  • NSTextAttachment embedded images (inline with text)

For AttributedString, DocX supports the attributes present in NSAttributedString, i.e. most attributes in AttributeScopes.AppKitAttributes or AttributeScopes.UIKitAttributes (see above for omissions). For AttributedStrings initialized from Markdown (AttributeScopes.FoundationAttributes), DocX supports links (AttributeScopes.FoundationAttributes.LinkAttribute), bold, italic, and strikethrough (AttributeScopes.FoundationAttributes.InlinePresentationIntentAttribute), and inline images (AttributeScopes.FoundationAttributes.ImageURLAttribute). Please note that images are not rendered by SwiftUI's Text.

Some attributes don't have a direct correspondence. For example NSAttributedString does (typically) not have the concept of a page size.

Dependencies

Alternatives

References

Licence

MIT

GitHub

link
Stars: 42
Last commit: Yesterday
jonrohan Something's broken? Yell at me @ptrpavlik. Praise and feedback (and money) is also welcome.

Related Packages

Release Notes

12 weeks ago
  • certain characters (& etc.) are now properly escaped
  • DocX now outputs modern .docx files, avoiding the compatibility mode warning in Word
  • greatly improved performance when writing long strings

Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics