Sakurai/pdf.js
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #12156 from timvandermeij/types-followup

Browse Source 
Improve the types generation and API documentation (PR 12102 follow-up)
This commit is contained in:
Tim van der Meij 2020-08-04 23:40:44 +02:00 committed by GitHub
commit 71f8e1f538
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 219 additions and 247 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
gulpfile.js
View File

@ -63,7 +63,8 @@ var GH_PAGES_DIR = BUILD_DIR + "gh-pages/";
var SRC_DIR = "src/";
var LIB_DIR = BUILD_DIR + "lib/";
var DIST_DIR = BUILD_DIR + "dist/";
var TYPES_BUILD_DIR = BUILD_DIR + "types/";
var TYPES_DIR = BUILD_DIR + "types/";
var TYPESTEST_DIR = BUILD_DIR + "typestest/";
var COMMON_WEB_FILES = ["web/images/*.{png,svg,gif,cur}", "web/debugger.js"];
var MOZCENTRAL_DIFF_FILE = "mozcentral.diff";
@ -1143,12 +1144,12 @@ gulp.task("jsdoc", function (done) {
});
gulp.task("types", function (done) {
console.log("### Generating typescript definitions using tsc");
var args = [
console.log("### Generating TypeScript definitions using `tsc`");
const args = [
"target ES2020",
"allowJS",
"declaration",
`outDir ${TYPES_BUILD_DIR}`,
`outDir ${TYPES_DIR}`,
"strict",
"esModuleInterop",
"forceConsistentCasingInFileNames",
@ -1352,40 +1353,34 @@ gulp.task(
})
);
gulp.task(
"typestest-pre",
gulp.series("testing-pre", "generic", "types", function () {
const [packageJsonSrc] = packageBowerJson();
return merge([
packageJsonSrc.pipe(gulp.dest(TYPESTEST_DIR)),
gulp
.src([
GENERIC_DIR + "build/pdf.js",
GENERIC_DIR + "build/pdf.worker.js",
SRC_DIR + "pdf.worker.entry.js",
])
.pipe(gulp.dest(TYPESTEST_DIR + "build/")),
gulp.src(TYPES_DIR + "**/**").pipe(gulp.dest(TYPESTEST_DIR + "build/")),
]);
})
);
gulp.task(
"typestest",
gulp.series(
"testing-pre",
"generic",
"types",
function () {
var packageJsonSrc = packageBowerJson()[0];
var TYPESTEST_DIR = BUILD_DIR + "typestest/";
return merge([
packageJsonSrc.pipe(gulp.dest(TYPESTEST_DIR)),
gulp
.src([
GENERIC_DIR + "build/pdf.js",
GENERIC_DIR + "build/pdf.worker.js",
SRC_DIR + "pdf.worker.entry.js",
])
.pipe(gulp.dest(TYPESTEST_DIR + "build/")),
gulp
.src(TYPES_BUILD_DIR + "**/**")
.pipe(gulp.dest(TYPESTEST_DIR + "build/")),
]);
},
function (done) {
exec(`node_modules/.bin/tsc -p test/types`, function (err, stdout) {
if (err !== null) {
console.log("couldn't compile typescript test: " + stdout);
}
done(err);
});
}
)
gulp.series("typestest-pre", function (done) {
exec("node_modules/.bin/tsc -p test/types", function (err, stdout) {
if (err) {
console.log(`Couldn't compile TypeScript test: ${stdout}`);
}
done(err);
});
})
);
gulp.task("baseline", function (done) {
@ -1752,9 +1747,7 @@ gulp.task(
gulp
.src(LIB_DIR + "**/*", { base: LIB_DIR })
.pipe(gulp.dest(DIST_DIR + "lib/")),
gulp
.src(TYPES_BUILD_DIR + "**/**")
.pipe(gulp.dest(DIST_DIR + "build/")),
gulp.src(TYPES_DIR + "**/**").pipe(gulp.dest(DIST_DIR + "build/")),
]);
}
)

395
src/display/api.js
View File

@ -89,6 +89,7 @@ let createPDFNetworkStream;
/**
* Sets the function that instantiates an {IPDFStream} as an alternative PDF
* data transport.
*
* @param {IPDFStreamFactory} pdfNetworkStreamFactory - The factory function
* that takes document initialization parameters (including a "url") and
* returns a promise which is resolved with an instance of {IPDFStream}.
@ -98,82 +99,84 @@ function setPDFNetworkStreamFactory(pdfNetworkStreamFactory) {
createPDFNetworkStream = pdfNetworkStreamFactory;
}
/* eslint-disable max-len */
/**
* @typedef {Int8Array | Uint8Array | Int16Array | Uint16Array | Int32Array | Uint32Array | Uint8ClampedArray | Float32Array | Float64Array} TypedArray
* @typedef {
* Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array |
* Int32Array | Uint32Array | Float32Array | Float64Array
* } TypedArray
*/
/* eslint-enable max-len */
/**
* Document initialization / loading parameters object.
*
* @typedef {Object} DocumentInitParameters
* @property {string} [url] - The URL of the PDF.
* @property {string} [url] - The URL of the PDF.
* @property {TypedArray|Array<number>|string} [data] - Binary PDF data. Use
* typed arrays (Uint8Array) to improve the memory usage. If PDF data is
* BASE64-encoded, use atob() to convert it to a binary string first.
* @property {Object} [httpHeaders] - Basic authentication headers.
* @property {boolean} [withCredentials] - Indicates whether or not
* BASE64-encoded, use `atob()` to convert it to a binary string first.
* @property {Object} [httpHeaders] - Basic authentication headers.
* @property {boolean} [withCredentials] - Indicates whether or not
* cross-site Access-Control requests should be made using credentials such
* as cookies or authorization headers. The default is false.
* @property {string} [password] - For decrypting password-protected PDFs.
* as cookies or authorization headers. The default is `false`.
* @property {string} [password] - For decrypting password-protected PDFs.
* @property {TypedArray} [initialData] - A typed array with the first portion
* or all of the pdf data. Used by the extension since some data is already
* loaded before the switch to range requests.
* @property {number} [length] - The PDF file length. It's used for
* progress reports and range requests operations.
* @property {PDFDataRangeTransport} [range]
* @property {number} [rangeChunkSize] - Specify maximum number of bytes
* fetched per range request. The default value is 2^16 = 65536.
* @property {PDFWorker} [worker] - The worker that will be used for
* the loading and parsing of the PDF data.
* @property {number} [verbosity] - Controls the logging level; the
* constants from {VerbosityLevel} should be used.
* @property {string} [docBaseUrl] - The base URL of the document,
* used when attempting to recover valid absolute URLs for annotations, and
* outline items, that (incorrectly) only specify relative URLs.
* @property {string} [cMapUrl] - The URL where the predefined
* Adobe CMaps are located. Include trailing slash.
* @property {boolean} [cMapPacked] - Specifies if the Adobe CMaps are
* binary packed.
* @property {Object} [CMapReaderFactory] - The factory that will be
* used when reading built-in CMap files. Providing a custom factory is useful
* for environments without `XMLHttpRequest` support, such as e.g. Node.js.
* The default value is {DOMCMapReaderFactory}.
* @property {number} [length] - The PDF file length. It's used for progress
* reports and range requests operations.
* @property {PDFDataRangeTransport} [range] - Allows for using a custom range
* transport implementation.
* @property {number} [rangeChunkSize] - Specify maximum number of bytes fetched
* per range request. The default value is {@link DEFAULT_RANGE_CHUNK_SIZE}.
* @property {PDFWorker} [worker] - The worker that will be used for loading and
* parsing the PDF data.
* @property {number} [verbosity] - Controls the logging level; the constants
* from {@link VerbosityLevel} should be used.
* @property {string} [docBaseUrl] - The base URL of the document, used when
* attempting to recover valid absolute URLs for annotations, and outline
* items, that (incorrectly) only specify relative URLs.
* @property {string} [cMapUrl] - The URL where the predefined Adobe CMaps are
* located. Include the trailing slash.
* @property {boolean} [cMapPacked] - Specifies if the Adobe CMaps are binary
* packed or not.
* @property {Object} [CMapReaderFactory] - The factory that will be used when
* reading built-in CMap files. Providing a custom factory is useful for
* environments without Fetch API or `XMLHttpRequest` support, such as
* Node.js. The default value is {DOMCMapReaderFactory}.
* @property {boolean} [stopAtErrors] - Reject certain promises, e.g.
* `getOperatorList`, `getTextContent`, and `RenderTask`, when the associated
* PDF data cannot be successfully parsed, instead of attempting to recover
* whatever possible of the data. The default value is `false`.
* @property {number} [maxImageSize] - The maximum allowed image size
* in total pixels, i.e. width * height. Images above this value will not be
* rendered. Use -1 for no limit, which is also the default value.
* @property {boolean} [isEvalSupported] - Determines if we can eval
* strings as JS. Primarily used to improve performance of font rendering,
* and when parsing PDF functions. The default value is `true`.
* @property {boolean} [disableFontFace] - By default fonts are
* converted to OpenType fonts and loaded via font face rules. If disabled,
* fonts will be rendered using a built-in font renderer that constructs the
* glyphs with primitive path commands. The default value is `false`.
* @property {number} [maxImageSize] - The maximum allowed image size in total
* pixels, i.e. width * height. Images above this value will not be rendered.
* Use -1 for no limit, which is also the default value.
* @property {boolean} [isEvalSupported] - Determines if we can evaluate strings
* as JavaScript. Primarily used to improve performance of font rendering, and
* when parsing PDF functions. The default value is `true`.
* @property {boolean} [disableFontFace] - By default fonts are converted to
* OpenType fonts and loaded via `@font-face` rules. If disabled, fonts will
* be rendered using a built-in font renderer that constructs the glyphs with
* primitive path commands. The default value is `false`.
* @property {boolean} [fontExtraProperties] - Include additional properties,
* which are unused during rendering of PDF documents, when exporting the
* parsed font data from the worker-thread. This may be useful for debugging
* purposes (and backwards compatibility), but note that it will lead to
* increased memory usage. The default value is `false`.
* @property {boolean} [disableRange] - Disable range request loading
* of PDF files. When enabled, and if the server supports partial content
* requests, then the PDF will be fetched in chunks.
* The default value is `false`.
* @property {boolean} [disableStream] - Disable streaming of PDF file
* data. By default PDF.js attempts to load PDFs in chunks.
* The default value is `false`.
* @property {boolean} [disableAutoFetch] - Disable pre-fetching of PDF
* file data. When range requests are enabled PDF.js will automatically keep
* @property {boolean} [disableRange] - Disable range request loading of PDF
* files. When enabled, and if the server supports partial content requests,
* then the PDF will be fetched in chunks. The default value is `false`.
* @property {boolean} [disableStream] - Disable streaming of PDF file data.
* By default PDF.js attempts to load PDF files in chunks. The default value
* is `false`.
* @property {boolean} [disableAutoFetch] - Disable pre-fetching of PDF file
* data. When range requests are enabled PDF.js will automatically keep
* fetching more data even if it isn't needed to display the current page.
* The default value is `false`.
* NOTE: It is also necessary to disable streaming, see above,
* in order for disabling of pre-fetching to work correctly.
* @property {boolean} [pdfBug] - Enables special hooks for debugging
* PDF.js (see `web/debugger.js`). The default value is `false`.
*
* NOTE: It is also necessary to disable streaming, see above, in order for
* disabling of pre-fetching to work correctly.
* @property {boolean} [pdfBug] - Enables special hooks for debugging PDF.js
* (see `web/debugger.js`). The default value is `false`.
*/
/**
@ -188,13 +191,14 @@ function setPDFNetworkStreamFactory(pdfNetworkStreamFactory) {
/**
* This is the main entry point for loading a PDF and interacting with it.
* NOTE: If a URL is used to fetch the PDF data a standard XMLHttpRequest(XHR)
* is used, which means it must follow the same origin rules that any XHR does
* e.g. No cross domain requests without CORS.
*
* @param {string|TypedArray|DocumentInitParameters|PDFDataRangeTransport} src
* Can be a url to where a PDF is located, a typed array (Uint8Array)
* already populated with data or parameter object.
* NOTE: If a URL is used to fetch the PDF data a standard Fetch API call (or
* XHR as fallback) is used, which means it must follow same origin rules,
* e.g. no cross-domain requests without CORS.
*
* @param {string|TypedArray|DocumentInitParameters|PDFDataRangeTransport} src -
* Can be a URL to where a PDF file is located, a typed array (Uint8Array)
* already populated with data or parameter object.
* @returns {PDFDocumentLoadingTask}
*/
function getDocument(src) {
@ -373,12 +377,13 @@ function getDocument(src) {
/**
* Starts fetching of specified PDF document/data.
*
* @param {PDFWorker} worker
* @param {Object} source
* @param {PDFDataRangeTransport} pdfDataRangeTransport
* @param {string} docId Unique document id, used as MessageHandler id.
* @returns {Promise} The promise, which is resolved when worker id of
* MessageHandler is known.
* @param {string} docId - Unique document ID, used in `MessageHandler`.
* @returns {Promise} A promise that is resolved when the worker ID of the
* `MessageHandler` is known.
* @private
*/
function _fetchDocument(worker, source, pdfDataRangeTransport, docId) {
@ -429,39 +434,24 @@ function _fetchDocument(worker, source, pdfDataRangeTransport, docId) {
* after which individual pages can be rendered.
*
* @typedef {Object} PDFDocumentLoadingTask
* @property {string} docId
* Unique document loading task id -- used in MessageHandlers.
* @property {boolean} destroyed
* Shows if loading task is destroyed.
* @property {cbOnPassword} [onPassword]
* Callback to request a password if wrong or no password was provided.
* The callback receives two parameters: function that needs to be called
* with new password and reason (see {PasswordResponses}).
* @property {cbOnProgress} onProgress
* Callback to be able to monitor the loading progress of the PDF file
* (necessary to implement e.g. a loading bar). The callback receives
* an {Object} with the properties: {number} loaded and {number} total.
* @property {cbOnUnsupportedFeature} onUnsupportedFeature
* Callback for when an unsupported feature is used in the PDF document.
* The callback receives an {UNSUPPORTED_FEATURES} argument.
* @property {Promise<PDFDocumentProxy>} promise
* Promise for document loading task completion.
* @property {cbDestroy} destroy
* Aborts all network requests and destroys worker.
* Returns a promise that is resolved after destruction activity is completed.
*
* @callback cbOnPassword
* @param {string} password
* @param {number} reason
*
* @callback cbOnProgress
* @param {number} loaded
* @param {number} total
*
* @callback cbOnUnsupportedFeature
* @param {string} featureId
*
* @callback cbDestroy
* @property {string} docId - Unique identifier for the document loading task.
* @property {boolean} destroyed - Whether the loading task is destroyed or not.
* @property {function} [onPassword] - Callback to request a password if a wrong
* or no password was provided. The callback receives two parameters: a
* function that should be called with the new password, and a reason (see
* {@link PasswordResponses}).
* @property {function} [onProgress] - Callback to be able to monitor the
* loading progress of the PDF file (necessary to implement e.g. a loading
* bar). The callback receives an {Object} with the properties `loaded`
* ({number}) and `total` ({number}) that indicate how many bytes are loaded.
* @property {function} [onUnsupportedFeature] - Callback for when an
* unsupported feature is used in the PDF document. The callback receives an
* {@link UNSUPPORTED_FEATURES} argument.
* @property {Promise<PDFDocumentProxy>} promise - Promise for document loading
* task completion.
* @property {Promise<void>} destroy - Abort all network requests and destroy
* the worker. Returns a promise that is resolved when destruction is
* completed.
*/
/**
@ -484,34 +474,38 @@ const PDFDocumentLoadingTask = (function PDFDocumentLoadingTaskClosure() {
this._worker = null;
/**
* Unique document loading task id -- used in MessageHandlers.
* Unique identifier for the document loading task.
* @type {string}
*/
this.docId = "d" + nextDocumentId++;
/**
* Shows if loading task is destroyed.
* Whether the loading task is destroyed or not.
* @type {boolean}
*/
this.destroyed = false;
/**
* Callback to request a password if wrong or no password was provided.
* The callback receives two parameters: function that needs to be called
* with new password and reason (see {PasswordResponses}).
* Callback to request a password if a wrong or no password was provided.
* The callback receives two parameters: a function that should be called
* with the new password, and a reason (see {@link PasswordResponses}).
* @type {function}
*/
this.onPassword = null;
/**
* Callback to be able to monitor the loading progress of the PDF file
* (necessary to implement e.g. a loading bar). The callback receives
* an {Object} with the properties: {number} loaded and {number} total.
* an {Object} with the properties `loaded` ({number}) and `total`
* ({number}) that indicate how many bytes are loaded.
* @type {function}
*/
this.onProgress = null;
/**
* Callback to when unsupported feature is used. The callback receives
* an {UNSUPPORTED_FEATURES} argument.
* Callback for when an unsupported feature is used in the PDF document.
* The callback receives an {@link UNSUPPORTED_FEATURES} argument.
* @type {function}
*/
this.onUnsupportedFeature = null;
}
@ -525,9 +519,8 @@ const PDFDocumentLoadingTask = (function PDFDocumentLoadingTaskClosure() {
}
/**
* Aborts all network requests and destroys worker.
* @returns {Promise<void>} A promise that is resolved after destruction
* activity is completed.
* @returns {Promise<void>} A promise that is resolved when destruction is
* completed.
*/
destroy() {
this.destroyed = true;
@ -554,7 +547,7 @@ class PDFDataRangeTransport {
/**
* @param {number} length
* @param {Uint8Array} initialData
* @param {boolean} progressiveDone
* @param {boolean} [progressiveDone]
*/
constructor(length, initialData, progressiveDone = false) {
this.length = length;
@ -626,8 +619,7 @@ class PDFDataRangeTransport {
}
/**
* Proxy to a PDFDocument in the worker thread. Also, contains commonly used
* properties that can be read synchronously.
* Proxy to a `PDFDocument` in the worker thread.
*/
class PDFDocumentProxy {
constructor(pdfInfo, transport) {
@ -644,7 +636,7 @@ class PDFDocumentProxy {
}
/**
* @type {number} Total number of pages the PDF contains.
* @type {number} Total number of pages in the PDF file.
*/
get numPages() {
return this._pdfInfo.numPages;
@ -660,7 +652,7 @@ class PDFDocumentProxy {
/**
* @param {number} pageNumber - The page number to get. The first page is 1.
* @returns {Promise<PDFPageProxy>} A promise that is resolved with
* a {@link PDFPageProxy} object.
* a {@link PDFPageProxy} object.
*/
getPage(pageNumber) {
return this._transport.getPage(pageNumber);
@ -678,8 +670,8 @@ class PDFDocumentProxy {
}
/**
* @returns {Promise<Object<string,any>>} A promise that is resolved with
* a lookup table for mapping named destinations to reference numbers.
* @returns {Promise<Object<string, Array<any>>>} A promise that is resolved
* with a mapping from named destinations to references.
*
* This can be slow for large documents. Use `getDestination` instead.
*/
@ -697,10 +689,9 @@ class PDFDocumentProxy {
}
/**
* @returns {Promise<Array<string> | null>} A promise that is
* resolved with an {Array} containing the page labels that correspond to
* the page indexes, or `null` when no page labels are present in the PDF
* file.
* @returns {Promise<Array<string> | null>} A promise that is resolved with
* an {Array} containing the page labels that correspond to the page
* indexes, or `null` when no page labels are present in the PDF file.
*/
getPageLabels() {
return this._transport.getPageLabels();
@ -723,8 +714,9 @@ class PDFDocumentProxy {
}
/**
* @returns {Promise<Object>} A promise that is resolved with an {Object}
* containing the viewer preferences.
* @returns {Promise<Object | null>} A promise that is resolved with an
* {Object} containing the viewer preferences, or `null` when no viewer
* preferences are present in the PDF file.
*/
getViewerPreferences() {
return this._transport.getViewerPreferences();
@ -748,9 +740,9 @@ class PDFDocumentProxy {
}
/**
* @returns {Promise<Array<string> | null>} A promise that is
* resolved with an {Array} of all the JavaScript strings in the name tree,
* or `null` if no JavaScript exists.
* @returns {Promise<Array<string> | null>} A promise that is resolved with
* an {Array} of all the JavaScript strings in the name tree, or `null`
* if no JavaScript exists.
*/
getJavaScript() {
return this._transport.getJavaScript();
@ -761,29 +753,19 @@ class PDFDocumentProxy {
* @property {string} title
* @property {boolean} bold
* @property {boolean} italic
* @property {Uint8ClampedArray} color
* @property {any} dest
* @property {string} url
* @property {Uint8ClampedArray} color - The color in RGB format to use for
* display purposes.
* @property {string | Array<any> | null} dest
* @property {string | null} url
* @property {string | undefined} unsafeUrl
* @property {boolean | undefined} newWindow
* @property {number | undefined} count
* @property {Array<OutlineNode>} items
*/
/**
* @returns {Promise<Array<OutlineNode>>} A promise that is resolved with
* an {Array} that is a tree outline (if it has one) of the PDF. The tree is
* in the format of:
* [
* {
* title: string,
* bold: boolean,
* italic: boolean,
* color: rgb Uint8ClampedArray,
* count: integer or undefined,
* dest: dest obj,
* url: string,
* items: array of more items like this
* },
* ...
* ]
* @returns {Promise<Array<OutlineNode>>} A promise that is resolved with an
* {Array} that is a tree outline (if it has one) of the PDF file.
*/
getOutline() {
return this._transport.getOutline();
@ -791,15 +773,15 @@ class PDFDocumentProxy {
/**
* @returns {Promise<OptionalContentConfig | null>} A promise that is resolved
* with an {@link OptionalContentConfig} that will have all the optional
* content groups (if the document has any).
* with an {@link OptionalContentConfig} that has all the optional content
* groups, or `null` if the document does not have any.
*/
getOptionalContentConfig() {
return this._transport.getOptionalContentConfig();
}
/**
* @returns {Promise<Array<string | null>>} A promise that is resolved with
* @returns {Promise<Array<number> | null>} A promise that is resolved with
* an {Array} that contains the permission flags for the PDF document, or
* `null` when no permissions are present in the PDF file.
*/
@ -837,19 +819,19 @@ class PDFDocumentProxy {
/**
* @returns {Promise<PDFDocumentStats>} A promise this is resolved with
* current statistics about document structures
* (see {@link PDFDocumentStats}).
* current statistics about document structures (see
* {@link PDFDocumentStats}).
*/
getStats() {
return this._transport.getStats();
}
/**
* Cleans up resources allocated by the document, on both the main- and
* worker-threads.
* Cleans up resources allocated by the document on both the main and worker
* threads.
*
* NOTE: Do not, under any circumstances, call this method when rendering is
* currently ongoing since that may lead to rendering errors.
* currently ongoing since that may lead to rendering errors.
*
* @returns {Promise} A promise that is resolved when clean-up has finished.
*/
@ -900,9 +882,9 @@ class PDFDocumentProxy {
* Page getTextContent parameters.
*
* @typedef {Object} getTextContentParameters
* @property {boolean} normalizeWhitespace - replaces all occurrences of
* @property {boolean} normalizeWhitespace - Replaces all occurrences of
* whitespace with standard spaces (0x20). The default value is `false`.
* @property {boolean} disableCombineTextItems - do not attempt to combine
* @property {boolean} disableCombineTextItems - Do not attempt to combine
* same line {@link TextItem}'s. The default value is `false`.
*/
@ -910,7 +892,7 @@ class PDFDocumentProxy {
* Page text content.
*
* @typedef {Object} TextContent
* @property {Array<TextItem>} items - array of {@link TextItem}
* @property {Array<TextItem>} items - Array of {@link TextItem} objects.
* @property {Object<string, TextStyle>} styles - {@link TextStyle} objects,
* indexed by font name.
*/
@ -919,22 +901,22 @@ class PDFDocumentProxy {
* Page text content part.
*
* @typedef {Object} TextItem
* @property {string} str - text content.
* @property {string} dir - text direction: 'ttb', 'ltr' or 'rtl'.
* @property {Array<any>} transform - transformation matrix.
* @property {number} width - width in device space.
* @property {number} height - height in device space.
* @property {string} fontName - font name used by pdf.js for converted font.
* @property {string} str - Text content.
* @property {string} dir - Text direction: 'ttb', 'ltr' or 'rtl'.
* @property {Array<any>} transform - Transformation matrix.
* @property {number} width - Width in device space.
* @property {number} height - Height in device space.
* @property {string} fontName - Font name used by PDF.js for converted font.
*/
/**
* Text style.
*
* @typedef {Object} TextStyle
* @property {number} ascent - font ascent.
* @property {number} descent - font descent.
* @property {boolean} vertical - text is in vertical mode.
* @property {string} fontFamily - possible font family
* @property {number} ascent - Font ascent.
* @property {number} descent - Font descent.
* @property {boolean} vertical - Whether or not the text is in vertical mode.
* @property {string} fontFamily - The possible font family.
*/
/**
@ -942,9 +924,8 @@ class PDFDocumentProxy {
*
* @typedef {Object} GetAnnotationsParameters
* @property {string} intent - Determines the annotations that will be fetched,
* can be either 'display' (viewable annotations) or 'print'
* (printable annotations).
* If the parameter is omitted, all annotations are fetched.
* can be either 'display' (viewable annotations) or 'print' (printable
* annotations). If the parameter is omitted, all annotations are fetched.
*/
/**
@ -952,48 +933,46 @@ class PDFDocumentProxy {
*
* @typedef {Object} RenderParameters
* @property {Object} canvasContext - A 2D context of a DOM Canvas object.
* @property {PageViewport} viewport - Rendering viewport obtained by
* calling the `PDFPageProxy.getViewport` method.
* @property {string} [intent] - Rendering intent, can be 'display' or 'print'
* (default value is 'display').
* @property {boolean} [enableWebGL] - Enables WebGL accelerated rendering
* for some operations. The default value is `false`.
* @property {boolean} [renderInteractiveForms] - Whether or not
* interactive form elements are rendered in the display
* layer. If so, we do not render them on canvas as well.
* @property {Array<any>} [transform] - Additional transform, applied
* just before viewport transform.
* @property {Object} [imageLayer] - An object that has beginLayout,
* endLayout and appendImage functions.
* @property {PageViewport} viewport - Rendering viewport obtained by calling
* the `PDFPageProxy.getViewport` method.
* @property {string} [intent] - Rendering intent, can be 'display' or 'print'.
* The default value is 'display'.
* @property {boolean} [enableWebGL] - Enables WebGL accelerated rendering for
* some operations. The default value is `false`.
* @property {boolean} [renderInteractiveForms] - Whether or not interactive
* form elements are rendered in the display layer. If so, we do not render
* them on the canvas as well.
* @property {Array<any>} [transform] - Additional transform, applied just
* before viewport transform.
* @property {Object} [imageLayer] - An object that has `beginLayout`,
* `endLayout` and `appendImage` functions.
* @property {Object} [canvasFactory] - The factory instance that will be used
* when creating canvases. The default value is
* {new DOMCanvasFactory()}.
* @property {Object} [background] - Background to use for the canvas.
* Can use any valid canvas.fillStyle: A DOMString parsed as
* CSS <color> value, a CanvasGradient object (a linear or
* radial gradient) or a CanvasPattern object (a repetitive
* image). The default value is 'rgb(255,255,255)'.
* @property {Object} [annotationStorage] - Storage for annotation data in
* forms.
* @property {Promise} [optionalContentConfigPromise] - A promise that should
* resolve with an {OptionalContentConfig} created from
* PDFDocumentProxy.getOptionalContentConfig. If null, the
* config will be automatically fetched with the default
* visibility states set.
* when creating canvases. The default value is {new DOMCanvasFactory()}.
* @property {Object | string} [background] - Background to use for the canvas.
* Any valid `canvas.fillStyle` can be used: a `DOMString` parsed as CSS
* <color> value, a `CanvasGradient` object (a linear or radial gradient) or
* a `CanvasPattern` object (a repetitive image). The default value is
* 'rgb(255,255,255)'.
* @property {AnnotationStorage} [annotationStorage] - Storage for annotation
* data in forms.
* @property {Promise<OptionalContentConfig>} [optionalContentConfigPromise] -
* A promise that should resolve with an {@link OptionalContentConfig}
* created from `PDFDocumentProxy.getOptionalContentConfig`. If `null`,
* the configuration will be fetched automatically with the default visibility
* states set.
*/
/**
* PDF page operator list.
*
* @typedef {Object} PDFOperatorList
* @property {Array<number>} fnArray - Array containing the operator
* functions.
* @property {Array<number>} fnArray - Array containing the operator functions.
* @property {Array<any>} argsArray - Array containing the arguments of the
* functions.
* functions.
*/
/**
* Proxy to a PDFPage in the worker thread.
* Proxy to a `PDFPage` in the worker thread.
*/
class PDFPageProxy {
constructor(pageIndex, pageInfo, transport, pdfBug = false) {
@ -1088,9 +1067,10 @@ class PDFPageProxy {
/**
* Begins the process of rendering a page to the desired context.
*
* @param {RenderParameters} params Page render parameters.
* @returns {RenderTask} An object that contains the promise, which
* is resolved when the page finishes rendering.
* @returns {RenderTask} An object that contains a promise that is
* resolved when the page finishes rendering.
*/
render({
canvasContext,
@ -1283,7 +1263,7 @@ class PDFPageProxy {
/**
* @param {getTextContentParameters} params - getTextContent parameters.
* @returns {ReadableStream} ReadableStream to read textContent chunks.
* @returns {ReadableStream} Stream for reading text content chunks.
*/
streamTextContent({
normalizeWhitespace = false,
@ -1309,8 +1289,8 @@ class PDFPageProxy {
/**
* @param {getTextContentParameters} params - getTextContent parameters.
* @returns {Promise<TextContent>} That is resolved a {@link TextContent}
* object that represent the page text content.
* @returns {Promise<TextContent>} A promise that is resolved with a
* {@link TextContent} object that represents the page's text content.
*/
getTextContent(params = {}) {
const readableStream = this.streamTextContent(params);
@ -1370,9 +1350,10 @@ class PDFPageProxy {
/**
* Cleans up resources allocated by the page.
*
* @param {boolean} [resetStats] - Reset page stats, if enabled.
* The default value is `false`.
* @returns {boolean} Indicating if clean-up was successfully run.
* @returns {boolean} Indicates if clean-up was successfully run.
*/
cleanup(resetStats = false) {
this.pendingCleanup = true;
@ -1653,9 +1634,9 @@ class LoopbackPort {
/**
* @typedef {Object} PDFWorkerParameters
* @property {string} [name] - The name of the worker.
* @property {Object} [port] - The `workerPort`.
* @property {Object} [port] - The `workerPort` object.
* @property {number} [verbosity] - Controls the logging level; the
* constants from {VerbosityLevel} should be used.
* constants from {@link VerbosityLevel} should be used.
*/
/** @type {any} */
@ -1775,7 +1756,7 @@ const PDFWorker = (function PDFWorkerClosure() {
}
/**
* PDF.js web worker abstraction, which controls the instantiation of PDF
* PDF.js web worker abstraction that controls the instantiation of PDF
* documents. Message handlers are used to pass information from the main
* thread to the worker thread and vice versa. If the creation of a web
* worker is not possible, a "fake" worker will be used instead.
@ -2014,7 +1995,7 @@ const PDFWorker = (function PDFWorkerClosure() {
/**
* @param {PDFWorkerParameters} params - The worker initialization
* parameters.
* parameters.
*/
static fromPort(params) {
if (!params || !params.port) {
@ -2705,7 +2686,6 @@ class PDFObjects {
/**
* Allows controlling of the rendering tasks.
* @alias RenderTask
*/
class RenderTask {
constructor(internalRenderTask) {
@ -2715,8 +2695,7 @@ class RenderTask {
* Callback for incremental rendering -- a function that will be called
* each time the rendering is paused. To continue rendering call the
* function that is the first argument to the callback.
* @callback
* @param {function}
* @type {function}
*/
this.onContinue = null;
}