#Directives

#'background only'

'background only' 指令允许你标记只会在后台线程执行的函数。在其他线程中，被标记函数的函数体会被移除。

要将函数标记为仅限后台，只需在函数体的第一行添加 'background only' 指令：

function bgOnlyAction(pureCallback) {
  'background only';
  lynx.getJSModule('GlobalEventEmitter').addListener('eventName', pureCallback);
}

在生成输出的主线程部分中，该函数会被替换为如下形式：

function bgOnlyAction(pureCallback) {}

通常，带有副作用的代码应该只在后台线程中执行，例如事件监听器、JSB 调用等。将这类函数标记为 'background only' 可以显著减小 bundle 体积。

使用 'background only' 的一种方式是与自定义 Hook 配合使用。例如，useFirstRender 是一个用户自定义的 Hook，用于在组件首次渲染时执行某些逻辑。我们希望用它来监听事件，而事件监听逻辑不应该、也不能在主线程上执行。这种情况下，可以使用 'background only' 指令标记这个函数，将事件监听逻辑从主线程中移除。

import {useFirstRender} from './useFirstRender';

function bgOnlyAction(pureCallback) {
  'background only';
  lynx.getJSModule('GlobalEventEmitter').addListener('eventName', pureCallback);
}

function Foo({ prop } ){
  const ref = useRef(null);
  useFirstRender(() => {
    bgOnlyAction(() => {
      // ...
    });
  });
  return <view>;
}

在其他线程中被移除的代码不只是标记为 'background only' 的部分；ReactLynx 默认还会移除代码中的某些部分，包括 useEffect、useLayoutEffect 的参数以及部分事件处理函数等。对于这些部分，你不需要将相应的函数标记为 'background only'。更多细节请参阅 Dual Runtime Code Splitting。

#'main thread'

'main thread' 指令允许你标记主线程函数。主线程函数是 Main Thread Script 系统的一部分，只能在主线程上执行。它们主要用于流畅的动画和手势处理。

要将后台线程函数转换为主线程函数，只需在函数的第一行添加 'main thread' 指令：

import { MainThread } from '@lynx-js/types';

export default function App() {
  const red = 'red';

  function handleTap(event: MainThread.TouchEvent) {
    'main thread';
    event.currentTarget.setStyleProperty('background-color', red);
  }

  return (
    <view main-thread:bindtap={handleTap}>
      <text>Hello World!</text>
    </view>
  );
}

主线程函数在定义时会自动捕获来自后台线程的外部变量，例如上面示例中的 red。

使用主线程函数作为事件处理函数时，该主线程函数接受一个包含事件基本信息的 event 参数。其中 event.target 和 event.currentTarget 参数与常规事件处理函数中的不同，它们是 MainThread.Element 对象。该对象可以方便地同步获取和设置节点属性，例如在示例中使用 setStyleProperty()。

一些重要说明：

• 主线程函数只能且必须运行在主线程上。主线程函数之间可以互相调用。
• 被捕获的变量需要使用 JSON.stringify() 在线程间传递，因此必须是可序列化为 JSON 的。
• 主线程函数只能在 TTI（Time to Interactive）之后执行，这意味着它们无法在首屏加载期间执行。
• 主线程函数不支持嵌套定义。
• 类组件的构造函数、getter 和 setter 不支持被指定为主线程函数。
• 不能在主线程函数内部修改从外部作用域捕获的变量。