lynx-typescript

TypeScript 与 Lynx

本 Skill 总结了 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 项目，需要在 tsconfig.json 中将 jsxImportSource 配置为 @lynx-js/react，以确保 JSX 能够正确编译并获得类型支持。

{
  "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 Hook useInitData() 的返回值类型：

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

这样，在使用 useInitData().userInfo 时就会显示类型提示。

2.3 IntrinsicElements（自定义原生组件）

如果使用了自定义原生组件，需要扩展 IntrinsicElements 以获得 JSX 类型检查：

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

扩展 NativeModules 类型以支持自定义 Native Module 调用：

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 (自定义原生组件) 了解类型扩展。 -> 另外，请检查是否安装了冲突的类型包。

• 错误：类型 'UnsafeLynx' 上不存在属性 'cancelAnimationFrame' 或 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 {}，以避免全局污染。