Revision 272494 of FAQ Extensões

  • Slug da revisão: FAQ_Extensões
  • Título da revisão: FAQ Extensões
  • ID da revisão: 272494
  • Criado:
  • Autor: Verruckt
  • É revisão atual? Não
  • Comentário
Etiquetas: 

Conteúdo da revisão

This is quick set of answers to the most common issues with extension development. They are currently written with mostly Firefox in mind, but most if not all should easily translate to SeaMonkey, Thunderbird or any of the other applications.

If you're looking for a place to get started, try our tutorial, Building an Extension or MozillaZine's Getting started tutorial. Use the Extension Wizard to generate a template to start with.

Be sure to set the development preferences.

Debugging

You should set development preferences before attempting to debug your extension.

The Venkman JavaScript debugger may be useful in complex cases, remember to turn off the "Debug -> Exclude Browser Files" option when working on extension code.

How can I see errors in my code?

After you set the preference javascript.options.showInConsole to true, the errors will be reported to the JavaScript console. Note that despite its name, all kinds of errors are reported there.

How can I display what my extension is doing?

You can use alert(), dump(), Components.utils.reportError(), or the console service to display variable data and debugging text.

Why doesn't my script run properly?

If your script doesn't function as expected, the first thing you should do is check the JavaScript Console (see above).

One common mistake is trying to access the DOM of a window before it is fully loaded. This happens if you place the initialization code at the top level of your script (i.e. outside of any functions). The fix is to use a load event listener to delay your code until the window has finished loading:

function exampleBrowserStartup(event)
{
  // place your startup code here
}
window.addEventListener("load", exampleBrowserStartup, false);

Accessing the document of a webpage doesn't work

To get the document of the current webpage from a browser.xul overlay, you should use content.document, instead of just document which is the document of the browser's window itself. See Working with windows in chrome code for details.

Also, by default XPCNativeWrapper prevents you from accessing script-defined objects in the webpage and doing some other things.

I get an XML parsing error, but the file looks fine!

A common source of parsing errors (some red text with a -------------^ underneath) is an & or a < character in your script or an attribute value, which has special meaning in XML. For example:

<button oncommand="window.open('http://example.com/q?param1=value&param2=val2')"/>

or

<script>function lesser(a,b) { return a < b ? a : b; }</script>

The problem can be solved in one of the following ways:

  1. replace the character with its non XML conflicting representation (Ex: "&" -> "&amp;", "<" -> "&lt;")
  2. (in case it's a text node, such as script) place CDATA tags around it:
    <script><![CDATA[
       function lesser(a,b) {
         return a < b ? a : b;
       }
     ]]></script>
  3. Put your script in a separate file and include it using:
    <script type="application/x-javascript" src="our.js"/>

Example code

The easiest way to find out what code you need to use in order to do something useful is to find an extension (or part of Mozilla itself) that does it and look at its code. (The XPI and JAR files use the ZIP format.)

There is also some documentation. See the list of extension-related articles on MDC, Code snippets, and Example code page on MozillaZine.

Where can I get more help?

Please see Extensions:Other Resources and Extensions:Community.

Before asking for help, be sure to set the debugging prefs and check the JavaScript Console for related messages. Also, don't forget to do at least a simple search before asking. And read this FAQ!

{{ wiki.languages( { "en": "en/Extension_Frequently_Asked_Questions", "es": "es/Preguntas_frecuentes_sobre_Extensiones", "fr": "fr/Foire_aux_questions_sur_les_extensions", "it": "it/Domande_frequenti_sulle_Estensioni", "ja": "ja/Extension_Frequently_Asked_Questions" } ) }}

Fonte da revisão

<p>This is quick set of answers to the most common issues with <a href="pt/Extension">extension</a> development. They are currently written with mostly Firefox in mind, but most if not all should easily translate to SeaMonkey, Thunderbird or any of the other applications.
</p><p>If you're looking for a place to get started, try our tutorial, <a href="pt/Building_an_Extension">Building an Extension</a> or <a class="external" href="http://kb.mozillazine.org/Getting_started_with_extension_development">MozillaZine's Getting started tutorial</a>.  Use the <a class="external" href="http://ted.mielczarek.org/code/mozilla/extensionwiz/">Extension Wizard</a> to generate a template to start with.
</p><p>Be sure to <a class="external" href="http://kb.mozillazine.org/Setting_up_extension_development_environment">set the development preferences</a>.
</p>
<h3 name="Debugging"> Debugging </h3>
<p>You should <a class="external" href="http://kb.mozillazine.org/Setting_up_extension_development_environment">set development preferences</a> before attempting to debug your extension.
</p><p>The <a href="pt/Venkman">Venkman</a> JavaScript debugger may be useful in complex cases, remember to turn off the "Debug -&gt; Exclude Browser Files" option when working on extension code.
</p>
<h4 name="How_can_I_see_errors_in_my_code.3F"> How can I see errors in my code? </h4>
<p>After you <a class="external" href="http://kb.mozillazine.org/Setting_up_extension_development_environment">set the preference <b>javascript.options.showInConsole</b> to <b>true</b></a>, the errors will be reported to the JavaScript console. Note that despite its name, all kinds of errors are reported there.
</p>
<h4 name="How_can_I_display_what_my_extension_is_doing.3F"> How can I display what my extension is doing? </h4>
<p>You can use <code><a href="pt/DOM/window.alert">alert()</a></code>, <code><a href="pt/DOM/window.dump">dump()</a></code>, <code><a href="pt/Components.utils.reportError">Components.utils.reportError()</a></code>, or <a href="pt/NsIConsoleService">the console service</a> to display variable data and debugging text.
</p>
<h4 name="Why_doesn.27t_my_script_run_properly.3F"> Why doesn't my script run properly? </h4>
<p>If your script doesn't function as expected, the first thing you should do is check the JavaScript Console (see <a href="#How_can_I_see_errors_in_my_code.3F">above</a>).
</p><p>One common mistake is trying to access the DOM of a window before it is fully loaded. This happens if you place the initialization code at the top level of your script (i.e. outside of any functions). The fix is to use a <code>load</code> event listener to delay your code until the window has finished loading:
</p>
<pre class="eval">function exampleBrowserStartup(event)
{
  // place your startup code here
}
window.addEventListener("load", exampleBrowserStartup, false);
</pre>
<h4 name="Accessing_the_document_of_a_webpage_doesn.27t_work"> Accessing the document of a webpage doesn't work </h4>
<p>To get the document of the current webpage from a browser.xul overlay, you should use <code>content.document</code>, instead of just <code>document</code> which is the document of the browser's window itself. See <a href="pt/Working_with_windows_in_chrome_code#Content_windows">Working with windows in chrome code</a> for details.
</p><p>Also, by default <a href="pt/XPCNativeWrapper">XPCNativeWrapper</a> prevents you from accessing script-defined objects in the webpage and doing some other things.
</p>
<h4 name="I_get_an_XML_parsing_error.2C_but_the_file_looks_fine.21"> I get an XML parsing error, but the file looks fine! </h4>
<p>A common source of parsing errors (some <font color="red">red text</font> with a <font color="red">-------------^</font> underneath) is an &amp; or a &lt; character in your script or an attribute value, which has special meaning in XML. For example:
</p>
<pre class="eval">&lt;button oncommand="window.open('<span class="plain">http://example.com/</span>q?param1=value<b>&amp;param2</b>=val2')"/&gt;
</pre>
<p>or
</p>
<pre class="eval">&lt;script&gt;function lesser(a,b) { return <b>a &lt; b</b> ? a : b; }&lt;/script&gt;
</pre>
<p>The problem can be solved in one of the following ways:
</p>
<ol>
<li>replace the character with its non XML conflicting representation (Ex: "&amp;" -&gt; "&amp;amp;", "&lt;" -&gt; "&amp;lt;")</li>
<li>(in case it's a text node, such as script) place CDATA tags around it:
<pre>&lt;script&gt;&lt;![CDATA[
   function lesser(a,b) {
     return a &lt; b ? a : b;
   }
 ]]&gt;&lt;/script&gt;</pre>
</li>
<li>Put your script in a separate file and include it using:
<pre>&lt;script type="application/x-javascript" src="our.js"/&gt;</pre>
</li></ol>
<h3 name="Example_code"> Example code </h3>
<p>The easiest way to find out what code you need to use in order to do something useful is to find an extension (or part of Mozilla itself) that does it and look at its code. (The XPI and JAR files use the ZIP format.)
</p><p>There is also some documentation. See <a href="Special:Tags?tag=Extensions&amp;language=pt">the list of extension-related articles on MDC</a>, <a href="pt/Code_snippets">Code snippets</a>, and <a class="external" href="http://kb.mozillazine.org/Category:Example_code">Example code page on MozillaZine</a>.
</p>
<h3 name="Where_can_I_get_more_help.3F"> Where can I get more help? </h3>
<p>Please see <a href="pt/Extensions/Other_Resources">Extensions:Other Resources</a> and <a href="pt/Extensions/Community">Extensions:Community</a>.
</p><p>Before asking for help, be sure to set the <a href="#Debugging">debugging prefs</a> and <a href="#How_can_I_display_what_my_extension_is_doing.3F">check the JavaScript Console</a> for related messages. Also, don't forget to do at least a simple search before asking. And read this FAQ!
</p>{{ wiki.languages( { "en": "en/Extension_Frequently_Asked_Questions", "es": "es/Preguntas_frecuentes_sobre_Extensiones", "fr": "fr/Foire_aux_questions_sur_les_extensions", "it": "it/Domande_frequenti_sulle_Estensioni", "ja": "ja/Extension_Frequently_Asked_Questions" } ) }}
Reverter para esta revisão