已合并
docs: upgrade README to v0.4.2 template for br_rnoh0.72 #5
docs: upgrade README to v0.4.2 template for br_rnoh0.72 #5
已合并
fangzhen创建于 9月16日
fangzhen
fangzhen成员
9月16日

变更类型

请在对应类型(请勿多选)前打 √,仅可选择一项:

变更内容

  • 简要描述本次变更的具体内容、解决的问题;
  • 若为破坏性变更,请详细说明:
    • 影响范围(哪些 API/配置/功能被修改);
    • 用户适配方案(旧版→新版的替换步骤)

本 PR 为纯文档变更,无破坏性变更。

修改说明

将 br_rnoh0.72 分支 README.md 由指向 usage-docs 的存根文档升级为 v0.4.2 完整版模板文档,并新增同步的英文版 README_en.md。

主要修改

  1. 模板升级:存根文档 → v0.4.2 完整版;章节按模板顺序重排:简介 → 下载安装 → 约束与限制 → 使用示例 → 使用说明 → 接口说明 → 遗留问题 → 其他 → 目录结构 → 贡献代码 → 开源协议。
  2. 顶部版本映射表(仅保留本分支 0.72.* 行):
    • @react-native-ohos/react-native-drag-sort ~2.4.5(npm 正式版,无“开发中”标注):发布信息 GitCode Releases,源码 br_rnoh0.72,Autolink 否,编译 API12+;
    • @react-native-oh-tpl/react-native-drag-sort <=2.4.4-0.1.0@deprecated(sig 行);
    • 社区基线版本 2.4.4(与本分支 package.json 依赖 react-native-drag-sort@^2.4.4 一致)。
  3. 下载安装:npm/yarn 加粗分列,安装 @react-native-ohos/react-native-drag-sort(其 npm 依赖已包含社区基线包 react-native-drag-sort@^2.4.4)。
  4. Link、依赖关系说明章节:删除——npm tarball 实测为纯 JS 库(无 har/原生代码),无鸿蒙化依赖库。
  5. 约束与限制:兼容性仅保留本分支验证条目(RNOH: 0.72.98; SDK: HarmonyOS-5.0.0(API12); IDE: DevEco Studio 5.0.3.906; ROM: NEXT.0.0.71);权限要求——lib 无 module.json5,如实填写“无特殊权限要求”。
  6. 接口说明:新增组件表(3 组件)与属性表(IProps/AutoIProps/AnySizeIProps 共 53 行);新增“默认值”列并逐项对照组件 defaultProps 实测(parentWidth=屏幕宽度、sortable=true、maxScale=1.1、autoThrottle=2、areaOverlapRatio=0.55 等);必填列统一小写 yes/no;表头统一“OpenHarmony平台支持”;回调签名对照 index.d.ts 核对。
  7. 使用示例/使用说明:使用示例移至约束与限制之后(模板顺序);AnySize 示例整体重写为自包含代码,可直接复制运行。
  8. 目录结构:按本分支 git ls-tree 实测逐条目校验后编写。
  9. 链接统一:gitcode 链接统一 CPF-RN 组织;发布信息统一 GitCode(大写 C);开源协议指向上游 GitHub LICENSE(Apache-2.0,实测可达)。

检视意见修复

  1. 【AI-Review】scrollIndicatorInsets 平台标注不一致:AnySizeIProps 属性表该属性 Platform 列 iOS/Android → iOS,与 AutoIProps 表保持一致(该属性为 iOS 专属 ScrollView 属性,两组件透传方式相同);并在两张表的该属性描述中关联遗留问题 issue#179;README_en.md 同步修改。(commit cdb681d)
  2. 【gyange】AnySize 示例引用不存在的 ../SourceLibraryDemo/data/img/clear.png:该意见针对 PR 早期版本;当前 head 示例已重写为自包含代码(grep 零命中),无需再修改。

测试步骤

  1. 在 PR Files changed 页查看 README.md / README_en.md 渲染:表格、目录树、代码块、TIP/WARNING 块显示正常,中英文章节与表行数一致(映射表 2 行、组件 3 行、属性 53 行)。
  2. 数据核对:npm registry 版本(ohos 2.4.5 / tpl 2.4.4-0.1.0)、社区基线 2.4.4、链接可达性(GitCode Releases、br_rnoh0.72 分支、issue#179、上游 LICENSE)均实测通过。
  3. 属性表与 br_rnoh0.72 分支源码逐项比对(index.d.ts 必填性、defaultProps 默认值)。

测试情况

纯文档变更,以下条目均不适用,不勾选(CI 状态经 commits API 核实为 None,无流水线数据)。

合入前自检

关联 issue:#5

likedislike
Pull Request已成功合入, 合并人@openharmony_ci
(感谢 fangzhen 的贡献)
openharmony_ci
openharmony_ci成员
9月16日 评论:

感谢提交 Pull Requests!
Thanks for submitting a pull request.

likedislike
openharmony_ciopenharmony_ci成员
9月16日 添加了label:dco检查成功
cpf-manager
cpf-manager9月16日进行代码检视3
README.md
已过期
@@ -14,0 +472,4 @@
472+| autoThrottle | number | 2 | no | iOS/Android | Yes | 自动滑动到目的地的间隔时间 |
473+| autoThrottleDuration | number | 10 | no | iOS/Android | Yes | 自动滑动到目的地的持续时间 |
474+| onDragEnd | () => void | 无 | yes | iOS/Android | Yes | 拖拽结束后调用 |
475+| scrollIndicatorInsets | {top: number, left: number, bottom: number, right: number} | {top: 0, left: 0, bottom: 0, right: 1} | no | iOS/Android | No | 滚动条内边距 |
cpf-manager
cpf-manager9月16日评论:

【AI-Review】【一般】【基础代码问题】【可读性问题】scrollIndicatorInsets 平台支持标注不一致

● 问题:README.md 第475行 AnySizeIProps 属性表中,scrollIndicatorInsets 的 Platform 列标注为 "iOS/Android",而第454行 AutoIProps 属性表中同一属性标注为 "iOS"。经核实源码,AutoDragSortableView.js:588 和 AnySizeDragSortableView.js:411 均以相同方式将该属性透传给底层 ScrollView 组件(scrollIndicatorInsets={this.props.scrollIndicatorInsets}),两组件对该属性的处理完全一致。React Native 中 ScrollView 的 scrollIndicatorInsets 为 iOS 专属属性,Android 平台不生效。

● 影响:一般。用户查阅 AnySizeIProps 表时会误以为 scrollIndicatorInsets 在 Android 平台生效,实际在 Android 上不生效(仅 iOS 支持),造成对原三方库跨平台能力一致性的误解。README_en.md 第475行存在相同问题。

● 建议:将第475行 scrollIndicatorInsets 的 Platform 列由 "iOS/Android" 修改为 "iOS",与第454行 AutoIProps 表保持一致,确保同一属性在不同组件属性表中的平台支持描述一致。README_en.md 第475行需同步修改。

likedislike
System
系统消息系统
16 天前 评论:

changed this line on cdb681dd view diff detail

fangzhen
fangzhen成员
16 天前 评论:

已解决

cpf-manager
cpf-manager9月16日进行代码检视3
README_en.md
已过期
@@ -0,0 +472,4 @@
472+| autoThrottle | number | 2 | no | iOS/Android | Yes | Interval for auto sliding to the destination |
473+| autoThrottleDuration | number | 10 | no | iOS/Android | Yes | Duration for auto sliding to the destination |
474+| onDragEnd | () => void | None | yes | iOS/Android | Yes | Called after dragging ends |
475+| scrollIndicatorInsets | {top: number, left: number, bottom: number, right: number} | {top: 0, left: 0, bottom: 0, right: 1} | no | iOS/Android | No | Margin on scroll |
cpf-manager
cpf-manager9月16日评论:

【AI-Review】【一般】【基础代码问题】【可读性问题】scrollIndicatorInsets 平台支持标注不一致

● 问题:README_en.md 第475行 AnySizeIProps 属性表中,scrollIndicatorInsets 的 Platform 列标注为 "iOS/Android",而第454行 AutoIProps 属性表中同一属性标注为 "iOS"。经核实源码,AutoDragSortableView.js:588 和 AnySizeDragSortableView.js:411 均以相同方式将该属性透传给底层 ScrollView 组件(scrollIndicatorInsets={this.props.scrollIndicatorInsets}),两组件对该属性的处理完全一致。React Native 中 ScrollView 的 scrollIndicatorInsets 为 iOS 专属属性,Android 平台不生效。

● 影响:一般。用户查阅 AnySizeIProps 表时会误以为 scrollIndicatorInsets 在 Android 平台生效,实际在 Android 上不生效(仅 iOS 支持),造成对原三方库跨平台能力一致性的误解。

● 建议:将第475行 scrollIndicatorInsets 的 Platform 列由 "iOS/Android" 修改为 "iOS",与第454行 AutoIProps 表保持一致,确保同一属性在不同组件属性表中的平台支持描述一致。

likedislike
System
系统消息系统
16 天前 评论:

changed this line on cdb681dd view diff detail

fangzhen
fangzhen成员
16 天前 评论:

已解决

gyange成员26 天前进行代码检视2
README.md
@@ -14,0 +349,4 @@
349+ autoThrottle={100}
350+ autoThrottleDuration={500}
351+ areaOverlapRatio={0.5}
352+ childMarginTop={10}
gyange26 天前评论:

AnySizeDragSortableView 示例代码中 require("../SourceLibraryDemo/data/img/clear.png") 引用了项目中不存在的路径。用户复制这段示例代码运行时会报模块找不到错误。应改为项目中实际存在的图片路径或使用 base64/网络图片替代。

likedislike
fangzhen
fangzhen成员
16 天前 评论:

该问题在当前 head(commit 7b5c4ac 起)已不存在:AnySizeDragSortableView 使用示例已整体重写为自包含代码,移除了对 ../SourceLibraryDemo/data/img/clear.png 及外部图片资源的引用,可直接复制运行。

fangzhenfangzhen成员
16 天前 推送  1 个提交:cdb681dd-docs: fix scrollIndicatorInsets platform column and link issue#179
openharmony_ci
openharmony_ci成员
16 天前 评论:

感谢提交 Pull Requests!
Thanks for submitting a pull request.

likedislike
cpf-manager
cpf-manager16 天前进行代码检视3
README.md
已过期
@@ -14,0 +348,4 @@
348+ scrollIndicatorInsets={{ top: 1, left: 1, bottom: 1, right: 1 }}
349+ autoThrottle={100}
350+ autoThrottleDuration={500}
351+ areaOverlapRatio={0.5}
cpf-manager
cpf-manager16 天前评论:

【AI-Review】【一般】【基础代码问题】【可读性问题】
● 问题: README.md 第351行 AnySizeDragSortableView 示例代码中 areaOverlapRatio={0.5},与第478行 API 属性表中该属性约束 "必须大于 0.5" 相互矛盾。经核实源码 lib/AnySizeDragSortableView.js:480 默认值为 0.55 且源码注释为 "Must be greater than 0.5",0.5 并不满足 "大于 0.5" 的约束条件(0.5 等于 0.5,而非大于 0.5)。

● 影响: 一般。用户参照示例代码设置 areaOverlapRatio=0.5 会违反文档自身声明的约束条件;根据源码 lib/AnySizeDragSortableView.js:278 的判定逻辑 if (overlapArea < minArea * areaOverlapRatio || !overlapArea) continue,当该值设为 0.5 时,在拖拽项与目标项重叠面积恰好等于最小面积 50% 的临界场景下会被判定为有效目标,可能触发源码注释所述的 "repeated switching caused by triggering the critical point" 反复切换问题,导致拖拽结束位置判定不稳定。README_en.md 第351行存在相同问题。

● 建议: 将第351行 areaOverlapRatio={0.5} 修改为大于 0.5 的值(如默认值 0.55 或 0.6),使示例与第478行 API 表中 "必须大于 0.5" 的约束保持一致。README_en.md 第351行需同步修改。

likedislike
System
系统消息系统
16 天前 评论:

changed this line on 4f2fadce view diff detail

fangzhen
fangzhen成员
16 天前 评论:

已解决

cpf-manager
cpf-manager16 天前进行代码检视3
README_en.md
已过期
@@ -0,0 +348,4 @@
348+ scrollIndicatorInsets={{ top: 1, left: 1, bottom: 1, right: 1 }}
349+ autoThrottle={100}
350+ autoThrottleDuration={500}
351+ areaOverlapRatio={0.5}
cpf-manager
cpf-manager16 天前评论:

【AI-Review】【一般】【基础代码问题】【可读性问题】
● 问题: README_en.md 第351行 AnySizeDragSortableView 示例代码中 areaOverlapRatio={0.5},与第478行 API 属性表中该属性约束 "must be greater than 0.5" 相互矛盾。经核实源码 lib/AnySizeDragSortableView.js:480 默认值为 0.55 且源码注释为 "Must be greater than 0.5",0.5 并不满足 "greater than 0.5" 的约束条件(0.5 等于 0.5,而非大于 0.5)。

● 影响: General. Users following the example to set areaOverlapRatio=0.5 would violate the constraint declared in the documentation itself; according to the source code lib/AnySizeDragSortableView.js:278 judgment logic if (overlapArea < minArea * areaOverlapRatio || !overlapArea) continue, when this value is set to 0.5, in the critical scenario where the overlap area between the dragged item and the target item happens to equal 50% of the minimum area, it would be judged as a valid target, which may trigger the "repeated switching caused by triggering the critical point" issue described in the source comment, leading to unstable drag-end position judgment. README.md line 351 has the same issue.

● 建议: Change line 351 areaOverlapRatio={0.5} to a value greater than 0.5 (such as the default 0.55 or 0.6), so that the example is consistent with the "must be greater than 0.5" constraint in the API table on line 478. README.md line 351 needs to be updated synchronously.

likedislike
System
系统消息系统
16 天前 评论:

changed this line on 4f2fadce view diff detail

fangzhen
fangzhen成员
16 天前 评论:

已解决

fangzhenfangzhen成员
16 天前 修改了pull request 的描述
fangzhenfangzhen成员
16 天前 修改了pull request 的描述
fangzhenfangzhen成员
16 天前 推送  1 个提交:4f2fadce-docs: fix areaOverlapRatio example value to 0.55 to satisfy >0.5 constraint
fangzhen
fangzhen成员
16 天前 评论:

start build

likedislike
openharmony_ci
openharmony_ci成员
16 天前 评论:
fangzhenfangzhen成员
16 天前 关联了issue:[Document]: 升级0.72分支readme到0.4.2
fangzhenfangzhen成员
16 天前 删除了关联的issue:[Document]: update README.md to template 0.4.2 and add README_en.md
fangzhen
fangzhen成员
16 天前 评论:

start build

likedislike
openharmony_ci
openharmony_ci成员
16 天前 评论:

首次触发
门禁构建开始,包含静态检查,预计在60分钟内完成,门禁结果会同步发送到注册邮箱。您可以通过如下链接跟踪门禁进展:http://dcp.openharmony.cn/workbench/cicd/detail/6ac9ff6464650f998b7b4357/runlist

likedislike
openharmony_ciopenharmony_ci成员
16 天前 添加了label:静态检查失败
openharmony_ci
openharmony_ci成员
16 天前 评论:

代码门禁未通过
您可以通过如下链接查看门禁报告:http://dcp.openharmony.cn/workbench/cicd/detail/6ac9ff6464650f998b7b4357/runlist

静态检查:

# check type result report
1 codeCheck noPass >>>

likedislike
dingchengjiedingchengjie成员
14 天前 将dingchengjie设为审查人
fangzhen
fangzhen成员
14 天前 评论:

start build

likedislike
openharmony_ciopenharmony_ci成员
14 天前 删除了label:静态检查失败
openharmony_ci
openharmony_ci成员
14 天前 评论:

上次构建已超过12小时,重新全量验证,重置所有关联PR的验证状态
门禁构建开始,包含静态检查,预计在60分钟内完成,门禁结果会同步发送到注册邮箱。您可以通过如下链接跟踪门禁进展:http://dcp.openharmony.cn/workbench/cicd/detail/6acc50e064650f998b194e5e/runlist

likedislike
openharmony_ciopenharmony_ci成员
14 天前 添加了label:静态检查成功
openharmony_ciopenharmony_ci成员
14 天前 通过测试
openharmony_ci
openharmony_ci成员
14 天前 评论:

代码门禁通过
您可以通过如下链接查看门禁报告:http://dcp.openharmony.cn/workbench/cicd/detail/6acc50e064650f998b194e5e/runlist

静态检查:

# check type result report
1 codeCheck pass >>>

likedislike
dingchengjiedingchengjie成员
14 天前 通过审查
openharmony_ci
openharmony_ci成员
14 天前 评论:

数据库内未检测到最新commit的dco结果,无法合入,请评论check dco重新触发dco检查,检查通过后再评论submit触发合入

likedislike
dingchengjie
dingchengjie成员
9 天前 评论:

check dco

likedislike
openharmony_ci
openharmony_ci成员
9 天前 评论:

感谢提交 Pull Requests!
Thanks for submitting a pull request.

likedislike
dingchengjie
dingchengjie成员
9 天前 评论:

submit

likedislike
openharmony_ci
openharmony_ci成员
9 天前 评论:

验证结果已超过12小时,之前验证结果无效,自动重新触发构建,请关注最新验证结果

likedislike
openharmony_ci
openharmony_ci成员
9 天前 评论:

start build

likedislike
openharmony_ciopenharmony_ci成员
9 天前 删除了label:静态检查成功
openharmony_ci
openharmony_ci成员
9 天前 评论:

上次构建已超过12小时,重新全量验证,重置所有关联PR的验证状态
门禁构建开始,包含静态检查,预计在60分钟内完成,门禁结果会同步发送到注册邮箱。您可以通过如下链接跟踪门禁进展:http://dcp.openharmony.cn/workbench/cicd/detail/6ad30a7d64650f998b5b2287/runlist

likedislike
openharmony_ciopenharmony_ci成员
9 天前 添加了label:静态检查成功
openharmony_ciopenharmony_ci成员
9 天前 通过测试
openharmony_ci
openharmony_ci成员
9 天前 评论:

代码门禁通过
您可以通过如下链接查看门禁报告:http://dcp.openharmony.cn/workbench/cicd/detail/6ad30a7d64650f998b5b2287/runlist

静态检查:

# check type result report
1 codeCheck pass >>>

likedislike
openharmony_ciopenharmony_ci成员
9 天前 合入了pull request,合并节点 SHA:c4900290421048ebb26b93c062eac1671d37d068