A small framework that converts NSAttributedString to .docx Word files on iOS and macOS.
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.
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.
Add
pod 'DocX-Swift'
to your Podfile.
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.
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.
you can specify a page size using .pageDefinition
. Page definitions consist of a paper size and margins to determine the printable area. If no page definition is specified, Word will fall back to useful defaults based on the current system.
let A4 = PageDefinition(pageSize: .A4) // an A4 page with defaults margins
let square = PageDefinition(pageSize: .init(width: Measurement(value: 10, unit: .centimeters), height: Measurement(value: 10, unit: .centimeters))) // a custom square page size with default (72 pt) margins)
let custom = PageDefinition(pageSize: .init(width: .init(value: 30, unit: .centimeters), height: .init(value: 20, unit: .centimeters)), pageMargins: .init(top: .init(value: 1, unit: .centimeters), bottom: .init(value: 1, unit: .centimeters), left: .init(value: 1, unit: .centimeters), right: .init(value: 1, unit: .centimeters))) // a page with custom paper and custom margins
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.
A sample output on macOS opened in Word365.
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.
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.
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 insteadNSAttributedString.Key.textEffect
CTRubyAnnotation
for furigana (ruby) annotations in CoreTextNSTextAttachment
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. The page size can be specified by creating a PageDefinition
and specifying DocXOptions.pageDefinition
.
MIT
link |
Stars: 70 |
Last commit: 1 year ago |
Full Changelog: https://github.com/shinjukunian/DocX/compare/0.8.7...0.8.8
Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics