@ohos-cpf/3rdloop 0.0.11 → 0.0.13

package/vendor/Server/Skills/flutter-demo-code-generator/assets/PAGE_TEMPLATES.md

@@ -0,0 +1,544 @@
+# Flutter Demo 页面代码模板
+
+本文件提供 `flutter-demo-code-generator` 技能生成代码时使用的标准模板，可直接复制并替换占位符。按接口类型选择模板一/二/三，主导航与应用入口使用模板四/五。
+
+---
+
+## 模板一：Demo 页面（异步接口）
+
+**文件路径**：`lib/pages/{序号}_{snake_case描述}/{snake_case描述}_page.dart`
+
+```dart
+/// Demo {序号}: {英文功能描述（PascalCase）}
+///
+/// 功能说明：{从 Demo 描述文档提取的详细描述}
+/// 对应接口：
+///   - {接口签名 1}
+///   - {接口签名 2}
+
+import 'dart:developer' as dev;
+
+import 'package:flutter/material.dart';
+import 'package:{三方库包名}/{导入路径}';
+
+// ─── 日志 Tag ─────────────────────────────────────────────────────────────
+const String _kTag = '{LibraryName}_{UpperCamelCase组件名}';
+
+/// {UpperCamelCase组件名}Page - {Demo 功能一句话说明}
+///
+/// 展示 {库名} 的 {核心功能} 使用方法。
+class {UpperCamelCase组件名}Page extends StatefulWidget {
+  const {UpperCamelCase组件名}Page({super.key});
+
+  @override
+  State<{UpperCamelCase组件名}Page> createState() =>
+      _{UpperCamelCase组件名}PageState();
+}
+
+class _{UpperCamelCase组件名}PageState
+    extends State<{UpperCamelCase组件名}Page> {
+  // ─── 状态变量（所有需要触发 UI 更新的变量） ────────────────────────────
+  String _resultText = '';
+  bool _isLoading = false;
+
+  // ─── 非响应式成员（库实例、订阅等，不直接触发重建） ─────────────────────
+  // {LibraryClass}? _controller;
+
+  // ─── 生命周期 ──────────────────────────────────────────────────────────
+
+  @override
+  void initState() {
+    super.initState();
+    dev.log('Page appeared', name: _kTag);
+    // 初始化逻辑（如创建实例、注册监听等）
+  }
+
+  @override
+  void dispose() {
+    dev.log('Page disposed, releasing resources', name: _kTag);
+    // 释放所有资源
+    // _controller?.dispose();
+    super.dispose();
+  }
+
+  // ─── 核心功能方法 ────────────────────────────────────────────────────────
+
+  /// {方法说明}
+  ///
+  /// 调用 [{接口名称}] 实现 {功能描述}。
+  Future<void> _{camelCase方法名}() async {
+    dev.log('_{camelCase方法名} called', name: _kTag);
+    setState(() => _isLoading = true);
+    try {
+      final result = await {libraryCall};
+      dev.log('_{camelCase方法名} succeeded: $result', name: _kTag);
+      if (!mounted) return; // 页面可能已销毁，不再更新状态
+      setState(() {
+        _resultText = '结果：$result';
+        _isLoading = false;
+      });
+    } catch (e, stack) {
+      dev.log(
+        '_{camelCase方法名} failed',
+        name: _kTag,
+        error: e,
+        stackTrace: stack,
+      );
+      if (!mounted) return;
+      setState(() {
+        _resultText = '错误：$e';
+        _isLoading = false;
+      });
+    }
+  }
+
+  // ─── UI 构建 ────────────────────────────────────────────────────────────
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('[{序号}] {Demo 标题}'),
+      ),
+      body: SingleChildScrollView(
+        padding: const EdgeInsets.all(16),
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.stretch,
+          children: [
+            // 说明区域
+            Card(
+              child: Padding(
+                padding: const EdgeInsets.all(12),
+                child: Text(
+                  '{Demo 简要功能说明}',
+                  style: Theme.of(context).textTheme.bodyMedium,
+                ),
+              ),
+            ),
+            const SizedBox(height: 16),
+
+            // 操作按钮区域
+            ElevatedButton(
+              onPressed: _isLoading ? null : _{camelCase方法名},
+              child: const Text('{按钮文字}'),
+            ),
+            const SizedBox(height: 16),
+
+            // 结果展示区域
+            _buildResultArea(),
+          ],
+        ),
+      ),
+    );
+  }
+
+  /// 构建结果展示区域
+  Widget _buildResultArea() {
+    if (_isLoading) {
+      return const Center(
+        child: Padding(
+          padding: EdgeInsets.all(16),
+          child: CircularProgressIndicator(),
+        ),
+      );
+    }
+    return Container(
+      padding: const EdgeInsets.all(12),
+      decoration: BoxDecoration(
+        color: Colors.grey[100],
+        borderRadius: BorderRadius.circular(8),
+        border: Border.all(color: Colors.grey[300]!),
+      ),
+      child: SelectableText(
+        _resultText.isEmpty ? '（暂无结果，点击上方按钮执行）' : _resultText,
+        style: const TextStyle(fontFamily: 'monospace'),
+      ),
+    );
+  }
+}
+```
+
+---
+
+## 模板二：Demo 页面（仅同步接口）
+
+```dart
+/// Demo {序号}: {英文功能描述}
+///
+/// 功能说明：{描述}
+/// 对应接口：
+///   - {同步接口签名}
+
+import 'dart:developer' as dev;
+
+import 'package:flutter/material.dart';
+import 'package:{三方库包名}/{导入路径}';
+
+const String _kTag = '{LibraryName}_{ComponentName}';
+
+/// {ComponentName}Page - {功能说明}
+class {ComponentName}Page extends StatefulWidget {
+  const {ComponentName}Page({super.key});
+
+  @override
+  State<{ComponentName}Page> createState() => _{ComponentName}PageState();
+}
+
+class _{ComponentName}PageState extends State<{ComponentName}Page> {
+  String _resultText = '';
+
+  @override
+  void initState() {
+    super.initState();
+    dev.log('Page appeared', name: _kTag);
+  }
+
+  @override
+  void dispose() {
+    dev.log('Page disposed', name: _kTag);
+    super.dispose();
+  }
+
+  void _{syncMethod}() {
+    dev.log('_{syncMethod} called', name: _kTag);
+    try {
+      final result = {syncLibraryCall};
+      dev.log('_{syncMethod} result: $result', name: _kTag);
+      setState(() => _resultText = '结果：$result');
+    } catch (e, stack) {
+      dev.log('_{syncMethod} failed', name: _kTag, error: e, stackTrace: stack);
+      setState(() => _resultText = '错误：$e');
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: const Text('[{序号}] {标题}')),
+      body: Padding(
+        padding: const EdgeInsets.all(16),
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.stretch,
+          children: [
+            ElevatedButton(
+              onPressed: _{syncMethod},
+              child: const Text('{按钮文字}'),
+            ),
+            const SizedBox(height: 16),
+            Container(
+              padding: const EdgeInsets.all(12),
+              color: Colors.grey[100],
+              child: Text(_resultText.isEmpty ? '（暂无结果）' : _resultText),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+```
+
+---
+
+## 模板三：Demo 页面（含监听器/回调）
+
+```dart
+/// Demo {序号}: {英文功能描述（含事件监听）}
+///
+/// 功能说明：{描述}
+/// 对应接口：
+///   - {addListener 接口签名}
+///   - {removeListener 接口签名}
+///   - {触发接口签名}
+
+import 'dart:async';
+import 'dart:developer' as dev;
+
+import 'package:flutter/material.dart';
+import 'package:{三方库包名}/{导入路径}';
+
+const String _kTag = '{LibraryName}_{ComponentName}';
+
+class {ComponentName}Page extends StatefulWidget {
+  const {ComponentName}Page({super.key});
+
+  @override
+  State<{ComponentName}Page> createState() => _{ComponentName}PageState();
+}
+
+class _{ComponentName}PageState extends State<{ComponentName}Page> {
+  // ─── 双计数器（诊断回调链路） ────────────────────────────────────────────
+  int _triggerCount = 0;
+  int _callbackCount = 0;
+
+  // ─── 状态 ────────────────────────────────────────────────────────────────
+  String _lastEvent = '';
+
+  // ─── 非响应式 ─────────────────────────────────────────────────────────────
+  StreamSubscription<{EventType}>? _subscription;
+  // {LibraryClass}? _instance;
+
+  @override
+  void initState() {
+    super.initState();
+    dev.log('Page appeared', name: _kTag);
+    _registerListener();
+  }
+
+  @override
+  void dispose() {
+    dev.log('Page disposed, releasing resources', name: _kTag);
+    _subscription?.cancel();
+    _subscription = null;
+    // _instance?.dispose();
+    super.dispose();
+  }
+
+  /// 注册监听器
+  void _registerListener() {
+    dev.log('_registerListener called', name: _kTag);
+    _subscription = {library}.{eventStream}.listen(
+      ({EventType} event) {
+        dev.log('Event received: $event', name: _kTag);
+        if (!mounted) return;
+        setState(() {
+          _callbackCount++;
+          _lastEvent = event.toString();
+        });
+      },
+      onError: (Object e, StackTrace stack) {
+        dev.log('Stream error', name: _kTag, error: e, stackTrace: stack);
+        if (!mounted) return;
+        setState(() => _lastEvent = '事件流异常：$e');
+      },
+    );
+  }
+
+  /// 触发操作，预期会产生回调事件
+  void _triggerAction() {
+    dev.log('_triggerAction called', name: _kTag);
+    setState(() => _triggerCount++);
+    try {
+      {library}.{triggerMethod}();
+    } catch (e, stack) {
+      dev.log('_triggerAction failed', name: _kTag, error: e, stackTrace: stack);
+      setState(() => _lastEvent = '触发失败：$e');
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: const Text('[{序号}] {标题}')),
+      body: SingleChildScrollView(
+        padding: const EdgeInsets.all(16),
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.stretch,
+          children: [
+            // 操作按钮
+            ElevatedButton(
+              onPressed: _triggerAction,
+              child: const Text('{触发按钮文字}'),
+            ),
+            const SizedBox(height: 16),
+
+            // 诊断区域（双计数器）
+            Card(
+              child: Padding(
+                padding: const EdgeInsets.all(12),
+                child: Column(
+                  crossAxisAlignment: CrossAxisAlignment.start,
+                  children: [
+                    const Text('诊断信息', style: TextStyle(fontWeight: FontWeight.bold)),
+                    const SizedBox(height: 8),
+                    Text('触发次数: $_triggerCount'),
+                    Text('回调次数: $_callbackCount'),
+                    if (_triggerCount > 0 && _callbackCount == 0)
+                      const Text(
+                        '⚠️ 已触发但回调未收到，请检查监听注册',
+                        style: TextStyle(color: Colors.orange),
+                      ),
+                    if (_callbackCount > 0 && _triggerCount == _callbackCount)
+                      const Text(
+                        '✅ 链路正常',
+                        style: TextStyle(color: Colors.green),
+                      ),
+                  ],
+                ),
+              ),
+            ),
+            const SizedBox(height: 16),
+
+            // 最近事件展示
+            Container(
+              padding: const EdgeInsets.all(12),
+              decoration: BoxDecoration(
+                color: Colors.grey[100],
+                borderRadius: BorderRadius.circular(8),
+              ),
+              child: Text(
+                _lastEvent.isEmpty ? '（尚未收到事件）' : '最近事件：\n$_lastEvent',
+              ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+```
+
+---
+
+## 模板四：主导航页面
+
+**文件路径**：`lib/pages/demo_home_page.dart`
+
+```dart
+/// {LibraryName} Demo 主导航页面
+///
+/// 展示所有可用的 Demo 列表，点击后跳转到对应 Demo 页面。
+
+import 'dart:developer' as dev;
+
+import 'package:flutter/material.dart';
+
+// 导入所有 Demo 页面（按序号排列）
+import '001_{描述}/{描述}_page.dart';
+import '002_{描述}/{描述}_page.dart';
+// ... 其余 Demo 页面
+
+const String _kTag = '{LibraryName}_DemoHome';
+
+/// Demo 条目数据结构（私有，仅此文件使用）
+class _DemoEntry {
+  const _DemoEntry({
+    required this.id,
+    required this.title,
+    required this.description,
+    required this.builder,
+  });
+
+  final String id;
+  final String title;
+  final String description;
+  final WidgetBuilder builder;
+}
+
+/// Demo 列表配置（按序号排列，填写实际 Demo 信息）
+final List<_DemoEntry> _demoList = [
+  _DemoEntry(
+    id: '001',
+    title: '{Demo 1 中文名称}',
+    description: '{Demo 1 一句话描述，不超过 40 字}',
+    builder: (_) => const {Demo1ClassName}Page(),
+  ),
+  _DemoEntry(
+    id: '002',
+    title: '{Demo 2 中文名称}',
+    description: '{Demo 2 一句话描述}',
+    builder: (_) => const {Demo2ClassName}Page(),
+  ),
+  // ... 其余 Demo 条目
+];
+
+/// DemoHomePage - {LibraryName} Demo 示例主导航页
+class DemoHomePage extends StatelessWidget {
+  const DemoHomePage({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('{LibraryName} Demo 示例'),
+        centerTitle: true,
+      ),
+      body: ListView.separated(
+        padding: const EdgeInsets.all(16),
+        itemCount: _demoList.length,
+        separatorBuilder: (_, __) => const SizedBox(height: 8),
+        itemBuilder: (context, index) {
+          final demo = _demoList[index];
+          return _DemoCard(
+            demo: demo,
+            onTap: () {
+              dev.log(
+                'Navigate to demo: ${demo.id} - ${demo.title}',
+                name: _kTag,
+              );
+              Navigator.push(
+                context,
+                MaterialPageRoute(builder: demo.builder),
+              );
+            },
+          );
+        },
+      ),
+    );
+  }
+}
+
+/// Demo 列表卡片 Widget（私有）
+class _DemoCard extends StatelessWidget {
+  const _DemoCard({required this.demo, required this.onTap});
+
+  final _DemoEntry demo;
+  final VoidCallback onTap;
+
+  @override
+  Widget build(BuildContext context) {
+    return Card(
+      child: ListTile(
+        leading: CircleAvatar(
+          child: Text(demo.id, style: const TextStyle(fontSize: 12)),
+        ),
+        title: Text(
+          '[${demo.id}] ${demo.title}',
+          style: const TextStyle(fontWeight: FontWeight.w500),
+        ),
+        subtitle: Text(
+          demo.description,
+          maxLines: 2,
+          overflow: TextOverflow.ellipsis,
+        ),
+        trailing: const Icon(Icons.arrow_forward_ios, size: 16),
+        onTap: onTap,
+      ),
+    );
+  }
+}
+```
+
+---
+
+## 模板五：main.dart 应用入口
+
+**文件路径**：`lib/main.dart`
+
+```dart
+import 'package:flutter/material.dart';
+
+import 'pages/demo_home_page.dart';
+
+void main() {
+  runApp(const DemoApp());
+}
+
+/// DemoApp - {LibraryName} Flutter Demo 应用
+class DemoApp extends StatelessWidget {
+  const DemoApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      title: '{LibraryName} Demo',
+      debugShowCheckedModeBanner: false,
+      theme: ThemeData(
+        colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
+        useMaterial3: true,
+      ),
+      home: const DemoHomePage(),
+    );
+  }
+}
+```