feat: 初始化 Halo 暗色模式插件

- Halo Plugin 后端（Java/Gradle），含 DarkModePlugin 主类和测试 - Vue 3 + TypeScript 前端 UI，包含主题切换组件和设置页面 - 暗色模式 CSS 变量和覆盖样式（布局/编辑器/表单/滚动条等） - 设计文档和调查文档 - Halo 插件/主题开发 Agent Skills Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-06 21:03:00 +08:00
commit edbf78f236
115 changed files with 14745 additions and 0 deletions
@@ -0,0 +1,103 @@
+# @halo-dev/ui-shared Utilities
+
+Available from Halo 2.22. Requires plugin `spec.requires: ">=2.22.0"`.
+
+## Stores (Pinia)
+
+Install Pinia: `pnpm install pinia`
+
+### currentUser
+
+```ts
+import { stores } from "@halo-dev/ui-shared";
+import { storeToRefs } from "pinia";
+
+const userStore = stores.currentUser();
+await userStore.fetchCurrentUser();
+
+console.log(userStore.currentUser?.user.metadata.name);
+console.log(userStore.isAnonymous);
+
+// Reactive refs
+const { currentUser, isAnonymous } = storeToRefs(stores.currentUser());
+```
+
+| Property      | Type                        | Description                  |
+| ------------- | --------------------------- | ---------------------------- |
+| `currentUser` | `DetailedUser \| undefined` | Current user info            |
+| `isAnonymous` | `boolean`                   | Whether visitor is anonymous |
+
+### globalInfo
+
+```ts
+const globalInfoStore = stores.globalInfo();
+await globalInfoStore.fetchGlobalInfo();
+
+console.log(globalInfoStore.globalInfo?.externalUrl);
+console.log(globalInfoStore.globalInfo?.siteTitle);
+```
+
+| Property     | Type                      | Description                                                                                            |
+| ------------ | ------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `globalInfo` | `GlobalInfo \| undefined` | Site config: externalUrl, siteTitle, timeZone, locale, allowComments, allowRegistration, favicon, etc. |
+
+## Utils
+
+### date (dayjs-based)
+
+Dayjs is already bundled in `@halo-dev/ui-shared` and exposed via `utils.date`. **Always use this for any date handling in plugin UI code — do NOT install `dayjs`, `date-fns`, or any other date library, and do NOT write your own date formatting functions.**
+
+```ts
+import { utils } from "@halo-dev/ui-shared";
+
+utils.date.format(new Date()); // "2025-11-05 14:30"
+utils.date.format("2025-10-22", "YYYY/MM/DD"); // "2025/10/22"
+utils.date.toISOString(new Date()); // ISO string
+utils.date.toDatetimeLocal(new Date()); // "2025-10-22T14:30"
+utils.date.timeAgo("2025-10-23"); // "1 天后"
+utils.date.dayjs(); // raw dayjs instance for advanced usage
+```
+
+### permission
+
+```ts
+utils.permission.has(["core:posts:manage"]); // any match
+utils.permission.has(["core:posts:manage", "core:posts:delete"], false); // all match
+utils.permission.getUserPermissions(); // string[]
+```
+
+### attachment
+
+```ts
+// Generate thumbnail URL
+utils.attachment.getThumbnailUrl("/uploads/image.jpg", "M"); // "?width=800"
+// Sizes: "XL" (1600), "L" (1200), "M" (800), "S" (400)
+
+// Extract URL from various attachment formats
+utils.attachment.getUrl(attachmentObject);
+
+// Convert to simplified format
+utils.attachment.convertToSimple(attachmentObject);
+// -> { url: "...", alt?: "...", mediaType?: "..." }
+```
+
+### id
+
+```ts
+utils.id.uuid(); // UUID v7 (time-sortable)
+```
+
+## Events
+
+```ts
+import { events } from "@halo-dev/ui-shared";
+
+// Listen for plugin config updates
+events.on("core:plugin:configMap:updated", (data) => {
+  console.log(`Plugin ${data.pluginName} config updated, group: ${data.group}`);
+});
+```
+
+| Event                           | Payload                                 | Description                  |
+| ------------------------------- | --------------------------------------- | ---------------------------- |
+| `core:plugin:configMap:updated` | `{ pluginName: string, group: string }` | Plugin configuration changed |