@xiao-ying/miniapp-hooks 1.1.0 → 1.2.0

package/README.md

@@ -10,8 +10,10 @@ pnpm add @xiao-ying/miniapp-hooks @xiao-ying/miniapp-sdk react
 
 ## Hook 列表
 
+- `useAppearance()`：订阅宿主 appearance 变化，返回 `{ themeSeedColor }`。
+- `useThemeSeedColor()`：订阅宿主主题 seed color，返回 `#rrggbb` 字符串；旧引擎或缺字段时回退小应蓝 `#4da3ff`。
 - `useBrightness()`：订阅原生/浏览器亮度变化，返回 `{ brightness, isDark }`。
-- `useForeground()`：订阅前后台变化，返回 `{ isForeground }`。
+- `useForeground()`：订阅宿主提供的前后台提示（soft hint），返回 `{ isForeground }`。
 - `useMediaQuery()`：暴露注入的 `mediaQuery`（安全区、DPR、尺寸）。
 - `useStorage(key, options?)`：与 `xy.onStorageChange` 同步，提供 `value`、`loading`、`error` 以及 `setValue/remove/refresh`。
 - `useShare(input?)`：注册分享处理器，自动补齐默认 path/title。
@@ -26,16 +28,18 @@ pnpm add @xiao-ying/miniapp-hooks @xiao-ying/miniapp-sdk react
 ## 快速示例
 
 ```tsx
-import { useBrightness, useStorage } from '@xiao-ying/miniapp-hooks'
+import { useBrightness, useStorage, useThemeSeedColor } from '@xiao-ying/miniapp-hooks'
 
 const Preferences = () => {
   const { brightness, isDark } = useBrightness()
+  const themeSeedColor = useThemeSeedColor()
   const theme = isDark ? 'dark' : 'light'
   const storage = useStorage<string>('nickname', { defaultValue: '游客' })
 
   return (
     <div data-theme={theme}>
       <p>当前模式: {brightness}</p>
+      <p>主题色: {themeSeedColor}</p>
       <input
         value={storage.value ?? ''}
         onChange={(e) => storage.setValue(e.target.value)}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { useAppearance, useThemeSeedColor } from './use-appearance.js';
 export { useBrightness } from './use-brightness.js';
 export { useForeground } from './use-foreground.js';
 export { useMediaQuery, type UseMediaQueryResult } from './use-media-query.js';
@@ -7,5 +8,5 @@ export { useHapticFeedback, type UseHapticFeedbackOptions } from './use-haptic-f
 export { useSdkError, type UseSdkErrorOptions, type UseSdkErrorResult, type UseSdkErrorFilter } from './use-sdk-error.js';
 export { useHapticFeedback as useHapticPress } from './use-haptic-feedback.js';
 export { useAuthState } from './use-auth-state.js';
-export type { XYSdk, XYMediaQuery, XYSafeAreaInsets, XYViewportSize, XYBrightnessEvent, XYStorageEvent, XyShareData, XyShareHandlerPayload, MaybePromise } from '@xiao-ying/miniapp-sdk';
+export type { XYSdk, XYMediaQuery, XYSafeAreaInsets, XYViewportSize, XYBrightnessEvent, XYAppearance, XYAppearanceEvent, XYStorageEvent, XyShareData, XyShareHandlerPayload, MaybePromise } from '@xiao-ying/miniapp-sdk';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EACL,aAAa,EACb,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,0BAA0B,CAAA;AAC3F,OAAO,EACL,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAAE,iBAAiB,IAAI,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAElD,YAAY,EACV,KAAK,EACL,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,YAAY,EACb,MAAM,wBAAwB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EACL,aAAa,EACb,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,0BAA0B,CAAA;AAC3F,OAAO,EACL,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAAE,iBAAiB,IAAI,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAElD,YAAY,EACV,KAAK,EACL,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,YAAY,EACb,MAAM,wBAAwB,CAAA"}

package/dist/index.js

@@ -1,4 +1,5 @@
 'use client';
+export { useAppearance, useThemeSeedColor } from './use-appearance.js';
 export { useBrightness } from './use-brightness.js';
 export { useForeground } from './use-foreground.js';
 export { useMediaQuery } from './use-media-query.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,CAAA;AAEZ,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EACL,aAAa,EAEd,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,UAAU,EAGX,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,iBAAiB,EAAiC,MAAM,0BAA0B,CAAA;AAC3F,OAAO,EACL,WAAW,EAIZ,MAAM,oBAAoB,CAAA;AAC3B,yBAAyB;AACzB,OAAO,EAAE,iBAAiB,IAAI,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,CAAA;AAEZ,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EACL,aAAa,EAEd,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,UAAU,EAGX,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,iBAAiB,EAAiC,MAAM,0BAA0B,CAAA;AAC3F,OAAO,EACL,WAAW,EAIZ,MAAM,oBAAoB,CAAA;AAC3B,yBAAyB;AACzB,OAAO,EAAE,iBAAiB,IAAI,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/use-appearance.d.ts

@@ -0,0 +1,20 @@
+import { type XYAppearance } from '@xiao-ying/miniapp-sdk';
+/**
+ * 订阅宿主外观配置变化并返回当前 appearance。
+ *
+ * @returns `XYAppearance`，当前只包含 `{ themeSeedColor }`。
+ *
+ * @example
+ * const { themeSeedColor } = useAppearance()
+ */
+export declare const useAppearance: () => XYAppearance;
+/**
+ * 订阅宿主主题 seed color 变化。
+ *
+ * @returns 当前主题 seed color，格式为 `#rrggbb`。
+ *
+ * @example
+ * const themeSeedColor = useThemeSeedColor()
+ */
+export declare const useThemeSeedColor: () => string;
+//# sourceMappingURL=use-appearance.d.ts.map

package/dist/use-appearance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-appearance.d.ts","sourceRoot":"","sources":["../src/use-appearance.ts"],"names":[],"mappings":"AACA,OAAO,EAA+B,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAUvF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,QAAO,YAyBhC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,QAAO,MAAwC,CAAA"}

package/dist/use-appearance.js

@@ -0,0 +1,47 @@
+import { useEffect, useMemo, useState } from 'react';
+import { DEFAULT_XY_THEME_SEED_COLOR } from '@xiao-ying/miniapp-sdk';
+const readAppearance = () => {
+    try {
+        return xy.appearance();
+    }
+    catch (_) {
+        return { themeSeedColor: DEFAULT_XY_THEME_SEED_COLOR };
+    }
+};
+/**
+ * 订阅宿主外观配置变化并返回当前 appearance。
+ *
+ * @returns `XYAppearance`，当前只包含 `{ themeSeedColor }`。
+ *
+ * @example
+ * const { themeSeedColor } = useAppearance()
+ */
+export const useAppearance = () => {
+    const [appearance, setAppearance] = useState(() => readAppearance());
+    useEffect(() => {
+        if (typeof xy.onAppearanceChange !== 'function') {
+            return;
+        }
+        const unsubscribe = xy.onAppearanceChange((event) => {
+            setAppearance(event.appearance);
+        });
+        return () => {
+            if (typeof unsubscribe === 'function') {
+                unsubscribe();
+            }
+        };
+    }, []);
+    return useMemo(() => ({
+        themeSeedColor: appearance.themeSeedColor
+    }), [appearance.themeSeedColor]);
+};
+/**
+ * 订阅宿主主题 seed color 变化。
+ *
+ * @returns 当前主题 seed color，格式为 `#rrggbb`。
+ *
+ * @example
+ * const themeSeedColor = useThemeSeedColor()
+ */
+export const useThemeSeedColor = () => useAppearance().themeSeedColor;
+//# sourceMappingURL=use-appearance.js.map

package/dist/use-appearance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-appearance.js","sourceRoot":"","sources":["../src/use-appearance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AACpD,OAAO,EAAE,2BAA2B,EAAqB,MAAM,wBAAwB,CAAA;AAEvF,MAAM,cAAc,GAAG,GAAiB,EAAE;IACxC,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,UAAU,EAAE,CAAA;IACxB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,cAAc,EAAE,2BAA2B,EAAE,CAAA;IACxD,CAAC;AACH,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,GAAiB,EAAE;IAC9C,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,GAAG,QAAQ,CAAe,GAAG,EAAE,CAAC,cAAc,EAAE,CAAC,CAAA;IAElF,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,OAAO,EAAE,CAAC,kBAAkB,KAAK,UAAU,EAAE,CAAC;YAChD,OAAM;QACR,CAAC;QAED,MAAM,WAAW,GAAG,EAAE,CAAC,kBAAkB,CAAC,CAAC,KAAK,EAAE,EAAE;YAClD,aAAa,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;QACjC,CAAC,CAAC,CAAA;QAEF,OAAO,GAAG,EAAE;YACV,IAAI,OAAO,WAAW,KAAK,UAAU,EAAE,CAAC;gBACtC,WAAW,EAAE,CAAA;YACf,CAAC;QACH,CAAC,CAAA;IACH,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,CAAC;QACL,cAAc,EAAE,UAAU,CAAC,cAAc;KAC1C,CAAC,EACF,CAAC,UAAU,CAAC,cAAc,CAAC,CAC5B,CAAA;AACH,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAW,EAAE,CAAC,aAAa,EAAE,CAAC,cAAc,CAAA"}

package/dist/use-foreground.d.ts

@@ -1,5 +1,5 @@
 /**
- * 订阅前后台状态变化并返回当前前台状态。
+ * 订阅宿主提供的前后台提示并返回当前前台状态。
  *
  * @returns `{ isForeground }`。
  *

package/dist/use-foreground.js

@@ -1,6 +1,6 @@
 import { useEffect, useMemo, useState } from 'react';
 /**
- * 订阅前后台状态变化并返回当前前台状态。
+ * 订阅宿主提供的前后台提示并返回当前前台状态。
  *
  * @returns `{ isForeground }`。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiao-ying/miniapp-hooks",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "React hooks for @xiao-ying/miniapp-sdk to build reactive miniapp UIs",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -27,13 +27,13 @@
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
-    "@xiao-ying/miniapp-sdk": "^1.1.0"
+    "@xiao-ying/miniapp-sdk": "^1.3.2"
   },
   "devDependencies": {
-    "@types/react": "^19.2.5",
-    "react": "^19.2.0",
+    "@types/react": "^19.2.14",
+    "react": "^19.2.5",
     "typescript": "^5.9.3",
-    "@xiao-ying/miniapp-sdk": "^1.1.0"
+    "@xiao-ying/miniapp-sdk": "^1.3.2"
   },
   "scripts": {
     "build": "node ../scripts/clean-dist.mjs && tsc -p tsconfig.json",

package/src/index.ts

@@ -1,5 +1,6 @@
 'use client'
 
+export { useAppearance, useThemeSeedColor } from './use-appearance.js'
 export { useBrightness } from './use-brightness.js'
 export { useForeground } from './use-foreground.js'
 export {
@@ -29,6 +30,8 @@ export type {
   XYSafeAreaInsets,
   XYViewportSize,
   XYBrightnessEvent,
+  XYAppearance,
+  XYAppearanceEvent,
   XYStorageEvent,
   XyShareData,
   XyShareHandlerPayload,

package/src/use-appearance.ts

@@ -0,0 +1,55 @@
+import { useEffect, useMemo, useState } from 'react'
+import { DEFAULT_XY_THEME_SEED_COLOR, type XYAppearance } from '@xiao-ying/miniapp-sdk'
+
+const readAppearance = (): XYAppearance => {
+  try {
+    return xy.appearance()
+  } catch (_) {
+    return { themeSeedColor: DEFAULT_XY_THEME_SEED_COLOR }
+  }
+}
+
+/**
+ * 订阅宿主外观配置变化并返回当前 appearance。
+ *
+ * @returns `XYAppearance`，当前只包含 `{ themeSeedColor }`。
+ *
+ * @example
+ * const { themeSeedColor } = useAppearance()
+ */
+export const useAppearance = (): XYAppearance => {
+  const [appearance, setAppearance] = useState<XYAppearance>(() => readAppearance())
+
+  useEffect(() => {
+    if (typeof xy.onAppearanceChange !== 'function') {
+      return
+    }
+
+    const unsubscribe = xy.onAppearanceChange((event) => {
+      setAppearance(event.appearance)
+    })
+
+    return () => {
+      if (typeof unsubscribe === 'function') {
+        unsubscribe()
+      }
+    }
+  }, [])
+
+  return useMemo(
+    () => ({
+      themeSeedColor: appearance.themeSeedColor
+    }),
+    [appearance.themeSeedColor]
+  )
+}
+
+/**
+ * 订阅宿主主题 seed color 变化。
+ *
+ * @returns 当前主题 seed color，格式为 `#rrggbb`。
+ *
+ * @example
+ * const themeSeedColor = useThemeSeedColor()
+ */
+export const useThemeSeedColor = (): string => useAppearance().themeSeedColor

package/src/use-foreground.ts

@@ -1,6 +1,6 @@
 import { useEffect, useMemo, useState } from 'react'
 /**
- * 订阅前后台状态变化并返回当前前台状态。
+ * 订阅宿主提供的前后台提示并返回当前前台状态。
  *
  * @returns `{ isForeground }`。
  *