@g9tm/lynxcontrols-native

中文文档
1.7.3发布于 2026/11/16MITTypeScriptES Module近 30 天下载 1994

Android and iOS platform layer: the G9SqliteModule and G9HostModule native modules (Autolink) and their JS adapters.

原始使用文档
文档目录3 节
  1. How it works
  2. Layout
  3. Commands

@g9tm/lynxcontrols-native

Android and iOS platform layer for G9: three Lynx native modules and one element (<g9-video>), linked into a host by Lynx Autolink from node_modules, plus their JS adapters.

ModuleJS adapterAndroid (Kotlin)iOS (Objective-C)
G9SqliteModulecreateNativeSqliteDriver()androidx.sqlite BundledSQLiteDriver 2.7.1system sqlite3 (iOS 15+, serial queue per session, sqlite3_interrupt)
G9HostModulecreateNativeHostServices()SharedPreferences, moveTaskToBack, InputMethodManager, haptics, insets, appDataDirectory() = filesDirNSUserDefaults suite, resignFirstResponder, UIImpactFeedbackGenerator, safe-area insets, appDataDirectory() = Library
G9SpeechModulecreateNativeSpeechToText() → services.speech (dictation into fields)SpeechRecognizer (main thread, partial results), the microphone asked through the host activity's ActivityResultRegistrySFSpeechRecognizer over AVAudioEngine; register it on the host's LynxConfig; Info.plist NSMicrophoneUsageDescription + NSSpeechRecognitionUsageDescription
<g9-video> elementcreateNativeMediaProvider() (@g9tm/lynxcontrols-native/media)G9VideoUI: Media3 ExoPlayer 1.8.0 into a TextureView (opacity fades work); register G9VideoBehaviors.create()G9VideoUI: AVQueuePlayer + AVPlayerLooper in an AVPlayerLayer; self-registers (LYNX_REGISTER_UI)
import { createG9Sqlite, singleFileDatabaseLocator } from '@g9tm/lynxcontrols-sqlite';
import { createNativeHostServices, createNativeSqliteDriver } from '@g9tm/lynxcontrols-native';

const { host, preferences, appDataDirectory } = createNativeHostServices();
const root = await appDataDirectory(); // MAUI FileSystem.AppDataDirectory: the MAUI app's database stays found
const db = createG9Sqlite({ driver: createNativeSqliteDriver(), locator: singleFileDatabaseLocator(`${root}/g9.db`), /* … */ });
// <G9Provider services={{ clock, host, preferences }}>

How it works

  • Dictation (services.speech, MAUI IG9SpeechToText). createNativeSpeechToText() returns null where G9SpeechModule is not linked, so the fields hide their microphone. One session at a time natively; the adapter numbers sessions, routes the g9:speech global event ({"session","text"}, interim hypotheses) to the session that asked, turns an abort into cancel(session) and settles every listen once (recognized / no-match / cancelled / denied; a recogniser fault rejects with a G9Error). Android: the manifest merges RECORD_AUDIO and the RecognitionService query Android 11+ needs to see a recogniser; androidx.activity is compile-only (every host has it; a host activity that is not an ActivityResultRegistryOwner gets the current permission state, never a prompt). isAvailable(locale) is "a recogniser exists" on Android (asking a locale needs a broadcast some recognisers never answer; an unsupported language ends as no-match) and SFSpeechRecognizer(locale).isAvailable on iOS.

  • Video (the intro carousel's services.media). <g9-video> props: src, paused, loop, muted, start-seconds, near-end-seconds, object-fit; events ready, nearend, looped, error. The provider's player renders it with reactive props (no UI-method calls) and unmounts it on dispose(), which releases the native player. resolve() maps bundled assets with G9HostModule.assetUri (not-found when the app does not ship the file). The near-end/loop and start-seek rules are the platform-free cores video/core/G9VideoCore.kt and ios/src/core/G9VideoCore.m, tested on the JVM and on Linux.

  • Contract. The driver passes the shared contract @g9tm/lynxcontrols-sqlite/contract/cases.json (27 cases): on the JVM through the Kotlin core (npm run test:android-jvm), and in JS through the module protocol (src/native.test.ts).

  • Threads. One single-thread executor per open database with a bounded queue (256; overflow → busy). Replies are envelopes { ok, value | error }, so G9SqliteError fields (code, sqliteCode, sql, completedStatements) survive the bridge.

  • Cancellation. A batch aborted while queued in JS never reaches native code.

    • Aborting a running batch calls interrupt(session).
    • iOS: sqlite3_interrupt stops the statement, and the batch fails with interrupted.
    • Android: androidx connections have no interrupt, so the statement finishes (capabilities().interrupt === false).
  • Transport (plan/specs/06 §6). columnar (default): cell tags, float64 numbers and blob bytes as ArrayBuffers, text as strings. rows: tagged cells. Choose with createNativeSqliteDriver({ transport }). contract/transport-golden.json pins the bytes: the Kotlin encoder writes it, and the JS decoder test reads it.

  • Values. Safe integers cross as numbers, others as { int64 }, BLOBs as ArrayBuffer. NUL in text, NaN and undefined are rejected with misuse, as on every driver.

Layout

types/platform-native-module.d.ts   codegen input (`npm run codegen` → generated/, android/…/generated, ios/src/generated;
                                    then scripts/android-bridge-types.mjs --fix gives the Android specs the parameter
                                    types Lynx's bridge accepts — never run the bare generator)
scripts/android-bridge-types.mjs    `--fix` after codegen; without it, the check (`npm run check:android-types`)
android/src/main/java/com/g9lynx/g9native/
  sqlite/core/      pure Kotlin: G9SqliteCore, G9SqliteService (executors), G9SqliteTransport, values/errors
  sqlite/androidx/  AndroidxSqlEngine (BundledSQLiteDriver)
  host/core/        G9PreferencesCore
  G9SqliteModule.kt, G9HostModule.kt, G9SpeechModule.kt, G9Bridge.kt   Lynx modules (kapt + lynx-processor →
                    LynxLibraryProviderImpl)
android/src/test/   JVM tests: contract runner, core, service, transport golden, preferences
ios/src/core/       portable Objective-C (Foundation + sqlite3): G9SqliteCore, G9SqliteTransport, G9PreferencesCore
ios/src/            G9SqliteModule.m, G9HostModule.m, G9SpeechModule.m (dispatch queues, UIKit, Speech); register them
                    on the host's LynxConfig
ios/Tests/          G9NativeTestSuite (XCTest on a simulator; Linux harness in Tests/linux)
jvm/                JVM-only Gradle build of the core + tests (no Android SDK needed)
android-check/      cloud compile check of module + reference host against the published Lynx 4.1.0 classes (Media3,
                    androidx.sqlite and androidx.activity as compile-only stubs under stubs/), and
                    LynxBridgeSignatureTest: every @LynxMethod through Lynx's own LynxMethodWrapper

The Android package is com.g9lynx.g9native, not com.g9lynx.native: native is a reserved word in Java, so the generated Java specs could not compile under that name.

The native identifiers are internal and did not follow the npm rename to @g9tm/lynxcontrols-native (decision D12): the Android package com.g9lynx.g9native, the iOS pod g9lynx-native, the module classes G9SqliteModule and G9HostModule, and the preference store g9lynx.preferences keep their names, so hosts and stored data are not affected. The pod's version follows the package version (= the pinned G9MAUIControls version).

Commands

CommandWhat it proves
npm run test:android-jvmKotlin core: contract 27/27 over both transports (JDBC engine), unit tests, JaCoCo gate (lines ≥ 95 %, branches ≥ 85 %)
gradle -p packages/native/jvm check -Pg9.bundled=trueThe same on androidx BundledSQLiteDriver (needs Google Maven)
npm run check:android-moduleModule and host compile against Lynx 4.1.0, and the Autolink provider is generated
npm run test:ios-coreiOS core on Linux (clang + GNUstep): contract 27/27 × 2, golden byte-identical with Kotlin, interrupt, ARC syntax
npm run bench:transportJS decode cost of columnar vs rows

Host integration: docs/integration/android.md and docs/integration/ios.md (reference hosts: apps/android-host, apps/ios-host).

版本与发布记录

@g9tm/lynxcontrols-native 共发布 15 个版本,首次发布于 2026/10/07;过去 12 个月发布了 15 个版本。

版本发布日期距今
1.7.3latest2026/11/16今天
1.7.22026/11/132 天前
1.7.12026/11/133 天前
1.7.02026/11/133 天前
1.6.12026/11/123 天前
1.6.02026/11/123 天前

关于 @g9tm/lynxcontrols-native 的常见问题

@g9tm/lynxcontrols-native 是什么?

Android and iOS platform layer: the G9SqliteModule and G9HostModule native modules (Autolink) and their JS adapters.

如何安装 @g9tm/lynxcontrols-native?

在项目目录运行 npm install @g9tm/lynxcontrols-native,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@lynx-js/react(>=0.129.1 <0.130.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@g9tm/lynxcontrols-native 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@g9tm/lynxcontrols-native 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@g9tm/lynxcontrols-native 可以商用吗?

@g9tm/lynxcontrols-native 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@g9tm/lynxcontrols-native 的下载量有多少?

根据 npm 官方下载统计,@g9tm/lynxcontrols-native 在 2026/10/16 – 2026/11/14 这 30 天内被下载 1,994 次,日均约 66 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@g9tm/lynxcontrols-native 还在维护吗?

最新版本 1.7.3 发布于 2026/11/16(今天);至今共发布 15 个版本,其中过去 12 个月发布了 15 个;首次发布于 2026/10/07。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。