@bndynet/vue-site 1.4.0 → 1.5.0

package/README.md

@@ -117,7 +117,7 @@ Add `"dev": "vue-site dev"` (or `vs dev`) in `package.json` scripts if you like.
 | `auth` | Central authorization policy (`AuthConfig`) — see [Per-page authorization](#per-page-authorization-auth) |
 | `router` | History mode (`RouterConfig`) — `hash` (default) or HTML5 `web`; see [Router history](#router-history-router) |
 | `packageRepository` | Usually set by CLI from `package.json`; omit when using `createSiteApp` alone |
-| `custom` | Public application-specific values, available from `useSiteConfig().config.custom`; see [Custom client configuration](#custom-client-configuration-custom) |
+| `custom` | Public application-specific values, available from `useSiteConfig().config.custom` in components or `getSiteConfig().custom` elsewhere; see [Custom client configuration](#custom-client-configuration-custom) |
 | `env` | Dev/build options — see below |
 | `bootstrap` | Optional path from site root (e.g. `./bootstrap.ts`) — module loaded once before the Vue app |
 | `configureApp` | Optional `(app) => void \| Promise<void>` after router install, before `mount` (see [Local packages in `configureApp`](#local-packages-in-configureapp)) |
@@ -125,7 +125,7 @@ Add `"dev": "vue-site dev"` (or `vs dev`) in `package.json` scripts if you like.
 ### Custom client configuration (`custom`)
 
 Use `custom` for public, application-specific values that the framework should preserve without
-interpreting. They are available to every component through `useSiteConfig()`:
+interpreting:
 
 ```typescript
 // site.config.ts
@@ -144,6 +144,21 @@ const { config } = useSiteConfig()
 const apiBaseUrl = config.custom?.apiBaseUrl
 ```
 
+Ordinary modules such as `utils.ts` do not have Vue's injection context. Read the active config
+with `getSiteConfig()` instead:
+
+```typescript
+// utils/api.ts
+import { getSiteConfig } from '@bndynet/vue-site'
+
+export function getApiBaseUrl() {
+  return getSiteConfig().custom?.apiBaseUrl
+}
+```
+
+Call `getSiteConfig()` at runtime, after `createSiteApp()` has started. Do not evaluate it at the
+top level of a module imported by `site.config.ts`; the active config has not been registered yet.
+
 Use a different config file when the value changes between builds:
 
 ```typescript
@@ -639,7 +654,7 @@ app.mount('#app')
 
 Use a top-level `await` in your entry (or an async IIFE): `createSiteApp` is async and **awaits** `configureApp` when it returns a `Promise`. If you set optional `bootstrap` in config, that module loads before the app is created; if you omit `bootstrap`, that step is skipped.
 
-Exports: `createSiteApp`, `defineConfig`, `useTheme`, `useSiteConfig`, `useLocale`, `useLocalize`, `tk`, `resolveLocalized`, `resolveField`, `resolveMessage`, `mergeCatalog`, `flattenMessages`, `isMessageRef`, `localizedPage`, `builtinMessages`, `themeRefKey`, `localeRefKey`. Types: `SiteConfig`, `SiteEnvConfig`, `SiteViteConfig`, `SiteCustomConfig`, `SiteExternalLink`, `ShellConfig`, `ShellAction`, `ShellActionLoader`, `NavItem`, `StandalonePage`, `PageLayout`, `AuthRule`, `AuthContext`, `AuthConfig`, `RouterConfig`, `ThemeConfig`, `ThemeOption`, `ThemePaletteVars`, `ResolvedNavItem`, `I18nConfig`, `LocaleOption`, `LocaleCode`, `LocalizedString`, `IconRegistry`, `MessageRef`, `MessageTree`, `MessageCatalog`, `PageLoader`, `LocalizedPageOptions`.
+Exports: `createSiteApp`, `defineConfig`, `useTheme`, `useSiteConfig`, `getSiteConfig`, `useLocale`, `useLocalize`, `tk`, `resolveLocalized`, `resolveField`, `resolveMessage`, `mergeCatalog`, `flattenMessages`, `isMessageRef`, `localizedPage`, `builtinMessages`, `themeRefKey`, `localeRefKey`. Types: `SiteConfig`, `SiteEnvConfig`, `SiteViteConfig`, `SiteCustomConfig`, `SiteExternalLink`, `ShellConfig`, `ShellAction`, `ShellActionLoader`, `NavItem`, `StandalonePage`, `PageLayout`, `AuthRule`, `AuthContext`, `AuthConfig`, `RouterConfig`, `ThemeConfig`, `ThemeOption`, `ThemePaletteVars`, `ResolvedNavItem`, `I18nConfig`, `LocaleOption`, `LocaleCode`, `LocalizedString`, `IconRegistry`, `MessageRef`, `MessageTree`, `MessageCatalog`, `PageLoader`, `LocalizedPageOptions`.
 
 ### Theme in Vue pages (`useTheme`)
 

package/README.zh.md

@@ -112,15 +112,14 @@ npx vue-site build --base /app/
 | `auth` | 中心化的授权策略（`AuthConfig`）—— 参见[按页面授权](#按页面授权-auth) |
 | `router` | 历史模式（`RouterConfig`）—— `hash`（默认）或 HTML5 `web`；参见[路由历史](#路由历史-router) |
 | `packageRepository` | 通常由 CLI 从 `package.json` 设置；单独使用 `createSiteApp` 时可省略 |
-| `custom` | 公开的业务自定义配置，可通过 `useSiteConfig().config.custom` 读取；参见[自定义客户端配置](#自定义客户端配置-custom) |
+| `custom` | 公开的业务自定义配置；组件内通过 `useSiteConfig().config.custom` 读取，其他代码通过 `getSiteConfig().custom` 读取；参见[自定义客户端配置](#自定义客户端配置-custom) |
 | `env` | 开发/构建选项 —— 见下文 |
 | `bootstrap` | 可选的站点根目录相对路径（如 `./bootstrap.ts`）—— 在 Vue 应用之前加载一次的模块 |
 | `configureApp` | 可选的 `(app) => void \| Promise<void>`，在路由安装之后、`mount` 之前执行（参见 [`configureApp` 中的本地包](#在-configureapp-中使用本地包)） |
 
 ### 自定义客户端配置（`custom`）
 
-`custom` 用于存放框架无需解释、只需原样保留的公开业务配置。任何组件都可以通过
-`useSiteConfig()` 读取：
+`custom` 用于存放框架无需解释、只需原样保留的公开业务配置：
 
 ```typescript
 // site.config.ts
@@ -139,6 +138,20 @@ const { config } = useSiteConfig()
 const apiBaseUrl = config.custom?.apiBaseUrl
 ```
 
+`utils.ts` 等普通模块没有 Vue 注入上下文，应改用 `getSiteConfig()` 读取当前配置：
+
+```typescript
+// utils/api.ts
+import { getSiteConfig } from '@bndynet/vue-site'
+
+export function getApiBaseUrl() {
+  return getSiteConfig().custom?.apiBaseUrl
+}
+```
+
+请在 `createSiteApp()` 已开始执行后的运行时代码中调用 `getSiteConfig()`。不要在被
+`site.config.ts` 导入的模块顶层立即求值，因为此时当前配置尚未注册。
+
 如果不同构建环境使用不同的值，可以选择不同的配置文件：
 
 ```typescript
@@ -577,7 +590,7 @@ app.mount('#app')
 返回 `Promise` 时会 **await** 它。如果你在配置中设置了可选的 `bootstrap`，该模块会在应用创建前加载；
 如果省略 `bootstrap`，则跳过该步骤。
 
-导出：`createSiteApp`、`defineConfig`、`useTheme`、`useSiteConfig`、`useLocale`、`useLocalize`、`tk`、`resolveLocalized`、`resolveField`、`resolveMessage`、`mergeCatalog`、`flattenMessages`、`isMessageRef`、`localizedPage`、`builtinMessages`、`themeRefKey`、`localeRefKey`。类型：`SiteConfig`、`SiteEnvConfig`、`SiteViteConfig`、`SiteCustomConfig`、`SiteExternalLink`、`NavItem`、`StandalonePage`、`PageLayout`、`AuthRule`、`AuthContext`、`AuthConfig`、`RouterConfig`、`ThemeConfig`、`ThemeOption`、`ThemePaletteVars`、`ResolvedNavItem`、`I18nConfig`、`LocaleOption`、`LocaleCode`、`LocalizedString`、`MessageRef`、`MessageTree`、`MessageCatalog`、`PageLoader`、`LocalizedPageOptions`。
+导出：`createSiteApp`、`defineConfig`、`useTheme`、`useSiteConfig`、`getSiteConfig`、`useLocale`、`useLocalize`、`tk`、`resolveLocalized`、`resolveField`、`resolveMessage`、`mergeCatalog`、`flattenMessages`、`isMessageRef`、`localizedPage`、`builtinMessages`、`themeRefKey`、`localeRefKey`。类型：`SiteConfig`、`SiteEnvConfig`、`SiteViteConfig`、`SiteCustomConfig`、`SiteExternalLink`、`NavItem`、`StandalonePage`、`PageLayout`、`AuthRule`、`AuthContext`、`AuthConfig`、`RouterConfig`、`ThemeConfig`、`ThemeOption`、`ThemePaletteVars`、`ResolvedNavItem`、`I18nConfig`、`LocaleOption`、`LocaleCode`、`LocalizedString`、`MessageRef`、`MessageTree`、`MessageCatalog`、`PageLoader`、`LocalizedPageOptions`。
 
 ### 在 Vue 页面中使用主题（`useTheme`）
 

package/dist/composables/useSiteConfig.d.ts

@@ -10,5 +10,12 @@ export interface SiteContext {
 }
 /** Use `Symbol.for` so pages still inject context if Vite resolves the package twice. */
 export declare const siteContextKey: InjectionKey<SiteContext>;
+/** Register the configuration for access outside Vue's injection context. */
+export declare function registerSiteConfig(config: SiteConfig): void;
 export declare function provideSiteConfig(context: SiteContext): void;
+/**
+ * Return the active site configuration outside Vue's setup / injection context.
+ * `createSiteApp()` must have started before this function is called.
+ */
+export declare function getSiteConfig(): SiteConfig;
 export declare function useSiteConfig(): SiteContext;

package/dist/index.d.ts

@@ -6,8 +6,26 @@ export { useLocalize } from './composables/useLocalize';
 export { resolveLocalized, resolveField, resolveMessage, mergeCatalog, flattenMessages, tk, isMessageRef, localizedPage } from './i18n-utils';
 export type { LocalizedPageOptions, MessageCatalog } from './i18n-utils';
 export { builtinMessages } from './i18n-messages';
-export { useSiteConfig } from './composables/useSiteConfig';
+export { getSiteConfig, useSiteConfig } from './composables/useSiteConfig';
 export { builtinThemePalettes } from './theme/presets';
 export { ElMessage, ElMessageBox, ElNotification, } from 'element-plus';
 export type { SiteConfig, SiteEnvConfig, SiteViteConfig, SiteCustomConfig, SiteExternalLink, ShellConfig, ShellAction, ShellActionLoader, NavItem, StandalonePage, PageLayout, AuthRule, AuthContext, AuthConfig, RouterConfig, ThemeConfig, ThemeOption, ThemePaletteVars, ResolvedNavItem, LocaleCode, LocalizedString, IconRegistry, MessageRef, MessageTree, LocaleOption, I18nConfig, PageLoader, } from './types';
+/**
+ * Type-safe identity for a single config object. Use the single-argument form for a standalone
+ * config file.
+ *
+ * When composing multiple config files (e.g. `site.config.prod.ts` importing a shared
+ * `site.config.common.ts`), use the two-argument form so `custom` is deep-merged: properties
+ * from the base `custom` are preserved unless explicitly overridden.
+ *
+ * @example
+ * // site.config.common.ts
+ * export default defineConfig({ custom: { apiBaseUrl: '/api', appName: 'MyApp' }, ... })
+ *
+ * // site.config.prod.ts
+ * import common from './site.config.common'
+ * export default defineConfig(common, { custom: { apiBaseUrl: 'https://prod.example.com/api' } })
+ * // Result: custom.apiBaseUrl is overridden, custom.appName is preserved.
+ */
 export declare function defineConfig(config: SiteConfig): SiteConfig;
+export declare function defineConfig(base: SiteConfig, overrides: Partial<SiteConfig>): SiteConfig;