SDK

Manages multiple SDKInstance objects and provides convenience wrappers for each SDKMode.

Calling any init* method with a frameId that already exists reinitializes the existing instance; otherwise a new instance is created and stored in SDK.frames.

Example

import { SDK } from '@onlyoffice/docspace-sdk-js';

const sdk = new SDK();
const instance = sdk.initManager({
  frameId: 'ds-frame',
  src: 'https://portal.example.com',
});

Constructors

Constructor

new SDK(): SDK;

Returns

SDK

Methods

init()

init(config: TFrameConfig): SDKInstance;

Core factory method. Creates a new SDKInstance for the given config, or reinitializes the existing one if frameId is already in SDK.frames. Stores the result in SDK.frames.

Prefer the mode-specific wrappers (SDK.initManager, SDK.initEditor, etc.) which set mode automatically.

Parameters

Parameter	Type	Description
config	TFrameConfig	Frame configuration. See TFrameConfig.

Returns

SDKInstance

The created or reinitialized SDKInstance.

Example

import { SDK, SDKMode } from '@onlyoffice/docspace-sdk-js';

const sdk = new SDK();

// Create a manager instance
const instance = sdk.init({
  frameId: 'ds-frame',
  src: 'https://portal.example.com',
  mode: SDKMode.Manager,
});

// Reinitialize the same frame in a different mode — sdk.frames['ds-frame'] is reused
sdk.init({ frameId: 'ds-frame', src: 'https://portal.example.com', mode: SDKMode.Editor, id: 42 });

---

initChat()

initChat(config: TInitConfig): SDKInstance;

Initializes a frame in SDKMode.Chat mode — a full-page AI chat interface. The chat is bound to the AI agent when TFrameConfig.agentId is set; otherwise it is bound to the current user. Forces mode to SDKMode.Chat.

备注

The page renders a composer only when the frame's user is signed in and is not a guest. Otherwise it shows a no-access state (a "Chat history" control without an input) and fires TFrameEvents.onNoAccess — TFrameEvents.onAppReady still arrives. AI disabled on the portal hides the composer too, without the event. In OAuth mode the token must carry the scopes that read the user's profile; a token that cannot load the profile lands in the same no-access state.

Parameters

Parameter	Type	Description
config	TInitConfig	Frame configuration; mode is set by the wrapper. See TInitConfig.

Returns

SDKInstance

The initialized SDKInstance.

Example

import { SDK } from '@onlyoffice/docspace-sdk-js';

const sdk = new SDK();
const chat = sdk.initChat({
  frameId: 'ds-chat',
  src: 'https://portal.example.com',
  agentId: 123,
  events: {
    onAppReady: () => console.log('chat ready'),
  },
});

---

initEditor()

initEditor(config: TInitConfig): SDKInstance;

Initializes a frame in SDKMode.Editor mode — full document editor. Forces mode to SDKMode.Editor. Requires TFrameConfig.id.

Parameters

Parameter	Type	Description
config	TInitConfig	Frame configuration; mode is set by the wrapper. See TInitConfig.

Returns

SDKInstance

The initialized SDKInstance.

Example

import { SDK, EditorType } from '@onlyoffice/docspace-sdk-js';

const sdk = new SDK();
const instance = sdk.initEditor({
  frameId: 'ds-frame',
  src: 'https://portal.example.com',
  id: 42,
  editorType: EditorType.Desktop,
  editorCustomization: { autosave: true, forcesave: true },
  events: {
    onAppReady: () => console.log('ready'),
    onEditorCloseCallback: () => history.back(),
  },
});

---

initFileSelector()

initFileSelector(config: TInitConfig): SDKInstance;

Initializes a frame in SDKMode.FileSelector mode — a dialog for selecting a file. Forces mode to SDKMode.FileSelector. The selected file is returned via TFrameEvents.onSelectCallback.

Parameters

Parameter	Type	Description
config	TInitConfig	Frame configuration; mode is set by the wrapper. See TInitConfig.

Returns

SDKInstance

The initialized SDKInstance.

Example

import { SDK, SelectorFilterType } from '@onlyoffice/docspace-sdk-js';

const sdk = new SDK();
const instance = sdk.initFileSelector({
  frameId: 'ds-frame',
  src: 'https://portal.example.com',
  selectorType: SelectorFilterType.UserOnly,
  withBreadCrumbs: true,
  withSearch: true,
  events: {
    onSelectCallback: (file) => console.log('selected:', file),
    onCloseCallback: () => console.log('cancelled'),
  },
});

---

initForms()

initForms(config: TInitConfig): SDKInstance;

Initializes a frame in SDKMode.Forms mode — a forms gallery for the room specified by TFrameConfig.id. Forces mode to SDKMode.Forms. Sets showMenu to true by default.

Parameters

Parameter	Type	Description
config	TInitConfig	Frame configuration; mode is set by the wrapper. See TInitConfig.

Returns

SDKInstance

The initialized SDKInstance.

Example

import { SDK } from '@onlyoffice/docspace-sdk-js';

const sdk = new SDK();
const forms = sdk.initForms({
  frameId: 'ds-forms',
  src: 'https://portal.example.com',
  id: 'room-id',
  showMenu: true,
  events: {
    onCustomAction: (data) => console.log('action:', data),
  },
});

---

initFrame()

initFrame(config: TFrameConfig): SDKInstance;

Parameters

Parameter	Type	Description
config	TFrameConfig	Frame configuration. See TFrameConfig.

Returns

SDKInstance

The created or reinitialized SDKInstance.

Deprecated

Use SDK.init or a mode-specific wrapper instead.

---

initManager()

initManager(config: TInitConfig): SDKInstance;

Initializes a frame in SDKMode.Manager mode — a file/folder browser with full CRUD operations on rooms, folders, and files. Forces mode to SDKMode.Manager.

Parameters

Parameter	Type	Description
config	TInitConfig	Frame configuration; mode is set by the wrapper. See TInitConfig.

Returns

SDKInstance

The initialized SDKInstance.

Examples

import { SDK, ManagerViewMode, FilterSortBy, FilterSortOrder } from '@onlyoffice/docspace-sdk-js';

const sdk = new SDK();
const instance = sdk.initManager({
  frameId: 'ds-frame',
  src: 'https://portal.example.com',
  viewAs: ManagerViewMode.Table,
  showFilter: true,
  showMenu: true,
  filter: { sortBy: FilterSortBy.Name, sortOrder: FilterSortOrder.Ascending },
  events: {
    onAppReady: () => console.log('ready'),
    onFileManagerClick: (item) => console.log('clicked:', item),
  },
});

The rooms of one room group, pinned: search and filters inside the frame stay within the group.

const dealRooms = sdk.initManager({
  frameId: 'ds-frame',
  src: 'https://portal.example.com',
  rootPath: '/rooms/shared/',
  filter: { groupId: '42' },
});

---

initPersonal()

initPersonal(config: TInitConfig): SDKInstance;

Initializes a frame in SDKMode.Personal mode — a file/folder manager for the user's personal space: My Documents, Favorites, Recent, Shared with me, and Trash. The initial section is controlled by TFrameConfig.personalDestination; the frame has no navigation menu of its own, so the host switches sections with SDKInstance.navigateSection.

Forces mode to SDKMode.Personal.

Parameters

Parameter	Type	Description
config	TInitConfig	Frame configuration; mode is set by the wrapper. See TInitConfig.

Returns

SDKInstance

The initialized SDKInstance.

Example

import { SDK } from '@onlyoffice/docspace-sdk-js';

const sdk = new SDK();
const personal = sdk.initPersonal({
  frameId: 'ds-personal',
  src: 'https://portal.example.com',
  personalDestination: 'favorites',
  events: {
    onAppReady: () => console.log('ready'),
    onNavigate: (data) => console.log('section:', data.section),
    onFileManagerClick: (file) => console.log('opened file:', file),
  },
});

---

initPublicRoom()

initPublicRoom(config: TInitConfig): SDKInstance;

Initializes a frame in SDKMode.PublicRoom mode — anonymous access to view, edit, comment on, and review documents in a public room. Forces mode to SDKMode.PublicRoom. Requires TFrameConfig.requestToken.

Parameters

Parameter	Type	Description
config	TInitConfig	Frame configuration; mode is set by the wrapper. See TInitConfig.

Returns

SDKInstance

The initialized SDKInstance.

Examples

import { SDK } from '@onlyoffice/docspace-sdk-js';

const sdk = new SDK();
const instance = sdk.initPublicRoom({
  frameId: 'ds-frame',
  src: 'https://portal.example.com',
  requestToken: 'public-room-token',
  events: {
    onAppReady: () => console.log('ready'),
  },
});

With filter and header options.

const instance = sdk.initPublicRoom({
  frameId: 'ds-frame',
  src: 'https://portal.example.com',
  requestToken: 'public-room-token',
  showFilter: true,
  showHeader: true,
});

---

initRoomSelector()

initRoomSelector(config: TInitConfig): SDKInstance;

Initializes a frame in SDKMode.RoomSelector mode — a dialog for selecting a room. Forces mode to SDKMode.RoomSelector. The selected room is returned via TFrameEvents.onSelectCallback.

Parameters

Parameter	Type	Description
config	TInitConfig	Frame configuration; mode is set by the wrapper. See TInitConfig.

Returns

SDKInstance

The initialized SDKInstance.

Example

import { SDK } from '@onlyoffice/docspace-sdk-js';

const sdk = new SDK();
const instance = sdk.initRoomSelector({
  frameId: 'ds-frame',
  src: 'https://portal.example.com',
  showSelectorHeader: true,
  showSelectorCancel: true,
  events: {
    onSelectCallback: (room) => console.log('selected:', room),
    onCloseCallback: () => console.log('cancelled'),
  },
});

---

initSystem()

initSystem(config: TInitConfig): SDKInstance;

Initializes a frame in SDKMode.System mode — a blank page with a loader, used to call system methods (SDKInstance.login, SDKInstance.logout, SDKInstance.getUserInfo) without rendering any ONLYOFFICE Apps UI. Forces mode to SDKMode.System.

Parameters

Parameter	Type	Description
config	TInitConfig	Frame configuration; mode is set by the wrapper. See TInitConfig.

Returns

SDKInstance

The initialized SDKInstance.

Example

import { SDK } from '@onlyoffice/docspace-sdk-js';

const sdk = new SDK();
const system = sdk.initSystem({
  frameId: 'ds-system',
  src: 'https://portal.example.com',
  events: { onAppReady: () => console.log('system ready') },
});

system.getUserInfo().then((user) => console.log('current user:', user));

---

initUploader()

initUploader(config: TInitConfig): SDKInstance;

Initializes a frame in SDKMode.Uploader mode — a file upload interface. Forces mode to SDKMode.Uploader. Requires TFrameConfig.id (the target folder ID).

Parameters

Parameter	Type	Description
config	TInitConfig	Frame configuration; mode is set by the wrapper. See TInitConfig.

Returns

SDKInstance

The initialized SDKInstance.

Example

import { SDK } from '@onlyoffice/docspace-sdk-js';

const sdk = new SDK();
const uploader = sdk.initUploader({
  frameId: 'ds-uploader',
  src: 'https://portal.example.com',
  id: 'folder-id',
  acceptExtensions: '.docx,.xlsx,.pdf',
  isMultipleUpload: true,
  events: {
    onUploadSuccess: (files) => {
      if (Array.isArray(files)) console.log('uploaded:', files.map((f) => f.response?.title));
    },
    onUploadProgress: (p) => console.log(p.fileName, p.percent),
    onUploadError: (err) => console.error('error' in err ? err.error : err.message),
  },
});

---

initViewer()

initViewer(config: TInitConfig): SDKInstance;

Initializes a frame in SDKMode.Viewer mode — read-only document viewer. Forces mode to SDKMode.Viewer. Requires TFrameConfig.id.

Parameters

Parameter	Type	Description
config	TInitConfig	Frame configuration; mode is set by the wrapper. See TInitConfig.

Returns

SDKInstance

The initialized SDKInstance.

Example

import { SDK } from '@onlyoffice/docspace-sdk-js';

const sdk = new SDK();
const instance = sdk.initViewer({
  frameId: 'ds-frame',
  src: 'https://portal.example.com',
  id: 42,
  events: {
    onAppReady: () => console.log('ready'),
    onNoAccess: () => console.warn('access denied'),
    onNotFound: () => console.warn('document not found'),
  },
});

Properties

Property	Type	Default value	Description
frames	Record<string, SDKInstance>	{}	Registry of all active instances, keyed by TFrameConfig.frameId. Updated automatically by every init* call.