Skip to main content

SdkHelper

Helper 属性（即 ChameleonSdkHelper）提供一组静态通用工具方法，主要包括 URL 解析和时区转换功能。它是通过单例模式访问的，无需依赖注入。

概述​

ChameleonSdkHelper.Instance 提供了跨平台开发中常用的工具方法，特别是在处理多时区场景下的时间转换时非常有用。

API 方法​

URL 解析​

ParseUrlQuery — 解析 URL 查询参数​

将 URL 中的查询字符串解析为字典。

Dictionary<string, string> ParseUrlQuery(string url);

示例：

// 解析回调 URL 中的参数
var url = "https://example.com/callback?code=abc123&state=xyz789";
var params = sdk.Helper.ParseUrlQuery(params);

// params["code"] => "abc123"
// params["state"] => "xyz789"

// 常见场景：OAuth 回调处理
var code = sdk.Helper.ParseUrlQuery(callbackUrl)["code"];

时区转换​

Chameleon 平台支持多时区，数据库中统一存储 UTC 时间。以下方法帮助在 UTC 时间和本地时间之间进行转换。

UtcToLocalTime — UTC 转本地时间​

将 UTC 时间转换为当前用户的本地时区时间。

// DateTime 版本
DateTime UtcToLocalTime(DateTime utcTime, bool throwIfMissing = false);

// DateTimeOffset 版本（数据库字段常用）
DateTime UtcToLocalTime(DateTimeOffset utcTimeOffset);

示例：

// 数据库中的 UTC 时间转为本地显示时间
var dbTime = record.CreatedTime; // DateTimeOffset 类型
var localTime = sdk.Helper.UtcToLocalTime(dbTime);

// DateTime 版本
var utcNow = DateTime.UtcNow;
var localNow = sdk.Helper.UtcToLocalTime(utcNow);

LocalToUtcTime — 本地时间转 UTC​

将本地时间转换为 UTC 时间，用于写入数据库。

DateTime LocalToUtcTime(DateTime localTime, bool throwIfMissing = false);
DateTime LocalToUtcTime(DateTimeOffset localTimeOffset);

示例：

// 用户输入的本地时间转为 UTC 存储
var userSelectedDate = DateTime.Parse("2026-06-04 14:00:00");
var utcDate = sdk.Helper.LocalToUtcTime(userSelectedDate);
// 写入数据库...

UtcToChinaTime / ChinaToUtcTime — 中国标准时间转换​

专门针对中国标准时间（UTC+8）的便捷转换方法。

// UTC -> 中国标准时间
DateTime UtcToChinaTime(DateTime utcTime);
DateTime UtcToChinaTime(DateTimeOffset utcTimeOffset);

// 中国标准时间 -> UTC
DateTime ChinaToUtcTime(DateTime chinaTime);
DateTime ChinaToUtcTime(DateTimeOffset chinaTimeOffset);

示例：

// 转换为中国时间显示
var chinaTime = sdk.Helper.UtcToChinaTime(DateTime.UtcNow);

// 中国时间转 UTC 存储
var utcTime = sdk.Helper.ChinaToUtcTime(DateTime.Parse("2026-06-04 22:00:00"));

典型场景​

OAuth 回调处理​

public async Task<object> ExecuteAsync(ComponentContext context, ChameleonSDK sdk)
{
    // 从回调 URL 中解析授权码
    var queryParams = sdk.Helper.ParseUrlQuery(callbackUrl);
    var code = queryParams["code"];
    var state = queryParams["state"];

    // 使用授权码换取 token
    // ...
}

时间字段显示转换​

public async Task<object> ExecuteAsync(ComponentContext context, ChameleonSDK sdk)
{
    var entity = context.CurrentEntity;

    // 将数据库 UTC 时间转换为用户本地时间用于显示
    var createdTimeLocal = sdk.Helper.UtcToLocalTime(entity.CreatedTime);
    var updatedTimeLocal = sdk.Helper.UtcToLocalTime(entity.UpdatedTime);

    return new
    {
        Id = entity.Id,
        CreatedTime = createdTimeLocal.ToString("yyyy-MM-dd HH:mm:ss"),
        UpdatedTime = updatedTimeLocal.ToString("yyyy-MM-dd HH:mm:ss")
    };
}

时间条件查询​

public async Task<object> ExecuteAsync(ComponentContext context, ChameleonSDK sdk)
{
    // 用户选择的日期范围（本地时间）转为 UTC 用于查询
    var startDate = sdk.Helper.LocalToUtcTime(startDatePickerValue);
    var endDate = sdk.Helper.LocalToUtcTime(endDatePickerValue.AddDays(1));

    // 用 UTC 时间查询数据库
    var results = await query.Where(x => x.CreatedTime >= startDate && x.CreatedTime < endDate).ToListAsync();

    return results;
}

注意事项​

  • ParseUrlQuery 在 URL 为空或无效时返回空字典，不会抛出异常
  • 时区转换方法中的 throwIfMissing 参数：设为 true 时如果缺少时区信息会抛异常，默认 false 则回退到默认时区
  • 数据库中统一使用 UTC 时间存储，展示时再转换为本地时间
  • UtcToLocalTime 使用的是当前登录用户的时区配置，ChinaToUtcTime 固定使用 UTC+8

相关文档​