lynx-typescript

TypeScript @ Lynx

このスキルでは、Lynx 開発における一般的な TypeScript の問題とその解決策をまとめています。主に環境設定、型の拡張、イベント処理、コンポーネント、ReactLynx の高度な使い方を扱います。

1. 設定 (環境設定)

1.1 tsconfig.json の設定

Rspeedy はデフォルトでルートディレクトリの tsconfig.json を読み込みます。Rspeedy はトランスパイルに SWC を使用するため、ファイル間の型参照エラーを避けるために isolatedModules オプションを有効にすることを推奨します。

{
  "compilerOptions": {
    "isolatedModules": true,
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

1.2 型パッケージのインストール

正しい型パッケージがインストールされていることを確認してください。@lynx-js/types は Lynx のコア型パッケージです。

• ReactLynx: @lynx-js/types と @lynx-js/react をインストールします。

1.3 型宣言ファイル rspeedy-env.d.ts

TypeScript に Rspeedy の組み込み機能 (CSS Modules、静的リソースのインポートなど) を認識させるには、プロジェクトに src/rspeedy-env.d.ts ファイルを作成する必要があります:

/// <reference types="@rspeedy/core/client" />

(注: 実際のパッケージは Rspeedy のセットアップによって異なる場合があります。通常、オープンソースでは @rspeedy/core または同様のものです)

1.4 ReactLynx の JSX 設定

ReactLynx プロジェクトでは、JSX が正しくコンパイルされ型サポートを受けられるように、tsconfig.json で jsxImportSource を @lynx-js/react に設定する必要があります。

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@lynx-js/react"
  }
}

2. Lynx の型の拡張

Lynx はデフォルトの型定義を提供していますが、ビジネス要件に合わせてこれらを拡張する必要が通常あります。

2.1 GlobalProps

lynx.__globalProps の型を拡張します:

declare module '@lynx-js/types' {
  interface GlobalProps {
    appTheme: string;
    title: string;
    // Add other custom global properties
  }
}
export {};

これにより、lynx.__globalProps.appTheme を使用する際に型ヒントが表示されます。

2.2 InitData

ReactLynx フック useInitData() の戻り値の型を拡張します:

declare module '@lynx-js/react' {
  interface InitData {
    userInfo: {
      name: string;
      id: number;
    };
    // Add other initialization data properties
  }
}
export {};

これにより、useInitData().userInfo を使用する際に型ヒントが表示されます。

2.3 IntrinsicElements (カスタムネイティブコンポーネント)

カスタムネイティブコンポーネントを使用する場合、JSX の型チェックを受けるために IntrinsicElements を拡張する必要があります:

import type * as Lynx from '@lynx-js/types';
import type { CSSProperties } from '@lynx-js/types';

declare module '@lynx-js/types' {
  interface IntrinsicElements extends Lynx.IntrinsicElements {
    'custom-input': {
      'bindcustom-event'?: (e: { type: 'custom-event'; detail: { value: string } }) => void;
      value?: string;
      class?: string;
      className?: string;
      style?: string | CSSProperties;
    };
  }
}

2.4 NativeModules

カスタム Native Module の呼び出しをサポートするために、NativeModules 型を拡張します:

declare module '@lynx-js/types' {
  interface NativeModules {
    NativeLocalStorageModule: {
      getStorageItem(key: string): string | null;
      setStorageItem(key: string, value: string): void;
    };
  }
}
export {};

2.5 Lynx グローバルオブジェクト

lynx グローバルオブジェクトの型を拡張します (例: カスタムメソッド lynx.myMethod の追加):

declare module '@lynx-js/types' {
  interface Lynx {
    myMethod(param: string): void;
    customProperty: number;
  }
}
export {};

これにより、lynx.myMethod('test') を使用する際に型ヒントが表示されます。

3. イベント処理

イベントを処理する際は、any 型の使用を避けるべきです。Lynx は標準のイベント型を提供しています。

3.1 基本イベントとタッチイベント

タッチイベント (bindtap、bindtouchstart など) では、イベントオブジェクトに detail、touches、changedTouches などのプロパティが含まれます。

// Example: Handling a tap event
const handleTap = (event: any) => { // Using any is not recommended
  console.log(event);
};

// Recommended approach: Define event interfaces or use inferred types
import type { TouchEvent } from '@lynx-js/types';

// Usage example
const handleButtonTap = (e: TouchEvent) => {
  const { dataset } = e.currentTarget;
  console.log('Tapped!', dataset);
};

4. ReactLynx と LynxUI の型

4.1 LynxUI コンポーネントの型

LynxUI コンポーネントは通常、その Props と Ref の型定義をエクスポートします。@lynx-js/lynx-ui (またはそのサブパッケージである @lynx-js/lynx-ui-button、@lynx-js/lynx-ui-scroll-view など) のコンポーネントを使用する場合は、これらのエクスポートされた型を使用する必要があります。

ベストプラクティス:

1. Props 型と Ref 型を明示的にインポートします。
2. useRef を使用する際に Ref 型を指定します。

import { ScrollView } from '@lynx-js/lynx-ui-scroll-view';
import type { ScrollViewRef, ScrollViewProps } from '@lynx-js/lynx-ui-scroll-view';
import { useRef } from '@lynx-js/react';

function App() {
  // Explicitly specify the Ref type
  const scrollViewRef = useRef<ScrollViewRef>(null);

  const handleScroll: ScrollViewProps['onScroll'] = (e) => {
    console.log('Scrolled:', e.detail);
  };

  return (
    <ScrollView
      ref={scrollViewRef}
      onScroll={handleScroll}
      // ...
    />
  );
}

4.2 MainThreadRef とマルチスレッド API

ReactLynx はメインスレッドの状態を処理するための専用 API を提供しています。

import { useMainThreadRef, runOnMainThread } from '@lynx-js/react';

function AnimationComponent() {
  // Define the data type stored in MainThreadRef
  const widthRef = useMainThreadRef<number>(0);

  const handleTap = () => {
    // Call main thread logic from the background thread
    runOnMainThread(widthRef, (ref) => {
      // This callback executes on the main thread
      ref.current += 10;
      console.log('New width:', ref.current);
    });
  };

  return <view bindtap={handleTap} />;
}

4.3 Lynx グローバルオブジェクト

lynx グローバルオブジェクトは querySelector などのメソッドを提供しています。

// Select element
const element = lynx.querySelector('#my-id');
// The type of element is Element | null

// Register data processors (functional)
lynx.registerDataProcessors({
  defaultDataProcessor: (data) => {
    return data;
  }
});

5. よくあるエラーの修正ガイド

• エラー: プロパティ '...' は型 'GlobalProps' に存在しません -> 型の拡張については、2.1 GlobalProps を参照してください。

• エラー: プロパティ '...' は型 'InitData' に存在しません -> 型の拡張については、2.2 InitData を参照してください。

• エラー: プロパティ '...' は型 'JSX.IntrinsicElements' に存在しません -> 型の拡張については、2.3 IntrinsicElements (カスタムネイティブコンポーネント) を参照してください。 -> 競合する型パッケージがインストールされていないかも確認してください。

• エラー: プロパティ 'cancelAnimationFrame' は型 'UnsafeLynx' に存在しません または CSSProperties を割り当てることができません -> 原因: 通常、競合する複数の Lynx 型パッケージをインストールしたことが原因です。 -> 解決策: package.json を確認し、不要な型パッケージを削除して、@lynx-js/types と @lynx-js/react のみが残るようにしてください。

• エラー: モジュール '...' またはそれに対応する型宣言が見つかりません -> paths が設定されているか (1.1 を参照)、または d.ts の定義が不足していないかを確認してください。

• エラー: 'lynx' が定義されていません -> プロジェクトに参照 import {} from "@lynx-js/react" が含まれていることを確認してください。

• d.ts ファイルで declare module '@lynx-js/types' を使用する場合は、グローバル汚染を避けるために空のオブジェクト export {} を必ずエクスポートしてください。