All of the exported APIs in Weex are controllable and safe, they can not access private APIs or do any system hacks at runtime, neither can they change the primary purpose of the Application.
If you are extending your custom modules/components, be sure NOT to export the ability of Objective-C runtime, be sure NOT to export dynamic and uncontrolled methods such as
method_exchangeImplementations(), be sure NOT to export any private methods.
Weex SDK provides only rendering capabilities, rather than have other capabilities, such as network, picture, and URL redirection. If you want these features, you need to implement it.
For example: If you want to implement an address jumping function, you can achieve a Module following the steps below.
Step to customize a module#
customized must implement WXModuleProtocol
- A macro named
- The weexInstance should be synthesized. Each module object is bind to a specific instance.
- Module methods will be invoked in UI thread, so do not put time consuming operation there. If you want to execute the whole module methods in other thread, please implement the method
- (NSThread *)targetExecuteThreadin protocol. In the way, tasks distributed to this module will be executed in targetExecuteThread.
- Weex params can be String or Map.
WXModuleCallback, the params of which can be String or Map.
export synchronous methods v0.10+#
const eventModule = weex.requireModule('event')
You can alse return number/array/dictionary except string.
notice: the exported synchronous native method can only be called on JS thread. Do not do heavy work which will block js execution.
notice: Vue 2.0 has not supported this feature yet. It will be supported in version 0.12 at the soonest.
Register the module#
You can register the customized module by calling the method
registerModule:withClass in WXSDKEngine.
Weex SDK doesn’t have capabilitis, such as image download 、navigator operation，please implement these protocols by yourself.
Weex SDK has no image download capability, you need to implement
WXImgLoaderProtocol. Refer to the following examples.
Implement above protocol as follows.
Register the handler#
You can register the handler which implements the protocol by calling
registerHandler:withProtocol in WXSDKEngine.
Custom Native Components for iOS#
There are a lot of native components ready to be used in the Weex SDK, but users always have their own use cases. You might have written an awesome native UI widget in your previous work and just want to wrap up it and export to Weex. So we provide a way to enable developers to create their own custom fully-native components.
This guide will use the implementation of existing component
image to show you how to build a native component. It will also assume that you are familiar with iOS programming.
Defining a custom native component is simple. Just call
[WXSDKEngine registerComponent:withClass:] with the component’s tag name as first argument.
[WXSDKEngine registerComponent:@"image" withClass:[WXImageComponent class]];
Then you can create a
WXImageComponent class to represent the implementation of image component.
Now you can use
<image> wherever you want in the template.
The next thing we can do is to extend some native properties to make the component more powerful. As an image, let’s say we should have a
src attribute as image’s remote source and a
resize attribute as image’s resize mode(contain/cover/stretch).
@interface WXImageComponent ()
All of the styles, attributes and events will be passed to the component’s initialization method, so here you can store the properties which you are interested in.
The properties getted in the attributes are of
id type, so we have to convert them to the type we want using a conversion function. Basic conversion functions can be found in the
WXConvert file, or you can just add your own conversion function.
Hooking Render Life Cycle#
A Native Component has a life cycle managed by Weex. Weex creates it, layout it, renders it and destroys it.
Weex offers component life cycle hooks that give you visibility into these key moments and the ability to act when they occur.
|initWithRef:type:…||Initializes a new component using the specified properties.|
|layoutDidFinish||Called when the component has just laid out.|
|loadView||Creates the view that the component manages.|
|viewWillLoad||Called before the load of component’s view .|
|viewDidLoad||Called after the component’s view is loaded and set.|
|viewWillUnload||Called just before releasing the component’s view.|
|viewDidUnload||Called when the component’s view is released.|
|updateStyles:||Called when component’s style are updated.|
|updateAttributes:||Called when component’s attributes are updated.|
|addEvent:||Called when adding an event to the component.|
|removeEvent:||Called when removing an event frome the component.|
As in the image component example, if we need to use our own image view, we can override the
- (UIView *)loadView
Now Weex will use
WXImageView to render the
As an image component, we will need to fetch the remote image and set it to the image view. This can be done in
viewDidLoad method when the view is created and loaded.
viewDidLoad is also the best time to perform additional initialization for your view， such as content mode changing.
If image’s remote source can be changed, you can also hook the
updateAttributes: method to perform your attributes changing logic. Component’s view always has been loaded while
updateStyles: is called.
- (void)updateAttributes:(NSDictionary *)attributes
Maybe there is even more life cycle hooks you might need to consider, such as
layoutDidFinish while layout computing is finished. If you want to go deeper, check out the
WXComponent.h file in the source code.
Now you can use
<image> and its attributes wherever you want in the template.
<image style="your-custom-style" src="image-remote-source" resize="contain/cover/stretch"></image>
0.9.5, you can define your component method by macro
after your registration for your own custom component, now you can call it in your js file.