@napacitor/app 0.0.0-stage → 0.1.2-beta.3

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @napacitor/app
+
+应用生命周期插件(与 [@capacitor/app](https://github.com/ionic-team/capacitor-plugins/tree/main/app) 对应)。
+
+## 用法
+
+```ts
+import { App } from '@napacitor/app';
+
+const { isActive } = await App.getState();
+const { value: language } = await App.getAppLanguage(); // 'zh-CN'
+
+App.addListener('appStateChange', ({ isActive }) => console.log('active:', isActive));
+App.addListener('pause', () => console.log('进入后台'));
+App.addListener('resume', () => console.log('回到前台'));
+App.addListener('appUrlOpen', ({ url }) => console.log('深度链接:', url));
+App.addListener('backButton', ({ canGoBack }) => console.log('返回键'));
+
+const { url } = await App.getLaunchUrl();
+```
+
+## 结构
+
+- `src/` —— TypeScript 源码(index / definitions / web)
+- `dist/` —— 构建产物(CJS + d.ts,已提交)
+- `maui/` —— .NET MAUI C# 实现(程序集 `Napacitor.App`,运行时反射自动发现)
+
+原生实现映射:Window 生命周期事件 `Resumed / Stopped / Backgrounding`
+(appStateChange / pause / resume)、`Application.Quit`(exitApp)、
+`CultureInfo.CurrentUICulture`(getAppLanguage)。首个生命周期监听器注册(或首次
+`getState`)后惰性挂接主 Window。
+
+## 与 Capacitor 的差异
+
+- **exitApp**:映射 `Application.Quit`,仅 Windows/macOS 有原生语义;Android/iOS 系统
+  不鼓励程序化退出(HIG/Play 政策),如需强退需宿主平台代码;
+- **appUrlOpen / getLaunchUrl(深度链接)**:MAUI 无跨平台的 App Link 事件,宿主需
+  ①注册 URL scheme,②在 `App.xaml.cs` 转发:
+
+  ```csharp
+  protected override void OnAppLinkRequestReceived(Uri uri)
+  {
+      base.OnAppLinkRequestReceived(uri);
+      Napacitor.Plugins.App.AppPlugin.NotifyAppLink(uri);
+  }
+  ```
+
+  URL scheme 注册:Android 在 `AndroidManifest.xml` 的 MainActivity 加
+  `<intent-filter>`(`<data android:scheme="your-scheme" />`);iOS 在 `Info.plist` 加
+  `CFBundleURLTypes`;Windows 打包应用在 `Package.appxmanifest` 声明协议;
+- **backButton(Android)**:宿主在 `MainActivity` 重写返回键并转发:
+
+  ```csharp
+  public override void OnBackPressed()
+  {
+      if (!AppPlugin.NotifyBackButton())
+      {
+          base.OnBackPressed(); // 无 JS 监听器时走默认行为
+      }
+  }
+  ```
+
+  `NotifyBackButton` 返回 true 表示 JS 已监听(宿主应拦截本次返回键);
+- **appRestoredResult / minimizeApp / edgeGesture**:暂未实现。

package/dist/definitions.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @napacitor/app 类型定义。
+ * 应用生命周期 / 退出 / 语言 / 启动链接
+ * (映射 MAUI Window 生命周期事件 + Application.Quit + CultureInfo)。
+ */
+import type { PluginListenerHandle } from '@napacitor/core';
+/** 应用状态。 */
+export interface AppState {
+    /** 应用是否处于活跃状态(前台且可交互)。 */
+    isActive: boolean;
+}
+/** getAppLanguage() 返回值。 */
+export interface AppLanguage {
+    /** 应用语言(BCP-47 风格,如 'zh-CN';无法识别时退回 ISO 双字母)。 */
+    value: string;
+}
+/** getLaunchUrl() / appUrlOpen 事件载荷。 */
+export interface AppUrl {
+    /** 深度链接地址;未收到过时为空字符串。 */
+    url: string;
+}
+/** backButton 事件载荷。 */
+export interface BackButtonResponse {
+    /** WebView 历史是否可回退(宿主未提供时为 false)。 */
+    canGoBack: boolean;
+}
+export interface AppPlugin {
+    /** 退出应用(Windows/macOS 有效;Android/iOS 系统不鼓励程序化退出,见 README)。 */
+    exitApp(): Promise<void>;
+    /** 获取应用当前状态。 */
+    getState(): Promise<AppState>;
+    /** 获取触发应用启动的深度链接(需宿主注册 URL scheme 并转发,见 README)。 */
+    getLaunchUrl(): Promise<AppUrl>;
+    /** 获取应用语言。 */
+    getAppLanguage(): Promise<AppLanguage>;
+    /** 应用前后台切换时派发(payload 为 {isActive})。 */
+    addListener(eventName: 'appStateChange', listenerFunc: (state: AppState) => void): Promise<PluginListenerHandle> & PluginListenerHandle;
+    /** 应用进入后台时派发。 */
+    addListener(eventName: 'pause', listenerFunc: () => void): Promise<PluginListenerHandle> & PluginListenerHandle;
+    /** 应用回到前台时派发。 */
+    addListener(eventName: 'resume', listenerFunc: () => void): Promise<PluginListenerHandle> & PluginListenerHandle;
+    /** 应用经深度链接打开/唤起时派发(需宿主转发,见 README)。 */
+    addListener(eventName: 'appUrlOpen', listenerFunc: (data: AppUrl) => void): Promise<PluginListenerHandle> & PluginListenerHandle;
+    /** Android 硬件返回键按下时派发(需宿主转发,见 README)。 */
+    addListener(eventName: 'backButton', listenerFunc: (data: BackButtonResponse) => void): Promise<PluginListenerHandle> & PluginListenerHandle;
+    /** 移除该插件全部监听器。 */
+    removeAllListeners(): Promise<void>;
+}

package/dist/definitions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { AppPlugin } from './definitions';
+declare const App: AppPlugin;
+export * from './definitions';
+export { App };

package/dist/index.js

@@ -0,0 +1,38 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.App = void 0;
+/**
+ * @napacitor/app 入口。
+ */
+const core_1 = require("@napacitor/core");
+const App = (0, core_1.registerPlugin)('App', {
+    web: () => Promise.resolve().then(() => __importStar(require('./web'))).then((m) => new m.AppWeb()),
+});
+exports.App = App;
+__exportStar(require("./definitions"), exports);

package/dist/web.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @napacitor/app 浏览器实现(基于 document.visibilitychange 映射生命周期)。
+ */
+import type { PluginListenerHandle } from '@napacitor/core';
+import type { AppLanguage, AppState, AppUrl } from './definitions';
+type AnyCallback = (...args: any[]) => void;
+export declare class AppWeb {
+    private _listeners;
+    private _visibilityHandler;
+    exitApp(): Promise<void>;
+    getState(): Promise<AppState>;
+    getLaunchUrl(): Promise<AppUrl>;
+    getAppLanguage(): Promise<AppLanguage>;
+    addListener(eventName: string, callback: AnyCallback): Promise<PluginListenerHandle>;
+    removeAllListeners(): Promise<void>;
+    private _emit;
+    private _ensureVisibility;
+}
+export {};

package/dist/web.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppWeb = void 0;
+class AppWeb {
+    constructor() {
+        this._listeners = {};
+        this._visibilityHandler = null;
+    }
+    async exitApp() {
+        throw new Error('App.exitApp:浏览器不支持退出应用');
+    }
+    async getState() {
+        return { isActive: !document.hidden };
+    }
+    async getLaunchUrl() {
+        return { url: window.location.href };
+    }
+    async getAppLanguage() {
+        return { value: navigator.language || 'en' };
+    }
+    async addListener(eventName, callback) {
+        if (!this._listeners[eventName]) {
+            this._listeners[eventName] = [];
+        }
+        this._listeners[eventName].push(callback);
+        this._ensureVisibility();
+        return {
+            remove: async () => {
+                const arr = this._listeners[eventName];
+                if (arr) {
+                    const idx = arr.indexOf(callback);
+                    if (idx >= 0)
+                        arr.splice(idx, 1);
+                }
+            },
+        };
+    }
+    async removeAllListeners() {
+        this._listeners = {};
+        if (this._visibilityHandler) {
+            document.removeEventListener('visibilitychange', this._visibilityHandler);
+            this._visibilityHandler = null;
+        }
+    }
+    _emit(event, data) {
+        var _a;
+        ((_a = this._listeners[event]) !== null && _a !== void 0 ? _a : []).forEach((cb) => cb(data));
+    }
+    _ensureVisibility() {
+        if (this._visibilityHandler)
+            return;
+        this._visibilityHandler = () => {
+            const active = !document.hidden;
+            this._emit('appStateChange', { isActive: active });
+            this._emit(active ? 'resume' : 'pause');
+        };
+        document.addEventListener('visibilitychange', this._visibilityHandler);
+    }
+}
+exports.AppWeb = AppWeb;

package/maui/AppPlugin.cs

@@ -0,0 +1,184 @@
+using System.Globalization;
+using Microsoft.Maui.ApplicationModel;
+using Microsoft.Maui.Controls;
+
+namespace Napacitor.Plugins.App;
+
+/* ─── 返回 / 事件 DTO ─────────────────────────────────────── */
+
+/// <summary>应用状态。</summary>
+public class AppStateResult
+{
+    public bool IsActive { get; set; } = true;
+}
+
+/// <summary>getAppLanguage() 返回值。</summary>
+public class AppLanguageResult
+{
+    public string Value { get; set; } = string.Empty;
+}
+
+/// <summary>getLaunchUrl() / appUrlOpen 事件载荷。</summary>
+public class AppUrlResult
+{
+    public string Url { get; set; } = string.Empty;
+}
+
+/// <summary>backButton 事件载荷。</summary>
+public class AppBackButtonResult
+{
+    public bool CanGoBack { get; set; }
+}
+
+/* ─── 插件主体 ─────────────────────────────────────────────── */
+
+/// <summary>
+/// App 插件:应用生命周期 / 退出 / 语言 / 启动链接
+/// (映射 MAUI Window 生命周期事件 + Application.Quit + CultureInfo)。
+///
+/// 事件管线:首个 JS 监听器注册(或首次 getState)后,惰性挂接主 Window 的
+/// Resumed / Stopped / Backgrounding 事件(移动端前后台 + 桌面 Stop/Display),
+/// 状态变化经 appStateChange / pause / resume 派发。
+///
+/// 平台差异说明:appUrlOpen(深度链接)与 backButton(Android 返回键)MAUI 无
+/// 跨平台可订阅事件,宿主需少量平台代码转发到 <see cref="NotifyAppLink"/> /
+/// <see cref="NotifyBackButton"/>(见插件 README)。
+/// </summary>
+[NapacitorPlugin("App")]
+public class AppPlugin : NapacitorPluginBase
+{
+    private const string AppStateChangeEvent = "appStateChange";
+    private const string PauseEvent = "pause";
+    private const string ResumeEvent = "resume";
+    private const string AppUrlOpenEvent = "appUrlOpen";
+    private const string BackButtonEvent = "backButton";
+
+    /// <summary>当前插件实例(供宿主静态转发入口使用)。</summary>
+    private static AppPlugin? _current;
+
+    /// <summary>启动 / 最近一次收到的深度链接(宿主经 NotifyAppLink 写入)。</summary>
+    private static string? _launchUrl;
+
+    private Window? _window;
+    private bool _hooked;
+    private bool _isActive = true;
+
+    public AppPlugin()
+    {
+        _current = this;
+    }
+
+    /// <summary>获取应用当前状态(顺带惰性挂接生命周期钩子)。</summary>
+    [NapacitorMethod]
+    public Task<AppStateResult> GetState()
+    {
+        EnsureWindowHooked();
+        return Task.FromResult(new AppStateResult { IsActive = _isActive });
+    }
+
+    /// <summary>获取应用语言(CultureInfo.CurrentUICulture)。</summary>
+    [NapacitorMethod]
+    public Task<AppLanguageResult> GetAppLanguage()
+    {
+        var culture = CultureInfo.CurrentUICulture;
+        var value = string.IsNullOrEmpty(culture.Name)
+            ? culture.TwoLetterISOLanguageName
+            : culture.Name;
+        return Task.FromResult(new AppLanguageResult { Value = value });
+    }
+
+    /// <summary>获取启动深度链接(未收到过时 url 为空字符串)。</summary>
+    [NapacitorMethod]
+    public Task<AppUrlResult> GetLaunchUrl()
+    {
+        return Task.FromResult(new AppUrlResult { Url = _launchUrl ?? string.Empty });
+    }
+
+    /// <summary>退出应用(Windows/macOS 有效;移动端见 README 平台差异)。</summary>
+    [NapacitorMethod]
+    public Task ExitApp()
+    {
+        MainThread.BeginInvokeOnMainThread(() => Application.Current?.Quit());
+        return Task.CompletedTask;
+    }
+
+    /// <summary>生命周期事件首个监听器注册时惰性挂接主 Window。</summary>
+    protected override void OnListenerAdded(string eventName)
+    {
+        EnsureWindowHooked();
+    }
+
+    /* ── 宿主转发入口(深度链接 / Android 返回键)── */
+
+    /// <summary>
+    /// 宿主在 App.xaml.cs 的 OnAppLinkRequestReceived 重写中调用:
+    /// 记录启动链接并向 JS 派发 appUrlOpen 事件(插件实例尚未创建时仅记录,
+    /// getLaunchUrl 仍可读到)。
+    /// </summary>
+    public static void NotifyAppLink(Uri uri)
+    {
+        _launchUrl = uri.ToString();
+        _current?.NotifyListeners(AppUrlOpenEvent, new AppUrlResult { Url = _launchUrl });
+    }
+
+    /// <summary>
+    /// 宿主在 Android MainActivity 的 OnBackPressed 重写中调用:
+    /// 向 JS 派发 backButton 事件(无 JS 监听器时返回 false,走系统默认行为)。
+    /// </summary>
+    public static bool NotifyBackButton(bool canGoBack = false)
+    {
+        var plugin = _current;
+        if (plugin is null || plugin.ListenerCount(BackButtonEvent) == 0)
+        {
+            return false;
+        }
+        plugin.NotifyListeners(BackButtonEvent, new AppBackButtonResult { CanGoBack = canGoBack });
+        return true; // 已消费:宿主应拦截本次返回键
+    }
+
+    /* ── Window 生命周期挂接 ── */
+
+    private void EnsureWindowHooked()
+    {
+        if (_hooked)
+        {
+            return;
+        }
+        MainThread.BeginInvokeOnMainThread(() =>
+        {
+            if (_hooked)
+            {
+                return;
+            }
+            var window = Application.Current?.Windows?.FirstOrDefault();
+            if (window is null)
+            {
+                return; // 窗口尚未创建:下次 getState / OnListenerAdded 再试
+            }
+
+            _window = window;
+            _hooked = true;
+            window.Resumed += OnWindowResumed;       // 移动端回到前台
+            window.Stopped += OnWindowStopped;       // 移动端/桌面进入后台
+            window.Backgrounding += OnWindowBackgrounding; // iOS 即将转后台
+        });
+    }
+
+    private void OnWindowResumed(object? sender, EventArgs e) => SetActive(true);
+
+    private void OnWindowStopped(object? sender, EventArgs e) => SetActive(false);
+
+    private void OnWindowBackgrounding(object? sender, BackgroundingEventArgs e) =>
+        SetActive(false);
+
+    private void SetActive(bool active)
+    {
+        if (_isActive == active)
+        {
+            return;
+        }
+        _isActive = active;
+        NotifyListeners(AppStateChangeEvent, new AppStateResult { IsActive = active });
+        NotifyListeners(active ? ResumeEvent : PauseEvent, null);
+    }
+}

package/maui/Napacitor.App.csproj

@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <RootNamespace>Napacitor.Plugins.App</RootNamespace>
+    <AssemblyName>Napacitor.App</AssemblyName>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <LangVersion>latest</LangVersion>
+    <Description>Napacitor App 插件(.NET MAUI 实现)</Description>
+    <Version>0.1.0</Version>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <!-- Window 生命周期事件 / Application.Quit 需要 Controls 层 -->
+    <PackageReference Include="Microsoft.Maui.Essentials" Version="10.0.20" />
+    <PackageReference Include="Microsoft.Maui.Controls" Version="10.0.20" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\maui\src\Napacitor.csproj" Condition="Exists('..\..\maui\src\Napacitor.csproj')" />
+    <ProjectReference Include="..\..\..\maui\src\Napacitor.csproj" Condition="!Exists('..\..\maui\src\Napacitor.csproj')" />
+  </ItemGroup>
+
+</Project>

package/package.json

@@ -1,6 +1,13 @@
-{
-  "name": "@napacitor/app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@napacitor/app",
+  "version": "0.1.2-beta.3",
+  "description": "Napacitor App 插件(应用生命周期/退出/语言/启动链接,映射 MAUI 应用生命周期)",
+  "homepage": "https://github.com/jevonsflash/napacitor",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist/", "maui/", "!maui/bin/", "!maui/obj/"],
+  "scripts": { "build": "tsc", "type-check": "tsc --noEmit" },
+  "peerDependencies": { "@napacitor/core": "^0.1.0" },
+  "devDependencies": { "@napacitor/core": "^0.1.0", "typescript": "~5.4.5" }
+}