npm package: @ohmi/art
Description: > 模板版本：v0.2.2
Latest version: 15.0.0-0.7.1-rc.1.0.4

> 模板版本：v0.2.2

<p align="center">
  <h1 align="center"> <code>@ohmi/art</code> </h1>
</p>
<p align="center">
    <a href="https://github.com/<原库源码仓地址>">
        <img src="https://img.shields.io/badge/platforms-android%20|%20ios%20|%20harmony%20-lightgrey.svg" alt="Supported platforms" />
    </a>
    <a href="https://github.com/<原库源码仓LICENSE的路径（如有）>">
        <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License" />
        <!-- <img src="https://img.shields.io/badge/license-Apache-blue.svg" alt="License" /> -->
    </a>
</p>


> [!TIP] [Gitee 地址](https://e.gitee.com/kunyuan-hongke/projects/723653/repos/kunyuan-hongke/react-native-community-art/sources)

## 介绍
该项目基于[react-native-svg](https://github.com/react-native-oh-library/react-native-harmony-svg/releases)开发。


## 安装与使用


#### **npm**

```bash
npm install @ohmi/art
```

#### **yarn**

```bash
yarn add @ohmi/art
```

<!-- tabs:end -->

下面的代码展示了这个库的基本使用场景：

> [!WARNING] 使用时 import 的库名不变。

```js
// @flow
import React from 'react';
import {StyleSheet, Dimensions} from 'react-native';
import {
  Surface,
  Shape,
  Group
} from '@react-native-community/art';

const HEART_SHAPE = 
'M 10,30 A 20,20 0,0,1 50,30 A 20,20 0,0,1 90,30 Q 90,60 50,90 Q 10,60 10,30 z';

const App = () => {
  return (
    const surfaceDimensions = Dimensions.get('window').width;

    return (
      <Surface
        width={surfaceDimensions}
        height={surfaceDimensions / 2}
        style={styles.surface}>
        <Group
          x={surfaceDimensions / 2 - 50}
          y={surfaceDimensions / 4 - 50}
          visible={true}>
          <Shape
            d={HEART_SHAPE}
            strokeWidth={5}
            stroke={'#00ff00'}
            visible={true}
          />
        </Group>
      </Surface>
    );
  );
};

export default App;

const styles = StyleSheet.create({
  surface: {
    backgroundColor: 'black',
  }
});

```

## Link

本库 HarmonyOS 侧实现依赖@react-native-oh-tpl/react-native-svg 的原生端代码，如已在 HarmonyOS 工程中引入过该库，则无需再次引入，可跳过本章节步骤，直接使用。

如未引入请参照[react-native-svg-capi](https://gitee.com/react-native-oh-library/usage-docs/blob/master/zh-cn/react-native-svg-capi.md) 进行引入 


## 属性

> [!TIP] "Platform"列表示该属性在原三方库上支持的平台。

> [!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。

**Surface**：绘图元素容器（组件）

| 属性名称 | 类型             | 默认值 | 描述                   | 说明 | 是否必需 | 支持平台 | HarmonyOS 支持 |
| -------- | ---------------- | ------ | ---------------------- | ---- | -------- | -------- | -------------- |
| width    | string \| number | 0      | 盒子的宽，支持百分比   |      | 否       | All      | 是             |
| height   | number           | 0      | 盒子的高，不支持百分比 |      | 否       | All      | 是             |

**Group**：多个图形和文本元素组合在一起（组件）

| 属性名称 | 类型   | 默认值 | 描述 | 说明 | 是否必需 | 支持平台 | HarmonyOS 支持 |
| -------- | ------ | ------ | ---- | ---- | -------- | -------- | -------------- |
| width    | number | 0      |      |      | 否       | N        | 否             |
| height   | number | 0      |      |      | 否       | N        | 否             |

**Text**：文本（组件）

| 属性名称    | 类型                                       | 默认值 | 描述                                                         | 说明                                                         | 是否必需 | 支持平台 | HarmonyOS 支持 |
| ----------- | ------------------------------------------ | ------ | ------------------------------------------------------------ | ------------------------------------------------------------ | -------- | -------- | -------------- |
| font        | string                                     |        | 属性的值是一个字符串，格式为 "font-weight font-size font-family" | 1.font-weight：只支持 normal 和 bold，不支持其他样式（如 italic）。 2.font-size 的单位是像素（px），不能使用其他单位（如 % 或 em）。 3.font-family 必须是系统支持的字体或已导入的自定义字体。 | 否       | All      | 是             |
| alignment   | string                                     | left   | 用于控制文本的对齐方式                                       | 1.left：文本将从指定的（0,0） 坐标开始，向左对齐。 2.center：文本将从指定的（0,0） 坐标开始，居中对齐。 3.right：文本将从指定的 （0,0） 坐标开始，向右对齐。 | 否       | All      | 是             |
| fill        | string \| LinearGradient \| RadialGradient |        | 用于控制文本的颜色                                           | 如 #000,red,LinearGradient 注：0.61上的RadialGradient对象不生效，0.72上修复了这个bug，可以生效 | 否       | All      | 是             |
| stroke      | string                                     |        | 设置文本的描边颜色                                           |                                                              | 否       | All      | 是             |
| strokeWidth | number                                     | 1      | 设置描边的宽度（单位为像素）                                 |                                                              | 否       | All      | 是             |
| strokeCap   | string                                     | round  | 设置描边端点的样式。                                         | 1.butt：描边端点是平的。 2.square：描边端点是方形的。 3.round：描边端点是圆形的。 注：需要搭配strokeDash使用才可以看出效果 | 否       | All      | 是             |
| strokeDash  | Array<number>                              |        | 设置描边的虚线样式                                           | 例如：[10, 5] 表示绘制 10 像素的实线，然后绘制 5 像素的空白，如此循环。 | 否       | All      | 是             |
| strokeJoin  | string                                     | miter  | 设置描边连接处的样式。                                       | 1.bevel：连接处是斜面的。 2.miter：连接处是尖锐的。 3.round：连接处是圆形的。 | 否       | All      | 是             |

**Path**：路径绘制（类）

| 方法名称     | 参数                                                         | 描述                   | 说明                                                         | 支持平台 | HarmonyOS 支持 | HarmonyOS 支持 |
| ------------ | ------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------ | -------- | -------------- | -------------- |
| move         | dx:x 轴方向的偏移量 dy:y 轴方向的偏移量                      | 相对坐标移动           | 将路径的起点从当前位置沿着 x 轴和 y 轴方向移动偏移量 dx 和 dy。 | All      | 是             | 是             |
| moveTo       | x：移动到的目标 x 坐标。 y：移动到的目标 y 坐标。            | 绝对坐标移动           | 将路径的起点移动到指定的绝对坐标 (x, y)。                    | All      | 是             | 是             |
| line         | dx:x 轴方向的距离 dy:y 轴方向的距离                          | 相对坐标绘制直线       | 从当前路径的起点绘制一条直线，移动距离为 dx 和 dy。          | All      | 是             | 是             |
| lineTo       | x：绘制到的目标 x 坐标。 y：绘制到的目标 y 坐标。            | 绝对坐标绘制直线       | 从当前路径的起点绘制一条直线到指定的坐标                     | All      | 是             | 是             |
| curve        | c1x (number): 第一个控制点的 x 坐标。 c1y (number): 第一个控制点的 y 坐标。 c2x (number): 第二个控制点的 x 坐标。 c2y (number): 第二个控制点的 y 坐标。 ex (number): 结束点的 x 坐标（相对于当前点的偏移量）。 ey (number): 结束点的 y 坐标（相对于当前点的偏移量） | 相对坐标绘制贝塞尔曲线 | curve 方法使用相对坐标来指定结束点的位置，即结束点的坐标是相对于当前点的偏移量。  2个参数：(dx, dy) 绘制一条直线，从当前点到 (当前点 + dx, 当前点 + dy)。  3个参数：(c1x, c1y, ex) 绘制一条二次贝塞尔曲线，使用一个控制点。 ex = ex,ey = 整个坐标系y 0  4个参数：(c1x, c1y, ex, ey) 绘制一条二次贝塞尔曲线，使用一个控制点。  5个参数：(c1x, c1y, c2x, c2y, ex) 绘制一条三次贝塞尔曲线，使用俩个控制点。ex = ex,ey = 整个坐标系y 0  6个参数：(c1x, c1y, c2x, c2y, ex, ey) 绘制一条三次贝塞尔曲线，使用俩个控制点。  注：curve使用1个参数会报错 | All      | 是             | 是             |
| curveTo      | c1x (number): 第一个控制点的 x 坐标。 c1y (number): 第一个控制点的 y 坐标。 c2x (number): 第二个控制点的 x 坐标。 c2y (number): 第二个控制点的 y 坐标。 ex (number): 结束点的 x 坐标（绝对坐标）。 ey (number): 结束点的 y 坐标（绝对坐标） | 绝对坐标绘制贝塞尔曲线 | curveTo 方法使用绝对坐标来指定结束点的位置，即结束点的坐标是相对于整个坐标系的。  2个参数：(dx, dy) 绘制一条直线，从当前点到 (整个坐标系的dx, 整个坐标系的dy)。   4个参数：(c1x, c1y, ex, ey) 绘制一条二次贝塞尔曲线，使用一个控制点。   6个参数：(c1x, c1y, c2x, c2y, ex, ey) 绘制一条三次贝塞尔曲线，使用俩个控制点。  注：curveTo使用1个参数，3个参数或5个参数会报错 | All      | 是             | 是             |
| arc          | x (number): 终点的 x 坐标，相对于当前点的偏移量。 y (number): 终点的 y 坐标，相对于当前点的偏移量。 rx (number): 圆弧在 x 轴方向的半径。 ry (number): 圆弧在 y 轴方向的半径。 outer (boolean): 是否为外侧弧线。（若两点间的圆心角超过 180 度，设置 outer=true 会绘制较长的弧，false则绘制小弧） counterClockwise (boolean): 是否逆时针绘制弧线。true 表示逆时针，false 表示顺时针。 rotation (number): 旋转角度。 | 相对坐标绘制弧线       | 使用一个参数会报错                                           | All      | 是             | 是             |
| arcTo        | x (number): 终点的 x 坐标，相对于整个坐标系的值。 y (number): 终点的 y 坐标，相对于整个坐标系的值。 rx (number): 圆弧在 x 轴方向的半径。 ry (number): 圆弧在 y 轴方向的半径。 outer (boolean): 是否为外侧弧线。（若两点间的圆心角超过 180 度，设置 outer=true 会绘制较长的弧，false则绘制小弧） counterClockwise (boolean): 是否逆时针绘制弧线。true 表示逆时针，false 表示顺时针。 rotation (number): 旋转角度。 | 绝对坐标绘制弧线       | 使用一个参数会报错                                           | All      | 是             | 是             |
| counterArc   | x (number): 终点的 x 坐标，相对于当前点的偏移量。 y (number): 终点的 y 坐标，相对于当前点的偏移量。 rx (number): 圆弧在 x 轴方向的半径。 ry (number): 圆弧在 y 轴方向的半径。 outer (boolean): 是否为外侧弧线。（若两点间的圆心角超过 180 度，设置 outer=true 会绘制较长的弧，false则绘制小弧） | 相对坐标绘制弧线       | counterArc: function(x, y, rx, ry, outer){  return this.arc(x, y, rx, ry, outer, true);  }  经过观察源码，发现只是将arc的第六个参数counterClockwise使用逆时针进行使用而已，且只有5个参数值，用法与效果与arc5个参数效果一致 | All      | 是             | 是             |
| counterArcTo | x (number): 终点的 x 坐标，相对于整个坐标系的值。 y (number): 终点的 y 坐标，相对于整个坐标系的值。 rx (number): 圆弧在 x 轴方向的半径。 ry (number): 圆弧在 y 轴方向的半径。 outer (boolean): 是否为外侧弧线。（若两点间的圆心角超过 180 度，设置 outer=true 会绘制较长的弧，false则绘制小弧） | 绝对坐标绘制弧线       | counterArcTo: function(x, y, rx, ry, outer){  return this.arcTo(x, y, rx, ry, outer, true);  } 经过观察源码，发现只是将arc的第六个参数counterClockwise使用逆时针进行使用而已，且只有5个参数值，用法与效果与arcTo5个参数效果一致 | All      | 是             | 是             |
| close        | 无                                                           | 闭合路线               |                                                              | All      | 是             | 是             |
| reset        | 无                                                           | 重置路径               |                                                              | All      | 是             | 是             |
| initialize   | Path对象                                                     | 克隆Path相关路径       |                                                              | All      | 是             | 是             |

**Shape**：创建和渲染矢量图形（组件）

| 属性名称    | 类型                                       | 默认值 | 描述                                                         | 说明                                                         | 是否必需 | 支持平台 | HarmonyOS 支持 |
| ----------- | ------------------------------------------ | ------ | ------------------------------------------------------------ | ------------------------------------------------------------ | -------- | -------- | -------------- |
| d           | string \| Path对象                         |        | SVG格式的字符串 或者new Path()的对象                         |                                                              | 否       | All      | 是             |
| height      | number                                     |        | 盒子的高。 不知道有啥用，源码上有这个属性，但显示的内容，大小是根据d这个属性来决定的 |                                                              | 否       | All      | 是             |
| width       | number                                     |        | 盒子的高。 不知道有啥用，源码上有这个属性，但显示的内容，大小是根据d这个属性来决定的 |                                                              | 否       | All      | 是             |
| fill        | string \| LinearGradient \| RadialGradient |        | 用于控制文本的颜色                                           | 如 #000,red,LinearGradient 注：0.61上的RadialGradient对象不生效，0.72上修复了这个bug，可以生效 | 否       | All      | 是             |
| stroke      | string                                     |        | 设置文本的描边颜色                                           |                                                              | 否       | All      | 是             |
| strokeWidth | number                                     | 1      | 设置描边的宽度（单位为像素）                                 |                                                              | 否       | All      | 是             |
| strokeCap   | string                                     | round  | 设置描边端点的样式。                                         | 1.butt：描边端点是平的。 2.square：描边端点是方形的。 3.round：描边端点是圆形的。 | 否       | All      | 是             |
| strokeDash  | Array<number>                              |        | 设置描边的虚线样式                                           | 例如：[10, 5] 表示绘制 10 像素的实线，然后绘制 5 像素的空白，如此循环。 | 否       | All      | 是             |
| strokeJoin  | string                                     | miter  | 设置描边连接处的样式。                                       | 1.bevel：连接处是斜面的。 2.miter：连接处是尖锐的。 3.round：连接处是圆形的。 | 否       | All      | 是             |

**ClippingRectangle**：图形裁剪（组件）0.61不支持

| 属性名称 | 类型   | 默认值 | 描述     | 说明 | 是否必需 | 支持平台 | HarmonyOS 支持 |
| -------- | ------ | ------ | -------- | ---- | -------- | -------- | -------------- |
| width    | number | 0      | 盒子的宽 |      | 否       | N        | 否             |
| height   | number | 0      | 盒子的高 |      | 否       | N        | 否             |

**LinearGradient**：线性渐变填充（构造函数，下列是参数列表）

| 属性名称 | 类型                                                         | 默认值 | 描述                 | 说明 | 是否必需 | 支持平台 | HarmonyOS 支持 |
| -------- | ------------------------------------------------------------ | ------ | -------------------- | ---- | -------- | -------- | -------------- |
| stops    | type GradientStops = {[key: string]: ColorType} \| Array<ColorType>; |        | 渐变的颜色停止点数组 |      | 否       | All      | 是             |
| x1       | number                                                       |        | 渐变起始点的 x 坐标  |      | 否       | All      | 是             |
| y1       | number                                                       |        | 渐变起始点的 y 坐标  |      | 否       | All      | 是             |
| x2       | number                                                       |        | 渐变结束点的 x 坐标  |      | 否       | All      | 是             |
| y2       | number                                                       |        | 渐变结束点的 y 坐标  |      | 否       | All      | 是             |

**RadialGradient**：径向渐变填充（构造函数，下列是参数列表）0.61没有效果

| 属性名称 | 类型                                                         | 默认值 | 描述                 | 说明 | 是否必需 | 支持平台 | HarmonyOS 支持 |
| -------- | ------------------------------------------------------------ | ------ | -------------------- | ---- | -------- | -------- | -------------- |
| stops    | type GradientStops = {[key: string]: ColorType} \| Array<ColorType>; |        | 渐变的颜色停止点数组 |      | 否       | N        | 是             |
| fx       | number                                                       | 0.5    | 渐变焦点的 x 坐标    |      | 否       | N        | 是             |
| fy       | number                                                       | 0.5    | 渐变焦点的 y 坐标    |      | 否       | N        | 是             |
| rx       | number                                                       | 0.5    | 渐变外环的 x 半径    |      | 否       | N        | 是             |
| ry       | number                                                       | 0.5    | 渐变外环的 y 半径    |      | 否       | N        | 是             |
| cx       | number                                                       | 0.5    | 渐变中心点的 x 坐标  |      | 否       | N        | 是             |
| cy       | number                                                       | 0.5    | 渐变中心点的 y 坐标  |      | 否       | N        | 是             |

**Transform**：图形进行变换操作（构造函数，下列是参数列表）

| 属性名称  | 类型                                             | 默认值                           | 描述                             | 说明 | 是否必需 | 支持平台 | HarmonyOS 支持 |
| --------- | ------------------------------------------------ | -------------------------------- | -------------------------------- | ---- | -------- | -------- | -------------- |
| xx        | number                                           | 1                                | X轴方向的缩放因子。              |      | 否       | All      | 是             |
| yx        | number                                           | 0                                | Y轴方向的倾斜因子（相对于X轴）。 |      | 否       | All      | 是             |
| xy        | number                                           | 0                                | X轴方向的倾斜因子（相对于Y轴）。 |      | 否       | All      | 是             |
| yy        | number                                           | 1                                | Y轴方向的缩放因子。              |      | 否       | All      | 是             |
| x         | number                                           | 0                                | X轴方向的平移距离。              |      | 否       | All      | 是             |
| y         | number                                           | 0                                | Y轴方向的平移距离。              |      |          |          |                |
| 方法名称  | 参数                                             | 描述                             | 说明                             |      | 是否必需 | 支持平台 | HarmonyOS 支持 |
| transform | xx yx xy yy x y                                  | 用法与new Transform(...arg) 一致 |                                  |      | 否       | All      | 是             |
| translate | x y                                              | 沿X \| Y轴的平移距离。           | 正值向右移动，负值向左移动。     |      | 否       | All      | 是             |
| move      | x y                                              | 与translate用法一致              |                                  |      | 否       | All      | 是             |
| moveTo    | x y                                              | 与translate用法一致              |                                  |      | 否       | All      | 是             |
| scale     | xx yy                                            | 缩放比例。                       | 大于1表示放大，小于1表示缩小。   |      | 否       | All      | 是             |
| rotate    | deg 旋转角度 x 旋转的中心点x轴 y 旋转的中心点y轴 |                                  |                                  |      | 否       | All      | 是             |
| rotateTo  | deg 旋转角度 x 旋转的中心点x轴 y 旋转的中心点y轴 | 与rotate用法一致                 |                                  |      | 否       | All      | 是             |

**公共属性**：Common props 组件属性 HarmonyOS 侧支持情况（Surface与ClippingRectangle不生效，shadow系列的属性仅对Text和Shape组件生效）

| 属性名称      | 类型    | 默认值         | 描述                                   | 说明                                                   | 是否必需 | 支持平台 | HarmonyOS 支持 |
| ------------- | ------- | -------------- | -------------------------------------- | ------------------------------------------------------ | -------- | -------- | -------------- |
| opacity       | number  | 1              | 透明度（0-1）                          |                                                        | 否       | All      | 是             |
| originX       | number  | 0              | 原点 X 坐标                            | 需搭配rotation使用                                     | 否       | All      | 是             |
| originY       | number  | 0              | 原点 Y 坐标                            | 需搭配rotation使用                                     | 否       | All      | 是             |
| rotation      | number  | 0              | 旋转角度                               |                                                        | 否       | All      | 是             |
| scaleX        | number  | 1              | X 轴方向的缩放比例                     |                                                        | 否       | All      | 是             |
| scaleY        | number  | 1              | Y 轴方向的缩放比例                     |                                                        | 否       | All      | 是             |
| scale         | number  | 1              | 统一缩放比例（同时影响 X 轴和 Y 轴）   |                                                        | 否       | All      | 是             |
| x             | number  | 0              | 横坐标位移                             |                                                        | 否       | All      | 是             |
| y             | number  | 0              | 纵坐标位移                             |                                                        | 否       | All      | 是             |
| visible       | boolean | true           | 是否可见                               |                                                        | 否       | All      | 是             |
| shadowColor   | string  | #000           | 设置阴影的颜色                         |                                                        | 否       | All      | 是             |
| shadowOffset  | object  | { x: 0, y: 0 } | 设置阴影的偏移量                       | 包含 x 和 y 两个属性，分别表示水平和垂直方向的偏移量。 | 否       | All      | 是             |
| shadowOpacity | number  | 1              | 设置阴影的透明度                       |                                                        | 否       | All      | 是             |
| shadowRadius  | number  | 0              | 设置阴影的模糊半径，值越大阴影越模糊。 | 目前72上面这个属性不生效（OS底层暂时不支持）           | 否       |          | 否             |