feat(components): add notice component

demo/components/src/.vuepress/config.ts

@@ -49,6 +49,23 @@ export default defineUserConfig({
         "YouTube",
       ],
       iconAssets: "iconfont",
+      notice: {
+        locales: {
+          "/": {
+            title: "Notice Title",
+            content: "Notice Content",
+            actions: [
+              {
+                text: "Primary Action",
+                link: "https://vuepress-theme-hope.github.io/",
+                type: "primary",
+              },
+              { text: "Default Action" },
+            ],
+          },
+        },
+        fullscreen: true,
+      },
     }),
   ],
 });

demo/components/src/demo/README.md

@@ -4,6 +4,8 @@
 
 - BackToTop (Global Components)
 
+- Notice (Global Components)
+
 - [Badge](badge.md)
 
 - [BiliBili](bilibili.md)

docs/components/src/config.md

@@ -104,3 +104,82 @@ Link of font icon asset, `'iconfont'` and `'fontawesome'` keywords are supported
 - Default: Inferred from iconAssets
 
 Class prefix of font icon
+
+## notice
+
+- Type: `NoticeOptions`
+
+  ```ts
+  interface NoticeLocaleOptions {
+    /**
+     * Notice title
+     */
+    title: string;
+
+    /**
+     * Notice content
+     */
+    content: string;
+
+    /**
+     * Notice footer
+     */
+    actions: {
+      /**
+       * Action text
+       */
+      text: string;
+      /**
+       * Action link
+       */
+      link?: string;
+      /**
+       * Action type
+       *
+       * @default 'default
+       */
+      type?: "primary" | "default";
+    }[];
+  }
+
+  interface NoticeOptions {
+    /**
+     * Notice locales Options
+     */
+    locales: Record<string, NoticeLocaleOptions>;
+
+    /**
+     * Notice key
+     *
+     * @description Used to identify and store the notice status
+     */
+    key?: string;
+
+    /**
+     * Whether show notice only once or show it in every visit
+     *
+     * @description If `key` is not provided, this option will be ignored
+     *
+     * @default false
+     */
+    showOnce?: string;
+
+    /**
+     * Whether the user can close the notice
+     *
+     * @default true
+     */
+    canClose?: boolean;
+
+    /**
+     * Whether the notice should appear fullscreen
+     *
+     * @default false
+     */
+    fullscreen?: boolean;
+  }
+  ```
+
+- Required: No
+
+Config for global notice.

docs/components/src/guide/README.md

@@ -12,7 +12,7 @@ For example, if you call this plugin with `{ backToTop: true }`, then only `<Bac
 
 :::
 
-This plugin can register 8 components and 2 global components:
+This plugin can register 8 components and 3 global components:
 
 - [AddThis](addthis.md) (Global Components)
 
@@ -26,6 +26,8 @@ This plugin can register 8 components and 2 global components:
 
 - [FontIcon](fonticon.md)
 
+- [Notice](notice.md) (Global Components)
+
 - [PDF](pdf.md)
 
 - [StackBlitz](stackblitz.md)

docs/components/src/guide/notice.md

@@ -0,0 +1,101 @@
+---
+title: Notice
+---
+
+The plugin provides a global component `Notice` for you to show some notices to your visitors.
+
+You can configure it via `notice` option in plugin options.
+
+<!-- more -->
+
+## Usage
+
+You should set `notice.locale`, where the key is locale path and the value is the notice configuration.
+
+Notice configuration includes:
+
+- `title`: Notice title, support both text and HTMLString
+- `content`: Notice content, support both text and HTMLString
+- `actions`: Notice actions
+
+  Should be an array of objects containing:
+
+  - `text`: action text
+  - `link`: action link (optional).
+
+    Pathname will be treated as internal route link and handled by router, and absolute links will be treated as external link and being opened in new window.
+
+  - `type`: `"default"` or `"primary"` (optional)
+
+    Default value is `"default"`.
+
+Here is an example:
+
+```ts
+import { componentsPlugin } from "vuepress-plugin-components";
+
+export default {
+  plugins: [
+    componentsPlugin({
+      notice: {
+        locales: {
+          "/": {
+            title: "Notice",
+            content: "You may want to check official docs",
+            actions: [
+              {
+                text: "Check it now",
+                link: "https://vuepress-theme-hope.github.io/v2/components/notice.html",
+                type: "primary",
+              },
+              { text: "Later" },
+            ],
+          },
+          "/zh/": {
+            title: "通知",
+            content: "你可能想要查看官方文档",
+            actions: [
+              {
+                text: "现在查看",
+                link: "https://vuepress-theme-hope.github.io/v2/components/notice.html",
+                type: "primary",
+              },
+              { text: "稍后" },
+            ],
+          },
+        },
+      },
+    }),
+  ],
+};
+```
+
+## Advanced
+
+Also, we provide some advanced option for you to control notice display.
+
+::: info Notice Display Control
+
+By default, the notice will be shown whenever users enter the site, and it will remain closed in this time if users close it.
+
+To prevent notice being shown again in next visit after users close it, you can set `notice.showOnce: true` in plugin options.
+
+Also, notice remembering is based on notice title and notice content, you can set `noticeKey` option to use a key you want, so that you can edit notice without bothering users who already confirm them.
+
+:::
+
+::: info Close logic
+
+By default, there will be a close button on the right of notice, and users can close it by clicking it.
+
+However if you want users to confirm the notice, you can set `notice.canClose: false` and set a confirm action with only text, so that users can only close the notice by hitting the confirm button.
+
+:::
+
+::: info Fullscreen
+
+If you want to display a fullscreen popup, you can use `notice.fullscreen: true` in plugin options. We recommend you to use this together with `notice.canClose: false`.
+
+The notice will display in the center of screen, and the other places will be covered by a blur mask.
+
+:::

docs/components/src/zh/config.md

@@ -104,3 +104,82 @@ AddThis 的公开 ID。
 - 默认值: 尝试从 iconAssets 推断
 
 字体图标的 Class 前缀
+
+## notice
+
+- Type: `NoticeOptions`
+
+  ```ts
+  interface NoticeLocaleOptions {
+    /**
+     * 通知标题
+     */
+    title: string;
+
+    /**
+     * 通知内容
+     */
+    content: string;
+
+    /**
+     * 通知操作
+     */
+    actions: {
+      /**
+       * 操作文字
+       */
+      text: string;
+      /**
+       * 操作链接
+       */
+      link?: string;
+      /**
+       * 操作类型
+       *
+       * @default 'default
+       */
+      type?: "primary" | "default";
+    }[];
+  }
+
+  interface NoticeOptions {
+    /**
+     * Notice 多语言选项
+     */
+    locales: Record<string, NoticeLocaleOptions>;
+
+    /**
+     * Notice 的 key
+     *
+     * @description 用于标识和存储 notice 的状态
+     */
+    key?: string;
+
+    /**
+     * 是否只显示一次通知
+     *
+     * @description 如果没有提供 `key`，此选项将被忽略
+     *
+     * @default false
+     */
+    showOnce?: string;
+
+    /**
+     * 用户是否可以关闭通知
+     *
+     * @default true
+     */
+    canClose?: boolean;
+
+    /**
+     * 通知是否应该全屏显示
+     *
+     * @default false
+     */
+    fullscreen?: boolean;
+  }
+  ```
+
+- 必填: 否
+
+全局通知的配置

docs/components/src/zh/guide/README.md

@@ -12,7 +12,7 @@ title: 指南
 
 :::
 
-此插件可以注册 8 个组件和 2 个全局组件:
+此插件可以注册 8 个组件和 3 个全局组件:
 
 - [AddThis](addthis.md) (全局组件)
 
@@ -26,6 +26,8 @@ title: 指南
 
 - [FontIcon](fonticon.md)
 
+- [Notice](notice.md) (全局组件)
+
 - [PDF](pdf.md)
 
 - [StackBlitz](stackblitz.md)