跳到主要内容

Forms mode

Forms mode embeds the Forms UI for a specific Form filling room. Users can browse, fill out, and track forms without leaving your application, and the host page can extend the file/folder context menu with its own custom actions.

Initialization​

const docSpace = DocSpace.SDK.initForms({
  frameId: "ds-frame",
  src: "https://your-docspace.com",
  id: "your-room-id",
});

The parameters frameId and src are required. id (the room identifier) is optional — without it, the frame opens whichever room is configured in the portal's own Forms settings; the same applies to libraryId. All other parameters are optional and have sensible defaults.

For setup instructions (connecting the script, CSP configuration, npm package), see Get started.

Configuration, events, and methods​

initForms() accepts the full TFrameConfig configuration object and returns an SDKInstance. It forces mode to Forms, forces noLoader to true (the loading spinner never shows in Forms mode, regardless of that setting), and defaults showMenu to true (pass showMenu: false to hide the side panel).

navigateSection(), setCustomActions(), and upload() only work once the frame has connected — call them from inside onAppReady (or later), not right after initForms() returns. setCustomActions() also works in Manager and Personal mode; navigateSection() and upload() also work in Personal mode. Calling any of the three from an incompatible mode rejects the returned promise with SDKErrorCode.ModeMismatch — none of them throw synchronously.

onFileManagerClick also fires in Forms mode, same as in Manager and Public room mode. openEditorInSameTab controls where a file opens from the list when onEditorOpen isn't set — true navigates the host page to the editor, false forces a new tab, and leaving it unset follows the portal's own "Open in the same tab" setting. See Events and callbacks for its payload shape.

Forms mode also supports getUserInfo(), getFiles(), getFolders(), and getList() — the same read-only listing methods available in Manager and Personal mode.

headerOffset (inline-start padding added to header rows, so a host overlay like a floating side menu doesn't cover the header's own controls) and headerHeight (override the header's height to match your app's chrome) are also honored in Forms mode, alongside Chat and Personal.

Use cases​

Opening a specific section on load​

Set destination to skip the default "My forms" landing section:

const docSpace = DocSpace.SDK.initForms({
  frameId: "ds-forms",
  src: "https://your-docspace.com",
  id: "your-room-id",
  destination: "completed-forms",
});

Available sections: "my-forms", "in-progress", "completed-forms", "library", "settings".

Use navigateSection() on the returned instance instead of reinitializing the frame, and track the active section from the host page with onNavigate:

const docSpace = DocSpace.SDK.initForms({
  frameId: "ds-forms",
  src: "https://your-docspace.com",
  id: "your-room-id",
  events: {
    onAppReady: function () {
      document.getElementById("completed-button").onclick = () => {
        docSpace.navigateSection("completed-forms");
      };
    },
    onNavigate: function (data) {
      console.log("Section changed:", data.section);
    },
  },
});

Adding custom context menu actions​

Register your own entries in the file/folder context menu with setCustomActions() (or customActions in the config, to show them from the first render), then handle clicks via onCustomAction. setCustomActions() also works in Manager and Personal mode — see Manager mode's section for the full set of restriction fields (extensions, roomTypes, requireSecurity) and the onCustomAction payload shape; Forms mode itself only has a file/folder context menu, no rooms and no create menu.

const docSpace = DocSpace.SDK.initForms({
  frameId: "ds-forms",
  src: "https://your-docspace.com",
  id: "your-room-id",
  events: {
    onAppReady: function () {
      docSpace.setCustomActions({
        contextMenu: {
          file: [
            { key: "send-to-crm", label: "Send to CRM", icon: "https://your-app.com/icon.svg" },
            { key: "archive", label: "Archive", section: ["completed-forms"] },
          ],
          folder: [
            { key: "share-folder", label: "Share folder" },
          ],
        },
      });
    },
    onCustomAction: function (data) {
      console.log("Action:", data.action, "Item:", data.item);
    },
  },
});

section restricts an action to specific Forms sections; omit it to show the action everywhere.

Uploading a file without the picker dialog​

Call upload() directly with a File object — useful when the file comes from your own drop zone or input element rather than the ONLYOFFICE Apps UI. Wait for onAppReady before the frame will accept the call. The call has its own fixed 120-second transfer timeout, independent of methodTimeout — past that, the promise rejects with SDKErrorCode.UploadFailed. On success, the returned promise resolves with the same payload passed to onUploadSuccess ({ fileName, fileSize, uploadId }), so you can skip the event handler entirely if you only care about this specific call's outcome; onUploadProgress is never emitted for an upload()-initiated transfer, only for a native upload through Uploader mode's own dialog. onUploadSuccess/onUploadError fire with this narrower payload for an upload()-initiated transfer — see Events and callbacks for how it compares to Uploader mode's own (much larger) native-dialog payload:

const docSpace = DocSpace.SDK.initForms({
  frameId: "ds-forms",
  src: "https://your-docspace.com",
  id: "your-room-id",
  events: {
    onAppReady: function () {
      document.getElementById("upload-input").addEventListener("change", async function (e) {
        try {
          await docSpace.upload(e.target.files[0]);
        } catch (error) {
          console.error("Upload failed:", error.message);
        }
      });
    },
    onUploadSuccess: function (data) {
      console.log("Uploaded:", data.fileName, data.fileSize);
    },
    onUploadError: function (error) {
      console.error("Upload error:", error);
    },
  },
});

The whole file is read into memory before transfer, so validate its size on the host page first — the server-side upload limit is enforced separately and will reject oversized files.

Restricting to one forms library​

Pass libraryId to scope the Library section to one specific forms library instead of the portal's default — like id, it's optional and falls back to the portal's own Forms settings when omitted:

const docSpace = DocSpace.SDK.initForms({
  frameId: "ds-forms",
  src: "https://your-docspace.com",
  id: "your-room-id",
  libraryId: "your-library-id",
});