From 887de70aa0585de8afa0ba908bf0656e3ddc6595 Mon Sep 17 00:00:00 2001 From: Mister-Hope Date: Sun, 23 Mar 2025 21:05:32 +0800 Subject: [PATCH 1/2] feat(plugin-git): improve composables and add docs --- docs/plugins/development/git.md | 125 ++++++++++++++++++ docs/zh/plugins/development/git.md | 125 ++++++++++++++++++ .../plugin-theme-data/theme-data.spec.ts | 1 - .../src/client/components/GitChangelog.ts | 4 +- .../src/client/composables/useChangelog.ts | 11 +- .../src/client/composables/useContributors.ts | 11 +- .../src/client/composables/useLastUpdated.ts | 28 +++- .../src/client/components/VPPageMeta.vue | 32 +++-- .../src/client/composables/index.ts | 2 - .../src/client/composables/useContributors.ts | 19 --- .../src/client/composables/useLastUpdated.ts | 20 --- .../node/utils/assignDefaultLocaleOptions.ts | 1 - 12 files changed, 308 insertions(+), 71 deletions(-) delete mode 100644 themes/theme-default/src/client/composables/useContributors.ts delete mode 100644 themes/theme-default/src/client/composables/useLastUpdated.ts diff --git a/docs/plugins/development/git.md b/docs/plugins/development/git.md index 5c295e0724..25029a3dc9 100644 --- a/docs/plugins/development/git.md +++ b/docs/plugins/development/git.md @@ -269,6 +269,131 @@ gitInclude: Whether to collect the change history for the current page, this value will override the [changelog](#changelog) configuration item. +## Composables + +You can import the following composables from `@vuepress/plugin-git/client`. + +### useChangelog + +Get the changelog of the current page. + +```ts +export interface GitChangelogItem { + /** + * Commit hash + */ + hash: string + /** + * Unix timestamp in milliseconds + */ + time: number + /** + * Commit message + */ + message: string + /** + * The url of the commit + */ + commitUrl?: string + /** + * release tag + */ + tag?: string + /** + * The url of the release tag + */ + tagUrl?: string + /** + * Commit author name + */ + author: string + /** + * Commit author email + */ + email: string + + /** + * The co-authors of the commit + */ + coAuthors?: CoAuthorInfo[] + /** + * Date text of the commit + */ + date: string +} + +export const useChangelog: ( + enabled?: MaybeRefOrGetter, +) => ComputedRef +``` + +### useContributors + +Get the contributors of the current page. + +```ts +export interface GitContributorInfo { + /** + * Contributor display name + */ + name: string + /** + * Contributor email + */ + email: string + + /** + * Contributor username on the git hosting service + */ + username: string + /** + * Number of commits + */ + commits: number + /** + * Contributor avatar + */ + avatar?: string + /** + * The url of the contributor + */ + url?: string +} + +export const useContributors: ( + enabled?: MaybeRefOrGetter, +) => ComputedRef +``` + +### useLastUpdated + +Get the last updated time of the current page. + +```ts +export interface LastUpdated { + /** + * The date object of the last updated time + */ + date: Date + /** + * The ISO string of the last updated time + */ + iso: string + /** + * The formatted text of the last updated time + */ + text: string + /** + * The locale of the last updated time + */ + locale: string +} + +export const useLastUpdated: ( + enabled?: MaybeRefOrGetter, +) => ComputedRef +``` + ## Page Data This plugin will add a `git` field to page data. diff --git a/docs/zh/plugins/development/git.md b/docs/zh/plugins/development/git.md index 29137002af..ff1ac34b4b 100644 --- a/docs/zh/plugins/development/git.md +++ b/docs/zh/plugins/development/git.md @@ -258,6 +258,131 @@ gitInclude: 当前页面是否获取变更历史记录，该值会覆盖 [changelog](#changelog) 配置项。 +## 可组合式 API + +你可以从 `@vuepress/plugin-git/client` 中导入以下可组合式 API。 + +### useChangelog + +获取当前页面的变更历史记录。 + +```ts +export interface GitChangelogItem { + /** + * Commit hash + */ + hash: string + /** + * Unix timestamp in milliseconds + */ + time: number + /** + * Commit message + */ + message: string + /** + * The url of the commit + */ + commitUrl?: string + /** + * release tag + */ + tag?: string + /** + * The url of the release tag + */ + tagUrl?: string + /** + * Commit author name + */ + author: string + /** + * Commit author email + */ + email: string + + /** + * The co-authors of the commit + */ + coAuthors?: CoAuthorInfo[] + /** + * Date text of the commit + */ + date: string +} + +export const useChangelog: ( + enabled?: MaybeRefOrGetter, +) => ComputedRef +``` + +### useContributors + +获取当前页面的贡献者信息。 + +```ts +export interface GitContributorInfo { + /** + * Contributor display name + */ + name: string + /** + * Contributor email + */ + email: string + + /** + * Contributor username on the git hosting service + */ + username: string + /** + * Number of commits + */ + commits: number + /** + * Contributor avatar + */ + avatar?: string + /** + * The url of the contributor + */ + url?: string +} + +export const useContributors: ( + enabled?: MaybeRefOrGetter, +) => ComputedRef +``` + +### useLastUpdated + +获取当前页面的最后更新时间。 + +```ts +export interface LastUpdated { + /** + * The date object of the last updated time + */ + date: Date + /** + * The ISO string of the last updated time + */ + iso: string + /** + * The formatted text of the last updated time + */ + text: string + /** + * The locale of the last updated time + */ + locale: string +} + +export const useLastUpdated: ( + enabled?: MaybeRefOrGetter, +) => ComputedRef +``` + ## 页面数据 该插件会向页面数据中添加一个 `git` 字段。 diff --git a/e2e/tests/plugin-theme-data/theme-data.spec.ts b/e2e/tests/plugin-theme-data/theme-data.spec.ts index f958412100..6b26156736 100644 --- a/e2e/tests/plugin-theme-data/theme-data.spec.ts +++ b/e2e/tests/plugin-theme-data/theme-data.spec.ts @@ -71,7 +71,6 @@ test.describe('plugin-theme-data', () => { editLink: true, editLinkText: 'Edit this page', lastUpdated: true, - lastUpdatedText: 'Last Updated', contributors: true, contributorsText: 'Contributors', notFound: [ diff --git a/plugins/development/plugin-git/src/client/components/GitChangelog.ts b/plugins/development/plugin-git/src/client/components/GitChangelog.ts index a6e408068c..bef44da8a7 100644 --- a/plugins/development/plugin-git/src/client/components/GitChangelog.ts +++ b/plugins/development/plugin-git/src/client/components/GitChangelog.ts @@ -29,7 +29,7 @@ export const GitChangelog = defineComponent({ setup(props) { const changelog = useChangelog() const locale = useGitLocaleConfig() - const latestUpdated = useLastUpdated() + const lastUpdated = useLastUpdated() const [active, toggleActive] = useToggle() @@ -40,7 +40,7 @@ export const GitChangelog = defineComponent({ [ h('div', { class: 'vp-latest-updated' }, [ h('span', { class: 'vp-changelog-icon' }), - h('span', { 'data-allow-mismatch': '' }, latestUpdated.value!.text), + h('span', { 'data-allow-mismatch': '' }, lastUpdated.value!.text), ]), h('div', [ h('span', { class: 'vp-changelog-menu-icon' }), diff --git a/plugins/development/plugin-git/src/client/composables/useChangelog.ts b/plugins/development/plugin-git/src/client/composables/useChangelog.ts index b65aaa6071..8fec210f87 100644 --- a/plugins/development/plugin-git/src/client/composables/useChangelog.ts +++ b/plugins/development/plugin-git/src/client/composables/useChangelog.ts @@ -1,5 +1,5 @@ -import type { ComputedRef } from 'vue' -import { computed } from 'vue' +import type { ComputedRef, MaybeRefOrGetter } from 'vue' +import { computed, toValue } from 'vue' import { usePageData, usePageFrontmatter, usePageLang } from 'vuepress/client' import type { GitChangelogInfo, @@ -19,7 +19,9 @@ const RE_ISSUE = /#(\d+)/g export const useChangelog = typeof __GIT_CHANGELOG__ === 'boolean' && __GIT_CHANGELOG__ - ? (): ComputedRef => { + ? ( + enabled: MaybeRefOrGetter = true, + ): ComputedRef => { const frontmatter = usePageFrontmatter() const lang = usePageLang() const page = usePageData() @@ -28,7 +30,8 @@ export const useChangelog = const repo = resolveRepoLink(gitOptions.repo, provider) return computed(() => { - if (frontmatter.value.changelog === false) return [] + if (frontmatter.value.changelog === false || !toValue(enabled)) + return [] const formatter = new Intl.DateTimeFormat(lang.value, { dateStyle: 'short', diff --git a/plugins/development/plugin-git/src/client/composables/useContributors.ts b/plugins/development/plugin-git/src/client/composables/useContributors.ts index 7aeeb61f71..15d06f771d 100644 --- a/plugins/development/plugin-git/src/client/composables/useContributors.ts +++ b/plugins/development/plugin-git/src/client/composables/useContributors.ts @@ -1,5 +1,5 @@ -import type { ComputedRef } from 'vue' -import { computed } from 'vue' +import type { ComputedRef, MaybeRefOrGetter } from 'vue' +import { computed, toValue } from 'vue' import { usePageData, usePageFrontmatter } from 'vuepress/client' import type { GitContributorInfo, @@ -11,12 +11,15 @@ declare const __GIT_CONTRIBUTORS__: boolean export const useContributors = typeof __GIT_CONTRIBUTORS__ === 'boolean' && __GIT_CONTRIBUTORS__ - ? (): ComputedRef => { + ? ( + enabled: MaybeRefOrGetter = true, + ): ComputedRef => { const frontmatter = usePageFrontmatter() const page = usePageData() return computed(() => { - if (frontmatter.value.contributors === false) return [] + if (frontmatter.value.contributors === false || !toValue(enabled)) + return [] // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition return page.value.git?.contributors ?? [] diff --git a/plugins/development/plugin-git/src/client/composables/useLastUpdated.ts b/plugins/development/plugin-git/src/client/composables/useLastUpdated.ts index 7ff3dfefb2..26482407c9 100644 --- a/plugins/development/plugin-git/src/client/composables/useLastUpdated.ts +++ b/plugins/development/plugin-git/src/client/composables/useLastUpdated.ts @@ -1,21 +1,38 @@ -import type { ComputedRef } from 'vue' -import { computed } from 'vue' +import type { ComputedRef, MaybeRefOrGetter } from 'vue' +import { computed, toValue } from 'vue' import { usePageData, usePageLang } from 'vuepress/client' import type { GitPluginPageData } from '../../shared/index.js' import { useGitLocaleConfig } from './useGitLocales.js' export interface LastUpdated { + /** + * The date object of the last updated time + */ date: Date + /** + * The ISO string of the last updated time + */ iso: string + /** + * The formatted text of the last updated time + */ text: string + /** + * The locale of the last updated time + */ + locale: string } -export const useLastUpdated = (): ComputedRef => { +export const useLastUpdated = ( + enabled: MaybeRefOrGetter = true, +): ComputedRef => { const lang = usePageLang() const locale = useGitLocaleConfig() const page = usePageData() return computed(() => { + if (!toValue(enabled)) return null + const timeStamp = // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition page.value.git?.updatedTime ?? page.value.git?.changelog?.[0].time @@ -24,15 +41,16 @@ export const useLastUpdated = (): ComputedRef => { const date = new Date(timeStamp) - const formatted = new Intl.DateTimeFormat(lang.value, { + const text = new Intl.DateTimeFormat(lang.value, { dateStyle: 'short', timeStyle: 'short', }).format(timeStamp) return { date, + text, iso: date.toISOString(), - text: `${locale.value.latestUpdateAt} ${formatted}`, + locale: locale.value.latestUpdateAt, } }) } diff --git a/themes/theme-default/src/client/components/VPPageMeta.vue b/themes/theme-default/src/client/components/VPPageMeta.vue index ecb69821fc..7b86799cc8 100644 --- a/themes/theme-default/src/client/components/VPPageMeta.vue +++ b/themes/theme-default/src/client/components/VPPageMeta.vue @@ -1,15 +1,19 @@