API платформы

Небольшие неймспейсы, которым не нужна отдельная страница.

sdk.auth

getSession(): Promise<SdkAuthSession | undefined>

Объект текущей сессии пользователя: { id, userId, accessToken, isAuthenticated, isGuest } или undefined, если сессии нет. Оркестраторы используют accessToken для вызова бэкенд-сервисов от имени пользователя.

| Поле | Тип | Описание | | --- | --- | --- | | id | string | Id сессии. | | userId | string | Id вошедшего пользователя. | | accessToken | string | Токен доступа сессии. | | isAuthenticated | boolean | Выполнен ли вход. | | isGuest | boolean | Гостевая ли это сессия. |

sdk.i18n

localize(key: string, defaultValue: string, args?: Record<string, string | number>): string

Ищет ключ в пакете переводов вашего расширения (объявленном в contributes.languages) для текущего языка интерфейса; если ключа нет, возвращает defaultValue.

• Поиск выполняется только по вашим переводам и только в файле languageCode которого совпадает с текущим языком интерфейса. Запасного варианта на другом языке нет. Языки, объявленные с "target": "core", переводят приложение, а не ваш пакет.
• К вложенным объектам в файле переводов обращаются через точку: { "files": { "count": "…" } } — это ключ files.count.
• Плейсхолдеры {name} заменяются значениями из args и в переводе, и в defaultValue. Плейсхолдеры без значения остаются без изменений.
• Вызов синхронный. Переводы поступают в хост расширений асинхронно и обновляются при смене языка пользователем, поэтому вызывайте localize в момент показа текста, а не кешируйте результат при загрузке.

sdk.window.showInfoMessage(sdk.i18n.localize('greeting', 'Привет'))

{ "files": { "count": "{count} archivos" } }

sdk.i18n.localize('files.count', '{count} files', { count: 3 }) // '3 archivos' на испанском, иначе '3 files'

sdk.team

getActive(): Promise<TeamSnapshot | undefined>          // { id, displayName }
getCurrentUserRole(): Promise<TeamRole | undefined>     // 'owner' | 'developer' | 'member'
sdk.team.panel.left                                     // ExtensionSdkPanelHandle workspace команды

• getActive() возвращает undefined, если активной команды нет.
• getCurrentUserRole() возвращает undefined, если активной команды нет, пользователь не вошёл или не состоит в активной команде.
• sdk.team.panel.left управляет левой панелью рабочего пространства команды — те же члены, что у панелей проекта.

sdk.extensions

get(id: ExtensionId): Promise<ExtensionSnapshot | undefined>
getVersionDownloadUrl(versionId: ExtensionVersionId): Promise<string | undefined>

Метод get возвращает снимок расширения, установленного в этом приложении, или undefined, если расширения с таким id нет. Метод getVersionDownloadUrl запрашивает у маркетплейса URL для скачивания версии расширения и возвращает undefined, если запрос не удался.

ExtensionSnapshot:

| Поле | Тип | Описание | | --- | --- | --- | | id | ExtensionId | '<publisher>.<name>'. | | uuid | string | Уникальный идентификатор расширения. | | displayName | string | Отображаемое имя из манифеста. | | description | string | Описание из манифеста, '', если его нет. | | version | string | Установленная версия. | | versionId | ExtensionVersionId | Идентификатор установленной версии — передайте его в getVersionDownloadUrl. | | publisher | string | Значение publisher из манифеста. | | type | 'system' \| 'user' \| 'dev' | Встроено в приложение, установлено пользователем или расширение в разработке. | | state | 'installed' \| 'activating' \| 'active' \| 'inactive' \| 'disabled' \| 'failed' | Текущее состояние жизненного цикла. | | location | string | Папка установки в виде нативного пути файловой системы. |

sdk.assets

get(assetId: AssetId): Promise<Asset | undefined>

Asset — зарегистрированное определение ноды или связи. Метод get возвращает любой зарегистрированный asset по id или undefined.

| Поле | Тип | Описание | | --- | --- | --- | | id | AssetId | Id asset'а. | | kind | 'node' \| 'edge' | AssetKind экспортируется только как тип — сравнивайте со строкой. | | definition | object | Определение ноды или связь из её schema.json. | | source | { extension: { id, uuid, versionId, version } } | Расширение, добавившее asset. | | category | string? | Категория, в которой сгруппирован asset. | | workspace | 'auth' \| 'project' \| 'team' \| 'extensionWorkshop' \| 'home'? | Workspace, которым ограничен asset. | | visible | boolean? | false, если определение скрывает его из списка assets. | | location | URI components? | Папка определения. | | docsUri | URI components? | Файл документации, если он есть у определения. |

location и docsUri приходят как обычные объекты с scheme, authority, path, query и fragment — не экземпляры URI.

interface UriComponents {
  readonly scheme: string
  readonly authority: string
  readonly path: string
  readonly query: string
  readonly fragment: string
}

interface Asset {
  readonly id: AssetId
  readonly kind: 'node' | 'edge'          // AssetKind.Node | AssetKind.Edge
  readonly definition: object             // определение node или edge из schema.json
  readonly source: {
    readonly extension: { readonly id: ExtensionId; readonly uuid: string; readonly versionId: string; readonly version: string }
  }
  readonly category?: string
  readonly workspace?: 'auth' | 'project' | 'team' | 'extensionWorkshop' | 'home'
  readonly visible?: boolean
  readonly location?: UriComponents
  readonly docsUri?: UriComponents
}

sdk.input

onKeyboard: Event<SdkKeyboardEvent>

События клавиатуры из окна приложения: { type: 'keydown' | 'keyup', code, key, altKey, ctrlKey, metaKey, shiftKey, repeat, timestamp }. Полезно для управления в реальном времени — например, клавиатурная телеоперация робот-ноды.

| Событие | Когда приходит | | --- | --- | | keydown | При нажатиях клавиш в окне приложения, до обработки горячих клавиш Fragmenta, — кроме случаев, когда фокус в текстовом поле (input, textarea, редактируемый контент) или в терминале. В редакторе кода приходит только для клавиш, привязанных к горячим клавишам. Нажатия внутри вебвью тоже приходят как keydown, если фокус не в поле формы вебвью. | | keyup | При каждом отпускании клавиши в окне приложения, в том числе в текстовых полях. Отпускания клавиш внутри вебвью не доставляются. |

code, key, флаги модификаторов и repeat повторяют браузерный KeyboardEvent. timestamp — это KeyboardEvent.timeStamp: миллисекунды с загрузки страницы приложения, а не Unix-время.

interface SdkKeyboardEvent {
  readonly type: 'keydown' | 'keyup'
  readonly code: string       // физическая клавиша, например 'KeyW'
  readonly key: string        // введённое значение, например 'w'
  readonly altKey: boolean
  readonly ctrlKey: boolean
  readonly metaKey: boolean
  readonly shiftKey: boolean
  readonly repeat: boolean    // клавиша удерживается
  readonly timestamp: number  // мс с загрузки страницы
}