关闭

JavaScriptCode.FrameWork(Apple官方文档翻译整理)

标签: javascriptiOSXcodeHTML5
1103人阅读 评论(0) 收藏 举报
分类:

JavaScriptCode.FrameWork

Evaluate JavaScript programs from within an app, and support JavaScript scripting of your app.
评估JavaScript程序从内部应用程序,支持JavaScript应用程序的脚本。
GitHub源代码:https://github.com/Liuhaiyuan/JavaScriptCoreDemo.git

Overview(概述)/ 前言

The JavaScriptCore Framework allows you to evaluate JavaScript programs from within an Objective-C or C-based program. It also lets you insert custom objects to the JavaScript environment.

JavaScriptCore框架允许您从内部评估JavaScript程序一个objective - c或基于c的程序。它还允许您插入自定义对象的JavaScript环境。

在目前进行的HTML5开发时,经常会进行JavaScript与原生代码之间的交互,该框架即是主要处理交互的框架。

Class

JSContext

A JSContext object represents a JavaScript execution environment. You create and use JavaScript contexts to evaluate JavaScript scripts from Objective-C or Swift code, to access values defined in or calculated in JavaScript, and to make native objects, methods, or functions accessible to JavaScript.

JSContext对象代表一个JavaScript执行环境。您创建和使用JavaScript环境评估JavaScript脚本从objective - c或Swift代码,访问中定义的值或计算在JavaScript中,并使本地对象、方法或访问的JavaScript函数。

Creating JavaScript Contexts

init
- (instancetype)init;
  • Return Value: A new JavaScript context.
  • This initializer creates a context along with a new, independent virtual machine (a JSVirtualMachine object). You cannot pass JavaScript values (JSValue objects) between contexts in different virtual machines. To create contexts that share a virtual machine, use the initWithVirtualMachine: initializer.

  • 该方法是初始化方法,返回值是一个新的 JavaScript Context 对象。

  • SymbolsThis初始值设定项创建一个上下文连同一个新的、独立的虚拟机(JSVirtualMachine对象)。你不能通过JavaScript值(JSValue对象)之间在不同的虚拟机环境。创建上下文,共享一个虚拟机,使用initWithVirtualMachine:初始化器。
initWithVirtualMachine:
  • Creates a new JavaScript context associated with a specific virtual machine.
  • 创建一个新的JavaScript上下文关联到一个特定的虚拟机。
SWIFT
init!(virtualMachine virtualMachine: JSVirtualMachine!)
OBJECTIVE-C
- (instancetype)initWithVirtualMachine:(JSVirtualMachine *)virtualMachine
  • virtualMachine | The virtual machine with which to associate the new context.
  • 参数 virtualMachine 表示:虚拟机与它们相关联的新环境。

Evaluating Scripts (评估脚本)

- evaluateScript:

Executes the specified JavaScript code.
执行指定的JavaScript代码。

SWIFT
func evaluateScript(_ script: String!) -> JSValue!
OBJECTIVE-C
- (JSValue *)evaluateScript:(NSString *)script
  • Parameters
  • script: The JavaScript source code to evaluate.

  • JavaScript源代码来评估。

  • Return Value

  • The last value generated by the script. Note that a script can result in the JavaScript value undefined.

  • 最后一个值生成的脚本。注意,一个脚本可以导致JavaScript价值定义。

  • Discussion

  • Evaluating a script runs any top-level code and adds function and object definitions to the context’s global object.

  • 评估任何顶级代码运行脚本,并将功能和对象定义添加到上下文的全局对象。

  • Available in iOS 7.0 and later.

- evaluateScript:withSourceURL:

Executes the specified JavaScript code, treating the specified URL as its source location.

执行指定的JavaScript代码,把指定的URL作为它的源位置。

SWIFT
func evaluateScript(_ script: String!,
      withSourceURL sourceURL: NSURL!) -> JSValue!
OBJECTIVE-C
- (JSValue *)evaluateScript:(NSString *)script
              withSourceURL:(NSURL *)sourceURL
  • Parameters
  • script — The JavaScript source code to evaluate.
  • sourceURL — A URL to be considered as the script’s origin.

  • Return Value

  • The last value generated by the script. Note that a script can result in the JavaScript value undefined.

  • 最后一个值生成的脚本。注意,一个脚本可以导致JavaScript价值定义。

  • Discussion

  • Evaluating a script runs any top-level code and adds function or object definitions to the context’s global object.

  • The sourceURL parameter is informative only; debuggers may use this URL when reporting exceptions.

  • Available in iOS 8.0 and later.

  • 评估一个脚本运行任何顶级代码并将函数或对象定义添加到上下文的全局对象。

  • sourceURL参数信息,调试器可能时使用这个URL报告例外。

Inspecting Callback State in a Running Context (在运行过程中检查回调状态)

+ currentContext

Returns the context currently executing JavaScript code.
返回上下文当前执行的JavaScript代码。

SWIFT
class func currentContext() -> JSContext!
OBJECTIVE-C
+ (JSContext *)currentContext
  • Return Value
  • The currently executing context, or nil if not within native code called from JavaScript.
  • 当前执行的上下文,或零如果没有在本地代码从JavaScript调用。

  • Discussion

  • Call this method within an Objective-C or Swift block or method invoked from within JavaScript to obtain the JSContext object responsible for executing that Javascript code.
  • 调用这个方法在一个objective - c或swift block 或方法调用JavaScript来获得JSContext对象负责执行JavaScript代码。

  • If not currently in code invoked as a callback from JavaScript, this method returns nil.

  • 如果不是目前在代码中调用从JavaScript回调,该方法将返回零。

  • Availability

  • Available in iOS 7.0 and later.
+ currentCallee

Returns the currently executing JavaScript function.
返回当前执行的JavaScript函数。

SWIFT
class func currentCallee() -> JSValue!
OBJECTIVE-C
+ (JSValue *)currentCallee
  • Return Value
  • The currently executing JavaScript function, or nil if not within native code called from JavaScript.
  • 当前执行的JavaScript函数,或者零如果没有在本地代码从JavaScript调用。

  • Discussion

  • Call this method within an Objective-C or Swift block or method invoked from within JavaScript to obtain a JSValue object representing the JavaScript function responsible for executing that code.

  • If not currently in code invoked as a callback from JavaScript, this method returns nil.

  • 调用这个方法在一个objective - c或迅速阻止或方法调用JavaScript获得JSValue对象代表负责执行的JavaScript函数的代码。

  • Availability

  • Available in iOS 8.0 and later.
+ currentThis

Returns the value of the this keyword in currently executing JavaScript code.
返回该关键字的值在当前执行JavaScript code.

SWIFT
class func currentThis() -> JSValue!
OBJECTIVE-C
+ (JSValue *)currentThis
  • Return Value
  • The current value of the JavaScript this keyword, or nil if not within native code called from JavaScript.
  • JavaScript的当前值这个关键字,或者零如果没有在本地代码从JavaScript调用。

  • Discussion

  • Call this method within an Objective-C or Swift block or method invoked from within JavaScript to obtain a JSValue object representing the current value of the this keyword in that JavaScript code.
  • 调用这个方法在一个objective - c或迅速阻止或方法调用JavaScript获得JSValue对象代表的当前值这个关键字的JavaScript代码。

  • If not currently in code invoked as a callback from JavaScript, this method returns nil.

  • Availability

  • Available in iOS 7.0 and later.**
+ currentArguments

Returns the arguments to the current native callback from JavaScript code.
返回参数当前本地回调JavaScript代码。

SWIFT
class func currentArguments() -> [AnyObject]!
OBJECTIVE-C
+ (NSArray *)currentArguments
  • Return Value
  • The current callback arguments, or nil if not within native code called from JavaScript.
  • 当前的回调参数,或零如果没有在本地代码从JavaScript调用。

  • Discussion

  • Call this method within an Objective-C or Swift block or method invoked from within JavaScript to obtain an array of JSValue objects representing the arguments to the JavaScript function responsible for that callback.

  • If not currently in code invoked as a callback from JavaScript, this method returns nil.

  • Availability

  • Available in iOS 7.0 and later.

Working with JavaScript Global State (使用JavaScript全局状态)

globalObject

Property
The JavaScript global object associated with the context. (read-only)
与上下文相关的JavaScript全局对象。(只读)

SWIFT
var globalObject: JSValue! { get }
OBJECTIVE-C
@property(readonly, strong) JSValue *globalObject
  • Discussion
  • In a web browser, the global object of a JavaScript context is the browser window (the window object in JavaScript). Outside of web-browser use, a context’s global object serves a similar role, separating the JavaScript namespaces of different contexts. Global variables within a script appear as fields or subscripts in the global object—you can access them either through this JSValue object or through the methods listed in Accessing JavaScript Global State with Subscripts.
  • 在web浏览器中,全球一个JavaScript对象上下文是浏览器窗口(窗口对象的JavaScript)。浏览器以外的使用,一个上下文的全局对象具有类似的作用,分离不同上下文的JavaScript名称空间。全局变量在脚本中出现的字段或下标全局对象可以访问它们通过这个JSValue对象或方法中列出与下标访问JavaScript全局状态。

  • NOTE

  • For JSContext instances originating in WebKit, this method returns a reference to the WindowProxy object.
  • 源自WebKit JSContext实例,该方法返回一个引用WindowProxy对象。

  • Availability

  • Available in iOS 7.0 and later.

exception

A JavaScript exception to be thrown in evaluation of the script.
一个JavaScript脚本的评价异常被抛出。

SWIFT
var exception: JSValue!
OBJECTIVE-C
@property(strong) JSValue *exception
  • Discussion
  • Before performing a callback from JavaScript to an Objective-C or Swift block or method, the context preserves the prior value of this property and then sets its value to nil. After the callback has completed, the context reads the new value of the exception property—if this value is not nil, the context treats the value as an exception to be thrown in JavaScript as a result of the callback. After reading the property (and possibly throwing a JavaScript exception), the context restores the prior value of this property.
  • 之前执行从JavaScript回调一个objective - c或快速块或方法,这个属性的上下文保留之前的值,然后将它的值设置为零。完成回调后,异常的上下文读取新值属性,如果这个值不是零,上下文将抛出一个异常的价值JavaScript回调的结果。读完属性(可能抛出一个JavaScript异常),上下文恢复之前这个属性的价值。

  • By default, JavaScriptCore assigns any uncaught exception to this property, so you can check this property’s value to find uncaught exceptions arising from JavaScript function calls. To change the exception handling behavior, use the exceptionHandler property.

  • 默认情况下,这个属性JavaScriptCore分配任何未捕获异常,所以你可以检查这个属性的值找到未捕获的异常引起的JavaScript函数调用。改变异常处理的行为,使用exceptionHandler的财产。

  • Availability

  • Available in iOS 7.0 and later.
exceptionHandler

A block to be invoked should evaluating a script result in a JavaScript exception being thrown.
一块调用应该评估一个脚本导致JavaScript异常被抛出。

SWIFT
var exceptionHandler: ((JSContext!, JSValue!) -> Void)!
OBJECTIVE-C
@property(copy) void (^exceptionHandler)( JSContext *context, JSValue *exception)
  • Discussion
  • The block takes the following parameters:(要包含的参数)

  • context

  • The context in which the exception originates.
  • exception
  • The JavaScript exception thrown.
  • The default value exception handler block stores its exception parameter value into the context’s exception property. As a consequence, the default behavior is that unhandled exceptions occurring within a callback from JavaScript to native code are thrown again upon return. Setting this value to nil results in all uncaught exceptions being silently consumed.
  • 默认值异常处理程序块存储异常参数值上下文的异常性质。因此,默认行为是未处理的异常发生在一个回调JavaScript原生代码抛出再次返回。设置这个值为nil默默地消耗所有未捕获的异常导致。

  • Availability

  • Available in iOS 7.0 and later.
virtualMachine

The JavaScript virtual machine to which the context belongs. (read-only)
JavaScript上下文所属虚拟机。(只读)

SWIFT
var virtualMachine: JSVirtualMachine! { get }
OBJECTIVE-C
@property(readonly, strong) JSVirtualMachine *virtualMachine
  • Discussion
  • To create a context associated with a specific virtual machine, allowing JavaScript values to be passed between contexts that share the same virtual machine, use the initWithVirtualMachine: initializer.
  • 创建一个上下文关联到一个特定的虚拟机,允许JavaScript值之间传递上下文共享相同的虚拟机,使用initWithVirtualMachine:初始化器。

  • Availability

  • Available in iOS 7.0 and later.
name

A descriptive name for the context.
为下一个描述性的名称。

SWIFT
var name: String!
OBJECTIVE-C
@property(copy) NSString *name
  • Discussion
  • This name appears when using remote debugging to examine the context.
  • 这个名字出现在使用远程调试检查上下文。

  • Availability

  • Available in iOS 8.0 and later.

Accessing JavaScript Global State with Subscripts(与下标访问JavaScript全局状态)

- objectForKeyedSubscript:

Returns the value of the specified JavaScript property in the context’s global object, allowing subscript getter syntax.
返回指定的JavaScript属性的值在全局对象,允许下标getter语法。

SWIFT
func objectForKeyedSubscript(_ key: AnyObject!) -> JSValue!
OBJECTIVE-C
- (JSValue *)objectForKeyedSubscript:(id)key
  • Parameters
  • key
  • The name of a JavaScript property in the context’s global JavaScript object.
  • Return Value
  • The JavaScript property named by key, or nil if no such field or function exists.
  • JavaScript的名称属性中在全球的JavaScript对象。
  • 返回值的JavaScript属性命名的关键,或者零如果没有这样的领域或函数的存在。

  • Discussion

  • This method first constructs a JSValue object from the key parameter, then uses that value in JavaScript to look up the name of a property in the context’s global object.
  • 该方法首先构造一个JSValue对象的关键参数,然后使用该值在JavaScript中查找上下文属性的名称的全局对象。

  • Availability

  • Available in iOS 7.0 and later.
- setObject:forKeyedSubscript:

Sets the specified JavaScript property of the context’s global object, allowing subscript setter syntax.
设置指定上下文的JavaScript属性的全局对象,允许下标赋值语法。

SWIFT
      func setObject(_ object: AnyObject!,
  forKeyedSubscript key: protocol<NSCopying,
                             NSObjectProtocol>!)
OBJECTIVE-C
- (void)setObject:(id)object
forKeyedSubscript:(NSObject<NSCopying> *)key
  • Parameters
  • object
  • The value to set for the JavaScript property.
  • JavaScript的值来设置属性。
  • key
  • The JavaScript property name to use in the context’s global JavaScript object.
  • 的JavaScript属性名上下文中使用的全球JavaScript对象。
  • Discussion
  • This method first constructs a JSValue object from the key parameter, then uses that value in JavaScript to set the property in the context’s global object.
  • 该方法首先构造一个JSValue对象的关键参数,然后使用JavaScript来设置属性值的上下文的全局对象。

Use this method (or Objective-C subscript syntax) to bridge native objects or functions for use in JavaScript. For example, the following code creates a JavaScript function whose implementation is an Objective-C block:

JSContext *context = [[JSContext alloc] init];
context[@"makeNSColor"] = ^(NSDictionary *rgb){
    float r = rgb[@"red"].floatValue;
    float g = rgb[@"green"].floatValue;
    float b = rgb[@"blue"].floatValue;
    return [NSColor colorWithRed:(r / 255.f) green:(g / 255.f) blue:(b / 255.f) alpha:1.0];
};
  • Availability
  • Available in iOS 7.0 and later.

Working with the C JavaScriptCore API (使用C JavaScriptCore API)

JSGlobalContextRef

Returns the C representation of the JavaScript context. (read-only)
返回的C表示JavaScript上下文。(只读)

SWIFT
var JSGlobalContextRef: JSGlobalContextRef { get }
OBJECTIVE-C
@property(readonly) JSGlobalContextRef JSGlobalContextRef
  • Discussion
  • See JSContextRef.h Reference for the C JavaScriptCore API.

  • Availability

  • Available in iOS 7.0 and later.
+ contextWithJSGlobalContextRef:

Creates a JavaScript context object from the equivalent C representation.
创建一个JavaScript上下文对象从相当于C表示。

SWIFT
init!(JSGlobalContextRef jsGlobalContextRef: JSGlobalContextRef)
OBJECTIVE-C
+ (JSContext *)contextWithJSGlobalContextRef:(JSGlobalContextRef)jsGlobalContextRef
  • Parameters
  • jsGlobalContextRef
  • A C JavaScript context reference.
  • Return Value
  • A JavaScript context object representing the same context.

  • Discussion

  • See JSContextRef.h Reference for the C JavaScriptCore API.

  • Availability

  • Available in iOS 7.0 and later.

JSManagedValue

A JSManagedValue object wraps a JSValue object, adding “conditional retain” behavior to provide automatic memory management of values. The primary use case for a managed value is to store a JavaScript value in an Objective-C or Swift object that is itself exported to JavaScript.
不一个非受管JSValue对象存储在一个本地出口到JavaScript对象。因为其封闭JSContext JSValue对象引用对象,该操作创建一个保留周期,防止环境被收回。

Creating a Managed Value

- initWithValue:

Initializes a managed value with the specified JavaScript value.
初始化管理值与指定的JavaScript的价值。

SWIFT
init!(value value: JSValue!)
OBJECTIVE-C
- (instancetype)initWithValue:(JSValue *)value
  • Parameters
  • value
  • A JavaScript value.
  • Return Value
  • A new managed value.

  • To ensure that the underlying JavaScript value is retained as long as the managed value remains in use in the Objective-C or Swift runtime, report the managed value’s owner to the JavaScriptCore virtual machine using the addManagedReference:withOwner: method.

  • 以确保底层JavaScript值是保留只要管理价值仍在使用objective - c或迅速运行时,报告管理价值的主人JavaScriptCore虚拟机使用addManagedReference:withOwner:方法。

  • Availability

  • Available in iOS 7.0 and later.
+ managedValueWithValue:

Creates a managed value with the specified JavaScript value.
创建一个管理值与指定的JavaScript值。

OBJECTIVE-C
+ (JSManagedValue *)managedValueWithValue:(JSValue *)value
  • Parameters
  • value
  • A JavaScript value.
  • Return Value
  • A new managed value.

  • Discussion

  • To ensure that the underlying JavaScript value is retained as long as the managed value remains in use in the Objective-C or Swift runtime, report the managed value’s owner to the JavaScriptCore virtual machine using the addManagedReference:withOwner: method.
  • 以确保底层JavaScript值是保留只要管理价值仍在使用objective - c或迅速运行时,报告管理价值的主人JavaScriptCore虚拟机使用addManagedReference:withOwner:方法。

  • Availability

  • Available in iOS 7.0 and later.
+ managedValueWithValue:andOwner:

Creates a managed value and associates it with an owner.
创建一个管理价值,将它与一个所有者。

SWIFT
init!(value value: JSValue!,
   andOwner owner: AnyObject!)
OBJECTIVE-C
+ (JSManagedValue *)managedValueWithValue:(JSValue *)value
                                 andOwner:(id)owner                              
  • Parameters
  • value
  • A JavaScript value.
  • owner
  • The Objective-C or Swift object responsible for
  • Return Value
  • A new managed value.

  • Discussion

  • Calling this method is equivalent to creating a managed value and then reporting it to the JavaScriptCore virtual machine using the addManagedReference:withOwner: method.
  • 调用该方法等同于创建一个管理价值,然后报告给JavaScriptCore虚拟机使用addManagedReference:withOwner:方法。

  • Availability

  • Available in iOS 8.0 and later.

Accessing the Managed Value

value

The managed value’s underlying JavaScript value. (read-only)
价值管理的底层JavaScript的值。(只读)

SWIFT
var value: JSValue! { get }
OBJECTIVE-C
@property(readonly, strong) JSValue *value
  • Discussion
  • If the JavaScript garbage collector removes the underlying value, this property becomes nil.
  • 如果JavaScript垃圾收集器清除潜在价值,这个属性变成零。

  • Availability

  • Available in iOS 7.0 and later.
0
0

查看评论
* 以上用户言论只代表其个人观点,不代表CSDN网站的观点或立场
    个人资料
    • 访问:45897次
    • 积分:967
    • 等级:
    • 排名:千里之外
    • 原创:51篇
    • 转载:0篇
    • 译文:0篇
    • 评论:1条
    文章分类