@napacitor/action-sheet 0.0.0-stage → 0.1.2-beta.3

package/README.md

@@ -1,3 +1,38 @@
-# 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/action-sheet
+
+原生操作表插件(与 [@capacitor/action-sheet](https://github.com/ionic-team/capacitor-plugins/tree/main/action-sheet) 对应)。
+
+## 用法
+
+```ts
+import { ActionSheet } from '@napacitor/action-sheet';
+
+const { index, canceled } = await ActionSheet.showActions({
+  title: '选择操作',
+  options: [
+    { title: '上传' },
+    { title: '分享' },
+    { title: '删除', style: ActionSheetButtonStyle.Destructive },
+  ],
+  cancelable: true,
+});
+console.log(index, canceled); // 2 false / -1 true(取消)
+```
+
+## 结构
+
+- `src/` —— TypeScript 源码(index / definitions / web)
+- `dist/` —— 构建产物(CJS + d.ts,已提交)
+- `maui/` —— .NET MAUI C# 实现(程序集 `Napacitor.ActionSheet`,运行时反射自动发现)
+
+原生实现映射:`Page.DisplayActionSheet`(Windows 上由 MAUI 落到 `ContentDialog` 风格的
+选择弹层)。返回的下标按 `options` 数组顺序,被取消时为 `-1`。
+
+## 与 Capacitor 的差异
+
+- **style / message / icon**:仅 iOS / web 有语义,MAUI 的 DisplayActionSheet 无对应
+  参数,原生端当前忽略(破坏性按钮样式需平台代码);
+- **cancelable**:为 true 时提供 'Cancel' 取消按钮,点击取消返回 `{index: -1, canceled: true}`;
+- **web**:Capacitor 依赖 pwa-elements 渲染样式化操作表,Napacitor 0.1 暂无对应 UI
+  元素,调用时抛出不支持错误;
+- 该插件需要 `Microsoft.Maui.Controls` 包引用(Page API 属于 Controls 层)。

package/dist/definitions.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @napacitor/action-sheet 类型定义。
+ * 原生操作表(映射 MAUI Page.DisplayActionSheet)。
+ */
+/** 按钮风格(仅 iOS 生效;其余平台忽略)。 */
+export declare enum ActionSheetButtonStyle {
+    /** 默认。 */
+    Default = "DEFAULT",
+    /** 破坏性操作(红色)。 */
+    Destructive = "DESTRUCTIVE",
+    /** 取消。 */
+    Cancel = "CANCEL"
+}
+/** 操作表按钮。 */
+export interface ActionSheetButton {
+    /** 按钮文案。 */
+    title: string;
+    /** 按钮风格(仅 iOS 生效;其余平台忽略)。 */
+    style?: ActionSheetButtonStyle;
+    /** 按钮图标(仅 web 生效)。 */
+    icon?: string;
+}
+/** showActions() 参数。 */
+export interface ShowActionsOptions {
+    /** 操作表标题。 */
+    title: string;
+    /** 标题下的消息(仅 iOS 生效)。 */
+    message?: string;
+    /** 可选项。 */
+    options: ActionSheetButton[];
+    /** 点击表外区域是否可取消(默认 false)。 */
+    cancelable?: boolean;
+}
+/** showActions() 返回值。 */
+export interface ShowActionsResult {
+    /** 被点击选项的下标(从 0 起);被取消时为 -1。 */
+    index: number;
+    /** 是否被取消。 */
+    canceled: boolean;
+}
+export interface ActionSheetPlugin {
+    /** 显示操作表。 */
+    showActions(options: ShowActionsOptions): Promise<ShowActionsResult>;
+}

package/dist/definitions.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * @napacitor/action-sheet 类型定义。
+ * 原生操作表(映射 MAUI Page.DisplayActionSheet)。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionSheetButtonStyle = void 0;
+/** 按钮风格(仅 iOS 生效;其余平台忽略)。 */
+var ActionSheetButtonStyle;
+(function (ActionSheetButtonStyle) {
+    /** 默认。 */
+    ActionSheetButtonStyle["Default"] = "DEFAULT";
+    /** 破坏性操作(红色)。 */
+    ActionSheetButtonStyle["Destructive"] = "DESTRUCTIVE";
+    /** 取消。 */
+    ActionSheetButtonStyle["Cancel"] = "CANCEL";
+})(ActionSheetButtonStyle || (exports.ActionSheetButtonStyle = ActionSheetButtonStyle = {}));

package/dist/index.d.ts

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

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.ActionSheet = void 0;
+/**
+ * @napacitor/action-sheet 入口。
+ */
+const core_1 = require("@napacitor/core");
+const ActionSheet = (0, core_1.registerPlugin)('ActionSheet', {
+    web: () => Promise.resolve().then(() => __importStar(require('./web'))).then((m) => new m.ActionSheetWeb()),
+});
+exports.ActionSheet = ActionSheet;
+__exportStar(require("./definitions"), exports);

package/dist/web.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @napacitor/action-sheet 浏览器实现。
+ * Capacitor 依赖 pwa-elements 渲染样式化操作表;Napacitor 0.1 暂无对应
+ * UI 元素,调用时抛出不支持错误。
+ */
+import type { ShowActionsOptions, ShowActionsResult } from './definitions';
+export declare class ActionSheetWeb {
+    showActions(_options: ShowActionsOptions): Promise<ShowActionsResult>;
+}

package/dist/web.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionSheetWeb = void 0;
+class ActionSheetWeb {
+    async showActions(_options) {
+        throw new Error('ActionSheet.showActions:web 平台需要 UI 元素支持(Napacitor 0.1 暂未提供)');
+    }
+}
+exports.ActionSheetWeb = ActionSheetWeb;

package/maui/ActionSheetPlugin.cs

@@ -0,0 +1,79 @@
+using Microsoft.Maui.ApplicationModel;
+using Microsoft.Maui.Controls;
+
+namespace Napacitor.Plugins.ActionSheet;
+
+/* ─── 参数 / 返回 DTO ─────────────────────────────────────── */
+
+/// <summary>操作表按钮。</summary>
+public class ActionSheetButton
+{
+    /// <summary>按钮文案。</summary>
+    public string? Title { get; set; }
+
+    /// <summary>按钮风格(DEFAULT/DESTRUCTIVE/CANCEL;仅 iOS 语义,当前忽略)。</summary>
+    public string? Style { get; set; }
+}
+
+/// <summary>showActions() 参数。</summary>
+public class ShowActionsOptions
+{
+    /// <summary>操作表标题。</summary>
+    public string? Title { get; set; }
+
+    /// <summary>标题下的消息(仅 iOS 语义,DisplayActionSheet 无对应参数)。</summary>
+    public string? Message { get; set; }
+
+    /// <summary>可选项。</summary>
+    public List<ActionSheetButton>? Options { get; set; }
+
+    /// <summary>点击表外区域是否可取消(默认 false)。</summary>
+    public bool? Cancelable { get; set; }
+}
+
+/// <summary>showActions() 返回值。</summary>
+public class ShowActionsResult
+{
+    /// <summary>被点击选项的下标(从 0 起);被取消时为 -1。</summary>
+    public int Index { get; set; } = -1;
+
+    /// <summary>是否被取消。</summary>
+    public bool Canceled { get; set; } = true;
+}
+
+/* ─── 插件主体 ─────────────────────────────────────────────── */
+
+/// <summary>
+/// ActionSheet 插件:原生操作表(映射 MAUI Page.DisplayActionSheet)。
+/// </summary>
+[NapacitorPlugin("ActionSheet")]
+public class ActionSheetPlugin : NapacitorPluginBase
+{
+    /// <summary>显示操作表;被取消时 index 为 -1、canceled 为 true。</summary>
+    [NapacitorMethod]
+    public async Task<ShowActionsResult> ShowActions(ShowActionsOptions options)
+    {
+        var buttons = options.Options?
+            .Where(o => !string.IsNullOrEmpty(o.Title))
+            .Select(o => o.Title!)
+            .ToArray() ?? Array.Empty<string>();
+        if (buttons.Length == 0)
+        {
+            throw new NapacitorException(
+                NapacitorException.InvalidArguments, "ActionSheet.showActions:options 不能为空");
+        }
+
+        var app = Application.Current;
+        var page = (app?.Windows?.FirstOrDefault()?.Page ?? app?.MainPage)
+            ?? throw new NapacitorException(
+                NapacitorException.Unavailable, "ActionSheet:当前无可用页面(宿主窗口尚未创建)");
+
+        // cancelable 时提供取消按钮(DisplayActionSheet 不传 cancel 则点外无法收起)
+        var cancel = options.Cancelable == true ? "Cancel" : null;
+        var choice = await MainThread.InvokeOnMainThreadAsync(
+            () => page.DisplayActionSheet(options.Title ?? string.Empty, cancel, null, buttons));
+
+        var index = choice is null ? -1 : Array.IndexOf(buttons, choice);
+        return new ShowActionsResult { Index = index, Canceled = index < 0 };
+    }
+}

package/maui/Napacitor.ActionSheet.csproj

@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <RootNamespace>Napacitor.Plugins.ActionSheet</RootNamespace>
+    <AssemblyName>Napacitor.ActionSheet</AssemblyName>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <LangVersion>latest</LangVersion>
+    <Description>Napacitor ActionSheet 插件(.NET MAUI 实现)</Description>
+    <Version>0.1.0</Version>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <!-- Page.DisplayActionSheet 需要 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/action-sheet",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@napacitor/action-sheet",
+  "version": "0.1.2-beta.3",
+  "description": "Napacitor ActionSheet 插件(原生操作表,映射 MAUI Page.DisplayActionSheet)",
+  "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" }
+}