JavaScriptBridge
Web-мост к JavaScript, callbacks и byte buffers.
Мост Web-сборки к JavaScript страницы. Наличие SDK-класса или singleton на desktop не подтверждает поддержку: object/eval методы заглушены вне Web или без javascript_eval. Текущий C# exporter 1.0.0 не реализует Web; этот справочник не обещает C# browser export.
GetInterface ищет точное window[name], CreateObject вызывает его constructor. Передавайте ограниченный adapter API и проверяйте готовность скрипта. GetInterface/CreateCallback возвращают собственные RefCounted wrappers; engine-owned Singleton не освобождайте. Callback принимает один engine Array со всеми JS arguments; держите wrapper живым и отключайте внешнюю доставку перед освобождением. Native Callable return сейчас не передаётся в JS как синхронный результат.
Eval и object bridge преобразуют значения по-разному. DataView/non-Uint8Array копирование сейчас захватывает весь backing buffer; используйте проверенный copyViewBytes из руководства. Дефект воспроизведён в реальном JS-мосте с mock native memory; в движке не исправлялся. Native bool Variant fidelity и C#/WASM ABI не проверены.
DownloadBuffer — запрос browser download, ForceFsSync — планирование синхронизации, PwaUpdate — запрос service worker. Ни один не является общей квитанцией сохранения/обновления. На уровне JS выполнена 21 проверка; реальные browser permissions, DOM/download, storage, PWA и managed export не приняты как проверенные.
Объявления сверены с C# SDK 1.0.0. Раскройте имя, чтобы увидеть сигнатуры и описание.
Свойства1
SingletonСвойство
public static JavaScriptBridgeInstance Singleton { get; }Объект JavaScriptBridge, принадлежащий движку. Не создавайте второй экземпляр и не вызывайте Free/Dispose. Наличие singleton на desktop не означает browser support: соответствующие методы могут быть заглушками. Это отличается от собственных RefCounted wrappers, возвращённых GetInterface/CreateCallback.
Методы12
CreateCallbackJavaScriptObject
public static JavaScriptObject CreateCallback(Callable callable);Создаёт RefCounted JavaScriptObject функции из Callable, принимающего один engine Array со всеми JS arguments. Сохраните wrapper на срок подписки/ожидания; перед освобождением остановите внешнюю доставку. Не GetInterface. Текущий native код не передаёт return value Callable обратно в JS; threaded proxy может отложить callback. Вне Web/без javascript_eval — null.
| Имя | Тип | По умолчанию |
|---|---|---|
callable | Callable | — |
callableCallable с одним Array параметром: JavaScript arguments собраны в него. Проверяйте количество и типы; не рассчитывайте на синхронный return value.
JavaScriptObjectСобственный RefCounted wrapper callback либо null в неподдерживаемой сборке. Храните на срок внешней подписки; сначала отключите доставку, затем освобождайте ссылку.
CreateObject2 перегрузки
public static Variant CreateObject(string @object, params Variant[] args);Вызывает new windowname и возвращает Variant с wrapper нового JS-объекта. Имя точное, не dotted path; constructor должен быть готов в странице. При ошибке/отсутствии constructor возможен пустой результат с диагностикой. Не обещает конвертацию произвольных engine-коллекций; используйте поддерживаемые scalar/wrapper значения. Вне Web/без javascript_eval — заглушка.
| Имя | Тип | По умолчанию |
|---|---|---|
object | string | — |
args | Variant[] | — |
objectТочное имя constructor в window. Не expression и не dotted path; он должен быть загружен до вызова.
argsАргументы constructor в порядке передачи. Используйте поддерживаемые scalars и JavaScriptObject wrappers; обычные engine Array/Dictionary не обещаны как JS-коллекции.
VariantVariant с wrapper созданного JS-объекта либо пустой результат при ошибке/заглушке; не код успеха.
public static Variant CreateObject(string @object, ReadOnlySpan<Variant> args);Вызывает new windowname и возвращает Variant с wrapper нового JS-объекта. Имя точное, не dotted path; constructor должен быть готов в странице. При ошибке/отсутствии constructor возможен пустой результат с диагностикой. Не обещает конвертацию произвольных engine-коллекций; используйте поддерживаемые scalar/wrapper значения. Вне Web/без javascript_eval — заглушка.
| Имя | Тип | По умолчанию |
|---|---|---|
object | string | — |
args | ReadOnlySpan<Variant> | — |
objectТочное имя constructor в window. Не expression и не dotted path; он должен быть загружен до вызова.
argsАргументы constructor в порядке передачи. Используйте поддерживаемые scalars и JavaScriptObject wrappers; обычные engine Array/Dictionary не обещаны как JS-коллекции.
VariantVariant с wrapper созданного JS-объекта либо пустой результат при ошибке/заглушке; не код успеха.
DownloadBuffer2 перегрузки
public static void DownloadBuffer(byte[] buffer, string name, string mime = "application/octet-stream");Запрашивает browser download копии байтов через Blob и временную ссылку. Не возвращает подтверждение сохранения файла на диск, не экспортирует проект и не синхронизирует user://. Вне Web ничего не делает. Проверьте фактический файл и browser policy; MIME задаёт тип содержимого, не преобразует байты.
| Имя | Тип | По умолчанию |
|---|---|---|
buffer | byte[] | — |
name | string | — |
mime | string | "application/octet-stream" |
bufferБайты скачиваемого файла; MIME и расширение не меняют их кодировку. Проверьте содержимое до запроса download.
nameПредлагаемое имя файла для browser download, не абсолютный путь записи на компьютере пользователя.
mimeMIME-тип содержимого. byte[] overload по умолчанию application/octet-stream; ReadOnlySpan<byte> overload требует явного аргумента. Тип не конвертирует данные.
public static void DownloadBuffer(ReadOnlySpan<byte> buffer, string name, string mime);Запрашивает browser download копии байтов через Blob и временную ссылку. Не возвращает подтверждение сохранения файла на диск, не экспортирует проект и не синхронизирует user://. Вне Web ничего не делает. Проверьте фактический файл и browser policy; MIME задаёт тип содержимого, не преобразует байты.
| Имя | Тип | По умолчанию |
|---|---|---|
buffer | ReadOnlySpan<byte> | — |
name | string | — |
mime | string | — |
bufferБайты скачиваемого файла; MIME и расширение не меняют их кодировку. Проверьте содержимое до запроса download.
nameПредлагаемое имя файла для browser download, не абсолютный путь записи на компьютере пользователя.
mimeMIME-тип содержимого. byte[] overload по умолчанию application/octet-stream; ReadOnlySpan<byte> overload требует явного аргумента. Тип не конвертирует данные.
EvalVariant
public static Variant Eval(string code, bool useGlobalExecutionContext = false);Выполняет JS-код, по умолчанию в local execution context. Числа JS возвращаются floating Variant; строки и byte buffers имеют отдельные пути, обычные объекты/функции дают nil. Исключение логируется и тоже может дать nil. DataView/non-Uint8Array views сейчас копируют весь backing buffer: сначала нормализуйте copyViewBytes. JS bool tag есть, но C++ возвращает uint32-поле в Variant; native bool fidelity не проверена. Вне Web/без javascript_eval — nil.
| Имя | Тип | По умолчанию |
|---|---|---|
code | string | — |
useGlobalExecutionContext | bool | false |
codeJavaScript-код для выполнения. Предпочитайте именованный adapter API и передачу данных аргументами; не склеивайте код из внешнего текста.
useGlobalExecutionContextfalse по умолчанию — local eval context; true — indirect global eval с влиянием на page namespace. Не гарантирует object-return conversion.
VariantОграниченный Variant-результат. Nil неоднозначен: null, неподдерживаемый тип, ошибка или отключённый мост. Byte-range и native bool ограничения описаны выше.
ForceFsSyncvoid
public static void ForceFsSync();При доступном browser persistence отмечает FS для последующей синхронизации. Метод void: не ждёт writeback, не подтверждает сохранность и не инициирует download. Вне Web ничего не делает. Успешная запись в виртуальную FS и завершение сохранения IndexedDB — разные состояния.
GetInterfaceJavaScriptObject
public static JavaScriptObject GetInterface(string @interface);Получает новый wrapper точного window[name]. Строка app.sdk не разбирается как путь; объявите явный page-global adapter и дождитесь его готовности. В Web отсутствие имени даёт native error/null; вне Web или без javascript_eval — null. Wrapper — RefCounted handle: освобождение собственной ссылки не удаляет глобальный JS-объект. Singleton моста не освобождайте.
| Имя | Тип | По умолчанию |
|---|---|---|
interface | string | — |
interfaceТочное имя window global, например ReckfellPage, без разбора вложенных свойств.
JavaScriptObjectНовый RefCounted wrapper глобального JS-объекта либо null; владение самим page global не передаётся.
IsJsBufferbool
public static bool IsJsBuffer(JavaScriptObject javascriptObject);Проверяет, является ли JavaScriptObject ArrayBuffer или ArrayBuffer view. Для null возвращает false; вне Web/без javascript_eval — false. true не проверяет ожидаемую длину, формат или корректное ограничение view: текущий copy путь DataView/nonbyte views может захватить весь backing buffer.
| Имя | Тип | По умолчанию |
|---|---|---|
javascriptObject | JavaScriptObject | — |
javascriptObjectWrapper проверяемого JS-значения; null даёт false. Не подтверждает длину/схему буфера.
boolРезультат проверки формы JS-значения, не проверка корректного содержимого или диапазона.
JsBufferToPackedByteArraybyte[]
public static byte[] JsBufferToPackedByteArray(JavaScriptObject javascriptBuffer);Копирует JavaScript buffer в новый byte[]; сначала проверяет IsJsBuffer, при неподходящем объекте сообщает native error и даёт пустой массив. DataView/non-Uint8Array view сейчас разворачивается во весь backing ArrayBuffer без учёта offset/length. Передавайте fresh Uint8Array нужного диапазона, например результат copyViewBytes из руководства. Это копия, не shared memory и не перенос владения JS buffer.
| Имя | Тип | По умолчанию |
|---|---|---|
javascriptBuffer | JavaScriptObject | — |
javascriptBufferJS buffer wrapper. Для DataView/nonbyte view сначала создайте отдельный Uint8Array нужного byte range. Неподходящее значение вызывает native error/пустой результат.
byte[]Новый managed byte[] с копией; пустой при заглушке/ошибке и также для законного пустого буфера. Для nonbyte views нужен описанный workaround.
PwaNeedsUpdatebool
public static bool PwaNeedsUpdate();Читает сохранённый OS-флаг ожидания PWA update; вне Web false. Не опрашивает сеть, не сравнивает версии движка и не доказывает, что update всё ещё ожидает в registration. true ставится уведомлением service-worker пути; применение обновления проверяйте отдельно.
boolСохранённый waiting-флаг или false вне Web; не live-query service worker.
PwaUpdateError
public static Error PwaUpdate();Просит ожидающий service worker обновиться. В Web мост асинхронно получает registration и отправляет waiting.postMessage("update"). Ok означает принятие запроса этим синхронным мостом, не завершение установки/reload; registration может уже не иметь waiting. Сохраните состояние до запроса. Вне Web возвращает Unavailable; реальный PWA workflow здесь не выполнен.
ErrorError.Ok при принятом запросе моста, Failed при его отказе, Unavailable вне Web. Не подтверждение завершения async update.
Сигналы и события1
PwaUpdateAvailableСобытие
public static event Action PwaUpdateAvailable;Событие без аргументов при уведомлении, что PWA update ожидает. Сначала native-код ставит waiting-флаг. Это не уведомление о новом релизе движка и не доказательство установки update. Сохраните состояние и решите, когда вызывать PwaUpdate; обработчик не должен безусловно перезагружать незавершённую игру.