Features

  • 基于高德的定位打卡能力，支持内勤/外勤场景
  • 静默自动打卡：ClockInManager + LocationService 支持无 UI 检测与自动提交
  • 自动打卡时间窗口：AutoClockTimeWindow 可配置上/下班容差时间
  • 成功回调：onSilentClockSuccess 可用于推送通知、刷新宿主 UI
  • 日历体验：记录页支持点击标题选择月份，非当月显示“返回今天”按钮
  • 国际化扩展：新增静默打卡相关提示文案，可选自定义“选择月份”标题

快速上手

配置基础能力

JunnyPunchBasicConfig(
  autoClockTimeWindow: const AutoClockTimeWindow(
    clockInBeforeMinutes: 30,
    clockInAfterMinutes: 60,
    clockOutBeforeMinutes: 0,
    clockOutAfterMinutes: 120,
  ),
  onSilentClockSuccess: (SilentClockResult result) {
    // 发送本地通知或刷新宿主页面
  },
);

静默打卡/定位服务均已通过 lib/junny_location_punch.dart 导出：

import 'package:junny_location_punch/junny_location_punch.dart';

final check = await ClockInManager.instance.checkStatus();
if (check.result.isSuccess) {
  final autoResult = await ClockInManager.instance.silentAutoClock();
  if (!autoResult.success) {
    final message = autoResult.failReason?.getLocalizedMessage(context);
    // 处理失败提示
  }
}

国际化字段（新增）

JunnyPunchLocalizationConfig(
  selectMonth: ([context]) => '选择月份',
  silentAlreadyClockedTips: ([context]) => '今日已完成打卡',
  silentAutoClockFailedTips: ([context]) => '自动打卡失败',
  silentAutoClockSuccessTips: ([context]) => '自动打卡成功',
  silentCheckStatusFailedTips: ([context]) => '检测打卡状态失败',
  silentLocationUnavailableTips: ([context]) => '定位服务不可用',
  silentNoAttendancePermissionTips: ([context]) => '暂无考勤权限',
  silentNotWorkdayTips: ([context]) => '今日非工作日',
  silentOutsideRangeTips: ([context]) => '当前位置不在打卡范围内',
  silentOutsideTimeWindowTips: ([context]) => '当前时间不在打卡时间范围内',
  silentPermissionDeniedTips: ([context]) => '定位权限未授权，请手动打卡',
  // 其余必填字段保持原有实现
);

Getting started

Android

  • android/src/main/AndroidManifest.xml 添加以下内容 具体参考 example

<manifest>
    <application>
        /// 需要配置的
        <meta-data android:name="com.amap.api.v2.apikey" android:value="您的Key" />
    </application>
</manifest>

iOS

  1. 在info.plist中增加:
<key>NSLocationWhenInUseUsageDescription</key>
<string>要用定位</string>

如果ios定位没有返回逆地理信息,添加一下内容

	<key>NSAppTransportSecurity</key>
	<dict>
		<key>NSAllowsArbitraryLoads</key>
		<true/>
		<key>NSAllowsArbitraryLoadsForMedia</key>
		<true/>
		<key>NSAllowsArbitraryLoadsInWebContent</key>
		<true/>
		/// 解决ios HTTP 警告，需要添加的
        <key>NSExceptionDomains</key>
            <dict>
                <key>restios.amap.com/key>
                <dict>
                    <key>NSExceptionAllowsInsecureHTTPLoads</key>
                    <true/>
                    <key>NSIncludesSubdomains</key>
                    <true/>
                    <key>NSExceptionMinimumTLSVersion</key>
                    <string>TLSv1.2</string>
                </dict>
            </dict>
	</dict>
  1. iOS 9及以上版本使用后台定位功能, 需要保证"Background Modes"中的"Location updates"处于选中状态

3.使用地理围栏

iOS14及以上版本使用地理围栏功能，需要在plist中配置NSLocationTemporaryUsageDescriptionDictionary字典描述， 且添加自定义Key描述地理围栏的使用场景，此描述会在申请临时精确定位权限的弹窗中展示。 该回调触发条件：拥有定位权限，但是没有获得精确定位权限的情况下，会触发该回调。此方法实现调用申请临时精确定位权限API即可；

** 需要注意，在iOS9及之后版本的系统中，如果您希望程序在后台持续检测围栏触发行为，需要保证manager的 allowsBackgroundLocationUpdates 为 YES， 设置为YES的时候必须保证 Background Modes 中的 Location updates 处于选中状态，否则会抛出异常。

Libraries

junny_location_punch