|
1 | | -[](https://www.npmjs.com/package/docx-preview) |
2 | | -[](https://war.ukraine.ua/) |
3 | | - |
4 | | -# docxjs |
5 | | -Docx rendering library |
6 | | - |
7 | | -Demo - https://volodymyrbaydalka.github.io/docxjs/ |
8 | | - |
9 | | -Goal |
10 | | ----- |
11 | | -Goal of this project is to render/convert DOCX document into HTML document with keeping HTML semantic as much as possible. |
12 | | -That means library is limited by HTML capabilities (for example Google Docs renders *.docx document on canvas as an image). |
13 | | - |
14 | | -Installation |
15 | | ------ |
16 | | -``` |
17 | | -npm install docx-preview |
18 | | -``` |
19 | | - |
20 | | -Usage |
21 | | ------ |
22 | | -```html |
23 | | -<!--lib uses jszip--> |
24 | | -<script src="https://unpkg.com/jszip/dist/jszip.min.js"></script> |
25 | | -<script src="docx-preview.min.js"></script> |
26 | | -<script> |
27 | | - var docData = <document Blob>; |
28 | | -
|
29 | | - docx.renderAsync(docData, document.getElementById("container")) |
30 | | - .then(x => console.log("docx: finished")); |
31 | | -</script> |
32 | | -<body> |
33 | | - ... |
34 | | - <div id="container"></div> |
35 | | - ... |
36 | | -</body> |
37 | | -``` |
38 | | -API |
39 | | ---- |
40 | | -```ts |
41 | | -// renders document into specified element |
42 | | -renderAsync( |
43 | | - document: Blob | ArrayBuffer | Uint8Array, // could be any type that supported by JSZip.loadAsync |
44 | | - bodyContainer: HTMLElement, //element to render document content, |
45 | | - styleContainer: HTMLElement, //element to render document styles, numbeings, fonts. If null, bodyContainer will be used. |
46 | | - options: { |
47 | | - className: string = "docx", //class name/prefix for default and document style classes |
48 | | - inWrapper: boolean = true, //enables rendering of wrapper around document content |
49 | | - hideWrapperOnPrint: boolean = false, //disable wrapper styles on print |
50 | | - ignoreWidth: boolean = false, //disables rendering width of page |
51 | | - ignoreHeight: boolean = false, //disables rendering height of page |
52 | | - ignoreFonts: boolean = false, //disables fonts rendering |
53 | | - breakPages: boolean = true, //enables page breaking on page breaks |
54 | | - ignoreLastRenderedPageBreak: boolean = true, //disables page breaking on lastRenderedPageBreak elements |
55 | | - experimental: boolean = false, //enables experimental features (tab stops calculation) |
56 | | - trimXmlDeclaration: boolean = true, //if true, xml declaration will be removed from xml documents before parsing |
57 | | - useBase64URL: boolean = false, //if true, images, fonts, etc. will be converted to base 64 URL, otherwise URL.createObjectURL is used |
58 | | - renderChanges: false, //enables experimental rendering of document changes (inserions/deletions) |
59 | | - renderHeaders: true, //enables headers rendering |
60 | | - renderFooters: true, //enables footers rendering |
61 | | - renderFootnotes: true, //enables footnotes rendering |
62 | | - renderEndnotes: true, //enables endnotes rendering |
63 | | - renderComments: false, //enables experimental comments rendering |
64 | | - renderAltChunks: true, //enables altChunks (html parts) rendering |
65 | | - debug: boolean = false, //enables additional logging |
66 | | - }): Promise<WordDocument> |
67 | | - |
68 | | -/// ==== experimental / internal API === |
69 | | -// this API could be used to modify document before rendering |
70 | | -// renderAsync = parseAsync + renderDocument |
71 | | - |
72 | | -// parse document and return internal document object |
73 | | -parseAsync( |
74 | | - document: Blob | ArrayBuffer | Uint8Array, |
75 | | - options: Options |
76 | | -): Promise<WordDocument> |
77 | | - |
78 | | -// render internal document object into specified container |
79 | | -renderDocument( |
80 | | - wordDocument: WordDocument, |
81 | | - bodyContainer: HTMLElement, |
82 | | - styleContainer: HTMLElement, |
83 | | - options: Options |
84 | | -): Promise<void> |
85 | | -``` |
86 | | - |
87 | | -Thumbnails, TOC and etc. |
88 | | ------- |
89 | | -Thumbnails is added only for example and it's not part of library. Library renders DOCX into HTML, so it can't be efficiently used for thumbnails. |
90 | | - |
91 | | -Table of contents is built using the TOC fields and there is no efficient way to get table of contents at this point, since fields is not supported yet (http://officeopenxml.com/WPtableOfContents.php) |
92 | | - |
93 | | -Breaks |
94 | | ------- |
95 | | -Currently library does break pages: |
96 | | -- if user/manual page break `<w:br w:type="page"/>` is inserted - when user insert page break |
97 | | -- if application page break `<w:lastRenderedPageBreak/>` is inserted - could be inserted by editor application like MS word (`ignoreLastRenderedPageBreak` should be set to false) |
98 | | -- if page settings for paragraph is changed - ex: user change settings from portrait to landscape page |
99 | | - |
100 | | -Realtime page breaking is not implemented because it's requires re-calculation of sizes on each insertion and that could affect performance a lot. |
101 | | - |
102 | | -If page breaking is crutual for you, I would recommend: |
103 | | -- try to insert manual break point as much as you could |
104 | | -- try use editors like MS Word, that inserts `<w:lastRenderedPageBreak/>` break points |
105 | | - |
106 | | -NOTE: by default `ignoreLastRenderedPageBreak` is set to `true`. You may need to set it to `false`, to make library break by `<w:lastRenderedPageBreak/>` break points |
107 | | - |
108 | | -Status and stability |
109 | | ------- |
110 | | -So far I can't come up with final approach of parsing documents and final structure of API. Only **renderAsync** function is stable and definition shouldn't be changed in future. Inner implementation of parsing and rendering may be changed at any point of time. |
111 | | - |
112 | | -Contributing |
113 | | ------- |
114 | | -Please do not include contents of `./dist` folder in your PR's. Otherwise I most likely will reject it due to stability and security concerns. |
| 1 | +[](https://www.npmjs.com/package/docx-preview) |
| 2 | +[](https://war.ukraine.ua/) |
| 3 | + |
| 4 | +# docxjs |
| 5 | +Docx rendering library |
| 6 | + |
| 7 | +Demo - https://volodymyrbaydalka.github.io/docxjs/ |
| 8 | + |
| 9 | +Goal |
| 10 | +---- |
| 11 | +Goal of this project is to render/convert DOCX document into HTML document with keeping HTML semantic as much as possible. |
| 12 | +That means library is limited by HTML capabilities (for example Google Docs renders *.docx document on canvas as an image). |
| 13 | + |
| 14 | +Installation |
| 15 | +----- |
| 16 | +``` |
| 17 | +npm install docx-preview |
| 18 | +``` |
| 19 | + |
| 20 | +Usage |
| 21 | +----- |
| 22 | +```html |
| 23 | +<!--lib uses jszip--> |
| 24 | +<script src="https://unpkg.com/jszip/dist/jszip.min.js"></script> |
| 25 | +<script src="docx-preview.min.js"></script> |
| 26 | +<script> |
| 27 | + var docData = <document Blob>; |
| 28 | +
|
| 29 | + docx.renderAsync(docData, document.getElementById("container")) |
| 30 | + .then(x => console.log("docx: finished")); |
| 31 | +</script> |
| 32 | +<body> |
| 33 | + ... |
| 34 | + <div id="container"></div> |
| 35 | + ... |
| 36 | +</body> |
| 37 | +``` |
| 38 | +API |
| 39 | +--- |
| 40 | +```ts |
| 41 | +// renders document into specified element |
| 42 | +renderAsync( |
| 43 | + document: Blob | ArrayBuffer | Uint8Array, // could be any type that supported by JSZip.loadAsync |
| 44 | + bodyContainer: HTMLElement, //element to render document content, |
| 45 | + styleContainer: HTMLElement, //element to render document styles, numbeings, fonts. If null, bodyContainer will be used. |
| 46 | + options: { |
| 47 | + className: string = "docx", //class name/prefix for default and document style classes |
| 48 | + inWrapper: boolean = true, //enables rendering of wrapper around document content |
| 49 | + hideWrapperOnPrint: boolean = false, //disable wrapper styles on print |
| 50 | + ignoreWidth: boolean = false, //disables rendering width of page |
| 51 | + ignoreHeight: boolean = false, //disables rendering height of page |
| 52 | + ignoreFonts: boolean = false, //disables fonts rendering |
| 53 | + breakPages: boolean = true, //enables page breaking on page breaks |
| 54 | + ignoreLastRenderedPageBreak: boolean = true, //disables page breaking on lastRenderedPageBreak elements |
| 55 | + experimental: boolean = false, //enables experimental features (tab stops calculation) |
| 56 | + trimXmlDeclaration: boolean = true, //if true, xml declaration will be removed from xml documents before parsing |
| 57 | + useBase64URL: boolean = false, //if true, images, fonts, etc. will be converted to base 64 URL, otherwise URL.createObjectURL is used |
| 58 | + renderChanges: false, //enables experimental rendering of document changes (inserions/deletions) |
| 59 | + renderHeaders: true, //enables headers rendering |
| 60 | + renderFooters: true, //enables footers rendering |
| 61 | + renderFootnotes: true, //enables footnotes rendering |
| 62 | + renderEndnotes: true, //enables endnotes rendering |
| 63 | + renderComments: false, //enables experimental comments rendering |
| 64 | + renderAltChunks: true, //enables altChunks (html parts) rendering |
| 65 | + debug: boolean = false, //enables additional logging |
| 66 | + }): Promise<WordDocument> |
| 67 | + |
| 68 | +/// ==== experimental / internal API === |
| 69 | +// this API could be used to modify document before rendering |
| 70 | +// renderAsync = parseAsync + renderDocument |
| 71 | + |
| 72 | +// parse document and return internal document object |
| 73 | +parseAsync( |
| 74 | + document: Blob | ArrayBuffer | Uint8Array, |
| 75 | + options: Options |
| 76 | +): Promise<WordDocument> |
| 77 | + |
| 78 | +// render internal document object into specified container |
| 79 | +renderDocument( |
| 80 | + wordDocument: WordDocument, |
| 81 | + bodyContainer: HTMLElement, |
| 82 | + styleContainer: HTMLElement, |
| 83 | + options: Options |
| 84 | +): Promise<void> |
| 85 | +``` |
| 86 | + |
| 87 | +Thumbnails, TOC and etc. |
| 88 | +------ |
| 89 | +Thumbnails is added only for example and it's not part of library. Library renders DOCX into HTML, so it can't be efficiently used for thumbnails. |
| 90 | + |
| 91 | +Table of contents is built using the TOC fields and there is no efficient way to get table of contents at this point, since fields is not supported yet (http://officeopenxml.com/WPtableOfContents.php) |
| 92 | + |
| 93 | +Breaks |
| 94 | +------ |
| 95 | +Currently library does break pages: |
| 96 | +- if user/manual page break `<w:br w:type="page"/>` is inserted - when user insert page break |
| 97 | +- if application page break `<w:lastRenderedPageBreak/>` is inserted - could be inserted by editor application like MS word (`ignoreLastRenderedPageBreak` should be set to false) |
| 98 | +- if page settings for paragraph is changed - ex: user change settings from portrait to landscape page |
| 99 | + |
| 100 | +Realtime page breaking is not implemented because it's requires re-calculation of sizes on each insertion and that could affect performance a lot. |
| 101 | + |
| 102 | +If page breaking is crutual for you, I would recommend: |
| 103 | +- try to insert manual break point as much as you could |
| 104 | +- try use editors like MS Word, that inserts `<w:lastRenderedPageBreak/>` break points |
| 105 | + |
| 106 | +NOTE: by default `ignoreLastRenderedPageBreak` is set to `true`. You may need to set it to `false`, to make library break by `<w:lastRenderedPageBreak/>` break points |
| 107 | + |
| 108 | +Status and stability |
| 109 | +------ |
| 110 | +So far I can't come up with final approach of parsing documents and final structure of API. Only **renderAsync** function is stable and definition shouldn't be changed in future. Inner implementation of parsing and rendering may be changed at any point of time. |
| 111 | + |
| 112 | +Contributing |
| 113 | +------ |
| 114 | +Please do not include contents of `./dist` folder in your PR's. Otherwise I most likely will reject it due to stability and security concerns. |
0 commit comments