MJExtension

• A fast, convenient and nonintrusive conversion framework between JSON and model.
• 转换速度快、使用简单方便的字典转模型框架

📜✍🏻Release Notes: more details

Contents

• Getting Started 【开始使用】
  • Features 【能做什么】
  • Installation 【安装】
• Examples 【示例】
  • Usage in Swift
  • JSON -> Model
  • JSONString -> Model
  • Model contains model
  • Model contains model-array
  • Model name - JSON key mapping
  • JSON array -> model array
  • Model -> JSON
  • Model array -> JSON array
  • Core Data
  • Coding
  • Secure Coding
  • Camel -> underline
  • NSString -> NSDate, nil -> @""
  • NSDate -> NSString
  • More use cases

---

<a id="Getting_Started"></a> Getting Started【开始使用】

<a id="Features"></a> Features【能做什么】

• MJExtension是一套字典和模型之间互相转换的超轻量级框架

• JSON --> Model、Core Data Model
• JSONString --> Model、Core Data Model
• Model、Core Data Model --> JSON
• JSON Array --> Model Array、Core Data Model Array
• JSONString --> Model Array、Core Data Model Array
• Model Array、Core Data Model Array --> JSON Array
• Coding all properties of a model with only one line of code.
  • 只需要一行代码，就能实现模型的所有属性进行Coding / SecureCoding（归档和解档）

<a id="Installation"></a> Installation【安装】

CocoaPods【使用CocoaPods】

pod 'MJExtension'

Carthage

github "CoderMJLee/MJExtension"

Swift Package Manager

Released from 3.4.0

Manually【手动导入】

• Drag all source files under folder MJExtension to your project.【将MJExtension文件夹中的所有源代码拽入项目中】
• Import the main header file：#import "MJExtension.h"【导入主头文件：#import "MJExtension.h"】

<a id="Examples"></a> Examples【示例】

Add MJKeyValue protocol to your model if needed【如果有需要, 请在模型中加入 MJKeyValue 协议】

<a id="usage_in_swift"></a> Usage in Swift [关于在Swift中使用MJExtension] ‼️

Example:

• Model - MJTester.swift

• Usage - SwiftModelTests.swift

@objc(MJTester)
@objcMembers
class MJTester: NSObject {
    // make sure to use `dynamic` attribute for basic type & must use as Non-Optional & must set initial value
    dynamic var isSpecialAgent: Bool = false
    dynamic var age: Int = 0
    
    var name: String?
    var identifier: String?
}

1. @objc or @objcMembers attributes should be added to class or property for declaration of Objc accessibility [在 Swift4 之后, 请在属性前加 @objc 修饰或在类前增加 @objcMembers. 以保证 Swift 的属性能够暴露给 Objc 使用. ]
2. If you let Bool & Int as property type, make sure that using dynamic to attribute it. It must be Non-Optional type and assign a default value.[如果要使用 Bool 和 Int 等 Swfit 专用基本类型, 请使用 dynamic 关键字修饰, 类型为 Non-Optional, 並且给定初始值.]

纯Swift版的JSON与Model转换框架已经开源上架

• KakaJSON
• 中文教程
• 如果你的项目是用Swift写的Model，墙裂推荐使用KakaJSON
  • 已经对各种常用的数据场景进行了大量的单元测试
  • 简单易用、功能丰富、转换快速

<a id="JSON_Model"></a> The most simple JSON -> Model【最简单的字典转模型】

typedef enum {
    SexMale,
    SexFemale
} Sex;

@interface User : NSObject
@property (copy, nonatomic) NSString *name;
@property (copy, nonatomic) NSString *icon;
@property (assign, nonatomic) unsigned int age;
@property (copy, nonatomic) NSString *height;
@property (strong, nonatomic) NSNumber *money;
@property (assign, nonatomic) Sex sex;
@property (assign, nonatomic, getter=isGay) BOOL gay;
@end

/***********************************************/

NSDictionary *dict = @{
    @"name" : @"Jack",
    @"icon" : @"lufy.png",
    @"age" : @20,
    @"height" : @"1.55",
    @"money" : @100.9,
    @"sex" : @(SexFemale),
    @"gay" : @"true"
//   @"gay" : @"1"
//   @"gay" : @"NO"
};

// JSON -> User
User *user = [User mj_objectWithKeyValues:dict];

NSLog(@"name=%@, icon=%@, age=%zd, height=%@, money=%@, sex=%d, gay=%d", user.name, user.icon, user.age, user.height, user.money, user.sex, user.gay);
// name=Jack, icon=lufy.png, age=20, height=1.550000, money=100.9, sex=1

<a id="JSONString_Model"></a> JSONString -> Model【JSON字符串转模型】

// 1.Define a JSONString
NSString *jsonString = @"{\"name\":\"Jack\", \"icon\":\"lufy.png\", \"age\":20}";

// 2.JSONString -> User
User *user = [User mj_objectWithKeyValues:jsonString];

// 3.Print user's properties
NSLog(@"name=%@, icon=%@, age=%d", user.name, user.icon, user.age);
// name=Jack, icon=lufy.png, age=20

<a id="Model_contains_model"></a> Model contains model【模型中嵌套模型】

@interface Status : NSObject
@property (copy, nonatomic) NSString *text;
@property (strong, nonatomic) User *user;
@property (strong, nonatomic) Status *retweetedStatus;
@end

/***********************************************/

NSDictionary *dict = @{
    @"text" : @"Agree!Nice weather!",
    @"user" : @{
        @"name" : @"Jack",
        @"icon" : @"lufy.png"
    },
    @"retweetedStatus" : @{
        @"text" : @"Nice weather!",
        @"user" : @{
            @"name" : @"Rose",
            @"icon" : @"nami.png"
        }
    }
};

// JSON -> Status
Status *status = [Status mj_objectWithKeyValues:dict];

NSString *text = status.text;
NSString *name = status.user.name;
NSString *icon = status.user.icon;
NSLog(@"text=%@, name=%@, icon=%@", text, name, icon);
// text=Agree!Nice weather!, name=Jack, icon=lufy.png

NSString *text2 = status.retweetedStatus.text;
NSString *name2 = status.retweetedStatus.user.name;
NSString *icon2 = status.retweetedStatus.user.icon;
NSLog(@"text2=%@, name2=%@, icon2=%@", text2, name2, icon2);
// text2=Nice weather!, name2=Rose, icon2=nami.png

<a id="Model_contains_model_array"></a> Model contains model-array【模型中有个数组属性，数组里面又要装着其他模型】

@interface Ad : NSObject
@property (copy, nonatomic) NSString *image;
@property (copy, nonatomic) NSString *url;
@end

@interface StatusResult : NSObject
/** Contatins status model */
@property (strong, nonatomic) NSMutableArray *statuses;
/** Contatins ad model */
@property (strong, nonatomic) NSArray *ads;
@property (strong, nonatomic) NSNumber *totalNumber;
@end

/***********************************************/

// Tell MJExtension what type of model will be contained in statuses and ads.
[StatusResult mj_setupObjectClassInArray:^NSDictionary *{
    return @{
               @"statuses" : @"Status",
               // @"statuses" : [Status class],
               @"ads" : @"Ad"
               // @"ads" : [Ad class]
           };
}];
// Equals: StatusResult.m implements +mj_objectClassInArray method.

NSDictionary *dict = @{
    @"statuses" : @[
                      @{
                          @"text" : @"Nice weather!",
                          @"user" : @{
                              @"name" : @"Rose",
                              @"icon" : @"nami.png"
                          }
                      },
                      @{
                          @"text" : @"Go camping tomorrow!",
                          @"user" : @{
                              @"name" : @"Jack",
                              @"icon" : @"lufy.png"
                          }
                      }
                  ],
    @"ads" : @[
                 @{
                     @"image" : @"ad01.png",
                     @"url" : @"http://www.ad01.com"
                 },
                 @{
                     @"image" : @"ad02.png",
                     @"url" : @"http://www.ad02.com"
                 }
             ],
    @"totalNumber" : @"2014"
};

// JSON -> StatusResult
StatusResult *result = [StatusResult mj_objectWithKeyValues:dict];

NSLog(@"totalNumber=%@", result.totalNumber);
// totalNumber=2014

// Printing
for (Status *status in result.statuses) {
    NSString *text = status.text;
    NSString *name = status.user.name;
    NSString *icon = status.user.icon;
    NSLog(@"text=%@, name=%@, icon=%@", text, name, icon);
}
// text=Nice weather!, name=Rose, icon=nami.png
// text=Go camping tomorrow!, name=Jack, icon=lufy.png

// Printing
for (Ad *ad in result.ads) {
    NSLog(@"image=%@, url=%@", ad.image, ad.url);
}
// image=ad01.png, url=http://www.ad01.com
// image=ad02.png, url=http://www.ad02.com

<a id="Model_name_JSON_key_mapping"></a> Model name - JSON key mapping【模型中的属性名和字典中的key不相同(或者需要多级映射)】

@interface Bag : NSObject
@property (copy, nonatomic) NSString *name;
@property (assign, nonatomic) double price;
@end

@interface Student : NSObject
@property (copy, nonatomic) NSString *ID;
@property (copy, nonatomic) NSString *desc;
@property (copy, nonatomic) NSString *nowName;
@property (copy, nonatomic) NSString *oldName;
@property (copy, nonatomic) NSString *nameChangedTime;
@property (strong, nonatomic) Bag *bag;
@end

/***********************************************/

// How to map
[Student mj_setupReplacedKeyFromPropertyName:^NSDictionary *{
    return @{
               @"ID" : @"id",
               @"desc" : @"description",
               @"oldName" : @"name.oldName",
               @"nowName" : @"name.newName"