如何为Stack.Screen添加自定义screenOptions并解决TS类型报错？

尝试为@react-navigation/stack添加自定义头部选项，模拟Native Stack的交互效果，初始写法如下：

<Stack.Screen name="FixedHeader"
    options={{
        title: "Fixed Header",
        headerRight: () => <HeaderButtons><ColorSchemeSwitchButton /></HeaderButtons>,
        headerLargeTitle: false, // TS此处抛出类型错误
    }}
    component={FourthScreen}
/>

直接编写时TypeScript会抛出类型错误，暂时没找到将新增自定义属性加入screenOptions类型定义的正规方式，目前使用的临时规避方案是将整个options对象断言为StackNavigationOptions类型：

options={{
    title: "Fixed Header",
    headerRight: () => <HeaderButtons><ColorSchemeSwitchButton /></HeaderButtons>,
    headerLargeTitle: false,
} as StackNavigationOptions}

@react-navigation/stack（Web/JS实现的基础Stack导航）默认的StackNavigationOptions类型定义中，本身不包含headerLargeTitle这类Native Stack专属的配置属性，直接传入未定义的属性就会触发TS类型校验错误。
注意：直接对整个options对象做类型断言属于不安全的写法，会丢失TS的类型校验能力，后续如果出现属性名拼写错误、属性值类型不匹配的问题，TS无法给出提示，容易埋下线上隐患，不建议长期使用。

通过TypeScript的模块声明扩充能力，直接扩展@react-navigation/stack的原有类型定义，是最稳妥的解决方式：

• 在项目中找到被tsconfig.json覆盖的全局类型声明文件（通常命名为navigation.d.ts或者放在src/types目录下，没有的话可以新建一个.d.ts后缀的文件）
• 在文件中写入如下类型扩展代码：

import type { StackNavigationOptions } from '@react-navigation/stack';

declare module '@react-navigation/stack' {
  interface StackNavigationOptions {
    // 新增你需要的自定义配置项，类型和实际使用保持一致即可
    headerLargeTitle?: boolean;
    // 后续如果需要添加其他自定义头部属性，直接在这里补充类型定义就行
  }
}

配置完成后，就不需要再写类型断言代码了，直接在options或者screenOptions中传入headerLargeTitle属性，TS既不会报错，还能保留完整的类型校验、属性提示能力，属性写错或者值类型不对的时候TS会正常抛出错误。

如果只是临时调试需要，不想做全局类型扩展，可以用as const做窄类型断言，比直接断言整个StackNavigationOptions的风险更低：

<Stack.Screen 
  name="FixedHeader"
  options={{
    title: "Fixed Header",
    headerRight: () => <HeaderButtons><ColorSchemeSwitchButton /></HeaderButtons>,
    headerLargeTitle: false,
  } as const}
  component={FourthScreen}
/>

这个方案仅适合快速验证场景，正式项目还是推荐用上面的类型扩充方案。

内容的提问来源于stack exchange，提问作者Archimedes Trajano