alighasami/jordium-gantt-vue3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'master' into develop

Browse Source
This commit is contained in:
LINING-PC\lining
2025-12-23 12:22:05 +08:00
parent 8641c59583 5af8541363
commit 775a0d425c
8 changed files with 400 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
CHANGELOG.md
View File

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [1.6.2] - 2025-12-23
### Fixed
- 🔧 修复：I18n外部使用的问题
- 🔧 Fixed: Issue with using I18n externally
## [1.6.1] - 2025-12-15
### Fixed

214
README-EN.md
View File

@@ -2026,7 +2026,7 @@ const handleLanguageChange = (lang: 'zh-CN' | 'en-US') => {
#### Custom Translations
Override or extend default translations via `localeMessages` prop:
Pass custom multilingual text via the `localeMessages` prop, which will be automatically merged into the default translations:
```vue
<template>
@@ -2037,7 +2037,7 @@ Override or extend default translations via `localeMessages` prop:
const customMessages = {
"zh-CN": {
// Task list related
name: 'Task Name (Custom)',
taskName: 'Task Name (Custom)',
startDate: 'Start Date',
endDate: 'End Date',
duration: 'Duration',
@@ -2045,55 +2045,183 @@ const customMessages = {
predecessor: 'Predecessors',
assignee: 'Assignee',
estimatedHours: 'Estimated Hours',
actualHours: 'Actual Hours'
// Toolbar related
addTask: 'New Task',
addMilestone: 'New Milestone',
today: 'Today',
exportCsv: 'Export CSV',
exportPdf: 'Export PDF',
fullscreen: 'Fullscreen',
exitFullscreen: 'Exit Fullscreen',
language: 'Language',
theme: 'Theme',
expandAll: 'Expand All',
collapseAll: 'Collapse All'
// Internal Task editor related
title: 'Task Details',
titleEdit: 'Edit Task',
titleNew: 'New Task',
name: 'Task Name',
startDate: 'Start Date',
endDate: 'End Date',
assignee: 'Assignee',
predecessor: 'Predecessors',
description: 'Description',
estimatedHours: 'Estimated Hours',
actualHours: 'Actual Hours',
progress: 'Progress',
save: 'Save',
cancel: 'Cancel',
delete: 'Delete'
// Other texts
days: 'days',
hours: 'hours',
overtime: 'overtime',
overdue: 'overdue',
// ... More custom translations
// Custom fields (supports nested structure)
department: 'Department',
status: 'Status',
gantt: {
planEndDate: 'Plan End Date',
planStartDate: 'Plan Start Date'
}
},
"en-US": {......}
"en-US": {
department: 'Department',
status: 'Status',
gantt: {
planEndDate: 'Plan End Date',
planStartDate: 'Plan Start Date'
}
}
}
</script>
```
> **💡 Tip**：
> **💡 Tip**:
>
> - `localeMessages` adopts **deep merge** strategy, only need to pass fields that need to be overridden
> - supports nested objects, like `taskList.name`, `toolbar.addTask`, etc.
> - For complete translation keys, please refer to built-in `messages['zh-CN']` object in component
> - `localeMessages` uses a **deep merge** strategy, only pass fields that need to be overridden or added
> - Supports nested object structures, such as `gantt.planEndDate`
> - For complete built-in translation keys, please refer to `useI18n.ts` in the component source code
##### Using Translations in Custom Slots
The component exports the `useI18n` composable, which can be used in custom slots to access translation text. It supports two access methods:
**Method 1: Reactive Access (`t.field`)**
Access translation text directly through a reactive object, with concise syntax, suitable for use in templates:
```vue
<script setup>
import { GanttChart, TaskListColumn, useI18n } from 'jordium-gantt-vue3'
const { t } = useI18n()
const customMessages = {
'zh-CN': {
department: 'Department'
}
}
</script>
<template>
<GanttChart :tasks="tasks" :locale-messages="customMessages" />
<!-- Reactive access: directly through the t object -->
<TaskListColumn prop="startDate" label="Start Date" width="250">
<template #header>
<strong style="color: #1890ff;">{{ t.department }}</strong>
</template>
</TaskListColumn>
</template>
```
**Method 2: Function Access (`getTranslation()`)**
Supports nested keys and default values, suitable for accessing deep structures or dynamic keys:
```vue
<script setup>
import { GanttChart, TaskListColumn, useI18n } from 'jordium-gantt-vue3'
const { getTranslation } = useI18n()
const customMessages = {
'en-US': {
gantt: {
planEndDate: 'Plan End Date'
}
}
}
</script>
<template>
<GanttChart :tasks="tasks" :locale-messages="customMessages" />
<!-- Function access: supports nested keys and default values -->
<TaskListColumn prop="endDate" :label="getTranslation('gantt.planEndDate')" width="250" />
</template>
```
**Complete Example (with Language Switching):**
```vue
<script setup>
import { ref } from 'vue'
import { GanttChart, TaskListColumn, useI18n } from 'jordium-gantt-vue3'
// Custom multilingual configuration
const customMessages = {
'zh-CN': {
department: '部门',
gantt: {
planEndDate: '计划结束时间'
}
},
'en-US': {
department: 'Department',
gantt: {
planEndDate: 'Plan End Date'
}
}
}
// Use useI18n to access translations
const { t, getTranslation, locale, setLocale } = useI18n()
const tasks = ref([...])
// Language switching
const switchLanguage = () => {
setLocale(locale.value === 'zh-CN' ? 'en-US' : 'zh-CN')
}
</script>
<template>
<button @click="switchLanguage">Switch Language</button>
<GanttChart :tasks="tasks" :locale-messages="customMessages" />
<!-- Reactive access: directly through the t object -->
<TaskListColumn prop="startDate" label="Start Date" width="250">
<template #header>
<strong style="color: #1890ff;">{{ t.department }}</strong>
</template>
</TaskListColumn>
<!-- Function access: supports nested keys and default values -->
<TaskListColumn prop="endDate" :label="getTranslation('gantt.planEndDate')" width="250" />
</template>
```
**`useI18n` API Reference:**
| Export | Type | Description |
|--------|------|-------------|
| `t` | `Ref<object>` | Reactive translation object, access via `t.key` or `t.nested.key` |
| `getTranslation(key, defaultValue?)` | `Function` | Function-based access to translation text<br>• `key`: Translation key, supports nested paths (e.g., `'gantt.planEndDate'`)<br>• `defaultValue`: Optional, default value returned when translation is not found<br>• Returns: Translation text, default value, or the key itself |
| `formatTranslation(key, params)` | `Function` | Format translation text with parameters<br>• `key`: Translation key<br>• `params`: Parameter object, e.g., `{ name: 'Task1' }`<br>• Returns: Text with placeholders replaced (e.g., `'Task {name}'` → `'Task Task1'`) |
| `locale` | `Ref<string>` | Current language (`'zh-CN'` or `'en-US'`) |
| `setLocale(locale)` | `Function` | Switch language, automatically updates all components using `useI18n` |
| `formatYearMonth(year, month)` | `Function` | Format year-month display<br>• Chinese: `formatYearMonth(2024, 3)` → `'2024年03月'`<br>• English: `formatYearMonth(2024, 3)` → `'2024/03'` |
| `formatMonth(month)` | `Function` | Format month display<br>• Chinese: `formatMonth(3)` → `'3月'`<br>• English: `formatMonth(3)` → `'03'` |
**Usage Examples:**
```vue
<script setup>
import { useI18n } from 'jordium-gantt-vue3'
const { t, getTranslation, formatTranslation, formatYearMonth, formatMonth } = useI18n()
// 1. Basic access
const text1 = t.taskName // 'Task Name'
const text2 = getTranslation('gantt.planEndDate', 'Plan End') // 'Plan End Date' or default value
// 2. Translation with parameters
const message = formatTranslation('taskNotFound', { id: '123' }) // 'Task not found for update, ID: 123'
// 3. Date formatting
const yearMonth = formatYearMonth(2024, 3) // '2024年03月' (zh-CN) or '2024/03' (en-US)
const month = formatMonth(3) // '3月' (zh-CN) or '03' (en-US)
</script>
```
> **💡 Usage Tips**:
>
> - **Reactive access** (`t.key`): Concise syntax, suitable for direct use in templates
> - **Function access** (`getTranslation('nested.key', 'default')`): Supports nested keys and default values, suitable for accessing deep structures
> - Pass custom translations via the `localeMessages` prop, then access via `useI18n` to translate
> - Language switching is implemented via `setLocale()`, all components will automatically respond to updates
### Custom Extensions

212
README.md
View File

@@ -2017,7 +2017,7 @@ const handleLanguageChange = (lang: 'zh-CN' | 'en-US') => {
#### 自定义翻译
通过 `localeMessages` 属性覆盖或扩展默认翻译：
通过 `localeMessages` 属性传入自定义多语言文本，组件内部会自动合并到默认翻译中：
```vue
<template>
@@ -2028,7 +2028,7 @@ const handleLanguageChange = (lang: 'zh-CN' | 'en-US') => {
const customMessages = {
"zh-CN": {
// 任务列表相关
name: '任务名称（自定义）',
taskName: '任务名称（自定义）',
startDate: '开始日期',
endDate: '结束日期',
duration: '工期',
@@ -2036,55 +2036,183 @@ const customMessages = {
predecessor: '前置任务',
assignee: '负责人',
estimatedHours: '预估工时',
actualHours: '实际工时'
// 工具栏相关
addTask: '新建任务',
addMilestone: '新建里程碑',
today: '今天',
exportCsv: '导出 CSV',
exportPdf: '导出 PDF',
fullscreen: '全屏',
exitFullscreen: '退出全屏',
language: '语言',
theme: '主题',
expandAll: '全部展开',
collapseAll: '全部折叠'
// 内置任务编辑器相关
title: '任务详情',
titleEdit: '编辑任务',
titleNew: '新建任务',
name: '任务名称',
startDate: '开始日期',
endDate: '结束日期',
assignee: '负责人',
predecessor: '前置任务',
description: '描述',
estimatedHours: '预估工时',
actualHours: '实际工时',
progress: '进度',
save: '保存',
cancel: '取消',
delete: '删除'
// 其他文本
days: '天',
hours: '小时',
overtime: '超时',
overdue: '逾期',
// ... 更多自定义翻译
// 自定义字段（支持嵌套结构）
department: '部门',
status: '状态',
gantt: {
planEndDate: '计划结束时间',
planStartDate: '计划开始时间'
}
},
"en-US": {......}
"en-US": {
department: 'Department',
status: 'Status',
gantt: {
planEndDate: 'Plan End Date',
planStartDate: 'Plan Start Date'
}
}
}
</script>
```
> **💡 提示**：
>
> - `localeMessages` 采用**深度合并**策略，只需传递需要覆盖的字段即可
> - 支持嵌套对象，如 `taskList.name`、`toolbar.addTask` 等
> - 完整的翻译键请参考组件内置的 `messages['zh-CN']` 对象
> - `localeMessages` 采用**深度合并**策略，只需传递需要覆盖或新增的字段即可
> - 支持嵌套对象结构，如 `gantt.planEndDate`
> - 完整的内置翻译键请参考组件源码中的 `useI18n.ts`
##### 在自定义插槽中使用翻译
组件导出了 `useI18n` composable，可在自定义插槽中访问翻译文本，支持两种访问方式：
**方式一：引用式访问（`t.field`）**
通过响应式对象直接访问翻译文本，语法简洁，适合模板中使用：
```vue
<script setup>
import { GanttChart, TaskListColumn, useI18n } from 'jordium-gantt-vue3'
const { t } = useI18n()
const customMessages = {
'zh-CN': {
department: '部门'
}
}
</script>
<template>
<GanttChart :tasks="tasks" :locale-messages="customMessages" />
<!-- 引用式：直接通过 t 对象访问 -->
<TaskListColumn prop="startDate" label="开始时间" width="250">
<template #header>
<strong style="color: #1890ff;">{{ t.department }}</strong>
</template>
</TaskListColumn>
</template>
```
**方式二：函数式访问（`getTranslation()`）**
支持嵌套键和默认值，适合访问深层结构或动态键：
```vue
<script setup>
import { GanttChart, TaskListColumn, useI18n } from 'jordium-gantt-vue3'
const { getTranslation } = useI18n()
const customMessages = {
'zh-CN': {
gantt: {
planEndDate: '计划结束时间'
}
}
}
</script>
<template>
<GanttChart :tasks="tasks" :locale-messages="customMessages" />
<!-- 函数式：支持嵌套键和默认值 -->
<TaskListColumn prop="endDate" :label="getTranslation('gantt.planEndDate')" width="250" />
</template>
```
**完整示例（结合语言切换）：**
```vue
<script setup>
import { ref } from 'vue'
import { GanttChart, TaskListColumn, useI18n } from 'jordium-gantt-vue3'
// 自定义多语言配置
const customMessages = {
'zh-CN': {
department: '部门',
gantt: {
planEndDate: '计划结束时间'
}
},
'en-US': {
department: 'Department',
gantt: {
planEndDate: 'Plan End Date'
}
}
}
// 使用 useI18n 访问翻译
const { t, getTranslation, locale, setLocale } = useI18n()
const tasks = ref([...])
// 语言切换
const switchLanguage = () => {
setLocale(locale.value === 'zh-CN' ? 'en-US' : 'zh-CN')
}
</script>
<template>
<button @click="switchLanguage">切换语言</button>
<GanttChart :tasks="tasks" :locale-messages="customMessages" />
<!-- 引用式：直接通过 t 对象访问 -->
<TaskListColumn prop="startDate" label="开始时间" width="250">
<template #header>
<strong style="color: #1890ff;">{{ t.department }}</strong>
</template>
</TaskListColumn>
<!-- 函数式：支持嵌套键和默认值 -->
<TaskListColumn prop="endDate" :label="getTranslation('gantt.planEndDate')" width="250" />
</template>
```
**`useI18n` API 说明：**
| 导出项 | 类型 | 说明 |
|--------|------|------|
| `t` | `Ref<object>` | 响应式翻译对象，通过 `t.key` 或 `t.nested.key` 访问翻译文本 |
| `getTranslation(key, defaultValue?)` | `Function` | 函数式访问翻译文本<br>• `key`: 翻译键，支持嵌套路径（如 `'gantt.planEndDate'`）<br>• `defaultValue`: 可选，找不到翻译时返回的默认值<br>• 返回：翻译文本、默认值或 key 本身 |
| `formatTranslation(key, params)` | `Function` | 格式化带参数的翻译文本<br>• `key`: 翻译键<br>• `params`: 参数对象，如 `{ name: '任务1' }`<br>• 返回：替换占位符后的文本（如 `'任务{name}'` → `'任务任务1'`） |
| `locale` | `Ref<string>` | 当前语言（`'zh-CN'` 或 `'en-US'`） |
| `setLocale(locale)` | `Function` | 切换语言，会自动更新所有使用 `useI18n` 的组件 |
| `formatYearMonth(year, month)` | `Function` | 格式化年月显示<br>• 中文：`formatYearMonth(2024, 3)` → `'2024年03月'`<br>• 英文：`formatYearMonth(2024, 3)` → `'2024/03'` |
| `formatMonth(month)` | `Function` | 格式化月份显示<br>• 中文：`formatMonth(3)` → `'3月'`<br>• 英文：`formatMonth(3)` → `'03'` |
**使用示例：**
```vue
<script setup>
import { useI18n } from 'jordium-gantt-vue3'
const { t, getTranslation, formatTranslation, formatYearMonth, formatMonth } = useI18n()
// 1. 基础访问
const text1 = t.taskName // '任务名称'
const text2 = getTranslation('gantt.planEndDate', '计划结束') // '计划结束时间' 或默认值
// 2. 带参数的翻译
const message = formatTranslation('taskNotFound', { id: '123' }) // '未找到要更新的任务，ID：123'
// 3. 日期格式化
const yearMonth = formatYearMonth(2024, 3) // '2024年03月' (zh-CN) 或 '2024/03' (en-US)
const month = formatMonth(3) // '3月' (zh-CN) 或 '03' (en-US)
</script>
```
> **💡 使用提示**：
>
> - **引用式** (`t.key`)：语法简洁，适合模板中直接使用
> - **函数式** (`getTranslation('nested.key', 'default')`)：支持嵌套键和默认值，适合访问深层结构
> - 通过 `localeMessages` 属性传入自定义翻译，再通过 `useI18n` 访问并翻译
> - 语言切换通过 `setLocale()` 实现，所有组件会自动响应更新
### 自定义扩展

10
demo/version-history.json
View File

@@ -408,5 +408,15 @@
"🔧 修复：声明式Task List数据展示问题",
"🔧 Fixed: Declarative Task List data display issue"
]
},
{
"version": "1.6.2",
"date": "2025-12-23",
"notes": [
"🔧 修复：I18n外部使用的问题",
"<span style=\"font-weight: bold; color: #f00;\">特别感谢 he-shihao-3687@gitee的使用及反馈</span>",
"🔧 Fixed: Issue with external use of I18n",
"<span style=\"font-weight: bold; color: #f00;\">Special thanks to he-shihao-3687@gitee for their use and feedback</span>"
]
}
]

20
npm-demo/src/components/GanttTest.vue
View File

@@ -1,8 +1,10 @@
<script setup lang="ts">
import { ref } from 'vue'
import { GanttChart, TaskListColumn } from 'jordium-gantt-vue3'
import { GanttChart, TaskListColumn, useI18n } from 'jordium-gantt-vue3'
import 'jordium-gantt-vue3/dist/assets/jordium-gantt-vue3.css'
const { t, getTranslation } = useI18n();
const tasks = ref([
{
id: 1,
@@ -35,6 +37,10 @@ const customMessages = {
hours: '小时111',
overtime: '超时111',
overdue: '逾期111',
gantt: {
planStartDate: '计划开始时间',
//planEndDate: '计划结束时间',
}
},
'en-US': {
department: 'Department',
@@ -44,6 +50,10 @@ const customMessages = {
hours: 'Hour111',
overtime: 'OverTime111',
overdue: 'OverDue111',
gantt: {
planStartDate: 'Plan Start Date',
planEndDate: 'Plan End Date',
}
}
}
// const tasks = ref([])
@@ -228,8 +238,12 @@ const onTaskAdded = (res) => {
<span style="color: #52c41a;">{{ scope.row.name }}</span>
</template>
</TaskListColumn>
<TaskListColumn prop="startDate" label="开始时间" width="250" />
<TaskListColumn prop="endDate" label="结束时间" width="250" />
<TaskListColumn prop="startDate" label="开始时间" width="250">
<template #header>
<strong style="color: #1890ff;">{{ t.department }}</strong>
</template>
</TaskListColumn>
<TaskListColumn prop="endDate" :label="getTranslation('gantt.planEndDate', '结束的时间')" width="250" />
</GanttChart>
</div>
<!-- 自定义添加任务按钮 -->

2
package.json
View File

@@ -1,6 +1,6 @@
{
"name": "jordium-gantt-vue3",
"version": "1.6.1",
"version": "1.6.2",
"type": "module",
"main": "npm-package/dist/jordium-gantt-vue3.cjs.js",
"module": "npm-package/dist/jordium-gantt-vue3.es.js",

26
src/composables/useI18n.ts
View File

@@ -585,10 +585,28 @@ export function useI18n() {
return messages[currentLocale.value]
})
// 安全获取翻译文本的函数
const getTranslation = (key: string): string => {
const translation = t.value[key as keyof typeof t.value]
return typeof translation === 'string' ? translation : key
// 安全获取翻译文本的函数 - 支持多级键（如 'taskListConfig.title'）
const getTranslation = (key: string, defaultValue?: string): string => {
// 分割键路径
const keys = key.split('.')
// 从根对象开始递归访问
let value: any = t.value
for (const k of keys) {
if (value && typeof value === 'object' && k in value) {
value = value[k]
} else {
// 如果找不到，优先返回用户传入的 default，否则返回 key
return defaultValue || key
}
}
// 确保返回的是字符串
// 1. 如果找到了值且是字符串，返回该值
// 2. 如果值不是字符串，优先返回用户传入的 default
// 3. 否则返回 key
return typeof value === 'string' ? value : (defaultValue || key)
}
// 格式化带参数的翻译文本

3
src/index.ts
View File

@@ -11,6 +11,9 @@ export { default as TaskRow } from './components/TaskList/taskRow/TaskRow.vue'
export type { Task } from './models/classes/Task.ts' // 导出Task类型
export { useMessage } from './composables/useMessage.ts' // 导出useMessage组合式函数
// 导出 composables 供外部使用
export { useI18n } from './composables/useI18n'
// 导出配置类型
export type {
TaskListConfig,