API Reference

High-use public APIs exported by package:docx_editor/docx_editor.dart.

Use this page as the package-level API map. The root reviewer pages cover architecture, configuration, and rendering/conversion.

Editor Session

API	Purpose
SyncfusionDocxEditor	Flutter widget hosting Syncfusion DocumentEditor.
DocxController	Session controller for save, export, review, sign, audit, locks, lifecycle, dirty state, and capabilities.
DocxCapabilities	Capability presets, document-grant mapping, JSON conversion, and action gates.
DocumentGrant	Host-facing read, review, and edit access grants.
DocxCapability / DocxMode	Internal action flags and resolved editor modes.
DocxEditLock	Single-editor lock state.
DocxActor	Authenticated user attribution. Required for signing.
DocxLifecycleState	Draft, review, approved, effective, and superseded lifecycle states.
DocxLifecycleBinding	Resolves lifecycle and requested capabilities into an allowed session mode.
DocxPickedDocument	Resolved document passed into the editor.
DocxSource / DocxSourceKind	DOCX/SFDT/storage-reference source variants.
DocxSyncfusionConfig	Syncfusion license, service URL, CDN, toolbar mode, and trusted origin.
DocxAuditEvent / DocxAuditEventType	Typed audit events emitted by the controller.

Public Export Groups

package:docx_editor/docx_editor.dart exports these groups:

Export group	Public surface
src/docx_api.dart	Session, source, capabilities, lifecycle, lock, storage, review, revision, signing, conversion, picker, and error APIs.
src/widgets/syncfusion_docx_editor.dart	Main editor widget.
src/widgets/docx_review_view.dart	Unified redline, comment, and suggestion review surface.
src/widgets/docx_review_panel.dart	Comment-thread panel.
src/widgets/docx_compare_view.dart	Redline compare view.
src/controlled_print/*	Controlled print service, request/result types, host interfaces, and errors.

Controller Constructor

final controller = DocxController(
  capabilities: capabilities,
  storageAdapter: storageAdapter,
  trustedClock: trustedClock,
  actor: actor,
  lifecycleState: lifecycleState,
  requireResolvedCommentsForSign: true,
  signingVocabulary: signingVocabulary,
  onAuditEvent: auditSink.write,
);

Parameter	Meaning
capabilities	What this actor may do in this document session.
storageAdapter	Host contract for loading, saving drafts, creating versions, and download URLs.
trustedClock	Backend-authoritative UTC time.
onAuditEvent	Callback for durable audit persistence.
actor	Optional for view/edit, required for sign(). Also used as Syncfusion author metadata.
lifecycleState	Optional lifecycle guard. Released states cannot receive editable presets.
requireResolvedCommentsForSign	Blocks signing while open review threads remain.
signingVocabulary	Allowed controlled meanings for electronic signatures.

Controller Operations

Operation	Purpose	Gate
updateCapabilities	Replace session capabilities after host access changes.	Lifecycle guard.
attachFileGateway	Attach the live editor bridge.	Internal widget wiring.
updateEditLock	Apply host lock state.	Required for locked edit sessions.
updateCurrentPayload	Replace cached SFDT/DOCX/PDF payloads.	Host/editor synchronization.
recordOpened	Emit open audit after a document opens.	open.
saveDraft	Save mutable draft content.	save, lifecycle, lock.
createVersion	Create a versioned save.	save, lifecycle, lock.
getDownloadUrl	Ask host storage for a download URL.	download capability.
exportCurrentFile	Export current SFDT, DOCX, or PDF.	format-specific capability.
addComment	Add a comment at the current editor selection.	comment.
listRevisions	Read tracked-change summaries.	viewTrackChanges.
listComments	Read review threads.	showComments.
refreshReviewState	Recount unresolved threads.	showComments.
addReply	Append a reply to a thread.	comment.
resolveComment / reopenComment	Update comment thread state.	comment.
goToComment	Navigate the editor to a comment anchor.	showComments.
acceptFirstRevision / acceptRevisionById	Accept tracked changes.	acceptRevisions, lifecycle, lock.
rejectFirstRevision / rejectRevisionById	Reject tracked changes.	rejectRevisions, lifecycle, lock.
applySuggestion / rejectSuggestion	Map a suggestion to revision accept/reject.	revision gates.
printFile	Ask the live editor to print.	print.
sign	Record an electronic signature.	eSign, actor, reauth, vocabulary, optional resolved-comments gate.

Capability Presets

API	Purpose
DocxCapabilities.fromGrants(grants)	Preferred host-facing API. Expands DocumentGrant.read, review, and edit into internal editor action gates.
DocxCapabilities.viewOnly()	Open and search/read.
DocxCapabilities.commentOnly()	Add comments and view review state.
DocxCapabilities.revisionReview()	Accept/reject tracked changes and review comments.
DocxCapabilities.fullEdit()	Standard authoring, optional required track changes.
DocxCapabilities.editWithLock()	Full authoring with mandatory current-session edit lock.
DocxCapabilities.fromJson / tryFromJson	Parse serialized capabilities.

DocxCapability.eSign is deliberately not included in authoring presets. Add it only for a sign-off lifecycle step.

Source and Picked Document APIs

API	Purpose
DocxSource.docxBase64	Open a DOCX payload already encoded as base64.
DocxSource.docxBytes	Open DOCX bytes.
DocxSource.sfdtString	Open SFDT JSON text.
DocxSource.sfdtJson	Open a decoded SFDT map.
DocxSource.blankDocument	Open a new blank SFDT document with a valid paragraph anchor.
DocxSource.storageReference	Open a host storage reference through the storage adapter.
DocxPickedDocument.localBytes	Local .docx pick with optional source identity, lock, hash, and metadata.
DocxPickedDocument.networkBytes	Network-loaded .docx pick with URL metadata.
DocxPickedDocument.serverDocument	Host document record with source id, optional version id, lock, hash, and capabilities.
DocxPickedDocument.verifyIntegrity	Validate direct byte payloads against a host SHA-256 before opening.

Lifecycle and Lock APIs

API	Purpose
DocxLifecycleState.draft	Editable authoring state.
DocxLifecycleState.inReview	Review state; default resolver returns revision review access.
DocxLifecycleState.approved	Released read-only state.
DocxLifecycleState.effective	Released read-only state.
DocxLifecycleState.superseded	Released read-only state.
DocxLifecycleBinding.resolve	Converts lifecycle plus requested capabilities into the allowed session preset.
DocxLifecycleBinding.wouldBeEditable	Detects illegal editable access in released states.
DocxEditLock.notRequired	Session does not need a single-editor lock.
DocxEditLock.ownedByCurrentSession	Current session owns the lock and may mutate.
DocxEditLock.ownedByOther	Another session owns the lock; mutation must be blocked.

Host Contracts

API	Purpose
DocxStorageAdapter	Open, save draft, create version, and get download URL.
DocxOpenRequest / DocxLoadResult	Load request and result objects.
DocxSaveRequest / DocxSaveResult	Save request and result objects.
DocxDownloadRequest	Download/export request metadata.
DocxTrustedClock	Server-authoritative UTC time.
DocxCredentialVerifier	Re-authenticate actor for e-signing.
DocxReauthChallenge / DocxReauthResult	Re-authentication ceremony data.
DocxIntegrity helpers	Content hash and integrity checks.

Storage Contract Methods

Method	Responsibility
open(DocxOpenRequest)	Resolve a storage reference into a load result.
saveDraft(DocxSaveRequest)	Persist a mutable draft save.
createVersion(DocxSaveRequest)	Persist an immutable or versioned save.
getDownloadUrl(DocxDownloadRequest)	Return a host download URL when available.

Review and Signature

API	Purpose
DocxReviewThread	Comment/review thread data.
DocxReviewComment	Individual review comment.
DocxThreadStatus	Review thread lifecycle.
DocxRevisionSummary	Tracked-change summary.
DocxSuggestion	Higher-level suggestion over one or more revisions.
DocxSuggestionStatus	Suggestion lifecycle.
DocxSignatureRequest	E-sign request.
DocxSignatureResult	E-sign result.
DocxSigningVocabulary	Allowed signature meanings.

Widget APIs

Widget	Constructor inputs	Purpose
SyncfusionDocxEditor	document, syncfusionConfig, optional controller, conversionService, sizing, toolbar, callbacks	Main editor surface.
DocxCompareView	DocxDiffResult or base/revised DocxBuiltDocuments, title, initial mode	Reviewer redline.
DocxReviewPanel	Threads, current actor id, reply/status/navigation/create/refresh callbacks	Comment thread workflow panel.
DocxReviewView	Diff or base/revised documents, threads, suggestions, navigation/comment/suggestion callbacks	Unified review surface combining redline, comments, and suggestions.

Review Widgets

API	Purpose
DocxReviewView	Review-side panel for tracked changes and threads.
DocxReviewPanel	Comment-thread review panel.
DocxCompareView / DocxCompareMode	Side-by-side and inline comparison UI.

Controlled Print

API	Purpose
ControlledPrintService	Issues controlled/uncontrolled copies.
ControlledPrintRequest	Source document and issuance metadata.
ControlledPrintResult	Issued PDF bytes, copy number, hash, renderer ID, issue time.
PrintActor	Actor attribution for print issuance.
SignatureManifestEntry	Signature evidence included in controlled copies.
CopyClass	controlled or uncontrolled watermark class.
PrintPolicy	Host authorization check.
PrintAuthorization	Authorization decision.
CopyAllocator	Atomic copy-number and issuance-code allocation.
CopyAllocation	Allocated copy number and issuance code.
TrustedClock	Server-authoritative UTC issue time.
PrintRegister	Register row persistence.
IssuanceRecord	Register row payload.
AuditSink	Immutable print audit event persistence.
PrintAuditEvent / PrintAuditAction	Controlled-print audit payload.
ControlledPrintException subclasses	Typed failure modes such as denial, missing furniture, and content mismatch.

Conversion and Rendering

API	Purpose
DocxConversionService	Conversion interface.
DocxImportRequest / DocxImportResult	DOCX import to SFDT.
DocxExportRequest / DocxConversionResult	DOCX/PDF export payloads.
DocxConversionFormat	Supported export formats.
VyuhDocxConversionService	Pure-Dart conversion backed by vyuh_docx.
DocxConverter	High-level conversion facade.
DocxConversionError subclasses	Typed conversion failures.

Picking

API	Purpose
DocxPickerService	Opens local, network, or server-backed documents.
DocxPickerMode	Picker behavior mode.
DocxPickKind	Picked document source kind.

Errors

API	Purpose
DocxError subclasses	Invalid source, permission, service, reauth, lifecycle, comments, and integrity failures.

Common Snippets

final capabilities = DocxCapabilities.fromGrants(
  const {DocumentGrant.read, DocumentGrant.review, DocumentGrant.edit},
  singleEditorLockRequired: true,
);

final service = ControlledPrintService(
  policy: policy,
  allocator: allocator,
  clock: clock,
  register: register,
  audit: audit,
);