Skip to content

feat(calendarcard): 增加自定义头 #3285

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 26, 2025

Conversation

xiaoyatong
Copy link
Collaborator

@xiaoyatong xiaoyatong commented Jun 26, 2025

🤔 这个变动的性质是?

  • 新特性提交
  • 日常 bug 修复
  • 站点、文档改进
  • 演示代码改进
  • 组件样式/交互改进
  • TypeScript 定义更新
  • 包体积优化
  • 性能优化
  • 功能增强
  • 国际化改进
  • 重构
  • 代码风格优化
  • 测试用例
  • 分支合并
  • 其他改动(是关于什么的改动?)

🔗 相关 Issue

💡 需求背景和解决方案

☑️ 请求合并前的自查清单

⚠️ 请自检并全部勾选全部选项⚠️

  • 文档已补充或无须补充
  • 代码演示已提供或无须提供
  • TypeScript 定义已补充或无须补充
  • fork仓库代码是否为最新避免文件冲突
  • Files changed 没有 package.json lock 等无关文件

Summary by CodeRabbit

  • 新功能
    • CalendarCard 组件新增可选属性 title,支持自定义日历卡片头部内容。
    • 新增示例 Demo,展示如何结合 Ref 和自定义标题使用 CalendarCard
  • 文档
    • 文档新增“搭配 Ref 使用自定义头”示例,并补充 title 属性说明及用法。

@xiaoyatong xiaoyatong requested a review from oasis-cloud June 26, 2025 11:14
@github-actions github-actions bot added action:review This PR needs more reviews (less than 2 approvals) 3.x Target branch 3.x labels Jun 26, 2025
Copy link

coderabbitai bot commented Jun 26, 2025

Walkthrough

本次变更为 CalendarCard 组件新增了可选的 title 属性,允许通过该属性自定义日历卡片的头部内容。相关类型声明、组件实现、文档及演示 demo 均已同步更新,并新增了一个结合 ref 和自定义头部的使用示例。

Changes

文件/路径分组 变更简述
src/packages/calendarcard/calendarcard.tsx
src/packages/calendarcard/calendarcard.taro.tsx
CalendarCard 组件新增可选 title 属性,支持自定义头部渲染逻辑
src/types/spec/calendarcard/base.ts BaseCalendarCard 接口新增 title: ReactNode 属性
src/packages/calendarcard/demo.tsx
src/packages/calendarcard/demo.taro.tsx
新增 Demo12 示例,演示自定义头部及 ref 的结合用法
src/packages/calendarcard/demos/h5/demo12.tsx
src/packages/calendarcard/demos/taro/demo12.tsx
新增 Demo1 组件,结合 ref 和自定义 title 属性演示用法
src/packages/calendarcard/doc.md
src/packages/calendarcard/doc.taro.md
src/packages/calendarcard/doc.zh-TW.md
src/packages/calendarcard/doc.en-US.md
文档新增 title 属性说明及相关示例,补充多语言支持

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant DemoComponent
    participant CalendarCard

    User->>DemoComponent: 点击自定义头部
    DemoComponent->>CalendarCard: 通过 ref 调用 jump(-1)
    CalendarCard-->>DemoComponent: 日历切换到上个月
    CalendarCard-->>DemoComponent: 触发 onPageChange 回调
    DemoComponent-->>User: 更新头部显示的月份
Loading

Suggested reviewers

  • xiaoyatong
  • oasis-cloud

Poem

🐰
日历卡片添新意,
自定义头部任你题。
Ref 联动翻前月,
代码示例更明晰。
兔子挥笔庆更新,
前端世界添活力!

✨ Finishing Touches
  • 📝 Generate Docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share
🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

  • Review comments: Directly reply to a review comment made by CodeRabbit. Example:
    • I pushed a fix in commit <commit_id>, please review it.
    • Explain this complex logic.
    • Open a follow-up GitHub issue for this discussion.
  • Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
    • @coderabbitai explain this code block.
    • @coderabbitai modularize this function.
  • PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
    • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
    • @coderabbitai read src/utils.ts and explain its main purpose.
    • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
    • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

  • @coderabbitai pause to pause the reviews on a PR.
  • @coderabbitai resume to resume the paused reviews.
  • @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
  • @coderabbitai full review to do a full review from scratch and review all the files again.
  • @coderabbitai summary to regenerate the summary of the PR.
  • @coderabbitai generate docstrings to generate docstrings for this PR.
  • @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
  • @coderabbitai resolve resolve all the CodeRabbit review comments.
  • @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
  • @coderabbitai help to get help.

Other keywords and placeholders

  • Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
  • Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
  • Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

  • You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
  • Please see the configuration documentation for more information.
  • If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

  • Visit our Documentation for detailed information on how to use CodeRabbit.
  • Join our Discord Community to get help, request features, and share feedback.
  • Follow us on X/Twitter for updates and announcements.

@oasis-cloud oasis-cloud merged commit c415f48 into jdf2e:feat_v3.x Jun 26, 2025
5 of 6 checks passed
Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

🧹 Nitpick comments (3)
src/packages/calendarcard/demos/taro/demo12.tsx (1)

8-8: 考虑改善月份显示格式!

当前 dateStr 存储的是基于0的月份值(0代表1月),显示时可能需要+1以便更好地理解。

-  const [dateStr, setDate] = useState(date.getMonth())
+  const [dateStr, setDate] = useState(date.getMonth() + 1)

并更新 onPageChange 处理器:

   const onPageChange = (val: any) => {
     console.log('onPageChange', val)
-    setDate(val.month)
+    setDate(val.month)
   }

注意:由于 onPageChange 回调中的 val.month 已经是1-based的月份值,所以这里不需要+1。

src/packages/calendarcard/demos/h5/demo12.tsx (2)

7-7: 月份状态初始化可能引起混淆

使用 date.getMonth() 初始化状态会返回 0-11 的值,但在显示文本中可能会让用户误解月份编号。建议考虑是否需要调整显示逻辑以保持一致性。

-  const [dateStr, setDate] = useState(date.getMonth())
+  const [dateStr, setDate] = useState(date.getMonth() + 1) // 转换为 1-12 月份显示

或者在显示时进行转换:

-          自定义头,当前2025-01-01,展示月份-1:{dateStr}
+          自定义头,当前2025-01-01,展示月份-1:{dateStr + 1}

8-11: 改进类型安全性

onPageChange 回调函数的参数类型为 any,建议使用更具体的类型定义以提高代码的类型安全性。

-  const onPageChange = (val: any) => {
+  const onPageChange = (val: { month: number; year: number }) => {
📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 27382ce and b14b8c0.

📒 Files selected for processing (11)
  • src/packages/calendarcard/calendarcard.taro.tsx (2 hunks)
  • src/packages/calendarcard/calendarcard.tsx (2 hunks)
  • src/packages/calendarcard/demo.taro.tsx (5 hunks)
  • src/packages/calendarcard/demo.tsx (5 hunks)
  • src/packages/calendarcard/demos/h5/demo12.tsx (1 hunks)
  • src/packages/calendarcard/demos/taro/demo12.tsx (1 hunks)
  • src/packages/calendarcard/doc.en-US.md (1 hunks)
  • src/packages/calendarcard/doc.md (1 hunks)
  • src/packages/calendarcard/doc.taro.md (1 hunks)
  • src/packages/calendarcard/doc.zh-TW.md (1 hunks)
  • src/types/spec/calendarcard/base.ts (1 hunks)
🧰 Additional context used
🧠 Learnings (2)
src/packages/calendarcard/demos/h5/demo12.tsx (2)
Learnt from: irisSong
PR: jdf2e/nutui-react#3209
File: src/packages/searchbar/searchbar.taro.tsx:111-124
Timestamp: 2025-05-02T01:45:09.576Z
Learning: 在 React/Taro 组件中使用 setTimeout 或 setInterval 时,应当在组件卸载时通过 useEffect 的清理函数清除定时器,以防止内存泄漏。可以使用 useState 存储定时器 ID,并在 useEffect 的返回函数中清除。
Learnt from: oasis-cloud
PR: jdf2e/nutui-react#2700
File: src/packages/animatingnumbers/animatingnumbers.harmony.css:25-32
Timestamp: 2024-11-06T05:56:06.800Z
Learning: 在优化 NutUI React 动画性能时,添加 `will-change` 属性可能会对布局产生影响,需要谨慎使用。
src/packages/calendarcard/demos/taro/demo12.tsx (1)
Learnt from: irisSong
PR: jdf2e/nutui-react#3209
File: src/packages/searchbar/searchbar.taro.tsx:111-124
Timestamp: 2025-05-02T01:45:09.576Z
Learning: 在 React/Taro 组件中使用 setTimeout 或 setInterval 时,应当在组件卸载时通过 useEffect 的清理函数清除定时器,以防止内存泄漏。可以使用 useState 存储定时器 ID,并在 useEffect 的返回函数中清除。
🧬 Code Graph Analysis (1)
src/packages/calendarcard/demos/taro/demo12.tsx (2)
src/types/spec/calendarcard/base.ts (1)
  • CalendarCardRef (19-22)
src/packages/calendarcard/calendarcard.taro.tsx (1)
  • CalendarCard (31-459)
🪛 LanguageTool
src/packages/calendarcard/doc.zh-TW.md

[locale-violation] ~115-~115: 'single' é un xenismo. É preferíbel dicir "cuarto individual"
Context: ...-- | --- | --- | --- | | type | 類型,單個日期 single,多個日期 multiple,日期範圍 range,周選擇 `week...

(GL_BARBARISM_REPLACE)


[locale-violation] ~115-~115: 'single' é un xenismo. É preferíbel dicir "cuarto individual"
Context: ...e,日期範圍 range,周選擇 week|string|single| | title | 自定义标题 |ReactNode|-` ...

(GL_BARBARISM_REPLACE)

src/packages/calendarcard/doc.taro.md

[locale-violation] ~115-~115: 'single' é un xenismo. É preferíbel dicir "cuarto individual"
Context: ...-- | --- | --- | --- | | type | 类型,单个日期 single,多个日期 multiple,日期范围 range,周选择 `week...

(GL_BARBARISM_REPLACE)


[locale-violation] ~115-~115: 'single' é un xenismo. É preferíbel dicir "cuarto individual"
Context: ...e,日期范围 range,周选择 week|string|single| | title | 自定义标题 |ReactNode|-` ...

(GL_BARBARISM_REPLACE)

src/packages/calendarcard/doc.md

[locale-violation] ~115-~115: 'single' é un xenismo. É preferíbel dicir "cuarto individual"
Context: ...-- | --- | --- | --- | | type | 类型,单个日期 single,多个日期 multiple,日期范围 range,周选择 `week...

(GL_BARBARISM_REPLACE)


[locale-violation] ~115-~115: 'single' é un xenismo. É preferíbel dicir "cuarto individual"
Context: ...e,日期范围 range,周选择 week|string|single| | title | 自定义标题 |ReactNode|-` ...

(GL_BARBARISM_REPLACE)

⏰ Context from checks skipped due to timeout of 90000ms (2)
  • GitHub Check: build
  • GitHub Check: test
🔇 Additional comments (19)
src/packages/calendarcard/doc.en-US.md (2)

101-107: 文档更新合理

新增的 demo 部分清晰地展示了如何使用 title 属性和 ref 的组合功能,有助于用户理解新特性的使用方法。


116-116: Props 文档更新准确

title 属性的文档说明准确,类型和默认值描述正确。

src/packages/calendarcard/demo.taro.tsx (3)

18-18: 导入语句正确添加

Demo12 组件的导入语句正确,与其他 demo 组件保持一致的命名和导入方式。


36-36: 多语言支持完整

为所有支持的语言(中文、繁体中文、英文)都正确添加了 title 标签,保持了国际化的完整性。

Also applies to: 52-52, 68-68


98-99: Demo 渲染逻辑正确

新 Demo 组件的渲染逻辑与其他 demo 保持一致,正确使用了本地化的标题。

src/packages/calendarcard/calendarcard.tsx (2)

39-39: Props 解构正确添加

title 属性正确添加到 props 解构中,与其他属性保持一致的处理方式。


454-454: 条件渲染逻辑实现正确

使用 {title || renderHeader()} 的条件渲染逻辑简洁且正确,当提供 title 时渲染自定义标题,否则渲染默认头部,完全符合需求。

src/packages/calendarcard/doc.md (2)

101-107: 中文文档更新合理

新增的 demo 部分"搭配 Ref 使用自定义头"清晰地展示了新功能的使用方法,标题描述准确。


116-116: Props 文档说明准确

title 属性的中文文档说明"自定义标题"简洁明了,类型和默认值描述正确。

src/packages/calendarcard/doc.zh-TW.md (2)

101-107: 文档更新正确!

新增的自定义头部演示部分标题和引用路径都正确,与新功能匹配。


116-116: 属性文档完整准确!

title 属性的类型、说明和默认值都正确记录。

src/packages/calendarcard/doc.taro.md (2)

101-107: Taro版本文档更新正确!

新增演示部分正确引用了 taro/demo12.tsx 文件,与Taro平台匹配。


116-116: 属性文档保持一致!

title 属性文档与其他版本保持一致,描述准确。

src/packages/calendarcard/demo.tsx (3)

14-14: 导入语句正确!

Demo12 导入路径正确。


32-32: 多语言支持完整!

为所有支持的语言版本(zh-CN、zh-TW、en-US)都添加了 title 翻译键,保持了国际化的完整性。

Also applies to: 48-48, 64-64


93-94: 演示渲染逻辑正确!

新演示的渲染逻辑与其他演示保持一致。

src/packages/calendarcard/calendarcard.taro.tsx (2)

40-40: Props解构正确添加!

title 属性正确添加到组件props解构中。


455-455: 条件渲染逻辑完美!

使用 {title || renderHeader()} 的条件渲染逻辑正确,当提供自定义title时使用title,否则使用默认头部,保持了向后兼容性。

src/packages/calendarcard/demos/h5/demo12.tsx (1)

20-20: 点击交互实现正确

使用 ref 调用 jump(-1) 方法来实现月份跳转的逻辑是正确的,很好地展示了自定义标题与组件 API 的结合使用。

@@ -24,6 +24,7 @@ export type CalendarCardRef = {
export interface BaseCalendarCard extends BaseProps {
// 日视图-选择一个日期 | 日视图-选择多个日期 | 日视图-选择范围 | 周视图-选择某一周
type: 'single' | 'multiple' | 'range' | 'week'
title: ReactNode
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

修正类型定义的一致性问题

title 属性应该标记为可选属性,因为在组件实现中它被当作可选属性使用。当前的类型定义会导致 TypeScript 类型检查错误。

应用此修改来修正类型定义:

-  title: ReactNode
+  title?: ReactNode
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
title: ReactNode
title?: ReactNode
🤖 Prompt for AI Agents
In src/types/spec/calendarcard/base.ts at line 27, the title property is
currently required but should be marked as optional to match its usage in the
component. Fix this by adding a question mark after the title property name to
indicate it is optional in the type definition.

onPageChange={onPageChange}
title={
<View onClick={() => CalendarCardRef.current?.jump(-1)}>
自定义头,当前2025-01-01,展示月份-1:{dateStr}
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

修复硬编码的日期显示!

标题中的"当前2025-01-01"是硬编码的,不会随日历变化更新。另外,显示逻辑说是"展示月份-1",但实际显示的是当前月份,存在逻辑不一致。

建议修复为:

-          自定义头,当前2025-01-01,展示月份-1:{dateStr}
+          自定义头,当前月份:{dateStr}月,点击回到上个月

或者如果要显示实际的月份-1,应该计算正确的值:

-          自定义头,当前2025-01-01,展示月份-1:{dateStr}
+          自定义头,点击回到上个月,当前月份:{dateStr}月
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
自定义头,当前2025-01-01,展示月份-1{dateStr}
自定义头,当前月份{dateStr}月,点击回到上个月
Suggested change
自定义头,当前2025-01-01,展示月份-1{dateStr}
自定义头,点击回到上个月,当前月份{dateStr}
🤖 Prompt for AI Agents
In src/packages/calendarcard/demos/taro/demo12.tsx at line 22, the date
"2025-01-01" is hardcoded and does not update with the calendar state, causing
inconsistency with the displayed month logic. Replace the hardcoded date string
with a dynamic value derived from the current calendar date state, and adjust
the displayed month to correctly show the previous month by calculating it from
the current date instead of showing the current month directly.

console.log('onPageChange', val)
setDate(val.month)
}
const CalendarCardRef = useRef<CalendarCardRef>(null)
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

修复变量命名冲突!

变量名 CalendarCardRef 与第2行导入的类型名冲突,这可能导致混淆。建议重命名变量。

-  const CalendarCardRef = useRef<CalendarCardRef>(null)
+  const calendarRef = useRef<CalendarCardRef>(null)

并相应更新第21行的引用:

-        <View onClick={() => CalendarCardRef.current?.jump(-1)}>
+        <View onClick={() => calendarRef.current?.jump(-1)}>
🤖 Prompt for AI Agents
In src/packages/calendarcard/demos/taro/demo12.tsx at line 13, the variable name
CalendarCardRef conflicts with the imported type name on line 2, causing
confusion. Rename the variable to a distinct name such as calendarCardRef and
update all its references accordingly, including the usage on line 21.

Comment on lines +19 to +23
title={
<div onClick={() => CalendarCardRef.current?.jump(-1)}>
自定义头,当前2025-01-01,展示月份-1:{dateStr}
</div>
}
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

自定义标题存在硬编码和逻辑不一致问题

自定义标题中存在以下问题:

  1. 硬编码的日期 "2025-01-01" 不会随实际状态更新
  2. 显示的月份值可能与用户期望不符(0-11 vs 1-12)

建议修改为动态显示当前状态:

      title={
-        <div onClick={() => CalendarCardRef.current?.jump(-1)}>
-          自定义头,当前2025-01-01,展示月份-1:{dateStr}
-        </div>
+        <div onClick={() => CalendarCardRef.current?.jump(-1)}>
+          自定义头部(点击跳转上月),当前显示月份:{dateStr + 1}
+        </div>
      }
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
title={
<div onClick={() => CalendarCardRef.current?.jump(-1)}>
自定义头,当前2025-01-01,展示月份-1{dateStr}
</div>
}
title={
<div onClick={() => CalendarCardRef.current?.jump(-1)}>
自定义头部(点击跳转上月),当前显示月份{dateStr + 1}
</div>
}
🤖 Prompt for AI Agents
In src/packages/calendarcard/demos/h5/demo12.tsx around lines 19 to 23, the
custom title contains a hardcoded date "2025-01-01" and the displayed month
offset may confuse users due to zero-based indexing. Replace the hardcoded date
with a dynamic value reflecting the current state and adjust the month display
to use 1-based indexing for clarity. Update the JSX to compute and show the
actual current date and month offset dynamically.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
3.x Target branch 3.x action:review This PR needs more reviews (less than 2 approvals) size/L
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants