docs/zh-cn/自定义组件.md · OpenHarmony-SIG/ohos_react_native

# Fabric 自定义组件开发指导

## ArkTS版本自定义组件（仅支持叶子节点类型组件）

本节以[示例工程 - Sample](附录.md)中的 `MarqueeView` 为例，介绍了 Fabric ArkTS 自定义组件的实现步骤。

### 1.编写 RN 调用 Fabric 组件的代码

编写 `MarqueeViewNativeComponent.tsx`。注意，如果要使用 `Codegen`，文件必须以 `<ModuleName>NativeComponent` 命名。在文件中使用 `codegenNativeComponent` 创建 `MarqueeView` 组件，其中 `MarqueeViewProps` 里声明了 `src` 属性和 `onStop` 事件：

```javascript
type OnStopEventData = Readonly<{
  isStop: boolean
}>;

interface MarqueeViewProps extends ViewProps {
  src: string,
  onStop?: DirectEventHandler<OnStopEventData>;
}

const MarqueeView = codegenNativeComponent<MarqueeViewProps>(
  'MarqueeView'
) as HostComponent<MarqueeViewProps>;
```

和其他标准组件的创建方式一样，在组件容器内添加 `MarqueeView` 标签：

```javascript
<MarqueeView
  src="双十一大促，消费是社会再生产过程中的一个重要环节，也是最终环节。它是指利用社会产品来满足人们各种需要的过程。"
  style={{height: 180, width: '100%', backgroundColor: 'hsl(210, 80%, 50%)'}}
  onStop={(e) => {
    SampleTurboModule.rnLog("native调用了RN的onStop，isStop = "+e.nativeEvent.isStop)
    setMarqueeStop(e.nativeEvent.isStop)
  }}
/>
```

### 2. 编写 ArkTS 原生实现代码

#### Descriptor

`Descriptor` 的功能是封装 **RN** 侧组件代码传递到 **ArkUI** 组件的参数，`MarqueeView` 对 **RN** 侧公开了一个 `src` 参数，用于显示跑马灯的滚动内容。原生侧定义 `MarqueeViewDescriptor` 代码如下：

```javascript
export interface MarqueeViewProps extends ViewBaseProps {
  src: string
}

export type MarqueeViewDescriptor = Descriptor<"MarqueeView", MarqueeViewProps>;
```

`Descriptor` 不需要我们手动创建，由 rnoh 自动生成；组件 `tag` 也不需要我们手动设置，rnoh 会为组件自动分配 `tag`。开发者只需要通过 `getDescriptor` 方法获取对应 `tag` 的 `Descriptor`：

```javascript
this.descriptor = this.ctx.descriptorRegistry.getDescriptor<MarqueeViewDescriptor>(this.tag)
```

当 **RN** 侧传递过来的属性参数发生变化时，我们需要更新 `Descripotor`：

```javascript
this.unregisterDescriptorChangesListener = this.ctx.descriptorRegistry.subscribeToDescriptorChanges(this.tag, (newDescriptor) => {
    this.descriptor = (newDescriptor as MarqueeViewDescriptor)
})
```

#### RN 调用原生方法

RN侧调用 `UIManager.dispatchViewManagerCommand` 向原生发送消息：

```javascript
UIManager.dispatchViewManagerCommand(
  findNodeHandle(nativeRef.current),
  'toggleMarqueeState',
  [],
)
```

原生组件通过 `componentCommandReceiver.registerCommandCallback` 接收消息并执行对应方法：

```javascript
this.ctx.componentCommandReceiver.registerCommandCallback(this.tag, (commandName) => {
  if (commandName === "toggleMarqueeState") {
    this.start = !this.start
    console.log("will emitComponentEvent");
  }
})
```

#### 原生组件调用RN侧方法

RN 侧添加 `onStop` 方法实现：

```javascript
<MarqueeView
  onStop={(e) => {
    // 原生组件调用了 RN 侧的 MarqueeView 的 onStop 方法
    const isStop = e.nativeEvent.isStop
    ...
  }}
/>
```

原生侧发送调用 **RN** 组件事件的消息：

```javascript
this.ctx.rnInstance.emitComponentEvent(
  this.descriptor.tag,
  "MarqueeView",
  { type: "onStop", isStop: !this.start }
)
```

#### arkTsComponentNames

在创建 `RNApp` 或 `RNInstance` 的时候，将组件的 name 放到数组中，并作为 `arkTsComponentNames` 的参数传入：
   
```typescript
const arkTsComponentNames = [MarqueeView.NAME];

// 作为RNApp的参数
RNApp({
  rnInstanceConfig: {
    ···
    arkTsComponentNames: arkTsComponentNames
  },
  ···
})

// 创建RNInstance时传入
await rnohCoreContext.createAndRegisterRNInstance({
  ···
  arkTsComponentNames: arkTsComponentNames
});
```

#### buildCustomComponent

创建 `RNSurface` 加载 JSBundle 时，传入 `buildCustomComponent` 用于加载原生 Fabric 组件：

```javascript
import { RNAbility, ComponentBuilderContext, RNSurface } from "rnoh";
import { MarqueeView } from '../customView/MarqueeView'

@Builder
public buildCustomComponent(ctx: ComponentBuilderContext) {
  if (ctx.componentName === MarqueeView.NAME) {
    MarqueeView({
      ctx: ctx.rnComponentContext,
      tag: ctx.tag
    })
  }
}
...

RNSurface({
  ...
  buildCustomComponent: this.buildCustomComponent,
})
```

### 3. 编写 Codegen 的 C++ 代码

开发者可以使用 [Codegen](Codegen.md) 生成 C++ 侧的胶水代码，也可以手动实现这部分代码，推荐使用 Codegen 生成这部分代码。在本节中会详细介绍如何手动实现这部分代码。

1. 首先创建属性 `Props` 和事件 `Emitter` 两部分的 C++ 类，在 `Descriptor` 中进行绑定。
2. 实现 `MarqueeViewEventEmitRequestHandler` 的 `handleEvent` 方法，根据原生消息的事件名，调用 `eventEmitter` 向 **RN** 侧组件发送事件消息。
3. 实现 `MarqueeViewJSIBinder` 类的属性和事件绑定方法。
4. 实现 `MarqueeViewNapiBinder` 类的属性映射方法。
5. 将以上文件引入到 `SampleTurboModulePackage` 的对应方法实现中进行绑定。

#### Props

创建 `Props` 的 C++ 文件用于定义 `MarqueeView` 的 `Descriptor` 对应的属性。
`Props.h`：

```cpp
#include <jsi/jsi.h>
#include <react/renderer/components/view/ViewProps.h>
#include <react/renderer/core/PropsParserContext.h>
#include <react/debug/react_native_assert.h>

namespace facebook {
namespace react {
class JSI_EXPORT MarqueeViewProps final : public ViewProps {
  public:
    MarqueeViewProps() = default;
    MarqueeViewProps(const PropsParserContext &context, const MarqueeViewProps &sourceProps, const RawProps &rawProps);

#pragma mark - Props
    std::string src{""};
};

} // namespace react
} // namespace facebook
```

```cpp
// Props.cpp
#include <react/renderer/components/rncore/Props.h>
#include <react/renderer/core/PropsParserContext.h>
#include <react/renderer/core/propsConversions.h>
#include "Props.h"

namespace facebook {
namespace react {
MarqueeViewProps::MarqueeViewProps(
    const PropsParserContext &context, 
    const MarqueeViewProps &sourceProps, 
    const RawProps &rawProps): ViewProps(context, sourceProps, rawProps),

src(convertRawProp(context, rawProps, "src", sourceProps.src, {""}))
      {}
} // namespace react
} // namespace facebook
```

#### MarqueeViewEventEmitter

`MarqueeViewEventEmitter.h` 中添加 `onStop` 方法，并自定义了属性结构体：

```cpp
#include <react/renderer/components/view/ViewEventEmitter.h>
#include <jsi/jsi.h>

namespace facebook {
namespace react {

class JSI_EXPORT MarqueeViewEventEmitter : public ViewEventEmitter {
  public:
    using ViewEventEmitter::ViewEventEmitter;
    struct OnStop {
      bool isStop;
    };

void onStop(OnStop value) const;
};

} // namespace react
} // namespace facebook
```

`MarqueeViewEventEmitter.cpp` 中实现 `onStop` 事件的发送和参数绑定：

```cpp
#include "MarqueeViewEventEmitter.h"

namespace facebook {
namespace react {

void MarqueeViewEventEmitter::onStop(OnStop event) const {
    dispatchEvent("stop", [event = std::move(event)](jsi::Runtime &runtime) {
        auto payload = jsi::Object(runtime);
        payload.setProperty(runtime, "isStop", event.isStop);
        return payload;
    });
}

} // namespace react
} // namespace facebook
```

#### MarqueeViewComponentDescriptor.h

将`MarqueeViewProps`、`MarqueeViewEventEmitter`绑定到`MarqueeViewComponentDescriptor`中：

```cpp
#include <react/renderer/core/ConcreteComponentDescriptor.h>
#include <react/renderer/components/view/ConcreteViewShadowNode.h>
#include <react/renderer/components/view/ViewShadowNode.h>
#include "MarqueeViewEventEmitter.h"
#include "Props.h"

namespace facebook {
namespace react {

extern const char MarqueeViewComponentName[] = "MarqueeView";

using MarqueeViewShadowNode = ConcreteViewShadowNode<MarqueeViewComponentName, MarqueeViewProps, MarqueeViewEventEmitter>;
  using MarqueeViewComponentDescriptor = ConcreteComponentDescriptor<MarqueeViewShadowNode>;

} // namespace react
} // namespace facebook
```

#### MarqueeViewEventEmitRequestHandler

`handleEvent` 方法中根据事件名调用事件消息发送方法 `eventEmitter->onStop(event)`：

```cpp
class MarqueeViewEventEmitRequestHandler : public EventEmitRequestHandler {
    public:
    void handleEvent(EventEmitRequestHandler::Context const &ctx) override {
        if (ctx.eventName != "MarqueeView") {
            return;
        }
        ArkJS arkJs(ctx.env);
        auto eventEmitter = ctx.shadowViewRegistry->getEventEmitter<react::MarqueeViewEventEmitter>(ctx.tag);
        if (eventEmitter == nullptr) {
            return;
        }

MarqueeViewEventType type = getMarqueeViewEventType(arkJs, ctx.payload);
        switch (type) {
        case MarqueeViewEventType::MARQUEE_VIEW_ON_STOP: {
            bool isStop = (bool)arkJs.getBoolean(arkJs.getObjectProperty(ctx.payload, "isStop"));
            react::MarqueeViewEventEmitter::OnStop event{isStop};
            eventEmitter->onStop(event);
            break;
        }
        default:
            break;
        }
    };
};
```

#### MarqueeViewJSIBinder

JSIBinder 是 **RN** 侧的属性和方法在 **JSI** 层的实现，主要调用了 `object.setProperty(rt, "src", "string")` 和 `events.setProperty(rt, "topStop", createDirectEvent(rt, "onStop"))` 这两个方法，`events.setProperty` 中注意 `topStop` 和 `onStop` 的命名规则：

```cpp
#pragma once
#include "RNOHCorePackage/ComponentBinders/ViewComponentJSIBinder.h"

namespace rnoh {
class MarqueeViewJSIBinder : public ViewComponentJSIBinder {
    facebook::jsi::Object createNativeProps(facebook::jsi::Runtime &rt) override {
        auto object = ViewComponentJSIBinder::createNativeProps(rt);
        object.setProperty(rt, "src", "string");
        return object;
    }
  
    facebook::jsi::Object createDirectEventTypes(facebook::jsi::Runtime &rt) override {
        facebook::jsi::Object events(rt);
        events.setProperty(rt, "topStop", createDirectEvent(rt, "onStop"));
        return events;
    }
};
} // namespace rnoh
```

#### NapiBinder

实现 C++ 代码和原生组件代码之间的属性映射，其中 `.addProperty("src", props->src)` 为 `MarqueeViewDescriptor` 的 `props` 增加了 `src` 字段；如果未添加该代码，`MarqueeView` 就需要从 `rawProps` 中获取 `src`：

```cpp
#include "RNOHCorePackage/ComponentBinders/ViewComponentNapiBinder.h"
#include "Props.h"

namespace rnoh {
class MarqueeViewNapiBinder : public ViewComponentNapiBinder {
public:
    napi_value createProps(napi_env env, facebook::react::ShadowView const shadowView) override {
        napi_value napiViewProps = ViewComponentNapiBinder::createProps(env, shadowView);
        if (auto props = std::dynamic_pointer_cast<const facebook::react::MarqueeViewProps>(shadowView.props)) {
            return ArkJS(env)
                .getObjectBuilder(napiViewProps)
                .addProperty("src", props->src) 
                .build();
        }
        return napiViewProps;
    };
};
} // namespace rnoh
```

#### SampleTurboModulePackage

在 `SampleTurboModulePackage.h` 中添加自定义组件相关的方法声明：

```cpp
#include "RNOH/Package.h"

namespace rnoh {
class SampleTurboModulePackage : public Package {
    public:
        std::vector<facebook::react::ComponentDescriptorProvider> createComponentDescriptorProviders() override;
        ComponentNapiBinderByString createComponentNapiBinderByName() override;
        ComponentJSIBinderByString createComponentJSIBinderByName() override;
        EventEmitRequestHandlers createEventEmitRequestHandlers() override;
    };
} // namespace rnoh
```

使用 `MarqueeViewComponentDescriptor`、`MarqueeViewEventEmitRequestHandler`、`MarqueeViewNapiBinder`、`MarqueeViewJSIBinder` 在 `SampleTurboModulePackage.cpp` 中完成对应方法实现：

```cpp
std::vector<react::ComponentDescriptorProvider> SampleTurboModulePackage::createComponentDescriptorProviders() {
    return {
react::concreteComponentDescriptorProvider<react::MarqueeViewComponentDescriptor>(),
    };
}

EventEmitRequestHandlers SampleTurboModulePackage::createEventEmitRequestHandlers() {
    return {std::make_shared<MarqueeViewEventEmitRequestHandler>()};
}

ComponentNapiBinderByString SampleTurboModulePackage::createComponentNapiBinderByName() {
    return {{"MarqueeView", std::make_shared<MarqueeViewNapiBinder>()}};
};

ComponentJSIBinderByString SampleTurboModulePackage::createComponentJSIBinderByName() {
    return {{"MarqueeView", std::make_shared<MarqueeViewJSIBinder>()}};
};
```

### 4. 优化原生ArkTS组件

之前介绍的 ArkTS 组件实现中，是通过调用对应的属性设置接口完成属性的设置，这种实现方式存在两个缺点：

- 自定义组件属性过多，影响执行效率：若需要使用系统组件的全量属性方法，则需在封装的自定义组件中注册穷举每个属性值。这样会大大影响每个组件的 Build 效率。
- 不利于后期维护：当自定义组件中的系统组件属性发生变更时，自定义组件也需要同步适配。

为了解决上述缺点，ArkTS 为每个系统组件提供了[动态属性设置](https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V5/ts-universal-attributes-attribute-modifier-V5)的方式，包括 `attributeModifier` 属性方法。该方法将组件属性设置分离到系统提供的 `AttributeModifier` 接口实现类实例中，通过自定义 Class 类实现 `AttributeModifier` 接口对系统组件属性进行扩展，本节介绍了如何优化 ArkTS 组件。

```typescript
export class MarqueeModifier implements AttributeModifier<MarqueeAttribute> {
  private constructor() {}
  private static instance: MarqueeModifier;
  protected descriptor: ViewBaseDescriptor = {} as ViewBaseDescriptor;

//提供单例方法获取MarqueeModifier实例。
  public static getInstance(): MarqueeModifier {
    if (!MarqueeModifier.instance) {
      MarqueeModifier.instance = new MarqueeModifier ();
    }
    return MarqueeModifier.instance;
  }

//提供方法设置该组件的描述信息，后面通过解析该描述信息得到该组件实例需要注册的属性和事件。
  setDescriptor(descriptor: ViewBaseDescriptor): MarqueeModifier {
    this.descriptor = descriptor;
    return MarqueeModifier.instance;
  }

//接口方法，ArkUI会调用该方法完成最终的MarqueeAttribute操作。
  applyNormalAttribute(instance: MarqueeAttribute): void {
    instance.width(this.descriptor.layoutMetrics.frame.size.width);
    instance.height(this.descriptor.layoutMetrics.frame.size.height);
    instance.position({ y: this.descriptor.layoutMetrics.frame.origin.y, x: this.descriptor.layoutMetrics.frame.origin.x });

if (this.descriptor.props.backgroundColor) {
      instance.backgroundColor(this.descriptor.props.backgroundColor);
    }
    /*  ......  其他需要设置的属性*/

}
}

@Builder
export function marqueeBuilder(ctx: RNOHContext, descriptor: ViewBaseDescriptor) {
  Marquee(···) {
    //通过AttributeModifier方法动态获取该组件实例化需要注册的属性和事件
    .attributeModifier(MarqueeModifier.getInstance().setDescriptor(descriptor))
  }
}
```

## 如何创建CAPI自定义组件

创建一个 Fabric 组件需要实现以下的代码：

- ComponentInstance：`ComponentInstance` 文件是该自定义组件所有的逻辑集合，也是自定义组件主要需要实现的部分，简单理解就是，一个自定义组件文件对应一个`ComponentInstance`。
- Package 文件：作用是声明创建该自定义组件的声明，指定创建 `Instance` 时会根据 `Packeage` 文件内的名称对应，从而生成对应的 `Instance` 对象。
- Props：`Props` 是 `ComponentInstance` 的 props 参数声明，具体作用是 **JS** 的参数传递，在自定义组件内部由父组件往子组件发送数据的时候也需要用到 props。
- EventEmitter：`EventEmitter` 是 `ComponentInstance` 的事件声明，主要作用是获取前端设置的事件回调，在组件内部以合适的时机触发。
- ShadowNode：`ShadowNode` 是 `ComponentInstance` 创建时所需要声明的其中一个类，将对应的 `Props`，`EventEmitter` 和 `ComponentName`（就是创建 `ComponentInstance` 的名字）组合起来。

### 1. 编写 RN 调用 Fabric 组件的代码

本节以[示例工程](附录.md)中的 `ButtonView` 为例，介绍了 Fabric CAPI 自定义组件的实现步骤。

编写 `ButtonViewNativeComponent.tsx`。注意，如果要使用 Codegen ，文件必须以 `<ModuleName>NativeComponent` 命名。在文件中使用 `codegenNativeComponent` 创建 `ButtonView` 组件，其中 `ButtonViewProps` 里声明了 `buttonText` 属性和 `onButtonClick` 事件：

```typescript
  export type OnButtonClickEventData = Readonly<{
      isButtonClick: boolean,
      type: string,
  }>;
  
  export interface ButtonViewProps extends ViewProps {
      buttonText: string,
      onButtonClick?: DirectEventHandler<OnButtonClickEventData>;
  }
  
  export default codegenNativeComponent<ButtonViewProps>(
      'CustomButtonView',
  ) as HostComponent<ButtonViewProps>;
```

和其他标准组件的创建方式一样，在组件容器内添加 `ButtonView` 标签：

```javascript
<ButtonView
  buttonText={"ButtonView: " + (buttonClick ? 'Click' : 'No Click')}
  ref={nativeRefButton}
  style= {{height: 50}}
  onButtonClick={(e) => {
    setButtonClick(e.nativeEvent.isButtonClick);
  }}
/>
```

### 2. 编写C-API 原生实现代码

#### C-API组件结构

原生端自定义组件主要包含两个部分，`ButtonViewComponentInstance.cpp` 以及 `ButtonViewNode.cpp`，其中 `ButtonViewComponentInstance` 为 **JS** 侧 `ButtonView` 组件对应的原生端实例，它继承RN框架中的组件实例模板类 `CppComponentInstance` 并转换为自己组件实现的 `ShadowNode` 类型，它应该重写基类上的一些通用方法，包括 `onChildInserted` 插入子节点、`getLocalRootArkUINode` 获取根节点以及 `onPropsChanged` 设置组件属性等，也可以实现组件的特有方法。同时它继承 `ButtonViewNode` 中声明的代理类 `ButtonViewNodeDelegate`，并重写代理类上的 `onXXX` 事件用于上报事件。
`CppComponentInstance` 是所有自定义组件 `ComponentInstance` 的父类，所有组件都继承于这个类，这个类包含了对组件进行操作的一些基础方法。

```cpp
// ButtonViewComponentInstance.h
#include "RNOH/CppComponentInstance.h"
#include "ButtonViewNode.h"
#include "ButtonViewComponentDescriptor.h"
...

namespace rnoh {
    class ButtonViewComponentInstance : public CppComponentInstance<facebook::react::ButtonViewShadowNode>, public ButtonViewNodeDelegate {
    private:
        ButtonViewNode m_buttonViewNode;
        ...
    public:
        // 重写CppComponentInstance中的通用方法
        ButtonViewComponentInstance(Context context);
        void onChildInserted(ComponentInstance::Shared const &childComponentInstance, std::size_t index) override;
        void onChildRemoved(ComponentInstance::Shared const &childComponentInstance) override;
        ButtonViewNode &getLocalRootArkUINode() override;
        void onPropsChanged(SharedConcreteProps const &props) override;
        // 处理Command命令
        void handleCommand(std::string const &commandName, folly::dynamic const &args) override;
        ...
        // 重写ButtonViewNodeDelegate的事件上报方法
        void onButtonClick() override;

...
     };
} // namespace rnoh
```

`ButtonViewNode` 对应具体的鸿蒙原生组件节点，它作为成员被组件实例持有，当设置属性或处理指令的时候，`ButtonViewComponentInstance` 会调用 `ButtonViewNode` 上实现的具体方法，以 `ButtonView` 在 **RN** 侧暴露的 `buttonText` 属性为例，在 **JS** 侧设置或更新属性的时候，框架会调用 `ButtonViewComponentInstance` 上的 `onPropsChanged` 方法，这个方法中会去调用 `ButtonViewNode` 上的 `setLabel` 方法去设置资源。

```cpp
#include "RNOH/arkui/ArkUINode.h"
#include "RNOH/arkui/NativeNodeApi.h"
...

namespace rnoh {

// 代理类的声明
    class ButtonViewNodeDelegate {
    public:
        virtual ~ButtonViewNodeDelegate() = default;
        // 组件的事件接口声明
        virtual void onButtonClick(){};
    };

class ButtonNode : public ArkUINode {
      protected:
        ButtonNodeDelegate* m_buttonNodeDelegate;

public:
        ButtonNode();
        ~ButtonNode();

// 实现Node的通用方法
        void insertChild(ArkUINode& child, std::size_t index);
        void removeChild(ArkUINode& child);
        void onNodeEvent(ArkUI_NodeEventType eventType, EventArgs& eventArgs) override;
        ButtonNode& setButtonNodeDelegate(ButtonNodeDelegate* buttonNodeDelegate);
        ···
        // 实现组件的属性设置方法
        ButtonNode& setLabel(const std::string &src);
    };

} // namespace rnoh
```

#### 属性、指令与事件

##### 属性

在 **RN** 侧设置的属性，会通过 `props` 传递到 `ComponentInstance` 中。通过 `ComponentInstance` 中的 `onPropsChanged` 可以获取到变化后的 Props。在 `onPropsChanged` 中需要做一次 diff 判断，然后就可以调用 `ComponentInstance` 保存的 `ComponentNode` 对象所实现的各种属性设置方法：

```cpp
// ButtonViewComponentInstance.cpp
void ButtonViewComponentInstance::onPropsChanged(
    SharedConcreteProps const& props) {
  CppComponentInstance::onPropsChanged(props);
  if (!m_props || props->buttonText != m_props->buttonText) {
    m_buttonNode.setLabel(props->buttonText);
  }
}
```

在 `ComponentNode` 中需要定义并实现对应属性的设置：

```cpp
// ButtonNode.cpp
ButtonNode& ButtonNode::setLabel(const std::string &src) {
  ArkUI_AttributeItem labelItem = {.string = src.c_str()};
  maybeThrow(NativeNodeApi::getInstance()->setAttribute(
      m_nodeHandle, NODE_BUTTON_LABEL, &labelItem, this));
  return *this;
}
```

##### 指令

RN 侧需要调用 `UIManager.dispatchViewManagerCommand` 向原生发送消息：

```javascript
UIManager.dispatchViewManagerCommand(
  findNodeHandle(nativeRef.current),
  'changeButtonText',
  ['changeButtonText'],
)
```

**RN** 框架内部已经封装好了指令通道，原生端只需在 instance 层重写实现 `handleCommand` 方法，根据接收指令名调用 node 层实现的对应方法即可，传入的参数以 object 对象的形式记录在 args 中：

```cpp
void ButtonViewComponentInstance::handleCommand(
    std::string const& commandName,
    folly::dynamic const& args) {
  if (commandName == "changeButtonText") {
      m_buttonNode.setLabel(args[0].asString());
    }
}
```

##### 事件

RN侧添加 `onButtonClick` 事件回调监听实现：

```javascript
<ButtonView
  onButtonClick={(e) => {
    // 原生组件调用了 RN 侧的 ButtonView 的 onButtonClick 方法
    setButtonClick(e.nativeEvent.isButtonClick);
  }}
/>
```

原生端在 instance 层重写事件代理类中的 `onButtonClick` 方法，并在该方法中调用 `ButtonViewEventEmitter.h` 的对应方法，将事件传到 **RN** 侧：

```cpp
void ButtonViewComponentInstance::onButtonClick() {
  facebook::react::ButtonViewEventEmitter::OnButtonClick m_onButtonClick;
  m_onButtonClick.isButtonClick = true;
  m_onButtonClick.type = "custom";
  m_eventEmitter->onButtonClick(m_onButtonClick);
}
```

事件的接收入口在对应的 node 类中，node 类在构造的时候需要注册组件需要监听的事件，并重写 `onNodeEvent` 方法，在该方法中调用 instance 层实现的具体事件方法：

```cpp
// 组件监听的事件枚举
static constexpr ArkUI_NodeEventType Button_NODE_EVENT_TYPES[] = {
    NODE_ON_CLICK};
···
// 在构造Node的时候注册事件监听
ButtonNode::ButtonNode()
    : ArkUINode(NativeNodeApi::getInstance()->createNode(
          ArkUI_NodeType::ARKUI_NODE_BUTTON)) {
  for (auto eventType : Button_NODE_EVENT_TYPES) {
    maybeThrow(NativeNodeApi::getInstance()->registerNodeEvent(
        m_nodeHandle, eventType, eventType, this));
  }
}
···
// 重写onNodeEvent上报事件
void ButtonNode::onNodeEvent(
    ArkUI_NodeEventType eventType,
    EventArgs& eventArgs) {
  if (eventType == ArkUI_NodeEventType::NODE_ON_CLICK) {
    if (m_buttonNodeDelegate != nullptr) {
      m_buttonNodeDelegate->onButtonClick();
    }
  }
}
```

### 3. 编写 Codegen 的 C++ 代码

1. 首先创建属性 `Props` 和事件 `Emitter` 两部分的 C++ 类，在 `Descriptor` 中进行绑定并注册 `Node` 类型。
2. 实现 `ButtonViewJSIBinder` 类的属性和事件绑定方法。
3. 将以上文件引入到 `SampleTurboModulePackage` 的对应方法实现中进行绑定。

#### Props

创建 `Props` 的 C++ 文件用于定义 `ButtonView` 的属性。
`Props.h`：

```cpp
#pragma once

#include <jsi/jsi.h>
#include <react/renderer/components/view/ViewProps.h>
#include <react/renderer/core/PropsParserContext.h>
#include <react/debug/react_native_assert.h>

namespace facebook {
namespace react {
class JSI_EXPORT ButtonViewProps final : public ViewProps {
  public:
    ButtonViewProps() = default;
    ButtonViewProps(const PropsParserContext &context, const ButtonViewProps &sourceProps, const RawProps &rawProps);

#pragma mark - Props

std::string buttonText{""};
};

} // namespace react
} // namespace facebook

```

```cpp
// Props.cpp
#include <react/renderer/components/rncore/Props.h>
#include <react/renderer/core/PropsParserContext.h>
#include <react/renderer/core/propsConversions.h>
#include "Props.h"

namespace facebook {
namespace react {
ButtonViewProps::ButtonViewProps(
    const PropsParserContext &context, 
    const ButtonViewProps &sourceProps, 
    const RawProps &rawProps): ViewProps(context, sourceProps, rawProps),

buttonText(convertRawProp(context, rawProps, "buttonText", sourceProps.buttonText, {""}))
      {}
} // namespace react
} // namespace facebook
```

#### ButtonViewEventEmitter

`ButtonViewEventEmitter.h` 中添加 `onButtonClick` 方法，并自定义了属性结构体：

```cpp
#pragma once

#include <react/renderer/components/view/ViewEventEmitter.h>
#include <jsi/jsi.h>

namespace facebook {
namespace react {

class JSI_EXPORT ButtonViewEventEmitter : public ViewEventEmitter {
  public:
    using ViewEventEmitter::ViewEventEmitter;
    struct OnButtonClick {
      bool isButtonClick;
      std::string type;
    };

void onButtonClick(OnButtonClick value) const;
};

} // namespace react
} // namespace facebook
```

`ButtonViewEventEmitter.cpp` 中实现 `onButtonClick` 事件的发送和参数绑定：

```cpp
#include "ButtonViewEventEmitter.h"

namespace facebook {
namespace react {

void ButtonViewEventEmitter::onButtonClick(OnButtonClick event) const {
    dispatchEvent("topButtonClick", [event = std::move(event)](jsi::Runtime &runtime) {
        auto payload = jsi::Object(runtime);
        payload.setProperty(runtime, "isButtonClick", event.isButtonClick);
        payload.setProperty(runtime, "type", event.type);
        return payload;
    });
}

} // namespace react
} // namespace facebook
```

#### ButtonViewComponentDescriptor.h

将 `ButtonViewProps`，`ButtonViewEventEmitter` 绑定到 `ButtonViewShadowNode` 中：

namespace facebook {
namespace react {

const char ButtonViewComponentName[] = "ButtonView";

using ButtonViewShadowNode = ConcreteViewShadowNode<ButtonViewComponentName, ButtonViewProps, ButtonViewEventEmitter>;
  using ButtonViewComponentDescriptor = ConcreteComponentDescriptor<ButtonViewShadowNode>;

} // namespace react
} // namespace facebook
```

#### ButtonViewJSIBinder

**JSIBinder** 是 **RN** 侧的属性和方法在 **JSI** 层的实现，主要调用了 `object.setProperty(rt, "buttonText", "string")` 和 `events.setProperty(rt, "topButtonClick", createDirectEvent(rt, "onButtonClick"));` 这两个方法，`events.setProperty` 中注意 `topButtonClick` 和 `onButtonClick` 的命名规则：

```cpp
#pragma once
#include "RNOHCorePackage/ComponentBinders/ViewComponentJSIBinder.h"

namespace rnoh {
    class ButtonViewJSIBinder : public ViewComponentJSIBinder {
        facebook::jsi::Object createNativeProps(facebook::jsi::Runtime &rt) override {
            auto object = ViewComponentJSIBinder::createNativeProps(rt);
            object.setProperty(rt, "buttonText", "string");
            return object;
        }
  
        facebook::jsi::Object createDirectEventTypes(facebook::jsi::Runtime &rt) override {
            facebook::jsi::Object events(rt);
  
            events.setProperty(rt, "topButtonClick", createDirectEvent(rt, "onButtonClick"));
            return events;
        }
    };
} // namespace rnoh
```

#### SampleTurboModulePackage

在 `SampleTurboModulePackage.h` 中添加自定义组件相关的方法声明：

```cpp
#include "RNOH/Package.h"

namespace rnoh {
class SampleTurboModulePackage : public Package {
    public:
        ComponentInstanceFactoryDelegate::Shared createComponentInstanceFactoryDelegate() override;
        ComponentJSIBinderByString createComponentJSIBinderByName() override;
        // ArkTS版本使用的通用方法
        ···
    };
} // namespace rnoh
```

创建 `ButtonViewPackageComponentInstanceFactoryDelegate` 对象，使用 `ButtonViewPackageComponentInstanceFactoryDelegate`、`ButtonViewJSIBinder`、`ButtonViewComponentInstance` 在 `SampleTurboModulePackage.cpp` 中完成对应方法实现：

```cpp
class ButtonViewPackageComponentInstanceFactoryDelegate : public ComponentInstanceFactoryDelegate {
    public:
        using ComponentInstanceFactoryDelegate::ComponentInstanceFactoryDelegate;
  
        ComponentInstance::Shared create(ComponentInstance::Context ctx) override {
            if (ctx.componentName == "CustomButtonView") {
                return std::make_shared<ButtonViewComponentInstance>(std::move(ctx));
            }
            return nullptr;
        }
};
···
ComponentJSIBinderByString SampleTurboModulePackage::createComponentJSIBinderByName() {
    return {
        {"MarqueeView", std::make_shared<MarqueeViewJSIBinder>(),},
        {"ButtonView", std::make_shared<ButtonViewJSIBinder>()}
    };
};

ComponentInstanceFactoryDelegate::Shared SampleTurboModulePackage::createComponentInstanceFactoryDelegate() override {
    return std::make_shared<ButtonViewPackageComponentInstanceFactoryDelegate>();
}
···
```

### 4. 在自定义组件中使用其他自定义组件

在自定义的组件中，可能并不是由一个基础组件实现的，而是由多个基础组件相互组合实现，例如自定义的 `Scroll`，内部可以持有一个 Header 组件。C-API 版本的中，有两种方式可以实现这个效果：

- 方式一：每一个组件的 `ComponentInstance` 中，都持有各个组件的 node 对象，node 中提供了修改属性发送事件等各种操作。所以开发者可以在同一个 `ComponentInstance` 中记录多个 node 对象，通过重写 `getLocalRootArkUINode()` 方法，用于获取容器节点；重写 `onChildInserted()` 方法，用于将子节点插入组件的容器类中；并在 `ComponentInstance` 中增加多个 node 之间相互处理的逻辑，即可完成开发；
- 方式二：组件都是以 `ComponentInstance` 的形式存在的，那么就可以采用父组件的 `ComponentInstance` 持有子组件的 `ComponentInstance` 的方式，达到组合成新的组件的目的。在这种方式中，需要在父组件的 `onPropsChanged`、`handleCommand` 等方法中，增加对子组件的对应方法的调用。

## 父子组件通讯

### 父组件向子组件通信

父组件创建子组件时已经持有子组件本身或对应的 `Delegate`，通过调用子组件的 `.setProps` 直接传递参数到子组件，或通过 `Delegate` 传递小规模参数。

例如：设置子组件的 `imageUrl` 地址

```cpp
mainImgComponentInstance = std::dynamic_pointer_cast<FlowMainImgComponentInstance>(componentInstance);
m_mainImgDelegate = std::dynamic_popinter_cast<rnoh::MainImgDelegate>(mainImgComponentInstance);
if (mainImgComponentInstance) {
  this->onChildInserted(mainImgComponentInstance, mainImgIndex);
  m_mainImgDelegate->setImage(imgUrl);
}
```

### 子组件向父组件通信

1. 子组件内需先定义类型和参数，该参数用于保存父组件的回调函数。

```cpp
   public:
     using onDeleteCardCallback = std::function<void(std::unordered_map<std::string, folly::dynamic> &&)>;
   ...
     std::unordered_map<std::string, folly::dynamic> m_waterFlowInfo;
     onDeleteCardCallback m_onCardDeleteChanged;
   ```

2. 子组件内定义赋值接口。

```cpp
   void FlowPicTxtCardComponentInstance::setOnCardDelete(onDeleteCardCallback callback) {
     m_onCardDeleteChanged = std::move(callback)
   }
   ```

3. 父组件调用子组件的赋值接口，给子组件参数赋值父组件的回调函数。

```cpp
   flowPicTxtCardComponentInstance->setOnCardDelete([this](
     std::map<std::string, folly::dynamic> &&expoInfo) {  });
   ```

4. 在子组件中调用回调函数，向父组件传递参数信息。

```cpp
   void FlowPicTxtCardComponentInstance::onTextClick(ArkUI_NodeEvent *event) {
     if (m_onCardDeleteChanged) {
       m_onCardDeleteChanged(std::move(m_waterFlowInfo));
     }
   }
   ```

OpenHarmony-SIG/ohos_react_native
關閉

簡介

發行版 (5)

貢獻者

語言

近期動態

OpenHarmony-SIG/ohos_react_native關閉 .gitee-modal { width: 500px !important; }

簡介

發行版 (5)

開源評估指數源自OSS-Compass評估體系，評估體系圍繞以下三個維度對項目展開評估：

貢獻者

語言

近期動態

搜索幫助

OpenHarmony-SIG/ohos_react_native
關閉