JSPatch README

The project's README from github.com/bang590/JSPatch. As one markdown file: README.md.

JSPatch

Travis CocoaPods Version License

中文介绍 | 文档 | JSPatch平台

请大家不要自行接入 JSPatch，统一接入 JSPatch 平台，让热修复在一个安全和可控的环境下使用。原因详见 这里

JSPatch bridges Objective-C and JavaScript using the Objective-C runtime. You can call any Objective-C class and method in JavaScript by just including a small engine. That makes the APP obtaining the power of script language: add modules or replacing Objective-C code to fix bugs dynamically.

JSPatch is still in development, welcome to improve the project together.

Notice: Please go to Wiki to get full document.

Example

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions 
{
    [JPEngine startEngine];
    NSString *sourcePath = [[NSBundle mainBundle] pathForResource:@"demo" ofType:@"js"];
    NSString *script = [NSString stringWithContentsOfFile:sourcePath encoding:NSUTF8StringEncoding error:nil];
    [JPEngine evaluateScript:script];
    
    self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds];
    [self.window addSubview:[self genView]];
    [self.window makeKeyAndVisible];
    
    return YES;
}

- (UIView *)genView
{
    return [[UIView alloc] initWithFrame:CGRectMake(0, 0, 320, 320)];
}

@end

// demo.js
require('UIView, UIColor, UILabel')
defineClass('AppDelegate', {
  // replace the -genView method
  genView: function() {
    var view = self.ORIGgenView();
    view.setBackgroundColor(UIColor.greenColor())
    var label = UILabel.alloc().initWithFrame(view.frame());
    label.setText("JSPatch");
    label.setTextAlignment(1);
    view.addSubview(label);
    return view;
  }
});

You can also try to use JSPatch Convertor to convertor code from Objective-C to JavaScript automatically.

Installation

CocoaPods

CocoaPods is a dependency manager for Objective-C, which automates and simplifies the process of using 3rd-party libraries like JSPatch in your projects. See the "Getting Started" guide for more information.

# Your Podfile
platform :ios, '6.0'
pod 'JSPatch'

Manually

Copy JSEngine.m JSEngine.h JSPatch.js in JSPatch/ to your project.

Usage

Objective-C

  1. #import "JPEngine.h"
  2. call [JPEngine startEngine]
  3. exec JavasScript by [JPEngine evaluateScript:@""]
[JPEngine startEngine];

// exec js directly
[JPEngine evaluateScript:@"\
 var alertView = require('UIAlertView').alloc().init();\
 alertView.setTitle('Alert');\
 alertView.setMessage('AlertView from js'); \
 alertView.addButtonWithTitle('OK');\
 alertView.show(); \
"];

// exec js file from network
[NSURLConnection sendAsynchronousRequest:[NSURLRequest requestWithURL:[NSURL URLWithString:@"http://cnbang.net/test.js"]] queue:[NSOperationQueue mainQueue] completionHandler:^(NSURLResponse *response, NSData *data, NSError *connectionError) {
    NSString *script = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
    [JPEngine evaluateScript:script];
}];

// exec local js file
NSString *sourcePath = [[NSBundle mainBundle] pathForResource:@"sample" ofType:@"js"];
NSString *script = [NSString stringWithContentsOfFile:sourcePath encoding:NSUTF8StringEncoding error:nil];
[JPEngine evaluateScript:script];

JavaScript

Base Usage

//require
require('UIView, UIColor, UISlider, NSIndexPath')

// Invoke class method
var redColor = UIColor.redColor();

// Invoke instance method
var view = UIView.alloc().init();
view.setNeedsLayout();

// set proerty
view.setBackgroundColor(redColor);

// get property 
var bgColor = view.backgroundColor();

// multi-params method (use underline to separate)
// OC：NSIndexPath *indexPath = [NSIndexPath indexPathForRow:0 inSection:1];
var indexPath = NSIndexPath.indexPathForRow_inSection(0, 1);

// method name contains underline (use double undeline to represent)
// OC: [JPObject _privateMethod];
JPObject.__privateMethod()

// use .toJS() to convert NSArray / NSString / NSDictionary to JS type.
var arr = require('NSMutableArray').alloc().init()
arr.addObject("JS")
jsArr = arr.toJS()
console.log(jsArr.push("Patch").join(''))  //output: JSPatch

// use hashes to represent struct like CGRect / CGSize / CGPoint / NSRange
var view = UIView.alloc().initWithFrame({x:20, y:20, width:100, height:100});
var x = view.bounds().x;

// wrap function with `block()` when passing block from JS to OC
// OC Method: + (void)request:(void(^)(NSString *content, BOOL success))callback
require('JPObject').request(block("NSString *, BOOL", function(ctn, succ) {
  if (succ) log(ctn)
}));

// GCD
dispatch_after(1.0, function(){
  // do something
})
dispatch_async_main(function(){
  // do something
})

Go to wiki page for more details: Base Usage

defineClass

You can redefine an existing class and override methods.

// OC
@implementation JPTableViewController
...
- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath
{
  NSString *content = self.dataSource[[indexPath row]];  //may cause out of bound
  JPViewController *ctrl = [[JPViewController alloc] initWithContent:content];
  [self.navigationController pushViewController:ctrl];
}
- (NSArray *)dataSource
{
  return @[@"JSPatch", @"is"];
}
- (void)customMethod
{
  NSLog(@"callCustom method")
}
@end

// JS
defineClass("JPTableViewController", {
  // instance method definitions
  tableView_didSelectRowAtIndexPath: function(tableView, indexPath) {
    var row = indexPath.row()
    if (self.dataSource().count() > row) {  //fix the out of bound bug here
      var content = self.dataSource().objectAtIndex(row);
      var ctrl = JPViewController.alloc().initWithContent(content);
      self.navigationController().pushViewController(ctrl);
    }
  },

  dataSource: function() {
    // get the original method by adding prefix 'ORIG'
    var data = self.ORIGdataSource().toJS();
    return data.push('Good!');
  }
}, {})

Go to wiki page for more details: Usage of defineClass

Extensions

There are some extensions provide support for custom struct type, C methods and other functional, call +addExtensions: after starting engine to add extensions:

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions 
{
    [JPEngine startEngine];

    //add extensions after startEngine
    [JPEngine addExtensions:@[@"JPInclude", @"JPCGTransform"]];

    NSString *sourcePath = [[NSBundle mainBundle] pathForResource:@"demo" ofType:@"js"];
    NSString *script = [NSString stringWithContentsOfFile:sourcePath encoding:NSUTF8StringEncoding error:nil];
    [JPEngine evaluateScript:script];
}

@end

include('test.js')   //include function provide by JPInclude.m
var view = require('UIView').alloc().init()

//CGAffineTransform is supported in JPCGTransform.m
view.setTransform({a:1, b:0, c:0, d:1, tx:0, ty:100})

Extensions can be added dynamiclly in JS, which is recommended:

require('JPEngine').addExtensions(['JPInclude', 'JPCGTransform'])

// `include()` and `CGAffineTransform` is avaliable now.

You can create your own extension to support custom struct type and C methods in project, see the wiki page for more details: Adding new extensions

Enviroment

JSPatch (bang590/JSPatch)

Searching Database…

11.3K ·GitHub
JSPatch
What is this?An iOS library that bridges Objective-C and JavaScript through the Objective-C runtime: with a small embedded engine, the app can call any Objective-C class and method from JavaScript. It is generally used to hotfix iOS apps.
Is this something I install on a device, or code that goes into my app?A library you embed in your iOS app, not a standalone tool: JSEngine.m, JSEngine.h and JSPatch.js go into the project, and the app gains the power of a script language at runtime.
How do I add it to an iOS project?Add it with CocoaPods, or manually copy JSEngine.m, JSEngine.h and JSPatch.js into your project. In code: import JPEngine.h, call [JPEngine startEngine], then execute JavaScript with [JPEngine evaluateScript:].
Does it need any special frameworks to work?Only one framework is required: JavaScriptCore.framework. CocoaPods is the suggested way to pull the library in, but there are no other dependencies.
The README opens with a Chinese warning — what is it about?The author asks developers not to integrate JSPatch on their own and to go through the JSPatch Platform instead, so that hotfixing happens in a safe and controlled environment.
Is it just for patching bugs, or can it ship new features too?Primarily teams that need to hotfix a shipped iOS app: patches replace Objective-C code to fix bugs dynamically. The same mechanism also lets an app add new modules at runtime.
Which iOS versions and devices does it support?iOS 7 and newer, with forward compatibility to iOS 6, on armv7, armv7s and arm64 devices.
What can the JavaScript side actually do once the engine is running?Anything the runtime exposes: call any Objective-C class and method, and use defineClass to redefine an existing class and override its methods.
Do I have to write all patch code in JavaScript by hand?No. JSPatch Convertor converts Objective-C code to JavaScript automatically, and the wiki documents base usage and defineClass.
What if a patch needs C functions or custom structs?Extensions cover that: call +addExtensions: after starting the engine, or add them dynamically from JavaScript, which the README recommends. You can also write your own extension for custom structs or C methods.
Is JSPatch still being developed?Yes: the README says it is still in development and welcomes improvements, and the project has over 11,000 stars. For production hotfixing the author directs users to the managed JSPatch Platform.
What are similar projects?WebViewJavascriptBridge, FSCalendar, Spring, AsyncDisplayKit, SwiftyJSON, react-native-maps, IQKeyboardManager, Eureka
Which topics is it in?cocoapods, scripting, runtime, objective-c, mobile-development, mobile, ios, free, library, javascript, developer-tools, mit
Creator
bang590
Size
7.7 MB
Stars
11.3K
Updated
CommitApr 22
Age
11y
Commits · 90 Days