跳至主要内容

Android 原生 UI 组件

信息

原生模块和原生组件是我们稳定技术,由旧架构使用。当新架构稳定后,它们将被弃用。新架构使用 Turbo Native ModuleFabric Native Components 来实现类似的结果。

有大量的原生 UI 小部件可供在最新的应用程序中使用 - 其中一些是平台的一部分,另一些作为第三方库提供,还有一些可能在您自己的作品集中使用。React Native 已经包装了几个最关键的平台组件,例如 ScrollViewTextInput,但并非所有组件,当然也不包括您可能为以前的应用程序自己编写的组件。幸运的是,我们可以将这些现有组件包装起来,以便与您的 React Native 应用程序无缝集成。

与原生模块指南类似,本指南也属于更高级的指南,假设您对 Android SDK 编程有一定的了解。本指南将向您展示如何构建原生 UI 组件,并引导您完成对 React Native 核心库中现有 ImageView 组件子集的实现。

ImageView 示例

在本示例中,我们将逐步介绍在 JavaScript 中使用 ImageViews 的实现要求。

原生视图通过扩展 ViewManager 或更常见的 SimpleViewManager 来创建和操作。在本例中,SimpleViewManager 很方便,因为它应用了常见的属性,例如背景颜色、不透明度和 Flexbox 布局。

这些子类本质上是单例 - 桥接器只创建每个子类的单个实例。它们将原生视图发送到 NativeViewHierarchyManager,后者将委托给它们来设置和更新视图的属性,具体取决于需要。ViewManagers 通常也是视图的委托,通过桥接器将事件发送回 JavaScript。

要发送视图

  1. 创建 ViewManager 子类。
  2. 实现 createViewInstance 方法
  3. 使用 @ReactProp(或 @ReactPropGroup)注释公开视图属性设置器
  4. 在应用程序包的 createViewManagers 中注册管理器。
  5. 实现 JavaScript 模块

1. 创建 ViewManager 子类

在本示例中,我们创建了视图管理器类 ReactImageManager,它扩展了类型为 ReactImageViewSimpleViewManagerReactImageView 是管理器管理的对象类型,这将是自定义原生视图。getName 返回的名称用于从 JavaScript 引用原生视图类型。

public class ReactImageManager extends SimpleViewManager<ReactImageView> {

public static final String REACT_CLASS = "RCTImageView";
ReactApplicationContext mCallerContext;

public ReactImageManager(ReactApplicationContext reactContext) {
mCallerContext = reactContext;
}

@Override
public String getName() {
return REACT_CLASS;
}
}

2. 实现方法 createViewInstance

视图是在 createViewInstance 方法中创建的,视图应在其默认状态下初始化自身,任何属性都将通过后续调用 updateView 来设置。

  @Override
public ReactImageView createViewInstance(ThemedReactContext context) {
return new ReactImageView(context, Fresco.newDraweeControllerBuilder(), null, mCallerContext);
}

3. 使用 @ReactProp(或 @ReactPropGroup)注释公开视图属性设置器

需要在 JavaScript 中反映的属性需要暴露为带有 `@ReactProp`(或 `@ReactPropGroup`)注解的 setter 方法。setter 方法应该以要更新的视图(当前视图类型)作为第一个参数,属性值作为第二个参数。setter 应该公开且不返回值(即 Java 中的返回值类型应为 `void`,Kotlin 中的返回值类型应为 `Unit`)。发送到 JS 的属性类型会根据 setter 的值参数类型自动确定。目前支持以下类型的值(在 Java 中):`boolean`、`int`、`float`、`double`、`String`、`Boolean`、`Integer`、`ReadableArray`、`ReadableMap`。Kotlin 中的对应类型为 `Boolean`、`Int`、`Float`、`Double`、`String`、`ReadableArray`、`ReadableMap`。

注解 `@ReactProp` 只有一个必填参数 `name`,类型为 `String`。分配给与 setter 方法关联的 `@ReactProp` 注解的名称用于在 JS 端引用属性。

除了 `name` 之外,`@ReactProp` 注解还可以接受以下可选参数:`defaultBoolean`、`defaultInt`、`defaultFloat`。这些参数应该具有相应的类型(分别为 Java 中的 `boolean`、`int`、`float` 和 Kotlin 中的 `Boolean`、`Int`、`Float`),并且提供的值将在属性从组件中移除时传递给 setter 方法。请注意,"默认"值仅提供给基本类型,如果 setter 是某种复杂类型,则在相应的属性被移除时,将提供 `null` 作为默认值。

使用 `@ReactPropGroup` 注解的方法的 setter 声明要求与 `@ReactProp` 不同,请参阅 `@ReactPropGroup` 注解类文档以获取更多信息。**重要!** 在 ReactJS 中更新属性值将导致 setter 方法调用。请注意,我们可以更新组件的一种方式是移除之前设置的属性。在这种情况下,setter 方法也会被调用以通知视图管理器属性已更改。在这种情况下,将提供 "默认" 值(对于基本类型,可以使用 `@ReactProp` 注解的 `defaultBoolean`、`defaultFloat` 等参数指定 "默认" 值,对于复杂类型,setter 将被调用,其值为 `null`)。

  @ReactProp(name = "src")
public void setSrc(ReactImageView view, @Nullable ReadableArray sources) {
view.setSource(sources);
}

@ReactProp(name = "borderRadius", defaultFloat = 0f)
public void setBorderRadius(ReactImageView view, float borderRadius) {
view.setBorderRadius(borderRadius);
}

@ReactProp(name = ViewProps.RESIZE_MODE)
public void setResizeMode(ReactImageView view, @Nullable String resizeMode) {
view.setScaleType(ImageResizeMode.toScaleType(resizeMode));
}

4. 注册 `ViewManager`

最后一步是将 ViewManager 注册到应用程序,这与原生模块类似,通过应用程序包成员函数 createViewManagers 完成。

  @Override
public List<ViewManager> createViewManagers(
ReactApplicationContext reactContext) {
return Arrays.<ViewManager>asList(
new ReactImageManager(reactContext)
);
}

5. 实现 JavaScript 模块

最后一步是创建 JavaScript 模块,该模块定义了 Java/Kotlin 和 JavaScript 之间的接口层,供新视图的用户使用。建议您在此模块中记录组件接口(例如,使用 TypeScript、Flow 或普通注释)。

ImageView.tsx
import {requireNativeComponent} from 'react-native';

/**
* Composes `View`.
*
* - src: string
* - borderRadius: number
* - resizeMode: 'cover' | 'contain' | 'stretch'
*/
module.exports = requireNativeComponent('RCTImageView');

requireNativeComponent 函数接受原生视图的名称。请注意,如果您的组件需要执行更复杂的操作(例如,自定义事件处理),您应该将原生组件包装在另一个 React 组件中。下面的 MyCustomView 示例对此进行了说明。

事件

现在我们知道如何公开原生视图组件,我们可以从 JS 自由控制这些组件,但如何处理来自用户的事件,例如捏缩放或平移?当发生原生事件时,原生代码应该向视图的 JavaScript 表示发出事件,这两个视图通过从 getId() 方法返回的值进行链接。

class MyCustomView extends View {
...
public void onReceiveNativeEvent() {
WritableMap event = Arguments.createMap();
event.putString("message", "MyMessage");
ReactContext reactContext = (ReactContext)getContext();
reactContext
.getJSModule(RCTEventEmitter.class)
.receiveEvent(getId(), "topChange", event);
}
}

要将 topChange 事件名称映射到 JavaScript 中的 onChange 回调属性,请通过覆盖 ViewManager 中的 getExportedCustomBubblingEventTypeConstants 方法来注册它。

public class ReactImageManager extends SimpleViewManager<MyCustomView> {
...
public Map getExportedCustomBubblingEventTypeConstants() {
return MapBuilder.builder().put(
"topChange",
MapBuilder.of(
"phasedRegistrationNames",
MapBuilder.of("bubbled", "onChange")
)
).build();
}
}

此回调使用原始事件调用,我们通常在包装组件中处理它以创建更简单的 API。

MyCustomView.tsx
class MyCustomView extends React.Component {
constructor(props) {
super(props);
this._onChange = this._onChange.bind(this);
}
_onChange(event) {
if (!this.props.onChangeMessage) {
return;
}
this.props.onChangeMessage(event.nativeEvent.message);
}
render() {
return <RCTMyCustomView {...this.props} onChange={this._onChange} />;
}
}
MyCustomView.propTypes = {
/**
* Callback that is called continuously when the user is dragging the map.
*/
onChangeMessage: PropTypes.func,
...
};

const RCTMyCustomView = requireNativeComponent(`RCTMyCustomView`);

与 Android Fragment 集成的示例

为了将现有的原生 UI 元素集成到您的 React Native 应用程序中,您可能需要使用 Android Fragment,以便比从 ViewManager 返回 View 更精细地控制您的原生组件。如果您想添加与视图相关的自定义逻辑,借助生命周期方法(例如 onViewCreatedonPauseonResume),您将需要这样做。以下步骤将向您展示如何操作。

1. 创建一个示例自定义视图

首先,让我们创建一个扩展 FrameLayoutCustomView 类(此视图的内容可以是您想要渲染的任何视图)。

CustomView.java
// replace with your package
package com.mypackage;

import android.content.Context;
import android.graphics.Color;
import android.widget.FrameLayout;
import android.widget.ImageView;
import android.widget.TextView;

import androidx.annotation.NonNull;

public class CustomView extends FrameLayout {
public CustomView(@NonNull Context context) {
super(context);
// set padding and background color
this.setPadding(16,16,16,16);
this.setBackgroundColor(Color.parseColor("#5FD3F3"));

// add default text view
TextView text = new TextView(context);
text.setText("Welcome to Android Fragments with React Native.");
this.addView(text);
}
}

2. 创建一个 Fragment

MyFragment.java
// replace with your package
package com.mypackage;

import android.os.Bundle;
import android.view.LayoutInflater;
import android.view.View;
import android.view.ViewGroup;
import androidx.fragment.app.Fragment;

// replace with your view's import
import com.mypackage.CustomView;

public class MyFragment extends Fragment {
CustomView customView;

@Override
public View onCreateView(LayoutInflater inflater, ViewGroup parent, Bundle savedInstanceState) {
super.onCreateView(inflater, parent, savedInstanceState);
customView = new CustomView(this.getContext());
return customView; // this CustomView could be any view that you want to render
}

@Override
public void onViewCreated(View view, Bundle savedInstanceState) {
super.onViewCreated(view, savedInstanceState);
// do any logic that should happen in an `onCreate` method, e.g:
// customView.onCreate(savedInstanceState);
}

@Override
public void onPause() {
super.onPause();
// do any logic that should happen in an `onPause` method
// e.g.: customView.onPause();
}

@Override
public void onResume() {
super.onResume();
// do any logic that should happen in an `onResume` method
// e.g.: customView.onResume();
}

@Override
public void onDestroy() {
super.onDestroy();
// do any logic that should happen in an `onDestroy` method
// e.g.: customView.onDestroy();
}
}

3. 创建 ViewManager 子类

MyViewManager.java
// replace with your package
package com.mypackage;

import android.view.Choreographer;
import android.view.View;
import android.view.ViewGroup;
import android.widget.FrameLayout;

import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.fragment.app.FragmentActivity;

import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.bridge.ReadableArray;
import com.facebook.react.common.MapBuilder;
import com.facebook.react.uimanager.annotations.ReactProp;
import com.facebook.react.uimanager.annotations.ReactPropGroup;
import com.facebook.react.uimanager.ViewGroupManager;
import com.facebook.react.uimanager.ThemedReactContext;

import java.util.Map;

public class MyViewManager extends ViewGroupManager<FrameLayout> {

public static final String REACT_CLASS = "MyViewManager";
public final int COMMAND_CREATE = 1;
private int propWidth;
private int propHeight;

ReactApplicationContext reactContext;

public MyViewManager(ReactApplicationContext reactContext) {
this.reactContext = reactContext;
}

@Override
public String getName() {
return REACT_CLASS;
}

/**
* Return a FrameLayout which will later hold the Fragment
*/
@Override
public FrameLayout createViewInstance(ThemedReactContext reactContext) {
return new FrameLayout(reactContext);
}

/**
* Map the "create" command to an integer
*/
@Nullable
@Override
public Map<String, Integer> getCommandsMap() {
return MapBuilder.of("create", COMMAND_CREATE);
}

/**
* Handle "create" command (called from JS) and call createFragment method
*/
@Override
public void receiveCommand(
@NonNull FrameLayout root,
String commandId,
@Nullable ReadableArray args
) {
super.receiveCommand(root, commandId, args);
int reactNativeViewId = args.getInt(0);
int commandIdInt = Integer.parseInt(commandId);

switch (commandIdInt) {
case COMMAND_CREATE:
createFragment(root, reactNativeViewId);
break;
default: {}
}
}

@ReactPropGroup(names = {"width", "height"}, customType = "Style")
public void setStyle(FrameLayout view, int index, Integer value) {
if (index == 0) {
propWidth = value;
}

if (index == 1) {
propHeight = value;
}
}

/**
* Replace your React Native view with a custom fragment
*/
public void createFragment(FrameLayout root, int reactNativeViewId) {
ViewGroup parentView = (ViewGroup) root.findViewById(reactNativeViewId);
setupLayout(parentView);

final MyFragment myFragment = new MyFragment();
FragmentActivity activity = (FragmentActivity) reactContext.getCurrentActivity();
activity.getSupportFragmentManager()
.beginTransaction()
.replace(reactNativeViewId, myFragment, String.valueOf(reactNativeViewId))
.commit();
}

public void setupLayout(View view) {
Choreographer.getInstance().postFrameCallback(new Choreographer.FrameCallback() {
@Override
public void doFrame(long frameTimeNanos) {
manuallyLayoutChildren(view);
view.getViewTreeObserver().dispatchOnGlobalLayout();
Choreographer.getInstance().postFrameCallback(this);
}
});
}

/**
* Layout all children properly
*/
public void manuallyLayoutChildren(View view) {
// propWidth and propHeight coming from react-native props
int width = propWidth;
int height = propHeight;

view.measure(
View.MeasureSpec.makeMeasureSpec(width, View.MeasureSpec.EXACTLY),
View.MeasureSpec.makeMeasureSpec(height, View.MeasureSpec.EXACTLY));

view.layout(0, 0, width, height);
}
}

4. 注册 ViewManager

MyPackage.java
// replace with your package
package com.mypackage;

import com.facebook.react.ReactPackage;
import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.uimanager.ViewManager;

import java.util.Arrays;
import java.util.List;

public class MyPackage implements ReactPackage {

@Override
public List<ViewManager> createViewManagers(ReactApplicationContext reactContext) {
return Arrays.<ViewManager>asList(
new MyViewManager(reactContext)
);
}

}

5. 注册 Package

MainApplication.java
    @Override
protected List<ReactPackage> getPackages() {
List<ReactPackage> packages = new PackageList(this).getPackages();
...
packages.add(new MyPackage());
return packages;
}

6. 实现 JavaScript 模块

I. 从自定义视图管理器开始

MyViewManager.tsx
import {requireNativeComponent} from 'react-native';

export const MyViewManager =
requireNativeComponent('MyViewManager');

II. 然后实现调用 create 方法的自定义视图

MyView.tsx
import React, {useEffect, useRef} from 'react';
import {
PixelRatio,
UIManager,
findNodeHandle,
} from 'react-native';

import {MyViewManager} from './my-view-manager';

const createFragment = viewId =>
UIManager.dispatchViewManagerCommand(
viewId,
// we are calling the 'create' command
UIManager.MyViewManager.Commands.create.toString(),
[viewId],
);

export const MyView = () => {
const ref = useRef(null);

useEffect(() => {
const viewId = findNodeHandle(ref.current);
createFragment(viewId);
}, []);

return (
<MyViewManager
style={{
// converts dpi to px, provide desired height
height: PixelRatio.getPixelSizeForLayoutSize(200),
// converts dpi to px, provide desired width
width: PixelRatio.getPixelSizeForLayoutSize(200),
}}
ref={ref}
/>
);
};

如果您想使用 @ReactProp(或 @ReactPropGroup)注解公开属性设置器,请参阅上面的 ImageView 示例