文档模板：v0.4.2

react-native-cardview

本项目基于 react-native-cardview 开发。

该第三方库仓库已迁移至 Gitcode，并支持直接从 npm 下载。新的包名为 @react-native-ohos/react-native-cardview，版本对应关系如下：

第三方库名称	第三方库版本（npm 地址）	发布信息	支持 RN 版本	Autolink	编译 API 版本	社区基线版本	源码地址
@react-native-ohos/react-native-cardview	~ 2.1.2（开发中）	Gitcode 发布	0.82.* / 0.84.*	是	API12+	2.0.3	master
@react-native-ohos/react-native-cardview	~ 2.1.0	Gitcode 发布	0.77.*	否	API12+	2.0.3	br_rnoh0.77
@react-native-ohos/react-native-cardview	~ 2.0.4	Gitcode 发布	0.72.*	是	API12+	2.0.3	br_rnoh0.72
@react-native-oh-tpl/react-native-cardview	<= 2.0.3-0.0.2@deprecated	Github 发布（已废弃）	0.72.*	否	API12+	2.0.3	sig

简介

@react-native-ohos/react-native-cardview 第三方库是一个用于 React Native 的卡片视图组件，可在 iOS 和 Android（包括 Lollipop 及之前版本）上提供一致的卡片样式展示。 它的核心作用可以概括为：

• 卡片样式：提供圆角、阴影（elevation）等 Material Design 卡片视觉效果。
• 容器组件：可包裹任意子内容，并以卡片形式进行展示。

下载安装

进入工程目录后，输入以下命令：

npm

npm install @react-native-ohos/react-native-cardview

yarn

yarn add @react-native-ohos/react-native-cardview

链接

	是否支持 AutoLink	RN 框架版本
~ 2.1.2	是	0.82 / 0.84

使用 AutoLink 的工程需按照本文档进行配置。AutoLink 框架指导文档：https://gitcode.com/CPF-RN/ohos_react_native/blob/main/docs/zh-cn/02-开发/02-开发指南/Autolinking.md

ManualLink：此步骤用于指导手动配置原生依赖项。

首先，需要使用 DevEco Studio 打开项目中的 OpenHarmony 工程 harmony。

1. 覆盖 RN SDK

为使工程依赖统一版本的 RN SDK，需要在工程根目录的 oh-package.json5 中添加 overrides 字段，并指向工程所需使用的 RN SDK 版本。可替换的版本可以是具体版本号，也可以是模糊版本，还可以是本地已存在的 HAR 包或源码目录。

关于该字段的作用，请阅读官方说明

{
  "overrides": {
    "@rnoh/react-native-openharmony": "~0.82.18" // ohpm 在线版本
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony.har" // 指向本地 har 包的路径
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony" // 指向源码路径
  }
}

2. 集成原生端代码

目前有两种接入方式：

• 通过 har 包引入；
• 直接引用源码。

方式一：通过 har 包引入（推荐）

打开 entry/oh-package.json5，添加以下依赖

"dependencies": {
    "@react-native-ohos/react-native-cardview": "file:../../node_modules/@react-native-ohos/react-native-cardview/harmony/card_view.har"
  }

点击右上角的 sync 按钮

或者在命令行终端执行：

cd entry
ohpm install

方法二：直接链接源码

3. 配置 CMakeLists 和引入 CardViewPackage

打开 entry/src/main/cpp/CMakeLists.txt，添加：

project(rnapp)
cmake_minimum_required(VERSION 3.4.1)
set(CMAKE_SKIP_BUILD_RPATH TRUE)
set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
set(NODE_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../node_modules")
+ set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
set(RNOH_CPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../react-native-harmony/harmony/cpp")
set(LOG_VERBOSITY_LEVEL 1)
set(CMAKE_ASM_FLAGS "-Wno-error=unused-command-line-argument -Qunused-arguments")
set(CMAKE_CXX_FLAGS "-fstack-protector-strong -Wl,-z,relro,-z,now,-z,noexecstack -s -fPIE -pie")
set(WITH_HITRACE_SYSTRACE 1) # for other CMakeLists.txt files to use
add_compile_definitions(WITH_HITRACE_SYSTRACE)

add_subdirectory("${RNOH_CPP_DIR}" ./rn)

# RNOH_BEGIN: manual_package_linking_1
add_subdirectory("../../../../sample_package/src/main/cpp" ./sample-package)
+ add_subdirectory("${OH_MODULES}/@react-native-ohos/react-native-cardview/src/main/cpp" ./card-view)
# RNOH_END: manual_package_linking_1

file(GLOB GENERATED_CPP_FILES "./generated/*.cpp")

add_library(rnoh_app SHARED
    ${GENERATED_CPP_FILES}
    "./PackageProvider.cpp"
    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp"
)
target_link_libraries(rnoh_app PUBLIC rnoh)

# RNOH_BEGIN: manual_package_linking_2
target_link_libraries(rnoh_app PUBLIC rnoh_sample_package)
+ target_link_libraries(rnoh_app PUBLIC rnoh_card_view)
# RNOH_END: manual_package_linking_2

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "RNOH/PackageProvider.h"
#include "generated/RNOHGeneratedPackage.h"
#include "SamplePackage.h"
+ #include "CardViewPackage.h"

using namespace rnoh;

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
        std::make_shared<RNOHGeneratedPackage>(ctx),
        std::make_shared<SamplePackage>(ctx),
+       std::make_shared<CardViewPackage>(ctx),
    };
}

4. 运行

点击右上角的 sync 按钮

或者在命令行终端执行：

cd entry
ohpm install

随后编译、运行即可。

约束与限制

兼容性

本文档内容基于以下版本验证通过：

1. RNOH: 0.82.1; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;
2. RNOH: 0.84.1; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;

使用示例

以下代码展示了该库的基本使用场景：

import React, { Component } from 'react';
import { Text } from 'react-native';
import CardView from 'react-native-cardview';

export default class Example extends Component {
  render() {
    return (
      <CardView
        cardElevation={3}
        cardMaxElevation={3}
        cornerRadius={5}
        style={{
          height: 60,
          justifyContent: 'center',
          alignItems: 'center',
          margin: 20,
          backgroundColor: '#ffffff'
        }}
      >
        <Text style={{ color: '#000000', fontSize: 14 }}>CardView</Text>
      </CardView>
    );
  }
}

使用说明

基础卡片

CardView 可作为容器包裹任意内容，默认以卡片样式展示：

<CardView style={{ margin: 20 }}>
  <Text>基础卡片</Text>
</CardView>

设置圆角与阴影

通过 cornerRadius、cardElevation、cardMaxElevation 属性，可控制卡片的圆角和阴影效果：

<CardView
  cardElevation={3}
  cardMaxElevation={3}
  cornerRadius={5}
  style={{ height: 60, margin: 20 }}
>
  <Text>带圆角与阴影的卡片</Text>
</CardView>

接口说明

组件

名称	参数类型	必填	平台	OpenHarmony 平台支持	描述
CardView	ICardViewProps	Yes	iOS/Android	Yes	卡片视图组件，用于以卡片样式展示内容

属性

CardView 组件支持 React Native View 组件的全部 Props。

ICardViewProps

名称	参数类型	默认值	必填	平台	OpenHarmony 平台支持	描述
cornerRadius	number	0.0	No	iOS/Android	Yes	用于设置卡片圆角半径的属性。
cardElevation	number	0.0	No	iOS/Android	Yes	用于设置卡片阴影高度（elevation）的属性，可提高卡片投影效果；elevation 值过高可能带来性能影响。
cardMaxElevation	number	0.0	No	Android	Yes	用于在 Android Lollipop 之前设备上支持阴影的属性。
useCompatPadding	boolean	false	No	Android	No	CardView 在 Lollipop 之前的平台上会增加额外的内边距以绘制阴影。
cornerOverlap	boolean	true	No	Android	No	在 Lollipop 之前的平台上，CardView 不会裁剪卡片圆角边界，而是为内容添加内边距，避免内容与圆角重叠。

遗留问题

• 同时使用 cornerRadius 和 cardElevation 属性时，会导致阴影不显示：#issues14

其他

无

目录结构

/rntpc_react-native-cardview  # 项目根目录
├── buildEnv.sh                # 构建环境脚本
├── harmony                    # 鸿蒙适配代码
│   ├── card_view.har          # har 包
│   └── card_view              # 鸿蒙适配核心代码
│       ├── BuildProfile.ets   # 构建时自动生成的配置文件
│       ├── build-profile.json5 # 模块构建配置
│       ├── hvigorfile.ts       # 构建脚本
│       ├── index.ets           # 鸿蒙适配代码入口
│       ├── oh-package.json5    # 模块依赖配置
│       └── src/main
│           ├── cpp             # C++ 侧组件实现（CardViewComponentInstance、CardViewPackage、NativeNodeApi 等）
│           ├── ets             # ArkTS 侧代码（RNCardView.ets）
│           ├── module.json5    # 模块配置文件
│           └── resources       # 资源文件
├── example                    # 示例工程
├── index.js                   # JS 入口文件
├── jest                       # 单元测试
│   ├── CardView.test.js       # CardView 组件测试
│   ├── index.test.js          # 入口文件测试
│   └── __mocks__
│       └── react-native.js    # react-native 模块 mock
├── jest.config.js             # Jest 测试配置
├── libs                       # 鸿蒙平台 JS 实现脚本
│   └── CardView.harmony.js
├── package.json               # npm 包配置
├── CHANGELOG.md               # 版本变更记录
├── COMMITTERS.md              # 贡献者名单
├── LICENSE
├── OAT.xml
├── README.OpenSource
├── README.md                  # 中文安装使用方法
└── README_EN.md               # 英文安装使用方法

贡献代码

在使用过程中发现任何问题，都可以提交 Issue，当然，也非常欢迎提交 PR 。

开源协议

本项目基于 The MIT License (MIT) ，请自由使用并参与开源。