A JSValue instance is a reference to a JavaScript value. You use the JSValue class to convert basic values (such as numbers and strings) between JavaScript and Objective-C or Swift representations in order to pass data between native code and JavaScript code. You can also use this class to create JavaScript objects that wrap native objects of custom classes or JavaScript functions whose implementations are provided by native methods or blocks.
SDKs
- iOS 7.0+
- macOS 10.9+
- tvOS 9.0+
Framework
- JavaScriptCore
Overview
Each JSValue instance originates from a JSContext object that represents the JavaScript execution environment containing that value. The value holds a strong reference to its context object—as long as any value associated with a particular JSContext instance is retained, that context remains alive. When you invoke an instance method is invoked on a JSValue object, and that method returns another JSValue object, the returned value belongs to the same context as original value.
Each JavaScript value is also associated (indirectly via the context property) with a specific JSVirtual object representing the underlying set of execution resources for its context. You can pass JSValue instances only to methods on JSValue and JSContext instances hosted by the same virtual machine—attempting to pass a value to a different virtual machine raises an Objective-C exception.
Converting Between JavaScript and Native Types
When you use the methods listed in Creating JavaScript Values and Reading and Converting JavaScript Values, JavaScriptCore automatically converts native values to JavaScript values and vice versa, using the rules summarized below.
NSDictionaryobjects or Swift dictionaries and the keys they contain become JavaScript objects with matching named properties and vice versa. Values for keys are recursively copied and converted.NSArrayobjects or Swift arrays become JavaScript arrays and vice versa, with elements recursively copied and converted.Objective-C blocks (or Swift closures with the
@convention(block)attribute) become JavaScriptFunctionobjects, with parameter and return types converted using the same rules as values. Converting a JavaScript function backed by a native block or method returns that block or method; all other JavaScript functions convert as empty dictionaries.For all other native object types (and class types or metatypes), JavaScriptCore creates a JavaScript wrapper object with a constructor prototype chain reflecting the native class hierarchy. By default, the JavaScript wrapper for a native object does not make that object’s properties and methods available in JavaScript. To choose properties and methods for export to JavaScript, see
JSExport.
When you convert an object, method, or block, JavaScriptCore implicitly converts the types and values of object properties and method parameters using the rules summarized in Table 1.
Type Conversions Between Objective-C or Swift and JavaScript
Objective-C (and Swift) Types | JavaScript Types | Notes |
|---|---|---|
|
| |
| ||
| ||
|
| Conversion is consistent with the following methods:
|
|
| Recursive conversion. |
| Recursive conversion. | |
| ||
Objective-C or Swift object ( Objective-C or Swift class ( |
| Converts with |
Structure types: |
| Other structure types are not supported. |
Objective-C block (Swift closure) |
| Convert explicitly with JavaScript functions do not convert to native blocks/closures unless already backed by a native block/closure. |