已合并
docs: improve OpenHarmony documentation accuracy #40
sunkaiyang创建于 14 天前
docs: improve OpenHarmony documentation accuracy #40
已合并
共 4 个文件变更+147-163
| @@ -51,7 +51,7 @@ yarn add @react-native-ohos/react-native-view-shot | |||
| 51 | 51 | ||
| 52 | 首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 harmony。 | 52 | 首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 harmony。 |
| 53 | 53 | ||
| 54 | -### 1.在工程根目录的 `oh-package.json5` 添加 overrides 字段 | 54 | +### 1. Overrides RN SDK |
| 55 | 55 | ||
| 56 | ```json | 56 | ```json |
| 57 | { | 57 | { |
| @@ -63,7 +63,7 @@ yarn add @react-native-ohos/react-native-view-shot | |||
| 63 | } | 63 | } |
| 64 | ``` | 64 | ``` |
| 65 | 65 | ||
| 66 | -### 引入原生端代码 | 66 | +### 2. 引入原生端代码 |
| 67 | 67 | ||
| 68 | 目前有两种方法： | 68 | 目前有两种方法： |
| 69 | 69 | ||
| @@ -97,7 +97,7 @@ ohpm install | |||
| 97 | 97 | ||
| 98 | > [!TIP] 如需使用直接链接源码，请参考[直接链接源码说明](https://gitcode.com/CPF-RN/usage-docs/blob/master/zh-cn/link-source-code.md) | 98 | > [!TIP] 如需使用直接链接源码，请参考[直接链接源码说明](https://gitcode.com/CPF-RN/usage-docs/blob/master/zh-cn/link-source-code.md) |
| 99 | 99 | ||
| 100 | -### 配置 CMakeLists 和引入 ViewShotPackage | 100 | +### 3. 配置 CMakeLists 和引入 ViewShotPackage |
| 101 | 101 | ||
| 102 | 打开 `entry/src/main/cpp/CMakeLists.txt`，添加： | 102 | 打开 `entry/src/main/cpp/CMakeLists.txt`，添加： |
| 103 | 103 | ||
| @@ -145,9 +145,9 @@ std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Cont | |||
| 145 | } | 145 | } |
| 146 | ``` | 146 | ``` |
| 147 | 147 | ||
| 148 | -### 在 ArkTs 侧引入 ViewShotPackage | 148 | +### 4. 在 ArkTs 侧引入 ViewShotPackage |
| 149 | 149 | ||
| 150 | -打开 `entry/src/main/ets/RNPackagesFactory.ts`，添加： | 150 | +打开 `entry/src/main/ets/RNPackagesFactory.ets`，添加： |
| 151 | 151 | ||
| 152 | ```diff | 152 | ```diff |
| 153 | ... | 153 | ... |
| @@ -184,6 +184,14 @@ ohpm install | |||
| 184 | 184 | ||
| 185 | 1. RNOH: 0.72.96; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112; | 185 | 1. RNOH: 0.72.96; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112; |
| 186 | 186 | ||
| 187 | +### 权限要求 | ||
| 188 | + | ||
| 189 | +无需额外权限。 | ||
| 190 | + | ||
| 191 | +### 编译运行API要求 | ||
| 192 | + | ||
| 193 | +API 12 及以上。 | ||
| 194 | + | ||
| 187 | 195 | ||
| 188 | ## 使用示例 | 196 | ## 使用示例 |
| 189 | 197 | ||
| @@ -197,7 +205,7 @@ import { View, Text, Button } from "react-native"; | |||
| 197 | import ViewShot, { captureRef, captureScreen } from "react-native-view-shot"; | 205 | import ViewShot, { captureRef, captureScreen } from "react-native-view-shot"; |
| 198 | 206 | ||
| 199 | export function ViewShotDemo() { | 207 | export function ViewShotDemo() { |
| 200 | - const view = React.useRef < View > (null); | 208 | + const view = React.useRef(null); |
| 201 | const ref = React.useRef(null); | 209 | const ref = React.useRef(null); |
| 202 | const onCapture = (res) => { | 210 | const onCapture = (res) => { |
| 203 | console.info("onCapture callback"); | 211 | console.info("onCapture callback"); |
| @@ -243,8 +251,8 @@ export function ViewShotDemo() { | |||
| 243 | <Button | 251 | <Button |
| 244 | title="ViewShot capture" | 252 | title="ViewShot capture" |
| 245 | onPress={() => { | 253 | onPress={() => { |
| 246 | - captureRef(ref).then((res) => { | 254 | + ref.current?.capture().then((res) => { |
| 247 | - console.info(`captureRef: ${res}`); | 255 | + console.info(`ViewShot.capture: ${res}`); |
| 248 | }); | 256 | }); |
| 249 | }} | 257 | }} |
| 250 | /> | 258 | /> |
| @@ -267,25 +275,28 @@ export function ViewShotDemo() { | |||
| 267 | 275 | ||
| 268 | > [!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。 | 276 | > [!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。 |
| 269 | 277 | ||
| 270 | -| Name | Description | Type | Required | Platform | HarmonyOS Support | | 278 | +| 名称 | 参数类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 | 描述 | |
| 271 | -| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | -------- | ------------ | ----------------- | | 279 | +| ---- | -------- | ------ | ---- | ---- | ----------------- | ---- | |
| 272 | -| captureMode | 未定义时（默认），截图不会自动进行，需要使用 ref 并手动调用 `capture()`。<br>`"mount"`：在组件挂载时自动截图一次。（需注意图片加载不会被等待，如需等待图片加载完成，建议使用 `"none"` 并在 Image#onLoad 后调用 viewShotRef.capture()。）<br>`"continuous"` 实验性功能，会持续不断地截图。仅适用于非常特殊的场景。<br> `"update"` 实验性功能，每次 React 重绘（on did update）时都会截图。仅适用于非常特殊的场景。 | ( 'mount' \| 'continuous' \| 'update') | no | Android, iOS | yes | | 280 | +| captureMode | `"mount"` \| `"continuous"` \| `"update"` | `undefined` | No | Android, iOS | Yes | 未定义时截图不会自动进行，需要使用 ref 并手动调用 `capture()`。<br>`"mount"`：组件挂载时自动截图一次；HarmonyOS 会在组件挂载后延迟约 100 ms 执行截图。图片加载不会被等待，如需等待图片加载完成，请不要设置 `captureMode`，并在 `Image#onLoad` 后调用组件 ref 的 `current.capture()`。<br>`"continuous"`：实验性功能，会持续不断地截图，仅适用于非常特殊的场景。<br>`"update"`：实验性功能，每次 React 重绘时截图，仅适用于非常特殊的场景。 | |
| 273 | -| onCapture | 当定义了 `captureMode` 时，截图成功后会调用此回调函数，并传入截图结果。 | function | no | Android, iOS | yes | | 281 | +| onCapture | `(uri: string) => void` | None | No | Android, iOS | Yes | 定义 `captureMode` 时，截图成功后调用并传入截图结果。 | |
| 274 | -| onCaptureFailure | 当定义了 `captureMode` 时，截图失败时会调用此回调函数。 | function | no | Android, iOS | yes | | 282 | +| onCaptureFailure | `(error: Error) => void` | None | No | Android, iOS | Yes | 定义 `captureMode` 时，截图失败后调用并传入错误对象。 | |
| 275 | -| options | 截图配置项。 | object | no | Android, iOS | partially | | 283 | +| options | `CaptureOptions` | None | No | Android, iOS | Partially | 截图配置项。 | |
| 276 | -| children | 实际需要被栅格化（截图）的内容。 | ReactNode | no | Android, iOS | yes | | 284 | +| children | `ReactNode` | None | No | Android, iOS | Yes | 实际需要被栅格化（截图）的内容。 | |
| 285 | +| onLayout | `(event: LayoutChangeEvent) => void` | None | No | Android, iOS | Yes | 组件挂载或布局变化时调用，并接收布局事件。 | | ||
| 286 | +| style | `StyleProp<ViewStyle>` | None | No | Android, iOS | Yes | 应用于 ViewShot 容器的视图样式。 | | ||
| 277 | 287 | ||
| 278 | ### options属性详情 | 288 | ### options属性详情 |
| 279 | 289 | ||
| 280 | -| Name | Description | Type | Required | Platform | HarmonyOS Support | | 290 | +| 名称 | 参数类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 | 描述 | |
| 281 | -| ------------------------ | ------------------------------------------------------------ | ------------------------------------ | -------- | ------------ | ----------------- | | 291 | +| ---- | -------- | ------ | ---- | ---- | ----------------- | ---- | |
| 282 | -| fileName | 文件名，长度必须至少为 3 个字符。 | string | no | Android, iOS | yes | | 292 | +| fileName | `string` | None | No | Android | Yes | 文件名，长度必须至少为 3 个字符。 | |
| 283 | -| width / height | 最终图片的宽度和高度（会根据 View 的边界进行缩放。如果需要保持原始像素大小，请勿提供此参数）。 | number | no | Android, iOS | yes | | 293 | +| width / height | `number` | None | No | Android, iOS | Yes | 最终图片的宽度和高度（会根据 View 的边界进行缩放。如果需要保持原始像素大小，请勿提供此参数）。 | |
| 284 | -| quality | 图片质量，范围为 0.0 - 1.0（默认值）。（仅适用于有损压缩格式，如 jpg） | number | no | Android, iOS | yes | | 294 | +| quality | `number` | `1` | No | Android, iOS | Yes | 图片质量，范围为 0.0 - 1.0。（仅适用于 jpg 等有损压缩格式。） | |
| 285 | -| format | 图片格式，可选 png 或 jpg，默认为 png。 | string | no | Android, iOS | yes | | 295 | +| format | `"jpg"` \| `"png"` \| `"webm"` \| `"raw"` | `"png"` | No | Android, iOS | Partially | 图片格式，可选 png、jpg、webm 或 raw，默认为 png。HarmonyOS 仅支持 png 和 jpg；webm 和 raw 仅 Android 支持。 | |
| 286 | -| result | 保存截图的方式，可选值如下：<br/>"tmpfile"（默认）：保存到临时文件（仅在应用运行期间有效）。<br/>"base64"：编码为 base64 并返回原始字符串。建议仅用于小图片，因为可能会导致卡顿（字符串会通过桥接传输）。注意：这不是 data uri，如需 data uri 请使用 data-uri。<br/>"data-uri"：与 base64 相同，但会包含 Data URI scheme 请求头。 <br/>'sandbox-file'（仅 OpenHarmony 支持）：保存到临时文件（仅在应用运行期间有效）。| ( 'tmpfile' \|'base64' \|'data-uri' \|'sandbox-file') | no | Android, iOS | yes | | 296 | +| result | `"tmpfile"` \| `"base64"` \| `"data-uri"` \| `"zip-base64"` \| `"sandbox-file"` | `"tmpfile"` | No | Android, iOS | Partially | 保存截图的方式，可选值如下：<br/>`"tmpfile"`（默认）：保存到应用临时目录并返回文件路径，仅在应用运行期间有效。<br/>`"base64"`：编码为 base64 并返回原始字符串。建议仅用于小图片，因为字符串传输可能导致卡顿。注意：这不是 data URI，如需 data URI 请使用 `data-uri`。<br/>`"data-uri"`：与 base64 相同，但包含 Data URI scheme 请求头。<br/>`"zip-base64"`：使用 Zip/Deflate 算法压缩数据，再转换为 base64；HarmonyOS 不支持（仅 Android 支持）。<br/>`"sandbox-file"`：保存到应用缓存目录 `cacheDir` 并返回 `file://` URI，仅 HarmonyOS 支持。 | |
| 287 | -| snapshotContentContainer | 如果为 true 且 view 为 ScrollView，则会使用 "content container" 的高度，而非容器本身的高度。 | boolean | no | Android, iOS | no | | 297 | +| snapshotContentContainer | `boolean` | `false` | No | Android, iOS | No | 如果为 true 且 view 为 ScrollView，则会使用 "content container" 的高度，而非容器本身的高度。 | |
| 288 | -| useRenderInContext | 修改 iOS 截图策略，使用 renderInContext 方法替代 drawViewHierarchyInRect，可能适用于某些特定场景。 | boolean | no | Android, iOS | no | | 298 | +| useRenderInContext | `boolean` | None | No | iOS | No | 修改 iOS 截图策略，使用 renderInContext 方法替代 drawViewHierarchyInRect，可能适用于某些特定场景。 | |
| 299 | +| handleGLSurfaceViewOnAndroid | `boolean` | `false` | No | Android | No | 如果设置为 true，且视图是 SurfaceView 或视图树中包含 SurfaceView，则捕获其内容。 | | ||
| 289 | 300 | ||
| 290 | ## API | 301 | ## API |
| 291 | 302 | ||
| @@ -293,11 +304,12 @@ export function ViewShotDemo() { | |||
| 293 | 304 | ||
| 294 | > [!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。 | 305 | > [!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。 |
| 295 | 306 | ||
| 296 | -| Name | Description | Type | Required | Platform | HarmonyOS Support | | 307 | +| 名称 | 类型 | 参数类型 | 返回值 | 必填 | 平台 | HarmonyOS平台支持 | 描述 | |
| 297 | -| ---------------- | ----------- | -------- | -------- | ------------ | ----------------- | | 308 | +| --- | --- | --- | --- | --- | --- | --- | --- | |
| 298 | -| `captureRef` | 组件截图 | function | no | Android, iOS | yes | | 309 | +| `captureRef` | function | `view: number \| ReactInstance \| RefObject<T>; optionsObject?: CaptureOptions` | `Promise<string>` | `view`: yes; `optionsObject`: no | Android, iOS | yes | 捕获指定组件并返回截图结果。 | |
| 299 | -| `captureScreen` | 屏幕截图 | function | no | Android, iOS | yes | | 310 | +| `captureScreen` | function | `optionsObject?: CaptureOptions` | `Promise<string>` | no | Android, iOS | yes | 捕获当前屏幕并返回截图结果。 | |
| 300 | -| `releaseCapture` | 资源释放 | function | no | Android, iOS | yes | | 311 | +| `releaseCapture` | function | `uri: string` | `void` | yes | Android, iOS | yes | 释放截图产生的临时文件。 | |
| 312 | +| `ViewShot.capture()` | function | / | `Promise<string>` | / | Android, iOS | yes | ViewShot 组件实例的命令式截图方法，通过组件 ref 的 `current.capture()` 调用，并使用组件 `options` 属性中的截图配置；未设置 `captureMode` 时可用它手动触发截图。 | | ||
| 301 | 313 | ||
| 302 | ## 遗留问题 | 314 | ## 遗留问题 |
| 303 | - [ ] 被截图组件需要设置背景色，否则截图效果全黑 [issues#3](https://github.com/react-native-oh-library/react-native-view-shot/issues/3)。 | 315 | - [ ] 被截图组件需要设置背景色，否则截图效果全黑 [issues#3](https://github.com/react-native-oh-library/react-native-view-shot/issues/3)。 |
| @@ -307,52 +319,28 @@ export function ViewShotDemo() { | |||
| 307 | 无 | 319 | 无 |
| 308 | 320 | ||
| 309 | ## 目录结构 | 321 | ## 目录结构 |
| 310 | -```` | 322 | +````text |
| 311 | -/rntpc_react-native-view-shot # 项目根目录 | 323 | +rntpc_react-native-view-shot/ |
| 312 | -│ LICENSE | 324 | +├─src |
| 313 | -│ OAT.xml | 325 | +│ │ index.js # JavaScript 入口和 ViewShot 组件 |
| 314 | -│ package.json | 326 | +│ │ index.d.ts # TypeScript 类型声明 |
| 315 | -│ README.md | 327 | +│ │ NativeModule.js # 原生模块入口 |
| 316 | -│ README.OpenSource | 328 | +│ └─ NativeViewShot.js # TurboModule 规格 |
| 317 | -│ README_en.md | 329 | +└─harmony |
| 318 | -│ | 330 | + └─view_shot # HarmonyOS 适配核心代码 |
| 319 | -├─example | 331 | + │ Index.ets # HAR 模块入口 |
| 320 | -│ | 332 | + │ ts.ets # ArkTS 导出入口 |
| 321 | -├─harmony | 333 | + └─src |
| 322 | -│ │ view_shot.har # 编译后的 HAR 包（HarmonyOS Archive） | 334 | + └─main |
| 323 | -│ │ | 335 | + ├─cpp # C++ TurboModule 注册与绑定 |
| 324 | -│ └─view_shot # 鸿蒙适配核心代码 | 336 | + │ │ CMakeLists.txt |
| 325 | -│ │ .gitignore | 337 | + │ │ ViewShotPackage.h |
| 326 | -│ │ build-profile.json5 | 338 | + │ │ ViewShotTurboModule.cpp |
| 327 | -│ │ hvigorfile.ts | 339 | + │ └─ ViewShotTurboModule.h |
| 328 | -│ │ Index.ets | 340 | + └─ets # ArkTS 业务实现 |
| 329 | -│ │ oh-package.json5 | 341 | + │ Logger.ts |
| 330 | -│ │ ts.ets | 342 | + │ ViewShotPackage.ets |
| 331 | -│ │ | 343 | + └─ ViewShotTurboModule.ts |
| 332 | -│ └─src | ||
| 333 | -│ └─main | ||
| 334 | -│ │ module.json5 | ||
| 335 | -│ │ | ||
| 336 | -│ ├─cpp # C++ 原生层（新架构 Fabric/TurboModule） | ||
| 337 | -│ │ CMakeLists.txt | ||
| 338 | -│ │ ViewShotPackage.h | ||
| 339 | -│ │ ViewShotTurboModule.cpp | ||
| 340 | -│ │ ViewShotTurboModule.h | ||
| 341 | -│ │ | ||
| 342 | -│ ├─ets # ArkTS 业务层 | ||
| 343 | -│ │ Logger.ts | ||
| 344 | -│ │ ViewShotPackage.ets | ||
| 345 | -│ │ ViewShotTurboModule.ets | ||
| 346 | -│ │ | ||
| 347 | -│ └─resources # 资源文件 | ||
| 348 | -│ | ||
| 349 | -└─src | ||
| 350 | - │ index.tsx | ||
| 351 | - │ RNViewShot.ts | ||
| 352 | - │ RNViewShot.web.ts | ||
| 353 | - │ | ||
| 354 | - └─specs | ||
| 355 | - NativeRNViewShot.ts | ||
| 356 | ```` | 344 | ```` |
| 357 | 345 | ||
| 358 | ## 贡献代码 | 346 | ## 贡献代码 |
| @@ -362,4 +350,4 @@ export function ViewShotDemo() { | |||
| 362 | 350 | ||
| 363 | ## 开源协议 | 351 | ## 开源协议 |
| 364 | 352 | ||
| 365 | -本项目基于 [The MIT License (MIT)](https://github.com/gre/react-native-view-shot/blob/master/LICENSE) ，请自由地享受和参与开源。 | 353 | +本项目基于 [The MIT License (MIT)](https://github.com/gre/react-native-view-shot/blob/master/LICENSE) ，请自由地享受和参与开源。 |
| @@ -1,4 +1,4 @@ | |||
| 1 | -> Template version: v0.4.2 | 1 | +> Document Template：v0.4.2 |
| 2 | 2 | ||
| 3 | <p align="center"> | 3 | <p align="center"> |
| 4 | <h1 align="center"> <code>react-native-view-shot</code> </h1> | 4 | <h1 align="center"> <code>react-native-view-shot</code> </h1> |
| @@ -8,7 +8,7 @@ This project is based on [react-native-view-shot](https://github.com/gre/react-n | |||
| 8 | 8 | ||
| 9 | This third-party library has been migrated to Gitcode and is now available for direct download from npm, the new package name is:`@react-native-ohos/react-native-view-shot`. The version correspondence details are as follows: | 9 | This third-party library has been migrated to Gitcode and is now available for direct download from npm, the new package name is:`@react-native-ohos/react-native-view-shot`. The version correspondence details are as follows: |
| 10 | 10 | ||
| 11 | -| Name | Version (npm address) | Release Information | Supported RN Version | Supported Autolink | Compile API Version | Community Baseline Version | Source | | 11 | +| Name | Version(Npm Address) | Release Information | Supported RN Version | Supported Autolink | Compile API Version | Community Baseline Version | Source code address | |
| 12 | | --------------| -------------- | ------------------------------ | ------------- | ------------- |------------------------ | ------------- | ------------- | | 12 | | --------------| -------------- | ------------------------------ | ------------- | ------------- |------------------------ | ------------- | ------------- | |
| 13 | | @react-native-ohos/react-native-view-shot | [~3.8.1](https://www.npmjs.com/package/@react-native-ohos/react-native-view-shot) | [Gitcode Releases](https://gitcode.com/CPF-RN/rntpc_react-native-view-shot/releases) | 0.72.* | Yes | API12+ | 3.8.0 | [br_rnoh0.72](https://gitcode.com/CPF-RN/rntpc_react-native-view-shot/tree/br_rnoh0.72) | | 13 | | @react-native-ohos/react-native-view-shot | [~3.8.1](https://www.npmjs.com/package/@react-native-ohos/react-native-view-shot) | [Gitcode Releases](https://gitcode.com/CPF-RN/rntpc_react-native-view-shot/releases) | 0.72.* | Yes | API12+ | 3.8.0 | [br_rnoh0.72](https://gitcode.com/CPF-RN/rntpc_react-native-view-shot/tree/br_rnoh0.72) | |
| 14 | | @react-native-oh-tpl/react-native-view-shot | [<=3.8.0-0.3.2@deprecated](https://www.npmjs.com/package/@react-native-oh-tpl/react-native-view-shot) | [Github Releases(deprecated)](https://github.com/react-native-oh-library/react-native-view-shot/releases) | 0.72.* | No | API12+ | 3.8.0 | [sig](https://github.com/react-native-oh-library/react-native-view-shot/tree/sig) | | 14 | | @react-native-oh-tpl/react-native-view-shot | [<=3.8.0-0.3.2@deprecated](https://www.npmjs.com/package/@react-native-oh-tpl/react-native-view-shot) | [Github Releases(deprecated)](https://github.com/react-native-oh-library/react-native-view-shot/releases) | 0.72.* | No | API12+ | 3.8.0 | [sig](https://github.com/react-native-oh-library/react-native-view-shot/tree/sig) | |
| @@ -42,12 +42,12 @@ yarn add @react-native-ohos/react-native-view-shot | |||
| 42 | 42 | ||
| 43 | ## Link | 43 | ## Link |
| 44 | 44 | ||
| 45 | -| | Is supported autolink | Supported RN Version | | 45 | +| | Supported Autolink | Supported RN Version | |
| 46 | |------------------------------------|-----------------------|----------------------| | 46 | |------------------------------------|-----------------------|----------------------| |
| 47 | | ~3.8.1 | Yes | 0.72 | | 47 | | ~3.8.1 | Yes | 0.72 | |
| 48 | 48 | ||
| 49 | 49 | ||
| 50 | -Using AutoLink need to be configured according to this document, Autolink Framework Guide Documentation: https://gitcode.com/CPF-RN/ohos_react_native/blob/master/docs/en/Autolinking.md | 50 | +Using AutoLink need to be configured according to this document, Autolink Framework Guide Documentation: https://gitcode.com/CPF-RN/ohos_react_native/blob/main/docs/en/02-development/02-development-guide/autolinking.md |
| 51 | 51 | ||
| 52 | If the version you use supports Autolink and the project has been connected to Autolink, skip the ManualLink configuration. | 52 | If the version you use supports Autolink and the project has been connected to Autolink, skip the ManualLink configuration. |
| 53 | <details> | 53 | <details> |
| @@ -57,7 +57,7 @@ This step provides guidance for manually configuring native dependencies. | |||
| 57 | 57 | ||
| 58 | First, use DevEco Studio to open the HarmonyOS project `harmony` in the project directory. | 58 | First, use DevEco Studio to open the HarmonyOS project `harmony` in the project directory. |
| 59 | 59 | ||
| 60 | -### Adding the overrides Field to oh-package.json5 File in the Root Directory of the Project | 60 | +### 1. Overrides RN SDK |
| 61 | 61 | ||
| 62 | ```json | 62 | ```json |
| 63 | { | 63 | { |
| @@ -69,7 +69,7 @@ First, use DevEco Studio to open the HarmonyOS project `harmony` in the project | |||
| 69 | } | 69 | } |
| 70 | ``` | 70 | ``` |
| 71 | 71 | ||
| 72 | -### Introducing Native Code | 72 | +### 2. Introducing Native Code |
| 73 | 73 | ||
| 74 | Currently, two methods are available: | 74 | Currently, two methods are available: |
| 75 | 75 | ||
| @@ -100,7 +100,7 @@ Method 2: Directly link to the source code. | |||
| 100 | 100 | ||
| 101 | > [!TIP] For details, see [Directly Linking Source Code](https://gitcode.com/CPF-RN/usage-docs/blob/master/en/link-source-code.md). | 101 | > [!TIP] For details, see [Directly Linking Source Code](https://gitcode.com/CPF-RN/usage-docs/blob/master/en/link-source-code.md). |
| 102 | 102 | ||
| 103 | -### Configuring CMakeLists and Introducing ViewShotPackage | 103 | +### 3. Configuring CMakeLists and Introducing ViewShotPackage |
| 104 | 104 | ||
| 105 | Open `entry/src/main/cpp/CMakeLists.txt` and add the following code: | 105 | Open `entry/src/main/cpp/CMakeLists.txt` and add the following code: |
| 106 | 106 | ||
| @@ -148,9 +148,9 @@ std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Cont | |||
| 148 | } | 148 | } |
| 149 | ``` | 149 | ``` |
| 150 | 150 | ||
| 151 | -### Introducing ViewShotPackage to ArkTS | 151 | +### 4. Introducing ViewShotPackage to ArkTS |
| 152 | 152 | ||
| 153 | -Open the `entry/src/main/ets/RNPackagesFactory.ts` file and add the following code: | 153 | +Open the `entry/src/main/ets/RNPackagesFactory.ets` file and add the following code: |
| 154 | 154 | ||
| 155 | ```diff | 155 | ```diff |
| 156 | ... | 156 | ... |
| @@ -187,6 +187,14 @@ The content in this document has been verified under the following environment: | |||
| 187 | 187 | ||
| 188 | 1. RNOH: 0.72.96; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112; | 188 | 1. RNOH: 0.72.96; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112; |
| 189 | 189 | ||
| 190 | +### Permission Requirements | ||
| 191 | + | ||
| 192 | +No additional permissions are required. | ||
| 193 | + | ||
| 194 | +### API requirements | ||
| 195 | + | ||
| 196 | +API 12 or later. | ||
| 197 | + | ||
| 190 | ## Example | 198 | ## Example |
| 191 | 199 | ||
| 192 | The following code shows the basic use scenario of the repository: | 200 | The following code shows the basic use scenario of the repository: |
| @@ -199,7 +207,7 @@ import { View, Text, Button } from "react-native"; | |||
| 199 | import ViewShot, { captureRef, captureScreen } from "react-native-view-shot"; | 207 | import ViewShot, { captureRef, captureScreen } from "react-native-view-shot"; |
| 200 | 208 | ||
| 201 | export function ViewShotDemo() { | 209 | export function ViewShotDemo() { |
| 202 | - const view = React.useRef < View > (null); | 210 | + const view = React.useRef(null); |
| 203 | const ref = React.useRef(null); | 211 | const ref = React.useRef(null); |
| 204 | const onCapture = (res) => { | 212 | const onCapture = (res) => { |
| 205 | console.info("onCapture callback"); | 213 | console.info("onCapture callback"); |
| @@ -245,8 +253,8 @@ export function ViewShotDemo() { | |||
| 245 | <Button | 253 | <Button |
| 246 | title="ViewShot capture" | 254 | title="ViewShot capture" |
| 247 | onPress={() => { | 255 | onPress={() => { |
| 248 | - captureRef(ref).then((res) => { | 256 | + ref.current?.capture().then((res) => { |
| 249 | - console.info(`captureRef: ${res}`); | 257 | + console.info(`ViewShot.capture: ${res}`); |
| 250 | }); | 258 | }); |
| 251 | }} | 259 | }} |
| 252 | /> | 260 | /> |
| @@ -269,25 +277,28 @@ export function ViewShotDemo() { | |||
| 269 | 277 | ||
| 270 | > [!TIP] If the value of **HarmonyOS Support** is **yes**, it means that the HarmonyOS platform supports this property; **no** means the opposite; **partially** means some capabilities of this property are supported. The usage method is the same on different platforms and the effect is the same as that of iOS or Android. | 278 | > [!TIP] If the value of **HarmonyOS Support** is **yes**, it means that the HarmonyOS platform supports this property; **no** means the opposite; **partially** means some capabilities of this property are supported. The usage method is the same on different platforms and the effect is the same as that of iOS or Android. |
| 271 | 279 | ||
| 272 | -| Name | Description | Type | Required | Platform | HarmonyOS Support | | 280 | +| Name | Parameter Type | Default Value | Required | Platform | OpenHarmony Platform Support | Description | |
| 273 | -| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | -------- | ------------ | ----------------- | | 281 | +| ---- | -------------- | ------------- | -------- | -------- | ---------------------------- | ----------- | |
| 274 | -| captureMode | if not defined (default). the capture is not automatic and you need to use the ref and call `capture()` yourself<br>`"mount"`. Capture the view once at mount. (It is important to understand image loading won't be waited, in such case you want to use "none" with viewShotRef.capture() after Image#onLoad.) <br>`"continuous"` EXPERIMENTAL, this will capture A LOT of images continuously. For very specific use-cases.<br> `"update"` EXPERIMENTAL, this will capture images each time React redraw (on did update). For very specific use-cases. | ( 'mount' \| 'continuous' \| 'update') | no | Android, iOS | yes | | 282 | +| captureMode | `"mount"` \| `"continuous"` \| `"update"` | `undefined` | No | Android, iOS | Yes | When undefined, captures are not triggered automatically; use a ref and call `capture()` manually.<br>`"mount"`: captures once after mounting. On HarmonyOS, capture is performed approximately 100 ms after the component mounts. Image loading is not awaited; to wait for an image, leave `captureMode` undefined and call the component ref's `current.capture()` from `Image#onLoad`.<br>`"continuous"`: captures continuously and is intended only for specific scenarios.<br>`"update"`: captures after each React redraw and is intended only for specific scenarios. | |
| 275 | -| onCapture | when a `captureMode` is defined, this callback will be called with the capture result. | function | no | Android, iOS | yes | | 283 | +| onCapture | `(uri: string) => void` | None | No | Android, iOS | Yes | Called with the capture result when `captureMode` is defined and a capture succeeds. | |
| 276 | -| onCaptureFailure | when a `captureMode` is defined, this callback will be called when a capture fails. | function | no | Android, iOS | yes | | 284 | +| onCaptureFailure | `(error: Error) => void` | None | No | Android, iOS | Yes | Called with the error object when `captureMode` is defined and a capture fails. | |
| 277 | -| options | view shot configuration. | object | no | Android, iOS | partially | | 285 | +| options | `CaptureOptions` | None | No | Android, iOS | Partially | View capture configuration. | |
| 278 | -| children | the actual content to rasterize. | ReactNode | no | Android, iOS | yes | | 286 | +| children | `ReactNode` | None | No | Android, iOS | Yes | The content to rasterize. | |
| 287 | +| onLayout | `(event: LayoutChangeEvent) => void` | None | No | Android, iOS | Yes | Invoked when the component mounts or its layout changes, with the layout event. | | ||
| 288 | +| style | `StyleProp<ViewStyle>` | None | No | Android, iOS | Yes | View styles applied to the ViewShot container. | | ||
| 279 | 289 | ||
| 280 | ### options | 290 | ### options |
| 281 | 291 | ||
| 282 | -| Name | Description | Type | Required | Platform | HarmonyOS Support | | 292 | +| Name | Parameter Type | Default Value | Required | Platform | OpenHarmony Platform Support | Description | |
| 283 | -| ------------------------ | ------------------------------------------------------------ | ------------------------------------ | -------- | ------------ | ----------------- | | 293 | +| ---- | -------------- | ------------- | -------- | -------- | ---------------------------- | ----------- | |
| 284 | -| fileName | the file name of the file. Must be at least 3 characters long. | string | no | Android, iOS | yes | | 294 | +| fileName | `string` | None | No | Android | Yes | The file name. It must be at least three characters long. | |
| 285 | -| width / height | the width and height of the final image (resized from the View bound. don't provide it if you want the original pixel size). | number | no | Android, iOS | yes | | 295 | +| width / height | `number` | None | No | Android, iOS | Yes | The width and height of the final image, resized from the View bounds. Omit these options to retain the original pixel size. | |
| 286 | -| quality | the quality. 0.0 - 1.0 (default). (only available on lossy formats like jpg) | number | no | Android, iOS | yes | | 296 | +| quality | `number` | `1` | No | Android, iOS | Yes | Image quality from 0.0 to 1.0. This applies only to lossy formats such as jpg. | |
| 287 | -| format | either png or jpg. Defaults to png. | string | no | Android, iOS | yes | | 297 | +| format | `"jpg"` \| `"png"` \| `"webm"` \| `"raw"` | `"png"` | No | Android, iOS | Partially | The image format. OpenHarmony supports only png and jpg; webm and raw are Android-only. | |
| 288 | -| result | the method you want to use to save the snapshot, one of:<br/>"tmpfile" (default): save to a temporary file (that will only exist for as long as the app is running).<br/>"base64": encode as base64 and returns the raw string. Use only with small images as this may result of lags (the string is sent over the bridge). N.B. This is not a data uri, use data-uri instead.<br/>"data-uri": same as base64 but also includes the Data URI scheme header. <br/>'sandbox-file'(OpenHarmony only): save to a temporary file (that will only exist for as long as the app is running).| ( 'tmpfile' \|'base64' \|'data-uri' \|'sandbox-file') | no | Android, iOS | yes | | 298 | +| result | `"tmpfile"` \| `"base64"` \| `"data-uri"` \| `"zip-base64"` \| `"sandbox-file"` | `"tmpfile"` | No | Android, iOS | Partially | The output method for the snapshot:<br/>`"tmpfile"` (default): saves the image in the application temporary directory and returns its file path; the file exists only while the application is running.<br/>`"base64"`: encodes the image as base64 and returns the raw string. Use it only for small images because transferring the string may cause lag. This is not a data URI; use `data-uri` when a data URI is required.<br/>`"data-uri"`: same as base64, but includes the Data URI scheme header.<br/>`"zip-base64"`: compresses the data with Zip/Deflate and converts it to base64. OpenHarmony does not support zip-base64; it is Android-only.<br/>`"sandbox-file"`: saves the image in the application `cacheDir` and returns a `file://` URI. It is OpenHarmony-only. | |
| 289 | -| snapshotContentContainer | if true and when view is a ScrollView, the "content container" height will be evaluated instead of the container height. | boolean | no | Android, iOS | no | | 299 | +| snapshotContentContainer | `boolean` | `false` | No | Android, iOS | No | When true and the view is a ScrollView, the content-container height is used instead of the container height. | |
| 290 | -| useRenderInContext | change the iOS snapshot strategy to use method renderInContext instead of drawViewHierarchyInRect which may help for some use cases. | boolean | no | Android, iOS | no | | 300 | +| useRenderInContext | `boolean` | None | No | iOS | No | Changes the iOS capture strategy to use renderInContext instead of drawViewHierarchyInRect, which may help in some cases. | |
| 301 | +| handleGLSurfaceViewOnAndroid | `boolean` | `false` | No | Android | No | When true, captures SurfaceView content when the view is a SurfaceView or contains one in its view tree. | | ||
| 291 | 302 | ||
| 292 | ## APIs | 303 | ## APIs |
| 293 | 304 | ||
| @@ -295,66 +306,43 @@ export function ViewShotDemo() { | |||
| 295 | 306 | ||
| 296 | > [!TIP] If the value of **HarmonyOS Support** is **yes**, it means that the HarmonyOS platform supports this property; **no** means the opposite; **partially** means some capabilities of this property are supported. The usage method is the same on different platforms and the effect is the same as that of iOS or Android. | 307 | > [!TIP] If the value of **HarmonyOS Support** is **yes**, it means that the HarmonyOS platform supports this property; **no** means the opposite; **partially** means some capabilities of this property are supported. The usage method is the same on different platforms and the effect is the same as that of iOS or Android. |
| 297 | 308 | ||
| 298 | -| Name | Description | Type | Required | Platform | HarmonyOS Support | | 309 | +| Name | Type | Parameter Type | Return Value | Required | Platform | OpenHarmony Platform Support | Description | |
| 299 | -| ---------------- | ----------- | -------- | -------- | ------------ | ----------------- | | 310 | +| --- | --- | --- | --- | --- | --- | --- | --- | |
| 300 | -| `captureRef` | component screenshot | function | no | Android, iOS | yes | | 311 | +| `captureRef` | function | `view: number \| ReactInstance \| RefObject<T>; optionsObject?: CaptureOptions` | `Promise<string>` | `view`: yes; `optionsObject`: no | Android, iOS | yes | Captures a specified component and returns the snapshot result. | |
| 301 | -| `captureScreen` | screenshot | function | no | Android, iOS | yes | | 312 | +| `captureScreen` | function | `optionsObject?: CaptureOptions` | `Promise<string>` | no | Android, iOS | yes | Captures the current screen and returns the snapshot result. | |
| 302 | -| `releaseCapture` | resource release | function | no | Android, iOS | yes | | 313 | +| `releaseCapture` | function | `uri: string` | `void` | yes | Android, iOS | yes | Releases temporary files created by a capture. | |
| 314 | +| `ViewShot.capture()` | function | / | `Promise<string>` | / | Android, iOS | yes | Imperatively captures the ViewShot component through the component ref's `current.capture()` method using the component's `options`; use it to trigger a capture manually when `captureMode` is not set. | | ||
| 303 | 315 | ||
| 304 | ## Known Issues | 316 | ## Known Issues |
| 305 | -- [ ] The captured component needs to set a background color, otherwise the screenshot effect will be completely black [issues#3](https://github.com/react-native-oh-library/react-native-view-shot/issues/3)。 | 317 | +- [ ] The captured component needs to set a background color, otherwise the screenshot effect will be completely black [issues#3](https://github.com/react-native-oh-library/react-native-view-shot/issues/3). |
| 306 | -- [ ] The screenshot configuration items snapshotContentContainer and useRenderInContext have not been implemented yet [issues#34](https://github.com/react-native-oh-library/react-native-view-shot/issues/34)。 | 318 | +- [ ] The screenshot configuration items snapshotContentContainer and useRenderInContext have not been implemented yet [issues#34](https://github.com/react-native-oh-library/react-native-view-shot/issues/34). |
| 307 | 319 | ||
| 308 | -## Others | 320 | +## Other |
| 309 | None | 321 | None |
| 310 | 322 | ||
| 311 | ## Directory Structure | 323 | ## Directory Structure |
| 312 | -```` | 324 | +````text |
| 313 | -/rntpc_react-native-view-shot # Project root directory | 325 | +rntpc_react-native-view-shot/ |
| 314 | -│ LICENSE | 326 | +├─src |
| 315 | -│ OAT.xml | 327 | +│ │ index.js # JavaScript entry and ViewShot component |
| 316 | -│ package.json | 328 | +│ │ index.d.ts # TypeScript declarations |
| 317 | -│ README.md | 329 | +│ │ NativeModule.js # Native module entry |
| 318 | -│ README.OpenSource | 330 | +│ └─ NativeViewShot.js # TurboModule specification |
| 319 | -│ README_en.md | 331 | +└─harmony |
| 320 | -│ | 332 | + └─view_shot # HarmonyOS adaptation core code |
| 321 | -├─example | 333 | + │ Index.ets # HAR module entry |
| 322 | -│ | 334 | + │ ts.ets # ArkTS export entry |
| 323 | -├─harmony | 335 | + └─src |
| 324 | -│ │ view_shot.har # Compiled HAR package (HarmonyOS Archive) | 336 | + └─main |
| 325 | -│ │ | 337 | + ├─cpp # C++ TurboModule registration and bindings |
| 326 | -│ └─view_shot # HarmonyOS adaptation core code | 338 | + │ │ CMakeLists.txt |
| 327 | -│ │ .gitignore | 339 | + │ │ ViewShotPackage.h |
| 328 | -│ │ build-profile.json5 | 340 | + │ │ ViewShotTurboModule.cpp |
| 329 | -│ │ hvigorfile.ts | 341 | + │ └─ ViewShotTurboModule.h |
| 330 | -│ │ Index.ets | 342 | + └─ets # ArkTS implementation |
| 331 | -│ │ oh-package.json5 | 343 | + │ Logger.ts |
| 332 | -│ │ ts.ets | 344 | + │ ViewShotPackage.ets |
| 333 | -│ │ | 345 | + └─ ViewShotTurboModule.ts |
| 334 | -│ └─src | ||
| 335 | -│ └─main | ||
| 336 | -│ │ module.json5 | ||
| 337 | -│ │ | ||
| 338 | -│ ├─cpp # C++ (Fabric/TurboModule) | ||
| 339 | -│ │ CMakeLists.txt | ||
| 340 | -│ │ ViewShotPackage.h | ||
| 341 | -│ │ ViewShotTurboModule.cpp | ||
| 342 | -│ │ ViewShotTurboModule.h | ||
| 343 | -│ │ | ||
| 344 | -│ ├─ets # ArkTS business layer | ||
| 345 | -│ │ Logger.ts | ||
| 346 | -│ │ ViewShotPackage.ets | ||
| 347 | -│ │ ViewShotTurboModule.ets | ||
| 348 | -│ │ | ||
| 349 | -│ └─resources # source file | ||
| 350 | -│ | ||
| 351 | -└─src | ||
| 352 | - │ index.tsx | ||
| 353 | - │ RNViewShot.ts | ||
| 354 | - │ RNViewShot.web.ts | ||
| 355 | - │ | ||
| 356 | - └─specs | ||
| 357 | - NativeRNViewShot.ts | ||
| 358 | ```` | 346 | ```` |
| 359 | 347 | ||
| 360 | ## How to Contribute | 348 | ## How to Contribute |
| @@ -23,14 +23,21 @@ | |||
| 23 | "viewshot", | 23 | "viewshot", |
| 24 | "view-snapshot", | 24 | "view-snapshot", |
| 25 | "snapshot", | 25 | "snapshot", |
| 26 | - "rasterize" | 26 | + "rasterize", |
| 27 | + "harmony", | ||
| 28 | + "ohos", | ||
| 29 | + "openharmony", | ||
| 30 | + "rnoh" | ||
| 27 | ], | 31 | ], |
| 28 | "author": "Gaëtan Renaudeau <renaudeau.gaetan@gmail.com>", | 32 | "author": "Gaëtan Renaudeau <renaudeau.gaetan@gmail.com>", |
| 29 | - "homepage": "https://gitcode.com/openharmony-sig/rntpc_react-native-view-shot", | 33 | + "homepage": "https://gitcode.com/CPF-RN/rntpc_react-native-view-shot/tree/br_rnoh0.72", |
| 34 | + "bugs": { | ||
| 35 | + "url": "https://gitcode.com/CPF-RN/rntpc_react-native-view-shot/issues" | ||
| 36 | + }, | ||
| 30 | "license": "MIT", | 37 | "license": "MIT", |
| 31 | "repository": { | 38 | "repository": { |
| 32 | "type": "git", | 39 | "type": "git", |
| 33 | - "url": "https://gitcode.com/openharmony-sig/rntpc_react-native-view-shot.git" | 40 | + "url": "https://gitcode.com/CPF-RN/rntpc_react-native-view-shot.git" |
| 34 | }, | 41 | }, |
| 35 | "dependencies": { | 42 | "dependencies": { |
| 36 | "react-native-view-shot": "3.8.0", | 43 | "react-native-view-shot": "3.8.0", |
| @@ -45,4 +52,4 @@ | |||
| 45 | "html-webpack-plugin": "^5.5.1", | 52 | "html-webpack-plugin": "^5.5.1", |
| 46 | "react-native-windows": "^0.63.16" | 53 | "react-native-windows": "^0.63.16" |
| 47 | } | 54 | } |
| 48 | -} | 55 | +} |
| @@ -43,8 +43,9 @@ declare module 'react-native-view-shot' { | |||
| 43 | * lags (the string is sent over the bridge). N.B. This is not a data uri, use data-uri instead. | 43 | * lags (the string is sent over the bridge). N.B. This is not a data uri, use data-uri instead. |
| 44 | " - data-uri": same as base64 but also includes the Data URI scheme header. | 44 | " - data-uri": same as base64 but also includes the Data URI scheme header. |
| 45 | " - zip-base64: compress data with zip deflate algorithm and than convert to base64 and return as a raw string." | 45 | " - zip-base64: compress data with zip deflate algorithm and than convert to base64 and return as a raw string." |
| 46 | + " - sandbox-file" (HarmonyOS only): save to the application cache directory and return a file:// URI. | ||
| 46 | */ | 47 | */ |
| 47 | - result?: 'tmpfile' | 'base64' | 'data-uri' | 'zip-base64'; | 48 | + result?: 'tmpfile' | 'base64' | 'data-uri' | 'zip-base64' | 'sandbox-file'; |
| 48 | /** | 49 | /** |
| 49 | * if true and when view is a ScrollView, the "content container" height will be evaluated instead of the | 50 | * if true and when view is a ScrollView, the "content container" height will be evaluated instead of the |
| 50 | * container height. | 51 | * container height. |